Phoscon ZigBee Gateway: AKA – ConBee or RaspBee – Part 4: Node-Red Integration

Paul Taylor from the Smarter Home Club has completed his series on RaspBee, covering Node-Red integration!

Welcome to the long delayed 4th and final part of a series on the Phoscon ZigBee Gateway.

The first part introducing the hardware is available at:

The second part on hardware and software installation is available at:

The third part on adding devices and connecting them together is available at:

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?

How to get started and how to use Node-Red has been extensively covered by people far smarter than me. But if you need a place to start check out this YouTube playlist featuring videos from Opto22 –

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 connect with Node-Red?

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 setup 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 setup 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:

Setting up the REST API

The REST API is very well documented and is available at:

The only tool needed to setup 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 webapp
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 as it will be need for all API requests.

Getting a list of lights

Sending a Get request to the API either through your REST client or directly from your browser like: http://deCONZ/api/01234567abc36/lights/ where deCONZ is your host IP or URL and 01234567abc36 is the key you generated previously.

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”}}

While this response isn’t pretty finding your endpoint numbers is pretty simple. Search the output for etag”:” Just before it you will see a number in “”. For example this output shows three lights available as ID’s 1, 3 & 4. The output also includes the device name as set in deCONZ for example ID 1 is named Laundry.

Controlling a light from Node-Red

A command must be sent as a PUT request with a JSON payload. For example sending:

“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. But for a dimmable light I have once again created a gist that can be imported to show this setup. It is available at is the website for our Facebook community, The Smarter Home Club – which is an umbrella for all kinds of smart home technologies – home automation, security, custom electronics, weather stations, alternative energy, you name it. DIY focused.

If you’re interested in joining the Smarter Home Club’s Facebook group, please follow this link:

The Smarter Home Club on Facebook