Documentation

Integrations / SDKs / Node-RED SDK

Node-RED SDK

Node-RED is an open-source visual programming tool for wiring together various protocols. A large range of community build nodes (i.e. plugins) are available for various protocols (including Modbus, OPC UA/DA, BACnet, CAN bus and M-Bus). We provide a set of Blockbax nodes to easily interact with our platform via Node-RED. Nodes can be deployed to its runtime with a single-click.

This built-in integration documentation starts with an explanation on how to use the Blockbax nodes for Node-RED. Next up, we will provide tutorials on how to use certain protocols in combination standard Node-RED nodes and the Blockbax nodes to speed up your integration work.

  1. Blockbax nodes
  2. Tutorial OPC-UA
  3. Tutorial Modbus

Blockbax nodes

This first part will tell you how to download Blockbax nodes for Node-RED so you can parse, aggregate and send data to the Blockbax Platform.

Installing Blockbax nodes

After you have installed Node-RED the Blockbax nodes can be easily installed using the palette manager. More information, e.g. about how to install manually, can be found in the library documentation. Here you see how to install the nodes:

Installing the Blockbax nodes with the palette manager
Nodes

There are a number of different nodes available. The first node can be used to parse measurement data to a common format which can be used by the other nodes. Once this is done, you can use nodes to aggregate the resulting measurements and the last node is to send this data to our platform.

Parse

The Parse node can take a msg from another node and create a new object that can be used by the other Blockbax nodes. You can configure what message properties represent the date, the value and the ingestion ID. There is also an option to generate a timestamp on input if the message has no timestamp property. The Parse node adds a series property to the message and sends it on input.

Here is how to setup a Parse node:

setting up parse node

The Parse node has four configurable properties, excluding the Name property.

  • Use Ingestion ID: Can be unchecked to use Subject External ID & Metric External ID.
  • Ingestion ID: Can either be a static Ingestion ID or a dynamic Ingestion ID by changing the type to msg.
  • Subject External ID: only when Use Ingestion ID is unchecked, Can either be a static or a dynamic by changing the type to msg.
  • Metric External ID: only when Use Ingestion ID is unchecked, Can either be a static or a dynamic by changing the type to msg.
  • Date: Can either be a msg property or it can be set to use the current date.
  • Value: Measurement value. Usually values are stored in the msg.payload property.
  • Data type: Data type. Choose either Number, Location or Text. Can be dynamically set by changing the type to msg.

When un-checking the Use Ingestion ID checkbox the Ingestion ID is replaced by two other properties: Subject External ID and Metric External ID. These two properties will together make a Ingestion ID in the form of <SUBJECT_EXTERNAL_ID>$<METRIC_EXTERNAL_ID>

  • Subject External ID: Can either be a static Subject External ID or a dynamic Subject External ID by changing the type to msg.
  • Metric External ID: Can either be a static Metric External ID or a dynamic Metric External ID by changing the type to msg.
Aggregate

The Aggregate node applies an aggregate function over a a specified time period. The available functions are:

Here is how to setup an Aggregate node.

setting up aggregate node

The Aggregate node has two configurable properties, excluding the Name property.

  • Function : Aggregation function to apply.
  • Period : Time period to aggregate over.
Send

The send node can either be used to batch and send measurements to the HTTP and MQTT endpoints or send data to a inbound connector. When used to send to an inbound connector messages are directly send to the inbound connector without batching. otherwise this node will sends batches of measurements upon a specified time interval. The minimal frequency at which data can be sent is 1 second. The available send options are:

  • HTTP: Recommended if irregular batches of data are being collected.
  • MQTT: Recommended if the incoming data is a frequent and regular stream of data points.

Here is how to setup a Send node.

setting up send node

The Send node has three configurable properties, excluding the Name property.

  • Project: Configuration of your project ID and access token information. You can also check the ‘Use environment variables’ checkbox to use the environment variables PROJECT_ID, ACCESS_TOKEN_PUBLIC_ID and ACCESS_TOKEN_SECRET instead.
  • Use Inbound Connector: Checked to false by default, check to send to a inbound connector.
  • Auto Create Subjects: Checked to false by default, check to auto create subjects.
  • Inbound Connector ID: Only when Use Inbound Connector is checked, set to the ID of the inbound connector.
  • Type: Type of connection used.
  • Batch Period: Only when Use Inbound Connector is unchecked, period for which measurements are batched before they are being send.

Tutorial OPC-UA

OPC-UA is a protocol commonly used in automation and other industrial settings. It’s often used in communication between PLCs, RTUs and SCADA systems. It’s a client/server protocol that has the capabilities to communicate with a publish/subscribe or request/response pattern. The standard OPC-UA Node-RED nodes make it possible to easily read and write data.

Goal

The goal of this tutorial is to show you how you can setup a OPC-UA client in Node-RED and connect the OPC-UA nodes to the Blockbax nodes and send data the Blockbax Platform.

