Just as an orchestra needs a conductor, Internet of Things (IoT) devices and web services need a tool that wires them together, defines their roles, and specifies rules for their behavior. This is essentially what Node-RED [1] does. Built by IBM, this open source Node.js-based application provides a graphical environment for building flows – simple and complex programs that tie various devices and services together, as well as manipulate and move data between them.

This functionality makes it possible to automate various tasks and program devices and services by connecting Node-RED modules called nodes and adding a dash of JavaScript code. For example, you can easily create a simple flow that pulls and processes weather data from the OpenWeatherMap service and sends daily weather reports to a specified email address. It is also possible to set up a flow that reads data from sensors connected to a Raspberry Pi or Particle's Photon WiFi board and pushes the obtained data to a Google Docs spreadsheet or Twitter. To automate tasks and orchestrate IoT devices and services, you need to master Node-RED's basics, and in this article, I will help you to get started with this powerful and versatile application.

Installing Node-RED

Although Node-RED can run on a regular Linux computer, you might want to use a dedicated machine to act as a Node-RED server (see the "Using FRED" box for more options); a low-cost single-board computer like Raspberry Pi is perfect for that. In fact, the latest version of Raspbian based on Debian Jessie has Node-RED preinstalled, so you don't even need to spend time deploying the application.

However, instead of choosing the easy route, you might want to opt for the Lite version of Raspbian and install Node-RED manually. This gives you a lean Raspbian system with Node-RED that will run even on the lowly Raspberry Pi Model A. Grab the latest Lite image of Raspbian, burn the image to an SD card, and boot the Raspberry Pi. Then, configure the desired settings using the raspi-config tool and install Node-RED by running the command:

sudo apt-get update && sudo apt-get install nodered -y

This installs the Node.js software and the Node-RED application. To install additional nodes, you also need to install the NPM package manager. To do this, run the commands:

sudo apt-get install npm
sudo npm install -g npm@2.x

To start Node-RED, run the node-red-start command and point your browser to http://127.0.0.1:1880 (replace 127.0.0.1 with the actual IP address or domain name of the Raspberry Pi running Node-RED).

Node-RED Basics

A flow in Node-RED consists of nodes connected to each other. Each node performs a specific task. An input node, for example, can request and receive data from an external service, source, or another node. A function node usually contains JavaScript code that processes obtained data, whereas a storage node makes it possible to store processed data or query results in a file, a database, or a web service.

