For years we’ve seen a trickle of really interesting home automation projects that use the Node-RED package. Each time, the hackers behind these projects have raved about Node-RED and now I’ve joined those ranks as well.

This graphic-based coding platform lets you quickly put together useful operations and graphic user interfaces (GUIs), whether you’re the freshest greenhorn or a seasoned veteran. You can use it to switch your internet-connected lights on schedule, or at the touch of a button through a web-app available to any device on your home network. You can use it as an information dashboard for the weather forecast, latest Hackaday articles, bus schedules, or all of them at once. At a glance it abstracts away the complexity of writing Javascript, while also making it simple to dive under hood and use your 1337 haxor skills to add your own code.

You can get this up and running in less than an hour and I’m going to tackle that as well as examples for playing with MQTT, setting up a web GUI, and writing to log files. To make Node-RED persistent on your network you need a server, but it’s lean enough to run from a Raspberry Pi without issue, and it’s even installed by default in BeagleBone distributions. Code for all examples in this guide can be found in the tutorial repository. Let’s dive in!

What It Is

Node-RED is a graphical programming language built on Node.js. It implements a server and runs what are called “Flows”: programs based on Javascript. Why would you want to run a server-side IDE for your programs? Because Node-RED also makes it dead simple to spin up web apps and use them as your online information and control system.

Installation

To make your Node-RED programs persistent you do need a server, however, if you just want to play for now you can run locally. Your server can be as simple as installing the platform on a Raspberry Pi or an always-on computer on your LAN. Prerequisites include Node.js and npm (the Node.js package manager) which on a Linux system are an easy install.

sudo apt install nodejs

Now we can install Node-RED and, to follow the examples below, you should also install the dashboard package:

npm install node-red
npm install node-red-dashboard

To run locally you can just type node-red in the terminal. However, the more eloquent way to run this is as a systemd service. Copy the contents of the nodered.service file to /etc/systemd/system/nodered.service and update the User, Group, and WorkingDirectory variables in that file to match an actual user on your system. With that in place, just enable and start the service. It will now restart on a crash or system reboot from here on out.

systemctl enable nodered.service
systemctl start nodered.service

You can now load up the Node-RED IDE simply by visiting localhost:1880 in a web browser.

Hello World

The simplest thing to do as your first “flow” in Node-RED is: click button, get timestamp. To make the image above I did nothing more than drag the “Inject” and “Debug” nodes from the left column into the center, then drag the line that connects the two nodes. You need to click the “Deploy” button on the upper right any time you make changes, and then clicking the button hanging off the left side of the inject node, which has the “timestamp” label by default, to spit out the time in the debug window. Click the bug icon in above the right window if you’re not seeing the debug output.

This example isn’t very useful, but that’s not the point of Hello World code. This drives home the power of the graphical code system. What’s also interesting is that flows can be exported as json files. Here’s what this Hello World looks like and it can be imported to your own Node-RED installation.

[
    {
        "disabled": false,
        "id": "ff177395.3cf468",
        "info": "",
        "label": "Hello World",
        "type": "tab"
    },
    {
        "crontab": "",
        "id": "1c6883be.759c24",
        "name": "",
        "once": false,
        "onceDelay": 0.1,
        "payload": "",
        "payloadType": "date",
        "repeat": "",
        "topic": "",
        "type": "inject",
        "wires": [
            [
                "1fec91a8.ab7156"
            ]
        ],
        "x": 200,
        "y": 140,
        "z": "ff177395.3cf468"
    },
    {
        "active": true,
        "complete": "false",
        "console": false,
        "id": "1fec91a8.ab7156",
        "name": "",
        "tosidebar": true,
        "tostatus": false,
        "type": "debug",
        "wires": [],
        "x": 370,
        "y": 140,
        "z": "ff177395.3cf468"
    }
]

MQTT Quickstart

