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

Zigbee Gateway

Welcome to the 4th part of a series on the Phoscon Zigbee Gateway. This section will focus on Node-Red Integration.

  1. Introduction
  2. Installation
  3. Connecting Devices

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

Node-Red Integration

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

Node-Red Integration

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.

  1. Introduction
  2. Installation
  3. Connecting 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.

You may also like...