Phoscon Zigbee Gateway: AKA – ConBee or RaspBee – Part 4: Node-Red Integration
This article is now considered outdated. Since it was initially published a proper node was released. Check out the new article
Part 5: Better Node-Red Integration
Welcome to the 4th part of a series on the Phoscon Zigbee Gateway. This section will focus on Node-Red Integration.
What is Node-Red?
From the Node-Red home page:
“Node-RED is a programming tool for wiring together hardware devices, APIs and online services in new and interesting ways.
It provides a browser-based editor that makes it easy to wire together flows using the wide range of nodes in the palette that can be deployed to its run-time in a single-click.”
New to Node-Red?
Getting started with Node-Red has been extensively covered. Check out this YouTube playlist featuring videos from Opto22 – https://youtu.be/3AR432bguOY
How does Node-Red connect to deCONZ?
The deCONZ software provides a pair of interfaces to interact with your Zigbee devices.
A WebSocket server sends push notifications for real-time feedback from things like motion sensors or switches
A REST API: This allows third-party applications easy monitoring and control of a Zigbee network from local or remote operating clients. Most functions that can be done from the Phoscon WebApp can also be done through the API
Why Node-Red Integration?
Normally if you have a single radio hub like an Echo Plus, IKEA TRÅDFRI gateway or Sengled Element hub. You can only provide interactions between the devices it talks to. By interconnecting the deCONZ hub with Node-Red you can set up interactions between pretty much anything Node-Red can talk to. For example, I have a TRÅDFRI 5 button switch setup to control some Connect by TCP 6loWPAN bulbs which are a very different protocol.
Setting up the WebSocket Connection
Node-Red has built-in capability for connecting to a Web-socket server. This is a very basic connection to receive sensor events from deCONZ.
The basic steps to set up the connection are as follows.
1. Add a web-socket input node to your flow:
2. Edit the new node.
a. Change the type to Connect to
b. Click the edit pencil next to Add New websocket-client
3. Enter the url for your deCONZ instance as ws://IPADDRESS :443/ or ws://URL:443/
a. Also, ensure Send/Receive is set to payload
b. Then click ADD then Done
You should now have a functional connection. Of course, this connection does very little without additional nodes to process the input you receive. The simplest way to test your connection is to add a debug node to the output of the WebSocket node and initiate an event from a Zigbee button or sensor.
I process my received events and output the result over MQTT. As such I have made available my processing logic as a gist that can be imported into your Node-Red instance. It’s available at:
https://gist.github.com/sktaylortrash/6e6511b520ebac8f3acd15307c19906c
Setting up the REST API
The REST API is very well documented and is available at https://dresden-elektronik.github.io/deconz-rest-doc/
The only tool needed to set up Node-Red is a REST client to access the API. There are various free clients available; I used Postman for Chrome from the Google Webstore
Acquire an API key
Any client that wants to access the API must provide a valid API key otherwise the access will fail.
To acquire an API key send a POST request to /api as pictured. Use the IP address and the port of your gateway. Before sending the request the gateway must be first be unlocked. That process is described below.
Unlock the gateway
In a new browser, tab open the web app
Click on Menu/Settings from the top menu
Click on the Unlock Gateway button
Now the gateway is unlocked for 60 seconds.
Send your key request within 60 seconds. You should get a reply like below
In the response body, the new API key is in the field username. Save this key. All API requests will need it.
Getting a list of lights
Send a Get request to the API through your REST client or directly from your browser. Like http://deCONZ/api/01234567abc36/lights/
- deCONZ is your host IP or URL
- 01234567abc36 is your previously generated key.
This will return a list of all lights like:
{“1”:{“etag”:”eaa0cf2d1e01b20c0655a133496afdb9″,”hascolor”:false,”manufacturername”:”Philips”,”modelid”:”LWW002″,”name”:”Laundry”,”state”:{“alert”:”none”,”bri”:254,”on”:false,”reachable”:true},”swversion”:”1.23.0_r20156″,”type”:”Dimmable light”,”uniqueid”:”00:17:88:01:03:c2:b6:3c-0b”},”3″:{“etag”:”9cb7ff58af08cd1b20098b08894e796c”,”hascolor”:false,”manufacturername”:”SmartDimmer”,”modelid”:”Dimmer_us”,”name”:”Switch2″,”state”:{“alert”:”none”,”bri”:254,”on”:false,”reachable”:true},”swversion”:”1.0.2″,”type”:”Dimmable light”,”uniqueid”:”00:12:4b:00:19:e7:6e:03-0b”},”4″:{“etag”:”aeb078b281e28033256596b11036ecff”,”hascolor”:false,”manufacturername”:”SmartDimmer”,”modelid”:”Dimmer_us”,”name”:”Switch1″,”state”:{“alert”:”none”,”bri”:233,”on”:false,”reachable”:true},”swversion”:”1.0.2″,”type”:”Dimmable light”,”uniqueid”:”00:12:4b:00:19:e7:c7:21-0b”}}This response isn’t pretty but finding your endpoint numbers is pretty simple. Search the output for etag”:” Just before it you will see a number in “ ”. This output shows three lights available as IDs 1, 3 & 4. Also included are the deCONZ device names. In this instance “ID 1” is named Laundry.
Controlling a light from Node-Red
A PUT request with a JSON payload must be sent. Send for example:
{
“on”: true,
“bri”: 127
}To http://deconz.local/api/01234567abc36/lights/1/state
This will turn on the light at approximately 50%.
How you send the request will be greatly dependent on what type of endpoint you are controlling and what it’s capabilities are. For a dimmable light, I have once again created a gist. It can be imported to show this setup. It is available at https://gist.github.com/sktaylortrash/75d010249e5a94123804e8921d95f77d
Now that your Node-Red Integration with the Phoscon Zigbee Gateway is functional. Explore all the ways Node-Red can be used to interact with and manipulate your devices.
We originally contributed this series of articles to the Smarter Home Club Blog starting on November 11, 2018. We are reposting it here to ensure our content remains available to all. Small corrections for grammar and spelling or dead links may have been made in the reposting.
