Chapter 3: Understanding Node-RED Characteristics by Creating Basic Flows

In this chapter, we'll actually create a flow using Node-RED Flow Editor. By creating a simple flow, you will understand how to use the tool and its characteristics. For a better understanding, we will create some sample flows.

From now on, you will create applications called flows using Node-RED. In this chapter, you will learn how to use Node-RED and how to create an application as a flow. To do this, we will cover the following topics:

• Node-RED Flow Editor mechanisms
• Using the Flow Editor
• Making a flow for a data handling application
• Making a flow for a web application
• Importing and exporting a flow definition

By the end of this chapter, you will have mastered how to use Node-RED Flow Editor and know how to build a simple application with it.

Technical requirements

To complete this chapter, you will need the following:

• Node-RED (v1.1.0 or above).
• The code for this chapter can be found in Chapter03 folder at https://github.com/PacktPublishing/-Practical-Node-RED-Programming.

Node-RED Flow Editor mechanisms

As you learned in the previous chapters, Node-RED has two logical parts: a development environment called the Flow Editor and an execution environment for executing the application that's been created there. These are called the runtime and the editor, respectively. Let's take a look at them in more detail:

• Runtime: This includes a Node.js application runtime. It is responsible for running the deployed flows.
• Editor: This is a web application where the user can edit their flows.

The main installable package includes both components, with a web server to provide Flow Editor as well as a REST Admin API for administering the runtime. Internally, these components can be installed separately and embedded into existing Node.js applications, as shown in the following diagram:

Figure 3.1 – Node-RED overview

Now that you understand the mechanisms of Node-RED, let's immediately learn how to use the Flow Editor.

Using the Flow Editor

Let's take a look at the main functions of the Flow Editor.

The main features of the Flow Editor are as follows:

• Node: The main building block of Node-RED applications, they represent well-defined pieces of functionality.
• Flow: A series of nodes wired together that represent the series of steps messages pass through within an application.
• The panel on the left is the palette: A collection of nodes that are available within the editor that you can use to build your application.
• Deploy button: Press this button to deploy your apps once you've edited them.
• Sidebar: A panel for displaying various functions, such as processing parameter settings, specifications, and debugger display.
• Sidebar tabs: Settings for each node, standard output, change management, and so on.
• Main menu: Flow deletion, definition import/export, project management, and so on.

These functions are arranged on the screen of the Flow Editor like so:

Figure 3.2 – Node-RED Flow Editor

You need to understand what is contained in the Flow menu before you start using Node-RED. Its contents may differ, depending on the version of Node-RED you're using, but it has some setting items such as Project management of flow, Arrange view, Import / export of flow, Installation of node published in library, and so on that are universal. For more information on how to use Node-RED, it's a good idea to refer to the official documentation as needed.

Important note

Node-RED User Guide: https://nodered.org/docs/user-guide/.

The following diagram shows all these Flow Editor menu options inside Node-RED:

Figure 3.3 – Node-RED Flow Editor menu

With that, you are ready to use Node-RED to build an application. So, let's get started!

First of all, you need to run Node-RED in your environment. Please refer to Chapter 2, Setting Up the Development Environment, to learn how to set it up with your environment, such as Windows, Mac, or Raspberry Pi, if you haven't done so already.

With Node-RED running, let's move on to the next section, where we'll be making our first flow.

Making a flow for a data handling application

In this section, you will create a working application (called a flow in Node-RED). Whether it is the internet of things (IoT) or server processing as a web application, the basic operation that Node-RED performs is sequentially transferring data.

Here, we'll create a flow where JSON data is generated in a pseudo manner, and the data is finally output to standard output via some nodes on Node-RED.

There are many nodes on the left-hand side of the palette. Please pay attention to the common categories here. You should be able to easily find the inject node, as shown in the following screenshot:

Figure 3.4 – Inject node

This node can inject a message into the next node. Let's get started:

1. Drag and drop it onto the palette of Flow 1 (the default flow tab).

   You will see that the node is labeled with the word timestamp. This is because its default message payload is a timestamp value. We can change the data type, so let's change it to a JSON type.