Node-RED feels like it’s made specifically to be used with MQTT, the popular Internet of Things protocol for which Elliot Williams has written a fantastic guide. It feels that way because an MQTT client is built in and most of the nodes have “topics” as well as message payloads which is all you really need to communicate with an MQTT broker.

As you can see above, I’m doing the exact same inject/debug trick but now I’ve dragged an “mqtt in” and “mqtt out” node from the “Network” column of possible nodes.

There’s slightly more setup here as we need to choose an MQTT server and select a topic to publish to and listen for. But the interface makes this very easy, just double-click one of the MQTT nodes. Here I’m using the mosquitto test server (test.mosquitto.org)and the topic Hackaday/nodered/test. Just realize that anyone looking at messages on that server can see this and if you use the exact same topic you may see other readers sending test messages. Node-RED can actually be used as an MQTT broker as well.

Try double-clicking the inject node and changing the payload from timestamp to a string and you can send your own custom messages. For the most part I find it easy to find my way around Node-RED and playing with settings is low-effort. Just make sure to hit the deploy button — your changes won’t actually be in place until you do.

Web Gui Hello World

Let’s get to the really exciting part of Node-Red, the ability to spin up a web app with very little effort.

Here you can see a smartphone displaying our app. The only really useful part here is the button. Click it and you’ll get “Hello Hackaday!” in the debug window of Node-RED as seen above. All it took to create this page was to install the dashboard package for Node-RED and then drag a button onto the canvas. Once deployed, your web app will be located at localhost:1880/ui

Installation of the package is a simple one-liner:

npm install node-red-dashboard

Dragging the button onto the canvas and hooking it to a debug node is also simple, but you need to do just a bit of configuration. Double-clicking on the button node you can change the payload to affect what message is sent to the debug window, but you also need to set a Group, and within the group edit dialog you’ll need to set a Tab. This affects the web app, with Groups organizing blocks on each page of the web app, and Tabs selecting different pages from the hamburger menu at the upper left. You can name groups and tabs however you like.

Let’s Build a Web App!

Enough with the Hello World code, let’s build something useful. I’ve been using Node-RED for a month or so and have built up a couple of useful apps, one interacts with my MQTT broker to control and monitor my front porchlight, the other I use as a simple button-press to keep track of the days I exercise. Let’s build up the exercise app bit by bit because there’s more to it than merely sending MQTT packets back and forth.

Here is the current state of the exercise app, which includes a button that records today’s date to a log file and a gauge that reads the log file to display how many of the last seven days have included exercise. Let’s build it up one block at a time.

GUI Button Writing to Files

This is where the flow begins. It consists of a button from the Dashboard package that sends a timestamp when clicked. This message will be logged to two “file” nodes, the first is exerciselog-raw.txt which simply records one UNIX timestamp for each line. That’s not human readable, so the second file node has a function node which translates the timestamp using the following JavaScript snippet. There’s a bit of magic in there to make sure the month and day are always two digits.

var date;
date = new Date();
var year = date.getFullYear();
var month = date.getMonth();
month = (month < 9 ? '0' : '') + (month+1)
var day = date.getDate();
day = (day < 10 ? '0' : '') + day
msg.payload = year + '-' + month + '-' + day;
return msg;

Adding a User Notification

The button works as expected, but it gives no feedback to the user. To improve upon this I added a notification node from the dashboard package. It is connected after the file node to confirm that the date had been written to the log file.

Reading a File, Displaying Data, Refreshing at Startup

This last part of the flow uses the tan “file in” node to read UNIX timestamps from the raw log file and displays it on the teal “gauge” node from the dashboard package. It is activated by two different triggers, one updates after a new date is written to the log files. The other is the lavender “inject” node which has an “index once after n seconds” option to populate the initial data when Node-RED starts.

The gauge is just looking for a number to populate and this is fed by a function node (I called it Magic). The following code reads in the logfile as an array, figures out the UNIX date code for seven days ago, and then iterates back through the last seven timestamps in the log file.

