How to connect NCD Vibration Temperature Sensor to ThingsBoard?

• Introduction
• Overview
• Requirements
• Configuring the NCD Vibration Sensor and Enterprise IIoT Gateway
  • Connect the sensor to the Gateway
  • NCD Vibration Sensor messages
  • RUN sensor_mode message
  • sensor_data message
• Configuring ThingsBoard Cloud
• Importing and configuring the NCD template flow
• Connect message
  • Attributes message
  • Telemetry message
• Checking connection to ThingsBoard Cloud
• Create a ThingsBoard Dashboard
• Summary

Introduction

Industrial IoT Wireless Vibration Temperature Sensor

This IIoT sensor is designed to monitor vibration, frequency, and temperature in industrial environments. It provides valuable data that can be used for predictive maintenance, equipment monitoring, and overall operational efficiency.

Some Vibration Plus Applications:

• Advanced Predictive Maintenance for Rotating Equipment
• Comprehensive Structural Health Monitoring
• Process Automation and Quality Control in Manufacturing
• Optimization of Energy Efficiency in Industrial Systems

In this tutorial, we will guide you through the process of setting up the NCD Industrial IoT Wireless Vibration and Temperature Sensor with the Enterprise IIoT Gateway.This includes creating a device, configuring parameters, transmitting sensor data to ThingsBoard via the MQTT protocol, and designing a real-time dashboard for sensor data monitoring and analysis.

Enterprise IIoT Gateway Lite

The Enterprise IIoT Gateway gets, processes, decodes, and transmits data from the NCD Industrial IoT sensor to various cloud services or Industrial protocols. You can think of it as a Wi-Fi router, but it uses a specialized wireless protocol called DigiMesh®. Both the NCD sensor and the Enterprise IIoT Gateway communicate using this protocol, which is specifically designed and tested for industrial applications.

Overview

The Industrial IoT Wireless Vibration and Temperature Sensor captures critical field parameters, including temperature and vibration data. Utilizing the robust DigiMesh® industrial protocol, the sensor transmits this data to the Enterprise IIoT Gateway. The gateway, equipped with the NCD Node-RED library, receives, decodes, and filters the data for further processing. Once prepared, the data is transmitted to the ThingsBoard platform via the MQTT protocol. Within ThingsBoard, the data can be queried, analyzed, and visualized in real-time through custom dashboards, providing actionable insights for monitoring and decision-making.

Requirements

To transmit data from NCD Industrial IoT sensors to ThingsBoard, certain prerequisites must be met.

• ThingsBoard Cloud account
• NCD Industrial IoT Wireless Vibration Temperature Sensor V3
• NCD Enterprise IIoT Gateway Standard or Lite version:
  • Enterprise IIoT Gateway
  • Enterprise IIoT Gateway Lite

Note: While the ThingsBoard Cloud is used in this example, ThingsBoard on-premise deployment can also be used.

Note: This tutorial can be replicated with any other NCD Industrial Sensor.

With these components, you can connect the NCD sensor to the Enterprise IIoT Gateway and leverage the built-in Node-RED instance to forward sensor data to ThingsBoard using the MQTT protocol.

This tutorial provides a comprehensive walkthrough of the essential configuration steps, including connecting NCD devices, registering them on the platform, setting up a ThingsBoard Cloud account, adding and linking a new gateway, and creating a dashboard to visualize real-time sensor data effectively.

Configuring the NCD Vibration Sensor and Enterprise IIoT Gateway

We’ll start by setting up the Enterprise IIoT Gateway and the Vibration Sensor, followed by connecting them. This process is straightforward, and we have a detailed guide available for reference. Below is a brief overview, but for complete instructions, please refer to the following NCD documentation:

• Industrial IoT Wireless Vibration Temperature Sensor V3 Quick Start Guide
  
• Industrial IoT Wireless Vibration Temperature Sensor V3 User Manual

Unbox your NCD Enterprise IIoT Gateway, connect it, and power it on following the provided instructions. Then, connect the ETH0 port to your DHCP-enabled router (the Gateway will act as a DHCP client). It will automatically obtain an IP address. After giving the device some time to boot, you should be able to access the Node-RED instance running on it by using its local IP address or domain name, appending port 1880 (the default Node-RED port).