2. Double-click the node and change its settings when the Properties panel of the node is opened:
   

   Figure 3.5 – Edit inject node Properties panel

3. Click the drop-down menu of the first parameter and select {}JSON. You can edit the JSON data by clicking the […] button on the right-hand side.
4. Click the […] button, and the JSON editor will open. You can make JSON data with a text-based editor or a visual editor.
5. This time, let's make JSON data with an item called {"name" : "Taiji"}. You should replace my name with your name:
   

   Figure 3.6 – JSON editor

   Great – you have successfully made some sample JSON data!

6. Click the Done button and close this panel.
7. Similarly, place a Debug node on the palette.
8. After placing it, wire the Inject and Debug nodes to it.

   Once you execute this flow, the JSON data that was passed from the Inject node will be output to the debug console (standard output) by the Debug node. You don't need to configure anything on the Debug node:

   

   Figure 3.7 – Placing the Debug node and wiring it

9. Finally, you need to deploy the flow you created. In Node-RED Flow Editor, we can deploy all our flows on the workspace to the Node-RED runtime by clicking the Deploy button in the top-right corner.
10. Before running the flow, you should select the Debug tab from the node menu's side panel to enable the debug console, as shown in the following screenshot:
    

    Figure 3.8 – Enabling the debug console

11. Let's run this flow. Click the switch of the Inject node to see the result of executing the flow on the debug console:

Figure 3.9 – Executing the flow and checking the result

This is a very simple and easy data handling flow sample. In the latter half of this book, we will also experiment with data handling by actually connecting IoT devices and passing data obtained from a web API. In this section, it is enough that you understand how to handle data in Node-RED. Next, we're going to experiment with making a flow for a web application.

Making a flow for a web application

In this section, you will create a new flow for a web application. We'll create this flow in the same way we created the previous data handling flow.

You can create it in the workspace of the same flow (Flow 1), but to make things clear and simple, let's create a new workspace for the flow by following these steps:

1. Select Flows | Add from the Flow menu. Flow 2 will be added to the right-hand side of Flow 1. These flow names, such as "Flow 1" and "Flow 2," are default names that are provided upon creation. You can rename the flow so that it has a more specific name if you want to:
   

   Figure 3.10 – Adding a new flow

2. Select the http in node from the network category on the palette, and then drag and drop it onto the palette of Flow 2 (the new flow tab you just added):
   

   Figure 3.11 – An http in node

3. Double-click the node to open its Edit dialog.
4. Enter the URL (path) of the web application you will create.

   This path will be used as part of the URL for the web application you will be creating, under the Node-RED URL. In this case, if your Node-RED URL is http://localhost:1880/, your web application URL will be http://localhost:1880/web. An example of this can be seen in the following screenshot:

   

   Figure 3.12 – Setting the path of the URL

5. To send a request via HTTP, an HTTP response is required. So, place an http response node on the workspace of your Node-RED.

   You can find this node in the network category of the palette, next to the http in node. Here, the http response node simply returns the response, so you don't need to open the configuration panel. You can leave it as-is. If you want to include a status code in the response message, you can do so from the settings panel, as shown in the following screenshot:

   

   Figure 3.13 – An http response node

6. After placing an http response node on the palette, add a wire from the http in node to the http response node.

   This completes the flow for the web application, since we've allowed an HTTP request and response. You will see a light blue dot in the top-right corner of each node, which indicates that they haven't been deployed yet – so please make sure you click the Deploy button:

   

   Figure 3.14 – Wired nodes

7. Once it's been successfully deployed, open a new tab in your browser.
8. Then, access the URL of the web application shown in the http in node section by entering http://localhost:1880/web.

You should find that only {} is displayed on your screen. This is not a mistake. It is a result of sending an HTTP request and returning a response to it. Right now, since we have not set the content to be passed to the response, an empty JSON is passed as message data. This looks as follows:

Figure 3.15 – Web application result

This isn't great, so let's create some content. Let's do something very simple and implement some simple HTML code. So, where should I code this? The answer is simple. Node-RED has a template node that allows you to specify the HTML code as-is as output. Let's use this:

1. Drag and drop a template node between the http in node and the http response node on the wire, so that the template node will be connected on it:
   

   Figure 3.16 – Placing a "template" node on the wire between our two existing nodes

2. Next, double-click the template node to open the settings panel. You can code on the Template area of the settings panel. This time, use the following sample HTML. The title is specified for the head. Let's attach a page heading to the body with the <h1> tag. Arrange the contents resembling the menu with the <h2> tag. The code will look like this:

   <html>

     <head>

       <title>Node-RED Web sample</title>

     </head>

     <body>

       <h1>Hello Node-RED!!</h1>

       <h2>Menu 1</h2>

       <p>It is Node-RED sample webpage.</p>

       <hr>

       <h2>Menu 2</h2>

       <p>It is Node-RED sample webpage.</p>

     </body>

   </html>

   Note

   You can also get this code from this book's GitHub repository at https://github.com/PacktPublishing/-Practical-Node-RED-Programming/tree/master/Chapter03.

3. Once you have finished editing the template node, click the Done button to close it.

   The following screenshot shows what your template node will look like as you edit it:

Figure 3.17 – Code in the Template area

With that, we have finished preparing the HTML to be shown on our page. Please make sure you click the Deploy button. Access the web page by going to http://localhost:1880/web once more. You should now see the following output:

Figure 3.18 – Web application result

At this point, you should understand how to make a web application on Node-RED. I imagine it has been nice and easy so far. Now that we have built up some momentum, let's continue learning. In the next section, we will import and export the flow definition that we have created.

Importing and exporting a flow definition

In this section, you will import and export the flow definition you have created. Usually, when developing, it is necessary to back up the source code and version control. You may also import source code created by others, or export your own source code and pass it on to others. Node-RED has a similar concept. In Node-RED, it is a normal practice to import and export the flow itself instead of importing or exporting the source code (for example, the template node described previously).

So, first, let's export the flow we have created so far. This is easy to do:

1. Simply select Export from the Edit dialog under the Main menu of the Node-RED Flow Editor.

   When the Export menu is displayed, you can only select the current flow or all your flows. You can also select raw JSON, without indentation, or formatted JSON, with indentation.

2. Here, select the current flow and select Formatted.
3. Now, you can select how to save the exported JSON data – Copy to clipboard or Download. Here, we'd want to download the JSON data, so click the Download button:
   

   Figure 3.19 – Export operation

   You will see a file called flows.json in the downloads location of your machine.

4. Open this file in a text editor so that you can check the contents of the JSON file.

With that, we have learned how to export.

Next, we need to import this definition (flows.json) into our Node-RED Flow Editor. Do this by following these steps:

1. Simply select Import from the Flow menu in the Node-RED Flow Editor.

   When the Import menu is displayed, you can select Paste flow json or Select a file based import. You can also select a current flow or a new flow from the flow tab. If you select new flow, a new flow tab will be added automatically.

2. Here, please choose Select a file based import and import to new flow. Then, pick the JSON file called flows.json you exported to your local machine.
3. Once the file has loaded, click the Import button:
   

   Figure 3.20 – Import operation

4. You now have the new tab, named Flow 2, next to the same flow on the old Flow 2 tab. It has been imported completely, but it hasn't been deployed yet, so click the Deploy button, as follows:
   

   Figure 3.21 – Adding the new flow

   With that, we've successfully prepared what will be shown on our web page using the flow we imported. Please make sure you click Deploy button.

5. Access the web page again by going to http://localhost:1880/web.

Here, you will see that this web page has the same design as the web page you exported. Great work!

Figure 3.22 – Result of the web application

Now, let's wrap this chapter up.

Summary

In this chapter, you learned how to use Node-RED Flow Editor to make basic flows and import/export flows. Now that you know how to use Node-RED Flow Editor, you'll want to learn about more of its features. Of course, Node-RED doesn't only have basic nodes such as Inject, http, and template, but also more attractive nodes such as switch, change, mqtt, and dashboard. In the next chapter, we'll try to use several major nodes so that we can code JavaScript, catch errors, perform data switching, delay functions, use the CSV parser, and more.