//Turn incoming timestamps log into an array:
var exercisearray = msg.payload.split("\n");
if (exercisearray.slice(-1)[0] === "") exercisearray.length = exercisearray.length-1

//Get timestamp for week ago to compare against
var thismorning = new Date()
thismorning.setHours(0)
thismorning.setMinutes(0)
thismorning.setSeconds(0)
thismorning.setMilliseconds(0)
var sixdays = 1000*60*60*24*6
var oneweekago = thismorning.getTime()-sixdays

//Iterate and count past week of exercise
var count = 0
var secondsinday = 60*24*7
for (var i=1; i<8; i++) {
  if (i>exercisearray.length) break;
  var testval = parseInt(exercisearray.slice(-i)[0]);
  if (testval >= oneweekago) ++count;
}

//Store our answer as the payload and pass along
msg.payload = count;
return msg;

Give Node-RED a Try!

One of my first concerns with the platform was version control but that’s available too. There is git integration built-in called Node-RED projects but it’s not enabled by default. I’m not accustomed to using a GUI for git, but then again I’m not accustomed to graphical programming interfaces so it doesn’t hurt to try something new.

The examples I’ve shown here are really the tip of the iceberg. Look around and you’ll find a ton of enthusiasm for Node-RED which translates to incredible flows and awesome web apps. For instance, I’ve been reading Scargill’s Tech Blog for years and there you’ll find a ton examples of what can be accomplished. Here we see Scargill’s thermostat control panel that has all kinds of customization to give it a special look. Finding examples that you like isn’t hard, and copying their code is even easier.

You can easily pick up Node-RED in an afternoon and end up with something useful. For those who want to spend more time, the sky’s the limit. If you have any kind of home automation, it’s something you must try as it unlocks the ability for anyone on your LAN to access information and control without installing an app. You can easily pull a disused smartphone out of the drawer and turn it into a dedicated control panel, something I did for the image at the top of this article with the help of an Android app called Fully Kiosk Browser Lockdown for a true fullscreen browser experience not provided by Chrome or Firefox for Android. Give it a try with your own surplus gear!

Resources:

• Example code repository

We’re living in the world of connected devices. It has never been easier to roll your own and implement the functionality you actually want, rather than live with the lowest common denominator that the manufacture chose.

In a previous article I walked though a small python script to talk to a BLE light and used it to cycle through some colors. Now I want to delve deeper into the world of Internet Connected BLE devices and how to set up a simple Internet-Of-Things light. With this example in hand the sky’s the limit on what you can build and what it will be able to do.

Join me after the break as I demonstrate how to use NodeJS to bridge the digital world with the physical world.

Bluetooth Support in Languages

NodeJS is very different from traditional languages in the way that Node is considered asynchronous in its execution. NodeJS uses an Event Loop and things happen as a consequence of events such as user actions as well as messages from other programs and threads. A traditional program or script is a sequence of actions that will get executed one by one until all actions are completed. If a particular action is blocking such as waiting for a button click or a message from a device, then the program will have to wait until the process is complete.

I am not an expert on NodeJS but the basics should be understood to be able to write our application. Details of Async.js and the event loop are beyond the scope of this article and we will start with a basic application and add the necessary functionality.

BLE support in NodeJS is enabled by the ‘NobleJS’ package by Sandeep Mistry. You can learn a lot by studing other programs that already use the package. I had a discussion with Alex Albino about his experience with BLE and NodeJS. Alex Albino is the same guy responsible for the IMUDuino I mentioned before and his web dashboard app is written in NodeJS. He has a number of other example applications up on GitHub that he put together with the help of Kas Perch and Russell Hay. I took inspiration from their work and created a small bridge application described here. It uses NobleJS which works on MacOS as well as Linux. Windows 10 support is available but I did not venture into that direction.

Let’s start with a basic application to get a better understanding of how things work.

A Simple BLE Scanner Application