We recommend using the local domain name format: ncd-xxxx.local:1880, where “xxxx” refers to the last four digits of the Enterprise IIoT Gateway’s MAC address (printed on the side of the device). For example, http://ncd-c398.local:1880

Connect the sensor to the Gateway

Upon accessing the Node-RED instance, you will notice a pre-configured flow that includes a Wireless Gateway node and a Debug node. These nodes form part of the default configuration, enabling the system to receive and display messages from connected devices.

This flow is preconfigured and ready to receive data from NCD sensors. When an NCD sensor connects to the wireless network and transmits data, the “Wireless Gateway” node automatically receives and processes the message. The processed message is then passed through its output terminal and sent to the “Debug” node. This node displays the message in the Debug window, located on the right side of the Node-RED editor. At this stage, everything is ready, and you can proceed to power on your NCD Vibration Sensor. NCD Industrial Sensors come pre-equipped with batteries and also support an external power supply option, which can be selected during the purchase process.

In this tutorial, we will focus on an example using a battery-powered sensor. However, the steps are equally applicable to sensors powered by an external supply. To activate the sensor, open its casing and toggle the power switch to the “Power by Internal Battery” position.

The power switch on this device has three positions:

• Battery Power
• Off
• External Power

The Battery Power position will use the onboard batteries to power the sensor and transmit data.

The Off position will power down all components of the sensor and no data will be transmitted

The External Power position will use the external power supply connected to the onboard barrel connector to power the sensor and transmit data.

NCD Vibration Sensor messages

Once the sensor is powered on, it begins transmitting data, and you will start seeing incoming messages. The “Wireless Gateway” node decodes the sensor data and forwards it through its output terminal to the “Debug” node. These messages are displayed in the debug window of the Node-RED editor. After activating the NCD Vibration Sensor, the Debug window should display messages similar to the following:

NCD sensors transmit a variety of messages that provide insight into the sensor's current mode and operational status, along with the actual sensor data. In this tutorial, we will focus specifically on the RUN sensor_mode and sensor_data message.

RUN sensor_mode message

A RUN message signifies that the sensor, identified by the msg.payload.mac property, is powered on and successfully communicating with the Enterprise IIoT Gateway via the wireless network. This message contains critical details, including the sensor's MAC Address, sensor type, node ID, mode, and timestamp.

sensor_data message

The sensor_data message includes critical information such as the firmware version, battery percentage, sensor type, data values, sensor name, MAC address, and other essential details.

The sensor_data message can be identified by the msg.topic property. When the sensor transmits a data message, the msg.topic is set to sensor_data which makes it easier to filter or manage the sensor data. To view the sensor data in the debug window, simply click on the message. You should see something like this.

In this tutorial, our primary focus will be on transmitting RUN sensor mode and sensor data messages to effectively monitor the sensor’s real-time status. We will explore these topics in greater detail later in the tutorial. For now, let’s move on to ThingsBoard to configure all the necessary components.

Configuring ThingsBoard Cloud

You can find the documentation to help you get started with ThingsBoard Professional Edition, as well as the MQTT Gateway API Reference, available here:

• Getting Started with ThingsBoard Professional Edition
• MQTT Gateway API Reference

The first step is to sign in using your ThingsBoard account.

Once you sign in, you will be presented with important resources to help you get started, along with solution templates. Take a moment to explore these to familiarize yourself with the ThingsBoard environment.

The first step is to add a new device to your ThingsBoard instance. To do this, follow thi steps:

• Go to the “Devices” page in the “Entities” section. In the next window, you will see a list of all your devices. We need to add a new one. Click the “+” icon in the upper right corner of the table. Then, from the dropdown menu, select “Add new device”.

• Once you do this, a new window will appear. You need to assign a name to the new device - in this case, we used “NCD Enterprise IIoT Gateway”. You can also specify a label, groups, description, and other parameters. Make sure to enable the “Is gateway” toggle. Next, click “Next: Credentials”.

