Creating a node for Node-RED: The Philips Hue Node

Guys at Node-RED are working hard to provide updates and bug fixes. Currently the most recent version is v.03.0 which adds some neat features like tabs to the workspace and the very much useful ‘switch‘ node which can route messages according to simple rules defined in the UI (like If msg.payload != true send to 1).

There are still things to do and there is always room for improvement, but Node-RED is a great tool as it is, and besides, if you need something that does not exist, you can always add it by implementing your own node. As in my previous post, where I implemented a Bluetooth 4.0 device scanning node.

There is not a lot of documentation yet on how to create your own node, and although there is the 99-sample.js.demo sample file, it might not be very clear on how to do it. So I decided to write down in this post the steps for creating a new node.

Note: Creating a new node is a good practise when you can build something that can be re-used from the community. For instance, porting an existing Node.js library to Node-RED and exposing all (or most) of its functionality. If you need only to import an module and use it on a specific workflow, you can do it through the function node using the built-in os module:

osModule:require('os')

Node-RED node essentials:

Each Node-RED node consists of two source files: The nodename.js and nodename.html files. The former contains the execution logic of the node and the latter the graphical element html code, which also defines parameters like what are the inputs, etc.

Both files need to be placed inside a folder name nodename under Node-RED/nodes/node-red-nodes/hardware, software, …

An Example -Building the Philips Hue Node:

I wanted to create a node that controls a Philips Hue wireless lamp through the Hue API. I made a search first online and luckily I found node-hue-api, by Peter Murray, which turned out the simplified the process a lot. Node-hue-api is a great Node.js library that exposes the full Hue API, so that you can build your own Node.js app to look for a bridge, get registered lights, register new lights, change the light status of a lamp, etc.

So, I started with the node samples provided by Node-RED. You can find them in ../nodes/node-red-nodes and the filenames are 99-sample.html.demo and 99-sample.js.demo. I saved them in a folder named ‘philips_hue’ and renamed them to 103-philips_hue.js and 103-philips_hue.html.

The sample code in 103-philips_hue.js (from 99-sample.js.demo) is more or less self-explanatory. It starts with importing the main RED module:

and then implements the main node function. In the 99-sample.js.demo file it is called SampleNode(n) so I changed it to HueNode(n).

Inside this function you write the main code of your node’s logic. The sample comes with a simple “Hello world !” message sent to the output of the node. No matter what you implement in this function, you need to start with initialising the RED node with the following:

RED.nodes.createNode(this,n);

Also, keep in mind that any code inside this main function will be executed upon registering the node in Node-RED, that is when and every time you start Node-RED. It will also be executed every time you provide an ‘input’ to the node.

If you need your node’s code to be executed only upon receiving an input, you have to add the following ‘event’ listener:

and add your code accordingly.

Designing the Node – the philips_hue.html

Before jumping into code implementation, it is good to identify first what the node inputs will be. In my case, I wanted the node to be able to act in dual mode: a) provide a scanning feature for identifying the IP address of a Philips Hue bridge in the local network and then querying it for registered lamps and b) provide a way to turn on/off and flash a particular lamp. So I decided to go with a checkbox in the philips_hue node configuration window. Also, one mandatory input to the node should be the authorization id or username that will authenticate the node as valid to use the Philips Hue API and perform commands on the bridge. More information on that and how to use the Philips API can be found here.

I have modified the default code from 99-sample.html.demo to look like the following:

The first edit was to change the data-template-name to “HueNode”. This is what my new node is called and will be also mapped within the code.

Secondly, I added the textfield for entering the ‘username’ used for authentication with the bridge. When adding your input parameter, make sure you change the id to “node-input-parametername” and the placeholder to “parametername“.

Next, I added the the html segment for the checkbox that will enable bridge scanning:

I added the input fields for the Lamp ID variable and for selecting the status of the lamp the same way. The status was a list with options like AUTO, ON and OFF. AUTO refers to when user wants to set the status of the specific lamp using the msg.payload, e.g., msg.payload = “ON”.

Finally I modified the javascript code at the end of the file by adding the variable’s I am using for input from the user:

You can see that on top of the code the ‘HueNode‘ is registered and under the defaults, each input parameter is defined accordingly.

You can check the complete code for philips_hue.html here.

The Code Implementation – the philips_hue.js

After having defined the inputs next step is the code implementation. Back to the philips_hue.js file, I have imported in the beginning of the file the node-hue-api library that will be used through two variables, hue and hueAPI.

Inside the main HueNode(n) function the user input parameters are saved into variables.

Then on “input” the code checks for bridge discovery mode and performs so using the node-hue-api methods.

When bridge discovery is done, the IP address of the located bridge is stored and then the lamp query begins for identifying registered lamps. At the end, the output of the discovery (JSON formatted string with information about the light names and IDs) is stored in a msg.payload and sent to the node output.

In a similar way, when discovery_mode!=1 the code uses the node-hue-api to change the state of a registered lamp through its lamp ID (1, 2, 3, …). The code segment for controlling the lamp status performs bridge discovery again so there is no need to use the discovery mode first if you want just to control the lamp.

You can find the complete code for philips_hue.js here.

The following Node-RED sketch demonstrates how to turn on lights when it is getting dark:


[{"id":"235afb71.dca504","type":"HueNode","name":"Turn Lamp Off","

username":"34fcc05c38c1a66f9cc1a34394809e7","discovery_mode":false,"lamp_id":"1","lamp_status":"OFF","x":560,"y":99,

"z":"62a1ac73.9d5e54","wires":[[]]}]

I am running Node-RED on my RaspberryPi and now I can easily turn on/off the lights based on proximity detection (using the ScanBLE node). Full instructions and code will follow soon!

 

4 Comments

  1. Asif Nadeem August 8, 2014 3:01 pm Reply

    Hi.

    Great tutorial. I wanted to know is it possible to bypass router connection. I would like to connect RPI and Phillips Hue Bridge directly with Ethernet. Is it possible to provide static IP to both and use?
    Is router with/without internet a necessity?

    Thanks,
    Asif Nadeem

    • Charalampos August 27, 2014 8:30 am Reply

      Hi Asif,

      Sure you can do that, since your Rpi can act as a gateway and give an IP address to the Hue Bridge, it can work. Just note that then, the only way to control the Hue lamps will be through the Rpi :-)

  2. Pradeep August 27, 2014 6:40 am Reply

    First of all thanks for excellent article, it gave me fair idea of how to do things. But I saw one issue here, whenever I try to see your complete code on GitHub it’s throwing 404 error. For eg: In this case “You can check the complete code for philips_hue.html here.” –> If I click link, I am getting 404 error. Can you please have a look? Thanks

    • Charalampos August 27, 2014 8:28 am Reply

      Hi there,

      Apologies for the inconvenience, had modified the repository to reflect the new node name (‘hue’) and neglected to update the links. Should be ok now. Please note that there are a few minor modifications on the current code based on how credentials are handled within Node-RED, etc.

Leave a Reply

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>