This is intended as a companion to our Node-RED tutorials and examples. In it we will define some of the terms and functionality we frequently use, and delve a little deeper into what some of the nodes are capable of. If we’ve used a term, or a node, in an article you would like more information on, let us know on our forum, we usually answer quickly, and I will get the answer added here so everyone else can benefit!
If you are currently using one of our packages, and have discovered an issue related to its functionality, posting it on github in the appropriate repository is the most helpful way to report it. If you need help building a flow, or planning a project, we also encourage you to post of the forum, our staff is happy to help, and we have some amazing community members who are always ready to share their expertise.
- Windows, Mac, or Linux machine (Including the Raspberry Pi and Beaglebone).
- Depending on which of our packages you are using, an available USB or I2C port.
- The ability to use a mouse and keyboard.
- Some NCD device(s) to play with!
If you are planning to use the native I2C capabilities of a Raspberry Pi or similar, you may need to enable the I2C Bus. The dependency we use for I2C communication has some information on their github page.
Serial Connection (USB)
Node-RED allows you to add packages through the UI, or through the more traditional use of NPM. To help keep the Node-RED library clean, we frequently release packages without adding them to the Node-RED library while we allow our community to try them out. Once we are satisfied that they are thoroughly documented and stable, they will be added to the Node-RED library which will enable installation through the UI. For simplicity sake we’re only going to explain how to install packages from the command line here.
To install a package on any platform you’ll need to navigate in the command line (Power shell for Windows users), to the Node-RED installation directory. This is usually ~/.node-red, but if you are unsure, you can start Node-RED (just type node-red) and you will see a line printed that looks something like this:
25 Mar 22:51:10 - [info] User Directory : /home/nol/.node-red
This is the location of Node-RED on your machine, once you’ve navigated to it you can install any available package with the
npm install command, i.e.
npm install node-red-dashboard
All of the NCD packages are prefixed with
ncd-red-. You can browse a list of our current packages here.
Wireless Enterprise Line
NCD I2C Products
Due to the widely varying line of chipsets and sensors used in our I2C products, the packages for these devices are separated into the corresponding sensor or chipset. All of these packages rely on our underlying communication package ncd-red-comm, which will be automatically installed with any package that requires it, provided you are using the LTS release of NodeJS. You can find a list of available I2C libraries here, and install them in the same way as any other package.
npm install ncd-red-mcp23008
For most users, you can launch Node-RED by simply typing
node-red in the command line. For advanced setups, or autostart information, check out the Node-RED docs.
When Node-RED starts, you will see a line in the output that reads something like:
25 Mar 22:51:10 - [info] Server now running at http://127.0.0.1:1880/
This line tells you that Node-RED is currently running locally on port 1880. You can access the front end at http://localhost:1880. If you require password protection, check out the Node-RED security page.
While we try to explain what these are when we use them in our articles, sometimes it’s easier to have a complete list for browse.
These terms are commonly used in Node-RED, and our documentation. It is best to have at least a basic understanding of the principles behind them when building any Node-RED project.
In the scope of this article, a package is defined as a modular piece of software for use with NodeJS. Packages may have dependencies on other packages, and those dependencies are managed through NPM.
An API, or Application Programming Interface, is easily described as a library of functionality that allows external software to interact with an application. APIs are how we communicate between software like Node-RED and hardware like a serial, or I2C port. APIs are also a large part of the cloud, providing authentication protocols and endpoints to third party services like MS Azure.
Front End (UI)
The front end of Node-RED, often referred to as the “Flow Builder”, is the UI that allows you to build, edit, and deploy your flows. This is where most of your time will be spent.
A flow can easily be thought of as the code running when you click the “deploy” button. It is comprised of Nodes and Wires that interact with Message objects. Individual flows can be accessed through the tabs at the top of the workspace, they can be renamed or deleted by double clicking on the tab, and new flows can be added with the + icon on the top right of the workspace.
A node is a graphical element that represents a piece of functionality in Node-RED, there are several types of node which are grouped by the functionality they provide.
Node-RED comes standard with a large variety of nodes, this section may be incomplete, as we will focus on the nodes that are primarily used in our tutorials. We will work on fleshing out this section with more descriptions as we use them. Most of these descriptions will be brief, more detailed information about any node can be found on its info tab.
Input nodes are what start the flow working, they output a message object which is then sent over any wires attached to their output.
Function nodes alter the message as it passes through them, they can change, add, or remove properties from the message object, as well a control timing or spawn additional messages.
This node allows you to either delay each message that passes through it, or rate limit messages.
The split node allows you to split a single payload into multiple messages based on the type of payload, and some user configurable options.
The switch node offers basic logic functionality, it can be used as a simple
if check, or can be used to route messages to different outputs based on specific rules that they match.
The template node allows you set a property based on a provided template.
These nodes are used to interact with third party social platforms and services
This node connects to an SMTP server to send emails containing the
Nodes in the NCD category are used to provide access to a variety of NCD products. We are constantly working to extent this offering, you can see our full catalog here.
The Wireless Gateway node sends out a message anytime that sensor data is received from any of our Wireless Enterprise Line of sensors. It also allows you to toggle between network IDs, giving you the ability to quickly switch your router from the “listening” network to the “config” network right on your flow.
The Wireless Device node filters incoming sensor data by the sensor type, and optionally the sensors MAC address. It also allows you to configure the sensor by presetting the configuration options, which will be flashed to the sensor next time the connected router determines it has entered config mode.
Dashboard nodes are provided by the node-red-dashboard package, this package supplies a dynamic UI for viewing and interacting with elements of your flow. You can read more about this package on its github page.
This node adds a gauge to the dashboard for displaying a numeric range of data. You can configure the label, the minimum and maximum range, and the colors of the gauge.
msg.payload as a popup or dialog message with “ok” and “close” buttons.
This node adds a slider to the dashboard which the user can interface with to send data to the flow, the value of the slider can also be controlled via a message sent to it.
The switch node adds a toggle switch to the dashboard, the output value for payload is configurable based on the new state of the switch after it is clicked.