• You will now be taken to the device credentials window. Select the “MQTT Basic” option (you can optionally add additional MQTT security layers here). Next, generate the Client ID, Username, and Password by clicking the “Generate” button next to each option. These credentials are required for configuring the Node-RED MQTT node to establish a connection with the Enterprise IIoT Gateway.

• After generating the credentials, use the “Copy” button to obtain each value. We recommend saving these values in a temporary file, as we will use them later in the Node-RED MQTT node in this guide. Next, click “Add”.

• After this, a new window will appear, allowing you to test the connectivity. However, since we are using a Gateway, a different set of MQTT topics is required for proper integration with the ThingsBoard gateway device. You can skip this step. For now, we will identify the MQTT server to use for the connection: “mqtt.thingsboard.cloud”. Click the “Close” button to proceed.

• We have successfully added a new Gateway configured to use the MQTT protocol. The next step is to configure the MQTT credentials in the Enterprise IIoT Gateway to verify connectivity.

Importing and configuring the NCD template flow

The next step is to import and configure a pre-configured flow template. This flow will allow us to filter and format the vibration sensor data before connecting it to the ThingsBoard MQTT broker server and publishing the sensor data. The flow will also set the appropriate topics based on the ThingsBoard MQTT Gateway API reference. To import the flow into your workspace, begin by navigating to the GitHub repository and copying or downloading the RAW JSON file: ncd-vibration-sensor-t80-to-thingsboard-mqtt.json

Internal note: This flow will be on NCD Github repository.

Next, in Node-RED, navigate to the main menu in the top right corner of the editor and click on the “Import” option:

To import the ncd-vibration-sensor-t80-to-thingsboard-mqtt.json file, simply open the window and either select the file using the “Select a file to import” button or paste the copied JSON code into the pink text box. Once done, click the “Import” button to proceed.

A pop-up message will appear at the top of the Node-RED editor, indicating the nodes that have been successfully imported into your workspace.

You can now position the flow within your Node-RED workspace. The next step is to connect the output of the “Wireless Gateway” node to the input of the “ncd-filter-mode” node, as demonstrated in the following image.

Next, we will provide a general overview of the function of each node in this flow. We will not go into a deep explanation of each node's function.

Note: If you want to learn more about how these nodes work, you can select a node within the Node-RED editor and click on the “Info” tab, where you can find documentation related to each node in Node-RED.

ncd-filter-mode: This node evaluates the incoming messages from the “Wireless Gateway” node. It specifically filters and directs messages based on their topic. Output 1 is dedicated to messages of topic sensor_mode, which contain the operational modes of the sensor. For this tutorial, we will focus on RUN mode, which indicates that the sensor is connected to the Enterprise IIoT Gateway network and ready to transmit data. Output 2 is for sensor_data messages, which include critical information such as battery percentage, vibration, temperature, and other sensor readings.

ncd-filter-by-run-mode: This node will evaluate whether the sensor is in RUN mode. If the sensor is not in RUN mode, the message will not flow through the node.

ncd-set-device: This node allows us to extract the MAC address of the sensor (by specifying the last 8 alphanumeric characters: 'xx:xx:xx:xx') and assign it as the msg.payload.device value.

Note: An example of an NCD device MAC address is: 00:13:A2:00:42:53:64:33. After processing through this node, the msg.payload.device property will contain the shortened MAC address: 42:53:64:33.

ncd-set-mqtt-topic-connect: This node sets the MQTT topic for ThingsBoard, which serves to inform the platform that the device is successfully connected to the Gateway.
msg.topic = 'v1/gateway/connect'

ncd-filter-by-type: NCD IoT manufactures a wide range of Industrial IoT Sensors, each identified by a sensor type. This node allows us to filter sensor messages based on the sensor type. In this case, it filters messages corresponding to the “One Channel Vibration Sensor”, which is identified by sensor type ‘80’.

ncd-attributes: This is a function node that uses JavaScript code to ensure that a sensor_data message of type 80 is sent only once after a deployment. The node allows us to define various sensor attributes, such as the address, sensor name, firmware version, node ID, and sensor type. These attributes are then wrapped in the correct format according to the ThingsBoard MQTT Gateway API. Below is the JavaScript code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// Retrieve the 'flag' from the context or default to false
const flag = context.get("flag") || false;

