Home Automation - controlling lights with CURL and HA-Bridge

 In order to control lights are years I'm using HA-Bridge, running on a server I call HA server.

Originally (and possible it will return there) was hosted by Opus, my main server.

It is quite  a while now is running over a Raspberry Pi.
This article is about how to control X10 via HA-Bridge from another computer in the network (hint, the network is not exposed to the outside)

There are already some articles about HA-Bridge in my blog :

• Home Automation - fixing Ha-Bridge
• Server chronicles - HA temporary server
• Playing with Alexa and Echo
• Home Automation - remotely controlling lights from HA server via ssh

Now the goal is to be able to send REST commands via Curl to HA-Bridge from another computer in the network.
Mainly is used to control the server area fans from a script on a computer in the server room.
The alternative would be to reinstall the HA server on the main server so that it can control directly X10 via  Heyu

HA-Bridge API

HA-Bridge supports some API as described in the documentation.

Using CURL from a terminal is possible to send out commands and retrieve information about the status of the controlled devices.

Before to start a session, is necessary to obtain a username that will be used in the subsequent commands.

In order to use the API is necessary to know some terms used :

• <user>
  Code obtained with a specific API to be used in some other API.
  NOT all the commands requires the user.
• <device ID>
  Is a numeric ID assigned to a device.
  Is possible to know th eID asking for the list of devices (or looking at the webconsole of the server)
• <HA server IP>
  URL of the HA server hosting the HA-Bridge

To work with the HA-Bridge API is necessary to follow this flow :

1. request username
2. API command
3. .......
4. API command

API 

Request username

To do so is enough to send out a command :

$ curl  -H  "Content-Type: application/json" -X POST -d '{"devicetype": "<any string>"}'  http://<HA server IP>/api

The string after the devicetype is arbitrary  and non important, is just used to generate the user code.
Note that the username will NOT be stored in the server, remains alive for the session.

If the server is up and OK, it will answer with (for example)  :

[{"success":{"username":"a2b0cdfd044246cb8c80717bdd2e727b"}}]

The username will be used in the light control commands as <user>, don't use double quote in the command API

List all lights registered info

$ curl -H  "Content-Type: application/json" -X GET http://<IP-address-server>/api/<user>/lights

So for example to retrieve the status of all the lights a command (assuming the HA server to be at 192.168.2.4 with a user named a2b0cdfd044246cb8c80717bdd2e727b will be :

$ curl -v -H  "Content-Type: application/json" -X GET http://192.168.2.4/api/a2b0cdfd044246cb8c80717bdd2e727b/lights

Note: Unnecessary use of -X or --request, GET is already inferred.

*   Trying 192.168.2.4:80...

* TCP_NODELAY set

* Connected to 192.168.2.4 (192.168.2.4) port 80 (#0)

> GET /api/amitheuser/lights HTTP/1.1

> Host: 192.168.2.4

> User-Agent: curl/7.68.0

> Accept: */*

> Content-Type: application/json

> 

* Mark bundle as not supporting multiuse

< HTTP/1.1 200 OK

< Date: Mon, 12 Jun 2023 14:02:49 GMT

< Content-Type: application/json

< Transfer-Encoding: chunked

< Server: Jetty(9.4.z-SNAPSHOT)

< 

{"1110":{"state":{"on":false,"bri":1,"alert":"none","reachable":true},"type":"Dimmable light","name":"All l

...........................................

...........................................

light","name":"Zapper","modelid":"LWB007","manufacturername":"Philips","uniqueid":"85:97:a6:cf:a7:4d:ef:0b-cb","swversion":"66012040"}}

Use the command jq to beautify the JSON result.
The first number of the block is the <device ID>

Retrieve status single light

Is possible to retrieve information and status about a single light :

$ curl  -H  "Content-Type: application/json" -X GET  http://<HA server IP>/api/devices/<device ID>

Alternatively is possible to use :

$ curl -H  "Content-Type: application/json" -X GET  http://<HA server IP>/api/<user>/lights

This is an example of  beautified block :

{

  "id": "1105",

  "uniqueid": "af:21:d0:c9:7d:b2:e2:0b-7e",

  "name": "Office lab",

  "mapId": "undefined-copy-copy",

  "mapType": "cmdDevice",

  "deviceType": "exec",

  "offUrl": "[{\"item\":\"/usr/local/bin/heyu -c /home/pi/.heyu/x10config off office_lab\",\"type\":\"cmdDevice\"}]",

  "onUrl": "[{\"item\":\"/usr/local/bin/heyu -c /home/pi/.heyu/x10config on office_lab\",\"type\":\"cmdDevice\"}]",

  "inactive": false,

  "noState": false,

  "offState": false,

  "description": "Office lab light (C5)",

  "deviceState": {

    "on": true,

    "bri": 254,

    "alert": "none",

    "reachable": true

  },

  "onFirstDim": false,

  "onWhenDimPresent": false,

  "lockDeviceId": false,

  "dimNoOn": false,

  "dimOnColor": false

}

Control a light

$ curl -v -H  "Content-Type: application/json" -X PUT -d "{"on": <true/false>}" http://<HA server IP>/api/<user>/lights/<device ID>/state

For example to turn ON a light :

$ curl -H  "Content-Type: application/json" -X PUT -d '{"on": true}' http://192.168.2.4/api/e4f3896c7a3d40118c6585129e2bc264/lights/1105/state

will return : 

[{"success":{"/lights/1105/state/on":true}}]

Workflow

A normal session thus should include to request a username and then use it to activate lights and/or retrieve status.

The good thing about using this method is exactly the capability to know if a light was turned on or off.

Some questions are open right now, hopefully I will find answers soon.

For example :

• how long a username is retained ?
  i.e. for how long I can use an obtained username before it stops to work.
  During early tests I noticed that using an arbitrary username did work only for retrieving commands, change state commands DO require a requested username.
  
  

Resources

• GitHub - HA-Bridge
• GitHub - API usage