Prerequisites

For this tutorial you will need:

  1. A Blockbax project
  2. Node-RED installed
  3. OPC-UA nodes installed within Node-RED
  4. Blockbax nodes installed within Node-RED

Do you want a example of the flow you are going to build? You can find it here.

Steps
  1. Make sure you are able to connect to the OPC-UA server and open Node-RED in a browser
  2. Create an inject node and check the “Inject once after x seconds” checkbox
    1. When you want to use the OPC UA Client with a READ action set the inject node to Repeat with a certain interval
    2. When you want to use the OPC UA Client with a READ action set a timestamp on the msg.date property because the client will not return data with a timestamp with this action
  3. To the inject node connect a OPC-UA item node and configure the node ID, corresponding data type and set the Name to the corresponding ingestion ID to later have it available in the msg.browseName property
  4. To the OPC-UA item node connect a OPC-UA Client node and configure the Endpoint, Action (READ or SUBSCRIBE) and Certificate
    1. When using the Client with a SUBSCRIBE action configure an Interval

You should have something looking like this:

OPC UA example so far
  1. Connect a parse node to the OPC-UA Client node and configure these specific settings:
    1. Configure the Ingestion ID to msg.browseName, this corresponse to the previously configured ingestion ID
    2. Leave the Value on msg.payload
    3. Leave the Value on msg.date When using the OPC-UA Client with a READ action or set to msg.sourceTimestamp When using the OPC-UA Client with a SUBSCRIBE action
  2. Optional: Connect a Blockbax aggregate node to the Parse node
  3. Connect the previous node to the Blockbax send node

Now your flow should look something like this:

Complete OPC UA flow

Great job! You can test the flow by opening Blockbax and see if the data is coming in.

OPC-UA pre-configured flow

We’ve created an example, so you have a pre-configured flow to double-check your own configuration. The example can be found here and you can easily import the example within your own Node-RED project. Go to the OPC-UA contribution page for more information about the nodes.

Here is a short video of an example of how Node-RED can be used to setup a OPC-UA client and connect incoming data to Blockbax.

setting up OPC-UA

Tutorial Modbus

Modbus is a very populair industrial protocol for reading and writing data. It’s often used to in communication between PLC’s, RTU’s and SCADA systems. There two types of Modbus protocols, serial Modbus protocols like Modbus RTU or Modbus ASCII and Modbus TCP/IP. The main difference between them is that Modbus RTU or Modbus ASCII is connected with a RS-232, RS-485 or other physical serial connection and Modbus TCP/IP uses Ethernet connections and communicates over a network. Modbus uses coils which can be read out or written to.

Goal

The goal of this tutorial is to show you how you can setup a Modbus RTU or TCP/IP client in Node-RED and connect the Modbus nodes to the Blockbax nodes and send data the Blockbax Platform.

Prerequisites

For this tutorial you will need:

  1. A Blockbax project
  2. Node-RED installed.
  3. Modbus nodes installed within Node-RED.
  4. Blockbax nodes installed within Node-RED.

Do you want a example of the flow you are going to build? You can find it here.

Steps
  1. Create a Modbus Read node
    1. Configure the Unit ID, Function (FC), Address, Quantity (count of register addresses) and Poll Rate
    2. Configure the Server which can either be your Modbus TCP/IP server or serial Modbus slave
Important to keep in mind:
  • A Unit ID can be configured within the Modbus Read and the server configuration node. The Unit ID inside the Modbus Read node overwrites the Unit ID from the Modbus server.
  • To better debug the Modbus Read node a Modbus Response node can be connected to the bottom connection on the Modbus Read node.

You should have something looking like this:

Modbus example so far

Parse data and send to Blockbax:

  1. Connect a Blockbax parse node to the uppter connection of the Modbus Read node and configure the specific settings:
    1. Set the Ingestion ID to the corresponding ingestion ID
    2. Set the Value to msg.payload[i], where i is the index of your data value
    3. Set date to “Generating Timestamp”
  2. Optional: Connect a Blockbax aggregate node to the parse node
  3. Connect the previous node to the Blockbax send node
Important to keep in mind:
  • The value returned from the Modbus Read node is an array inside the msg.payload property. the lenght of this array depends on the Quantity set in the Modbus Read node. The 'i' inside msg.payload[i] shows how to configure the parse node to access an index in this array
  • Data in Modbus can be split up in muliple registers and could be split up in multiple indexes inside the payload array. A function node can be used in between the Modbus Read node and parse node to further parse and combine multiple indexes.

Now your flow should look something like this:

Complete Modbus flow

Great job! You can test the flow by opening Blockbax and see if the data is coming in.

Modbus pre-configured flow

We’ve created an example, so you have a pre-configured flow to double-check your own configuration. The example can be found here and you can easily import the example within your own Node-RED project. Go to the Modbus contribution page for more information about the nodes.