if (!flag) {
   // Destructure properties from msg.payload
   const {
       addr,
       sensor_name: sensorName,
       firmware,
       nodeId,
       sensor_type: sensorType
   } = msg.payload;

   // Extract the device from the address
   const device = addr.substring(12);

   msg.payload = {
       [device]: {
           "Sensor Name": sensorName,
           "Firmware": firmware,
           "Node ID": nodeId,
           "Sensor Type": sensorType
       }
   };

   // Set the 'flag' in the context to avoid re-execution
   context.set("flag", true);
   return msg;
}

ncd-set-mqtt-topic-attributes: This node sets the MQTT topic for ThingsBoard. The topic is used to update the sensor attributes on ThingsBoard.
msg.topic = 'v1/gateway/attributes'

ncd-add-battery-to-sensor-data: This node allows us to add the property containing the vibration sensor’s battery percentage to the msg.payload.sensor_data message, which already includes temperature and vibration variables. This way, we can have all the relevant variables in a single message for this tutorial.

ncd-telemetry: This is a function node. The JavaScript code extracts the Sensor MAC address and timestamp data from the msg.payload message. It then retrieves the sensor_data message (which includes battery percentage) and wraps it in the correct format for the ThingsBoard MQTT Gateway API. The JavaScript code is as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Destructure relevant properties from msg.payload
const { addr, received: timestamp } = msg.payload;

// Extract the device ID from the address
const device = addr.substring(12);

// Extract the data from the message
const sensor_data = msg.payload.sensor_data;

// Construct the payload in a clean and structured way
msg.payload = {
   [device]: [
       {
           ts: timestamp,
           values: sensor_data
       }
   ]
};

return msg;

ncd-set-mqtt-topic-telemetry: this node Set the MQTT ThingsBoard telemetry topic, this topic serves to set the sensor data values on telemetry ThingsBoard.
msg.topic = 'v1/gateway/telemetry'

ncd-to-thingsboard: This MQTT output node establishes a connection to the MQTT Broker using the required credentials to connect to ThingsBoard, allowing the data generated by the vibration sensor to be published to the ThingsBoard Cloud.

Once we’ve reviewed the general functions of each Node-RED node in the flow, the next step is to configure the MQTT out node with the credentials generated in ThingsBoard. To access the properties of this node, double-click on the “ncd-to-ThingsBoard” node. Once you’ve opened the properties, the first step is to configure the “mqtt-broker config node”. To do this, click the “Add new mqtt-broker config node” button.

The next step is to set the Server property with the ThingsBoard MQTT Broker server address: “mqtt.thingsboard.cloud”. For this example, we'll use the default port, 1883. Lastly, you need to configure the Client ID property, which is generated in ThingsBoard.

The next step is to navigate to the security tab and enter the Username and Password credentials generated in ThingsBoard.

Finally, to save the configurations made within the node, click the “Update” button.

Once this is completed, the MQTT server configuration is finalized. The Topic property should be left empty because it will dynamically receive its value from the msg properties configured in the preceding nodes. These nodes have already defined the appropriate topics for each type of MQTT message.

To save the changes made within the MQTT out node, click on the “Done” icon.

Once the MQTT credentials are configured, the next time the NCD vibration sensor transmits a message, it will be published to ThingsBoard via MQTT on the corresponding topic. To save and apply the changes made in your Node-RED application, click the “Deploy” button located at the top-right corner of the Node-RED editor.

Once you press the “Deploy” button, you will see the status “connecting” displayed just below the MQTT out node. This indicates that the system is attempting to establish a connection with the MQTT server.

Once the connection is successfully established, you should see the status change to “connected”, indicating that the Node-RED instance is now communicating with the MQTT server.

To test communication, you can manually trigger a data transmission from the NCD Vibration Sensor by pressing the “RESET” button inside the sensor. To access the button, remove the four screws from the white casing. Once inside, locate the RESET button and press it once.

