The primary objectives of this lab are to learn how to install and use code-red for simple applications. The major steps are:
Testing node-red install (or installing)
Running node-red
Exploring the node-red interface
Creating a simple flow
Installing components in the palette
Building a flow with a dashboard
Communicating with a web service (weather) and displaying the data.
Deliverables: You should create a lab report, report.md, using markdown in your lab3 directory.
This report should include descriptions of the steps you take, any issues that you encounter, and what you learn at each step.
Your report should include screen shots of the flows that you create and your dashboard(s).
Your report should also include the JSON for the first
flow that you create – the purpose is to learn where and how these are stored.
Create a sub-directory for any images (img) and links in the markdown.
The grading rubric for this
lab is
Completion of tasks: 60%
node-red exploration: 10%
Simple flow: 10%
Dashboard + flow: 20%
Weather service: 20%
Demonstration of working flows and dashboard: 10%
Lab report: 30%
Steps taken + issues: 20%
Screenshots of flows/dashboards: 5%
JSON for your first flow + brief explanation: 5%
Overview of node-red
Building networked systems can be extremely challenging because of the diversity of software libraries (APIs) and programming languages required; and because the distributed nature of message-based communication makes it difficult to observe system activity in order to diagnose problems. In order to make the development of an internet of things tractable, we will make extensive use of a node-red – a tool that allows us to graphically connect various system components and, using built-in modules, enables very rapid testing of key components.
A node-red “program”, called a flow, consists of a set of nodes graphically wired together. nodes
are configurable, graphical objects that, generally, perform a single function. To get a sense of this tool, consider the following screen shot. On the left side of the screen is a palette of nodes, on the right is a tabbed region with node information, debugging output, etc. The center of the screen contains a simple flow consisting of two nodes connected by a “wire”.
Thus, the node-red “program” in this example is defined by the following flow – the left node generates (configurable) input data, and the right node prints received data to the debugging output. Communication between nodes is in the form of messages that carry data over “wires.”
In this example the “Test Message” node is an “inject” input node configured as illustrated in the following figure:
The node is configured to inject a timestamp (seconds since 1/1/1970) one time with the topic “time”. We’ve given it the name “Test message” which replaced the default node name (inject). An example message (captured from the debug output) is:
Messages in node-red are JSON objects. The message contains a topic, payload, and unique id (used internally by code-red). While the use of a topic is optional, in the world of IoT messages are frequently formed from a “topic” and a “payload”. In node-red, the payload can be virtually anything – a number, a string, another
JSON object, or even a binary “blob”.
The flow is itself defined by JSON – we can export the “code” for a flow or node from the GUI. This example flow is defined as (note this is pretty printed to make it more readable).
While not too readable, this flow defines a list consisting of the flow definition and its two nodes. The json consists of an array of three structures. The first defines the “flow”
and the remaining two the nodes. All three structures have internally generated “id”s.
The flow structure has type “tab” and is called “Flow 1”. The first node structure
defines an “inject” node called “Test Message” which generates messages with topic “time”. The
remaining fields define the parameters of the inject node, its location (x,y) and its
connection (wire) to other nodes. Note that “wires” simply name the nodes to which they are
connected (in more complicated cases they may define separate ports).
The second node structure defines a “debug” node with no output wires.
Never fear ! You won’t be writing JSON descriptions of flows, but it is helpful to know that they have a textual form.
node-red provides a large number of built-in node types in three basic categories – input nodes, output nodes, and processing nodes. For example http, tcp, and other data types are available for both input and output. In addition, there are many additional node types that can be added to the palette. The node-red application is a nodejs program and therefore, quite extensible. One class of add-ons that you will use in this lab provides a set of dashboard widgets.
A simple flow utilizing dashboard widgets is illustrated in the following figure. The node labeled ticker is an
“inject” node configured to output a timestamp every second. Each timestamp message triggers a random number generator that is configured to produce a number in the range 20.0 to 25.0.
The output from the random number generator in the previous figure is fed to both a gauge and a plot widget (notice that
broadcasting data is “free”). The resulting time series is illustrated in the following figure:
Thus, the dashboard provides a convenient way to view time-varying data.
1. Installing node-red
node-red should already be installed on the CS lab machines; however, if you wish to install a copy on your own machine
I include directions at the end of this document. I would not advise trying to run your flows from lab on different machines – I’m not at all certain that you won’t have problems with versions of node-red or its add-ons.
You can check to make sure every thing is installed with the following sequence of commands:
We will be using node-red in a slightly unconventional way. By default, node-red expects that each user
has a single, default, directory in which all information about flows is stored. Recently, a rather weak project
mechanism was added, but this isn’t really compatible with our use of git (it expects a unique git repo for each project).
Therefore, we will be creating a new project directory for each lab experiment. In your fork of the class repo,
there should be a structure like
lab-instructions
|
/labs
|
/node-red-template
For this lab,
$ cd your-repo/labs
$ cp -r ../lab-instructions/node-red-template lab3
$ cd lab3
$ execute `code .` and create a report.md file so you can capture screen shots and other information as you work through the lab.
Within your newly created lab3, you should find a script to start node-red
$ ./start-node-red
This will create a server – once the server is started, the final log messages will look something like
1 Nov 10:21:25 - [info] Starting flows
1 Nov 10:21:25 - [info] Started flows
1 Nov 10:21:25 - [info] Server now running at http://127.0.0.1:1880/
The last line indicates that the server is running. From a browser, you can access this as http://localhost:1880
You can kill the server by executing ctl-x in the terminal where it is running.
3. Exploring the node-red interface
Most of your work with node-red will be performed using the browser-based editor that you opend (http://localhost:1880)
In this section you should read through the editor documentation in
Begin by watching the short video. Then explore the three major sections
Workspace
Palette
Sidebar
As you read the documentation, try exploring the same thing in your open editor. This is a good time
to see what the various options/commands do. If you get into some weird state you can always kill the server.
Here are a few notes for things to explore
Workspace
An empty workspace has a single (blank) flow named “Flow 1”. By double-clicking the tab labeled “Flow 1”
you can change the flow name and provide a description for documentation. A drop-down menu provides
enables import and export of flows, “manage palette” which will enable the adding other node types, and
various tools for configuration.
Palette
The palette includes all the node types available in the current configuration – as part of this lab you will be adding some additional node types. For now, you should read the description of each node type by allowing the mouse to hover over the node in the palette. The most important nodes types for this class are:
Common
inject
debug
function
function
network
mqtt in
mqtt out
Try dragging one of them – for example the inject node into the workspace and “open” its configuration
by double-clicking. Notice that you can select from a variety of payload types, define the “topic” that the generated message will be associated with, define whether injection happens once or when repeated, and,
define an alternative name. In addition to the basic properties, there are other things you can configure for the node:
Sidebar
The sidebar has four “modes”; two are available through tabs, information i, and debug window 🐞. There is also a “pulldown” menu that provides access to a few other things – not important at the moment.
output – complete message object to – debug window
Once you have created the flow, you must “deploy” (upper right corner) before it can be used.
Select debug from the side window and note the messages
Export the complete flow to the clipboard and capture the result for your report. (Upper right menu->export).
You should try changing the configurations of both nodes – each time you do so, you will need to re-deploy the flow.
Finally, disable the debug node (click the right green rectangle)
5. Extending the Palette
In this section of the lab you will extend the palette with nodes to enable the creation of a dashboard.
In addition, you will create a simple random source to simulate a thermometer. Your dashboard will include
a graph to display the temperature trend, and a dial to display the current temperature.
Create a new flow (+ in upper right of workspace) and call it “Weather”.
Add three nodes connected as follows: inject -> function -> debug.
configure the inject node to emit a timestamp every second. Set its topic to “po181u/weather/temperature”
name the function node “Thermometer” and include the following (javascript) code for its function. This will generate a random number, with one decimal place, between 19 and 21 (degrees) every time it receives a timestamp (the timestamp will be overwritten by the random number).
Adding these components creates a new section in the palette
5. Add chart and gauge nodes to your flow – add wires from the “Thermometer” node to each of these.
* Configure the gauge node
- add a UI group (call it Temperature).
- You'll need to add a "tab" -- choose the "Home" default
- label the gauge "Centigrade" and set its range 0-50.
* Configure the chart
- Call it Temperature
- Set the y-axis range
Deploy
You should notice a new tab in the sidebar (info,debug,chart,..). Select that tab. Notice the following icon (square with arrow) that will take you to a browser window displaying your new dashboard.
The result of all this work is a dash displaying your (simulated) thermometer.
Even though the data are fake, the result should give you a good idea about what is feasible !
6. Connecting to a Real Weather Service
The final task of this lab is to create a flow and dash that collects data from a real weather service (open weather) and displays it.
Create a new flow (call it “Open Weather”)
Install node-red-node-openweathermap to your palette
Add an two sided node (port on the right)
Configure the API key you received when you registered.
Configure the coordinates of Claremont, CA (Latitude: 34.09985734, Longitude -117.713501)
Add an inject node (leave the configuration at the defaults) and wire it to the left port of the weather node.
Add a debug node and wire it to the right port of the weather node and deploy to test.
Click on the inject node and note the debug message. If all is well there will be a message with multiple fields (weather, tempk, tempc,…)
Create a function node wired to the weather node to extract the temperature component and add another debug node to check its output
1msg.payload=msg.payload.tempc
Add a new thermometer gauge and a new dashboard pane. When you are done things should look like:
Notice that the two dashboard panes are deployed. All of the flows you have created in this lab are running simultaneously.
You can change the inject node to issue periodic injections – but you must obey the open weather terms – checking their site every few minutes is all you are allowed. For now it’s best just to “click” on the inject node for an update.
Installing node-red at home
node-red should already be installed on the CS lab machines; however, you may wish to install a copy on your own machine. The official installation instructions for node-red are here. Note that there are two separate sets of installation instructions for windows/macintosh machines ! In the following, I summarize each of these. In either case, the pre-requisite for installation is to have installed Node.js and its package manager npm.
The following directions assume that you are using windows powershell. If you are uncomfortable using a command-line interface, you may want to seek out a powershell tutorial before proceeding.
