In a previous post I touched on the idea of using the SmartThings Hub to consume local APIs, specifically the json API exposed by my Domoticz install. I didn’t really show what Domoticz is, or how to find the details you need to configure the handler to talk to it.
This is the Domoticz switches interface. The grid shows every LightwaveRF device I still have active on Domoticz. It used to include all the powersocket based devices (mostly lamps) until I moved them to Z-Wave sockets. Clicking the bulbs here, or moving the sliders, will send a signal to the device to change state.
Each device in Domoticz has a unique ID, or idx, which can be found under
Setup->Devices. This list can be filtered to show only the kit being controlled by the RFXCOM USB antenna – which in my case is all the LightwaveRF devices. The Idx column shows the unique ID – this is needed to control the device via the json API.
You can see that the lights over my dining table have Idx 80. To turn them on I’d issue a GET request to:
http://domoticz:8080/json.htm?type=command¶m=switchlight&switchcmd=On&idx=80 Since they are configured as a dimmer device, we can also issue a Set Level command:
http://domoticz:8080/json.htm?type=command¶m=switchlight&switchcmd=Set%20Level&idx=80&level=16 That level=16 at the end there sets the brightness to roughly half. I say roughly because the fine control over this seems a bit flakey.
In the SmartThings handler I wrote, there is this little bit of code:
sendEvent(name: "switch", value: 'on') sendEvent(name: "level", value: value) value = value / 100 * 34 apiGet('Set Level', value)
That takes the SmartThings brightness request – expressed as a percentage – and converts it to a value in the 0-34 range expected by the Domoticz API. The apiGet calls a function which builds an http request and returns what in SmartThings land is called a HubAction. A HubAction is an http request that is allowed to be generated on the Hub itself on the LAN, rather than – as is usual – runs in the SmartThings cloud.
To add these devices to SmartThings, I’ve been using their online IDE/config site. Simply add a new device using the installed handler, and configure the details:
Of particular interest here are the two Preferences values. These are taken from the handler details, and have to be populated to make it work. deviceID is the Idx from Domoticz, and domoticzIP is the IP of the Domoticz server.
With these details saved any use of the device in SmartThings issues the call to the Domoticz API. You can see that this device – the main lights in the master bedroom – is involved in a number of custom actions and commands including “Wakie Wakie”, the routine that gently fades up the lights as an alarm in the morning.
Having spent a bit of time reading the SmartThings Developer documentation, I think I need to tidy up the handler code a bit. The dimmer functionality is especially weak – not remembering state for example. If I were really following the spec properly, the code would be able to find the Domoticz install and then query it for any compatible devices. Another project on the home automation list!