Note: It is also possible to wait for the next transmission from the sensor to perform the test, without the need to press the RESET button, as the sensor sends data periodically at user-defined intervals.

Once a new message is transmitted by the sensor, you should be able to see some messages into the debug window that comes from the “debug thingsboard” node, you can identify this messages by the msg.topic property:

• v1/gateway/connect
• v1/gateway/attributes
• v1/gateway/telemetry

When you press the “RESET” button on the sensor, it first attempts to establish wireless network communication. Once the sensor successfully connects to the Enterprise IIoT Gateway network, it transmits a RUN message. Afterward, the sensor sends a sensor_data message. The flow then uses the information from the RUN and sensor_data messages to build the connect, attributes, and telemetry messages. Let's break down each of these messages in detail.

Connect message

This first message is generated when the Industrial IoT Wireless Vibration Temperature Sensor successfully establishes a connection with the Enterprise IIoT Gateway. The Wireless Gateway node receives the sensor_mode message, which contains the connection status of the sensor. The flow then uses a switch node to check if the message is a RUN message, indicating the sensor is successfully connected and operational. If the message is a RUN message, the flow extracts the MAC address of the sensor and formats the message according to the ThingsBoard API. This message is crucial as it informs ThingsBoard that the device is successfully connected to the Gateway, allowing the platform to recognize the sensor and begin receiving telemetry and attribute data for further analysis and visualization.

1
Topic: v1/gateway/connect

1
2
3
Message: {
    "device":"Device A"
}

Attributes message

To build this message, the flow uses the sensor_data message, which contains essential sensor data. It extracts key pieces of information such as the sensor name, firmware version, node ID, and sensor type. This data is then formatted according to the ThingsBoard attributes API, which requires the data to be in key-value pair format. The flow sends this message only once to ThingsBoard.

In ThingsBoard, device attributes are key-value pairs that are associated with a device. These attributes are used to store important information, such as configuration settings, metadata, and operational details, providing context for the device. By including the sensor’s attributes, ThingsBoard can store relevant information like the sensor’s name, its version, and other characteristics, which are crucial for monitoring and managing the device efficiently within the platform.

1
Topic: v1/gateway/attributes

1
2
3
4
5
6
7
8
9
10
Message:{
    "Device A":{
        "attribute1":"value1", 
        "attribute2": 42
    }, 
    "Device B":{
        "attribute1":"value1",
        "attribute2": 42
    }
}

Telemetry message

This message contains the real-time sensor data, which includes key readings such as temperature, vibration, and battery percentage. The flow formats this data and publishes it to ThingsBoard as telemetry data. Telemetry data in ThingsBoard is used for real-time monitoring and visualization, enabling users to track the sensor’s status and performance over time.

By sending this telemetry message, the sensor’s data is continuously updated on the ThingsBoard platform, where it can be displayed on dashboards for analysis, triggering alerts, or taking other actions based on the sensor's readings. This allows for effective monitoring and management of sensor networks in industrial IoT applications.

1
Topic: v1/gateway/attributes

1
2
3
4
5
6
7
8
9
10
11
Message: {
    "Device A": [
        {
            "ts": 1483228800000,
            "values": {
                "temperature": 42,
                "humidity": 80
            }
        },
    ]
}

Checking connection to ThingsBoard Cloud

Now, return to the ThingsBoard platform. You will notice that a new device has been automatically added, identified by its MAC address. Both the Enterprise IIoT Gateway and the Sensor device will show an Active state. The system will automatically update the device status based on the sensor's communication. You can click on the newly added device to explore its details, Attributes, Latest telemetry, Alarms, Events, Relations, Audit Logs, among others. By reviewing these sections, you can gain deeper insights into the device’s status and performance within the ThingsBoard platform.

You can click on the “Attributes” tab to view the newly added sensor attributes. These attributes are typically updated once and do not change every time the sensor transmits data. They represent static or infrequent details about the sensor, such as:

• Sensor Name: The name assigned to the sensor for easy identification.
• Firmware Version: The version of the firmware currently installed on the sensor.
• Node ID: A unique identifier for the sensor within the network.
• Sensor Type: The type of sensor.