There are also nodes that allow Node-RED to communicate with physical devices (e.g., Raspberry Pi's GPIO pins) and services like email and Flickr. It's no surprise then that Node-RED's graphical interface is optimized for working with nodes, and it puts all the tools for building flows at your fingertips. The application's main page is split into three areas. The left sidebar contains all available nodes grouped by types.

The filter field at the top of the sidebar offers a quick way to locate the node you need. When you mouse over a node, its brief description appears in a pop-up bubble. Click on a node to select it, and you can read its detailed description under the info tab in the right sidebar. The debug section shows the output of the flow, which is useful for testing and troubleshooting flows. The working area in the middle is where you actually build flows by adding nodes, connecting them together, and configuring them.

Of course, the best way to learn Node-RED's ropes is to build an actual flow, and you might want to start with a simple flow that, when triggered, generates the Hello World! message followed by the current date (Figure 1). Start by dragging the inject node onto the working area. This node acts as a trigger that can be activated manually by clicking on its button or scheduled to run at specific times or intervals.

Figure 1: Basic Node-RED flow.

To configure the node, double-click on it. The edit dialog allows you to configure several options, with the key being the node's payload. Each node in Node-RED has a payload, or data that the node can receive or send further down the flow. The input payload can come from other nodes or be specified manually. The latter applies to the inject node, and you can choose between three payload types: timestamp, string, and blank. The first type outputs the current timestamp as the node's payload. To configure the inject node to generate the Hello World! message as its payload, select the string payload type and specify the message.

To generate the current date and assemble the final output, add the function node and connect it to the inject node by drawing a connector between the nodes using the mouse. Double-click on the function node to open it for editing (Figure 2). This node lets you write JavaScript code that can perform a wide range of tasks. In this case, the function should generate the Hello World! message received as a payload from the inject node followed by the current date. The code that does that is as follows:

date = new Date()
month = date.getMonth()+1
msg = msg.payload + " Today is " + date.getFullYear() + "-" + month + "-" + date.getDate()
return msg;

Figure 2: Adding JavaScript code to the function node.

If you are familiar with JavaScript, you shouldn't have any trouble understanding the code above. Note that the month variable adds 1 to the month number, because the getMonth() routine numbers months starting with 0 (January). Almost always, the final step in any function is the statement that returns the function's result as the msg variable. The value of this variable constitutes the payload of the function node. In the simple code above, the value of the msg variable is the "Hello World!" string and the value of the msg.payload variable is received from the inject node.

To view the output of the function, add the debug node to the flow. This node pumps whatever payload it receives to the debug console under the debug tab in the right sidebar. Your first flow is ready. To see it in action, click the button on the left side of the inject node, and you should see the generated message in the debug console.

More Flows

Once you have mastered Node-RED's basics, you can start building more complex and useful flows. For example, how about creating a flow that fetches the weather forecast from the OpenWeatherMap service, processes the received data, and sends a weather report to a specified email address? For this flow to work, you need to install the openweathermap node [3] first, because it's not bundled with Node-RED by default. To install the node locally (i.e., for the current user), use the following commands:

cd ~/.node-red
npm install node-red-node-openweathermap

Alternatively, you can install the node globally (i.e., for all users):

sudo npm install -g node-red-node-openweathermap

The flow you are about to build has four nodes: inject (triggers the flow), openweathermap (fetches weather data), function (processes the obtained data), and email (sends the processed data to an email address). So, add these nodes to the flow and connect them (Figure 3).

Figure 3: Weather Today flow.

Instead of creating the flow from scratch, you can import it from the Weather Report gist on GitHub [4] (see the "Import and Export Flows" box). Once the flow is ready, open the inject node for editing and configure it to trigger the flow at specified times or intervals. Open the openweathermap node for editing, enter your API key (if you don't have it, you can obtain one by signing up with the service), and specify the desired city and country (or geographical coordinates).

Figure 4: Exporting the current flow to the clipboard.

The task of the function node is to extract the specified data from the payload obtained by the openweathermap node. The payload coming from the openweathermap node has several properties, including msg.weather.detail (detailed description of weather), msg.payload.tempc (temperature in Celsius), and msg.payload.windspeed (wind speed in m/s). The code in Listing 1 parses these properties and assembles everything into a human-readable weather report.

Of course, you can extend this basic code in any way you like, assuming your JavaScript coding skills are up to scratch. For example, you can add a condition that warns you when it's raining (Listing 2). Finally, you need to configure the email node. Here, you have to specify the target email address and SMTP server settings. Once you've done that, press the Deploy button (this saves and activates all flows in Node-RED), then trigger the flow manually to make sure it works properly.

You can also use Node-RED to push payload to popular web services. For example, you can create a flow that automatically publishes a daily photo to Flickr (Figure 5). For this flow to work, you need to install the flickr [5] and exif [6] nodes. Once you've done that, import the Daily Photo to Flickr flow from Gist [7] into Node-RED. Here is what this flow does: First, the Pick File function checks the ~/photos/ directory for a JPEG photo with the current date as its file name (e.g., 2015-12-23.jpg) using the following code:

date = new Date()
month = date.getMonth()+1
msg.filename = "photos/" + date.getFullYear() + "-" + month + "-" + date.getDate() + ".jpg"
return msg;

Figure 5: Daily photo to Flickr flow.

The file name is pushed to the file node that picks up the appropriate photo and sends it as a buffer (i.e., binary data) to the flickr node to upload the photo on Flickr. The flickr node accepts several properties, including msg.title (the title for the photo), msg.description (the description for the photo), and msg.tags (tags to assign to the photo). The flow uses the exif node and the accompanying function to set the value of the msg.title property to the description from the photo's Exif metadata. Before you deploy the flow, you need to create a dummy Flickr app, add the generated key and secret token to the flickr node, and then authenticate the node with Flickr.