The NobleJS package page has all the necessary documentation required to get started. The basic install instructions are simple and include the tools we installed in the previous write-up. To start a new project, simply create a new folder and run the command:

npm init blescanner

NPM will ask you a number of questions and you just need to press return for what you don’t want to fill out. Just note the entry point which is index.js by default. This is the file where all the code will go.

Next, install the Noble package:

sudo npm install noble --save

Edit the index.js in your favorite editor. I’ve already sample code to get started. If you’re following along, copy this Github Gist and paste it into your index.js file.

The code has three parts. The first is to instantiate packages and create variables. The second is to add callbacks to functions such as the noble.on events. The third is a small interval loop that allows our program to enable and disable scanning of BLE. Once you run the script, it should spit out the names of BLE beacons and peripherals around you. I left some other data un-displayed for you to experiment with.

Talking to the BLE Lights

The scanner has the ability to print the IDs of all the peripherals in the vicinity. I renamed my scanner index.js to scanner.js and ran it to scan nearby BLE devices. Once the scanner lists out the BLE Lights, we create a list of UUIDs by a simple copy and paste which can be modified later.

I created a new index.js where I try to connect to each BLE Light and then write a known value to the relevant characteristic. Unlike the previous article where we wrote a 4 byte RGBW value, in this exercise, individual characteristics are used as a proof-of-concept. The code can be downloaded from my Github Repository.

In my experiment, I used the values 00 for each light since the BLE Lights turn on at full brightness by default when first powered ON and hence a successfully connected instance would turn the light OFF.

Connectivity – MQTT

There are a number of ways to interface our application to the internet to qualify it as an IoT app, however, we will employ the MQTT protocol.  MQTT is the same protocol used by Facebook Messenger for it’s connectivity, and it’s something of a favorite around here for home automation.

MQTT works by having a central post-office of sorts called an MQTT Broker and this broker allows clients to connect to it. Once a client registers itself with the broker, it subscribes to a particular topic which is equivalent to a post-box. Once a message is posted to the topic, it is distributed to the registered clients.

There are a number of decisions to be made such as authentication and ensuring delivery but the important thing is that every client connects outward to the broker. This means that there is no messing around with IP addresses and firewall settings(unless your network blocks all ports). The underlying protocol is TCP/IP and there is a lot that can be configured which I leave as an exercise for the reader.

For this exercise, we shall use the free MQTT broker at iot.eclipse.org which can be used without any registration at Eclipse which is pretty awesome. This can be used by anyone in any language and even by dedicated hardware. I have used the service to connect a CC3200 to the internet in the past (I will discuss the project in brief at the end of this article).

A sample program is available and I strongly urge you to try it out before going any further. Just replace the connect string to mqtt://iot.eclipse.org and you are good to go. At this point you have two pieces of the puzzle, tested and ready to go. Next we put humpty-dumpty together.

Creating a Bridge

The final thing to do here is create the actual bridge. Here is how it should work.

Once the NodeJS app is executed, it should attempt to connect to the MQTT Broker. If this fails then we should get an error, however, if all goes as expected, the app should subscribe to a topic and wait for a message event. Additionally, it should check if the BLE device on the machine is enabled and if so then it should start scanning for BLE devices on a regular interval. Local variables will be used to store R,G,B and W values that are to be transmitted to the BLE device. If this application were to be extended, more variables could be used to save data exchanged between BLE and our client application.

Once a message is received on the MQTT topic, the value is written to the local variable ready to be passed onto the BLE devices. Once a BLE device is found, the application should connect to it and write to the appropriate characteristic.

There are some design choices here to be made. Firstly, I chose to have the local data refreshed to the BLE devices even if it had already been written in a previous transaction. This is redundant and you could potentially save energy by adding a check here. Secondly, I have four different topics for R,G,B and W which means four different connections. A better way would be to either use JSON or a custom data packaging method to consolidate data into a single stream.

So now how do we send the commands? A similar application with only the MQTT part of the code would do the trick and I am including the source code for that as well. Check out my code and feel free to explore and fork it. I would love to see what you build with it.