You can also view the latest sensor telemetry under the “Latest telemetry” tab. This section displays the sensor’s real-time data, such as temperature, vibration, and battery percentage. These values are updated every time the sensor transmits data to the ThingsBoard platform. This telemetry data is of primary interest for monitoring the sensor’s performance and status. You can use this data to create alarms or build dashboards that visually represent the sensor’s real-time measurements. You should see something similar to this, displaying the updated values each time the sensor sends data.

Create a ThingsBoard Dashboard

The next step is to create a ThingsBoard Dashboard. The Dashboard in ThingsBoard allows users to visualize and monitor data collected from IoT devices. Let’s create a dashboard and add some widgets to display a list of entities and their latest NCD Sensor values. To create a new, empty dashboard, follow these steps:

• Navigate to the “Dashboards” page through the main menu on the left of the screen. By default, you navigate to the dashboard group “All”. Click the “+” sign in the upper right corner of the screen, and select “Create new dashboard” from the drop-down menu;

• In the opened dialog, it is necessary to enter a dashboard title, description is optional. Click “Add”;

• Click the “Add widget” button at the top of the screen or click the large “Add new widget” icon in the center of the screen (if this is your first widget on this dashboard);

• Find the “Digital gauges” widget bundle and click on it;

• Select the “Mini gauge” widget;

• You will need to specify the device this widget will be linked to. In the “Device” property, select the device we have created. In the “Data key” property, clicking “+Add” will display a list of variables emitted by the sensor. In this case, select the “Temperature” option.

• Within the properties, you can customize the unit of measurement, operation range, number of decimal places to be displayed, style, and many other settings. To add the widget to your dashboard, click the “Add” icon;

• To make the widget slightly larger, simply grab the bottom right corner and drag it.

Once this is done, you should see the gauge widget added to your dashboard, displaying the most recent value sent by the sensor, in this case, 23 degrees Celsius.

When you hover over the widget in ‘Edit’ mode, you will see buttons in the top-right corner of the widget. These buttons allow you to edit, download, or delete the widget, as well as adjust its position or size.

To add more widgets to the dashboard, follow this steps:

• Click the “Add widget” button again;

• In this case, we will add a second widget to display the sensor's battery percentage. Go to the “Status indicators” widget bundle;

• Select the “Battery level” widget;

• You will need to set the “Device” property again with the NCD device that we previously added. The next step is to set the “Data key” property. Click on the “Data key” field, and this will display the list of variables emitted by the NCD vibration sensor. From the list, select the property defined as “battery_percent”;

• We will adjust the layout by selecting the “Horizontal. Divided” option under the “Appearance” properties. ThingsBoard provides real-time visualization of available layout types for this widget, making it a valuable tool for fine-tuning this property. Click “Add”;

• Edit the size and position of the widget according to your needs. To save any changes made to your ThingsBoard dashboard, you should click the “Save” button located in the upper right corner.

This way, you can add as many widgets as you need to your dashboard. The steps for doing so are the same as shown earlier. Each widget can be customized and adjusted, including style, color, unit of measurement, icon, elements, distribution, size, and many other options. You can also link each widget to the variables emitted by the vibration sensor.

We have added several other widgets to our dashboard and linked each one to the vibration variables emitted by the sensor in the same way. The final layout of our dashboard looks as follows. You can view the dashboard in full screen by clicking the “Expand to fullscreen” button located at the top right.

Finally, our dashboard is displayed as follows:

Summary

This tutorial explained the basic, step-by-step process of integrating the NCD Industrial IoT Wireless Vibration and Temperature Sensor with ThingsBoard Cloud, enabling you to manage and visualize the vibration and temperature variables sent by the NCD sensor.

After successfully connecting the NCD Industrial IoT Wireless Vibration and Temperature Sensor to the ThingsBoard platform, you can expand its functionality by setting up thresholds and alarms for sensor data, enabling notifications via email, SMS, or web when thresholds are exceeded. You can manage users by adding them with specific roles and permissions, allowing customized access to devices and dashboards.