A Short Note on Front Ends

A command line tool is not the best way to present your idea and since we are using NodeJS, I thought I would just touch on the topic of front ends. Traditional applications would have to be written in Visual Basic or Java(AWT or Swing anyone?), however webapps and related technologies can be a portable solution of sorts. Instead of an executable, a webpage could be coded to display necessary buttons and have javascript functions to send necessary data to something like an MQTT server. Remember, NodeJS is javascript for the backend and the same(ish) code can be run in the modern web browser.

Need more inspiratoin? Check out three.js and MeteorJS and you will find yourself with the ability to have easy(ish) GUI applications with very few lines of code that you can port to the likes of the Raspberry Pi.

A Similar Project

Before I close, I wanted to add a video demo of a small project I did a few years ago with Texas Instruments’ CC3200 platform. Instead of having a laptop run the MQTT code, I had the CC3200 connect to the broker and wait for commands. Benjamin Cabe was the inspiration behind the work where the entire Eclipse PAHO library was used as a base. For the front-end, I used the PAHO JS library to send commands over MQTT and get status messages and display them in real-time.

(External Link to the live version)

That’s all I have for now and if you like what you saw, tell us about it. We would love to see your projects that are enabled by similar technologies and if you have something that you feel is amazing, feel free to send us a link via the tips line.

Here at Hackaday, we find Christmas time very exciting because it means an influx of holiday-themed hacks that really help us get into the festive mood. [Andrew’s] programmable Christmas tree hosted at HackMyXmas is certainly one of our favorites. The project consists of a 500 RGB LEDs wrapped around a typical Christmas tree and controlled by a Teensy.  However, not settling for the typical, simple and cyclical pattern for the LEDs, [Andrew] decided the tree had to be programmable of course! So, a single board computer (a C.H.I.P) running Linux was used to provide a Wifi connection and a web server to easily program the tree.

This is where things get very interesting. The C.H.I.P board hosts a comprehensive website that conveniently gives you the option to program the LEDs using either, Scratch like draggable blocks (using Googles Blockly) or even pure JavaScript. Once the perfect pattern is conceived, you can test run it on the online simulator or even send it off straight to the Tree, watching it blink in all its glory on the provided live stream.

We applaud [Andrew] mammoth effort for invoking programming in such a fun way! You can check out the live stream of [Andrew]’s Christmas tree below.

During conferences, a name-tag is one of the first things people look at when bumping in to others – mentally trying to keep track of faces and names. But gone are the days when your name tag was a post-it stuck on your arm. Over the years, conference badges have become increasingly interesting and complex. Hackable electronic badges are becoming the norm, and not just at hardware cons. For the recently concluded NodeConfEU conference in Ireland, [Gordon Williams], of Espruino fame, designed a JavaScript centric hackable badge.

NodeConf EU is the key Node.js event in Europe, providing a forum for the Node.js community. So when they brain-stormed ideas for a conference badge, they obviously gravitated towards a design that could run JS. [Gordon]’s Puck.js fit the requirements perfectly, and he was tasked with creating a new design based on the Puck.js. The feature list included BlueTooth Low Energy, low power consumption so it could run off a CR2032 battery, a high contrast LCD, some buttons, NFC, and a prototyping area – all packaged in a beautiful hexagonal shaped PCB (obviously) to resemble the Node.js logo. The badges were programmed with attendee names, but the fun, juicy part could be accessed by pressing buttons in the Konami code sequence.

Easy to follow, detailed documentation helped hackers quickly get started with code examples. They were also presented several challenges to work through allowing them to get familiar with the badge. Hacked badges were entered for a Grand Challenge with a chance to win a free ticket to next years conference. The badge hardware and firmware are open source and source files are hosted in a Github repository. Check out a short overview of the badge in the video after the break.

Thanks to [Conor] from nearForm for letting us know about this awesome badge.