Getting started with ThingsBoard IoT Gateway

Let’s add an MQTT connector, which will subscribe to some data topics using the demo broker with a built-in data generator and send data to the gateway.

Setup demo MQTT broker

As a demo MQTT broker, we will use docker image, that can be installed and run using the following command:

1
docker run -it -p 1884:1884 thingsboard/tb-gw-mqtt-broker:latest

After running docker image, you can see the following logs in your terminal:

Setup connector

MQTT connector will establish a connection to a broker named “Demo Broker” at “host.docker.internal” on port 1884, using an anonymous security type. It will include a data mapping for the “data/” topic, specifying a JSON converter and defining attribute and time series mappings for device data. Additionally, it will handle connect and disconnect requests for sensors with expressions to extract device names from topic filters.

To create a connector, follow these steps:

• Click on “Connectors configuration” button on the right panel;

• Click the “+ Add connector” button;

• Choose “MQTT” connector type from the dropdown, fill in “Name” field, choose “Logging level” to INFO, disable “Fill configuration with default values” field and click on “Add” button;

• Connector created.

First, we need to configure the connection to the demo broker. Let’s start from the “Connection to broker” section. This section offers detailed connection configuration options and contains several important fields, including host, port, MQTT version, client ID, and security settings. The host field specifies the address of the broker, while the port field indicates the communication port. The MQTT version field ensures compatibility with the protocol version being used. The client ID uniquely identifies the client, and the security settings provides configuration for client authorization at MQTT Broker.

Fill in the following fields with values:

Now, we are ready to move to the “Data mapping” section. This configuration section contains an array of topics that the gateway will subscribe to after connecting to the broker, along with settings about processing incoming messages (converter).

Let’s configure data map using the following steps:

• Click on “Add mapping” button
• In the opened window, fill in the “Topic filter” field with “data/”, select the “QoS” field to “0 - At most once”, and select the “Payload type” to JSON.

• Scroll down to “Data conversion” section:
  • For “Device” subsection use the following options/values:
    • In the “Name” row, select “Constant” in the “Source” dropdown field, fill in the “Value / Expression” field with the “Device Demo” value.
    • In the “Profile name” row, select “Constant” in the “Source” dropdown field, fill in the “Value / Expression” field with the “default” value.

• Click on pencil icon opposite to “Attributes” subsection and use the following options/values in the opened window:
  • Click on “Add attribute” button and fill in “Key” field with “frequency” value, select “Integer” option in “Type” field and fill in “Value” field with “${frequency}” value.
  • Click on “Add attribute” button and fill in “Key” field with “power” value, select “Integer” option in “Type” field and fill in “Value” field with “${power}” value.
  • Click on “Apply” button.

• Click on pencil icon opposite to “Time series” subsection and use the following options/values in the opened window:
  • Click on “Add time series” button and fill in “Key” field with “temperature” value, select “Integer” option in “Type” field and fill in “Value” field with “${temperature}” value.
  • Click on “Add time series” button and fill in “Key” field with “humidity” value, select “Integer” option in “Type” field and fill in “Value” field with “${humidity}” value.
  • Click on “Apply” button.
• Click “Add” button. Data mapping added.

“Requests mapping” section of the configuration outlines an array that includes all the supported requests for both the gateway and ThingsBoard:

• connect requests;
• disconnect requests;
• attribute requests;
• attribute updates;
• RPC commands.

But for now, we need only connect and disconnect requests. Let’s configure requests map using the following steps:

• Click on “Add mapping” button;
• In the opened window, select “Connect request” in the “Request type” dropdown field, fill in “Topic filter” with “sensor/connect” value. For “Device” subsection use the following options/values:
  • In the “Name” row, select “Extract from message” in the “Source” dropdown field, fill in the “Value / Expression” field with the “${SerialNumber}” value.
  • In the “Profile name” row, select “Constant” in the “Source” dropdown field, fill in the “Value / Expression” field with the “default” value.
• Click on “Add” button.

Now, let’s add another connect request using the following steps:

• Click on “+” button;
• In the opened window, select “Connect request” in the “Request type” dropdown field, fill in “Topic filter” with “sensor/+/connect” value. For “Device” subsection use the following options/values:
  • In the “Name” row, select “Extract from topic” in the “Source” dropdown field, fill in the “Value / Expression” field with the “(?<=sensor\/)(.*?)(?=\/connect)” value.
  • In the “Profile name” row, select “Constant” in the “Source” dropdown field, fill in the “Value / Expression” field with the “default” value.
• Click on “Add” button.

And finally, let’s add disconnect requests. For this purpose, follow the steps below:

• Click on “+” button;
• In the opened window, select “Disconnect request” in the “Request type” dropdown field, fill in “Topic filter” with “sensor/disconnect” value. For “Device” subsection use the following options/values:
  • In the “Name” row, select “Extract from message” in the “Source” dropdown field, fill in the “Value / Expression” field with the “${SerialNumber}” value.
• Click on “Add” button.

Now, let’s add another disconnect request using the following steps:

• Click on “+” button;
• In the opened window, select “Disconnect request” in the “Request type” dropdown field, fill in “Topic filter” with “sensor/+/disconnect” value. For “Device” subsection use the following options/values:
  • In the “Name” row, select “Extract from topic” in the “Source” dropdown field, fill in the “Value / Expression” field with the “(?<=sensor\/)(.*?)(?=\/disconnect)” value.
• Click on “Add” button.

• Click on “Save” button.

Following the steps outlined, your gateway will receive and apply the new configuration. It will then synchronize its state with the remote server. You can view the synchronization status of the connector configuration in the “Configuration” column, which will indicate whether the gateway is successfully aligned with the remote settings.

Also, you can see the connector logs to make sure that the connector works, for this purpose, follow these steps:

• Click on logs icon to open connector logs page;

• You can see the “Logs” table that consists of “Created time”, “Status” and “Message” columns.

For now, the gateway is ready to process data through the newly created and configured MQTT connector.

Let’s publish data to the MQTT Broker defined in the configuration above, you can follow these steps using a tool like mosquitto_pub or an MQTT client library in your preferred programming language. In this example, we’ll use the mosquitto_pub command-line tool.

1.Ensure that the Mosquitto MQTT clients are installed on your system. Typically, you can install them using the package manager of your operating system:

• For Ubuntu:

  1
  sudo apt-get install mosquitto-clients
  

• For Windows:

  Download the Mosquitto client tools from the official website.

  Install the tools, ensuring that the installation directory is added to the system’s PATH.

• For MacOS:

  1
  brew install mosquitto
  

2.Use the mosquitto_pub command to publish data to a specific MQTT topic. In this case, we’ll use the “data/” topic as defined in the configuration:

1
mosquitto_pub -h localhost -p 1884 -t data/ -m '{"frequency": 50, "power": 100, "temperature": 25, "humidity": 60}'

Where:

• -h - specifies the MQTT broker’s host address;
• -p - specifies the MQTT broker’s port;
• -t - specifies the MQTT topic to publish to (“data/” in our case);
• -m - specifies the payload or message to publish. It should be in JSON format, following the structure defined in the mapping section of your configuration.

Adjust the payload values as needed.

Let’s add a Modbus connector, which will read some data from the demo slave to the created gateway.

Setup demo server

As a demo simulation slave, we will use docker image, that can be installed and run using the following command:

1
docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest

After running docker image, you can see the following logs in your terminal:

Setup connector

This Modbus connector configuration sets up a master to communicate with a slave device located at “host.docker.internal” on port 5021 using TCP. The configuration includes specifications for data retrieval such as byte and word order, timeout, and polling period. The slave device, named “Demo Device” is configured to handle Modbus function code 4 requests. Attribute and time series mappings are defined for parameters like frequency, power, humidity, and temperature. Additionally, settings for connection attempts, retries, and wait times after failed attempts are provided.

To create a connector, follow these steps:

• Click on “Connectors configuration” button on the right panel;

• Click the “+ Add connector” button;

• Choose “MODBUS” connector type from the dropdown, fill in “Name” field, choose “Logging level” to “INFO”, turn off the “Fill configuration with default values” option and click on “Add” button;

• Connector created.

First, we need to add new slave and configure the connection to it. Let’s start from the “Master Connections” tab. This section offers slave adding and detailed connection configuration options that contains several important fields, including connection type, host, port, unit ID, method, and other.

• Go to the “Master Connections” tab, and click “Add Slave” button;
• Fill in fields with the following values:

Now, we are ready to move to the “Attributes” section. The configuration in this unit provides settings for processing data on Modbus server. These settings will be interpreted in the ThingsBoard platform instance as attributes of the device.

Let's configure attribute section using the following steps:

• Click on “pencil” icon in the “Attributes” section;
• In the opened window, click on “Add attribute” button;
• Fill in the fields:
  • Fill the “Key” field with “frequency”;
  • Select the “Type” field to “8int”;
  • Select the “Function code” to “04 - Read Input Registers”;
  • Set “Objects count” to “1”;
  • Set “Address” field to “4”.

Let's add another attribute. Collapse the recently added “frequency” attribute, click the “Add attribute” button, and fill in the fields with the following values, using the same process as before:

Click the “Apply” button after you've completed the “Attributes” section configuration.

We finish with the “Attributes” section, so let's move to the “Time series” section. The configuration in this unit provides settings for processing data on Modbus server. These settings will be interpreted in ThingsBoard platform instance as time series of the device.

Let's configure time series section using the following steps:

• Click on “pencil” icon on “Time series” section.
• In the opened window, click on “Add time series” button;
• Fill in the fields:
  • Fill the “Key” field with “humidity”;
  • Select the “Type” field to “8uint”;
  • Select the “Function code” to “04 - Read Input Registers”;
  • Set “Objects count” to “1”;
  • Set “Address” field to “4”.

Let's add another time series. Collapse the recently added “humidity” time series, click the “Add time series” button, and fill in the fields with the following values, using the same process as before:

The final view of your configured connector will look like on the following image. Click the “Add” button after you've completed the configuration.

Finally, save the Modbus configuration by clicking the “Save” button.

Following the steps outlined, your gateway will receive and apply the new configuration. It will then synchronize its state with the remote server. You can view the synchronization status of the connector configuration in the “Configuration” column, which will indicate whether the gateway is successfully aligned with the remote settings.

Also, you can see the connector logs to make sure that the connector works, for this purpose, follow these steps:

• Click on “logs” icon to open connector logs page;

• You can see the “Logs” table that consists of “Created time”, “Status” and “Message” columns.

For now, the gateway is ready to process data through the newly created and configured Modbus connector.

Let’s add an OPC-UA connector, which will read some data from the demo server to the created gateway.

Setup demo server

As a demo simulation server, we will use docker image, that can be installed and run using the following command:

1
docker run -it -p 4840:4840 thingsboard/tb-gw-opcua-server:latest

After running docker image, you can see the following logs in your terminal:

Setup connector

This OPC-UA connector configuration establishes a connection to a server named “OPC-UA Demo Server” at “opc.tcp://host.docker.internal:4840/freeopcua/server/”. The configuration specifies various settings, including timeouts, scan periods, and security mechanisms such as “Basic128Rsa15” with anonymous identity.

The mapping section defines how OPC-UA nodes are mapped to devices and their attributes and time series. In this case, a device with the name “Demo Device” and type “default” is mapped to nodes under “Root.Objects.MyObject”. Attributes such as frequency and power, as well as time series like temperature and humidity, are mapped to specific paths in the OPC-UA server. Additionally, the configuration supports RPC methods and attribute updates.

To create a connector, follow these steps:

• Click on “Connectors configuration” button on the right panel;

• Click the “+ Add connector” button;

• Choose “OPCUA” connector type from the dropdown, fill in “Name” field, choose “Logging level” to “INFO”, turn off the “Fill configuration with default values” option and click on “Add” button;

• Connector created.

First, we need to configure the connection to the demo OPC-UA server. Let’s start from the “Server” tab. This section offers detailed connection configuration options and contains several important fields, including server endpoint url, security settings, scan period, poll period, subscriptions settings and other.

• Go to the “Server” tab, and fill in the fields with following values:

Now, we are ready to move to the “Data mapping” section. This configuration section contains list of nodes that the gateway will subscribe to after connecting to the OPC-UA server, along with settings for processing data from these nodes.

Let's add new node using the following steps:

• Go to the “Data mapping” tab, and click on “Add mapping” button.
• In the opened window, fill in the “Device node” with “Path” type and “Root.Objects.MyObject” value;
• For “Device” subsection use the following options/values:
  • The “Name” row: select “Constant” in the “Source” dropdown field, fill in the “Value / Expression” field with the “Device Demo” value;
  • The “Profile name” row: select “Constant” in the “Source” dropdown field, fill in the “Value / Expression” field with the “default” value.

Let's move to “Attributes” section to add “frequency” and “power” attributes. The configuration in this unit provides settings for processing data from OPC-UA server. These settings will be interpreted in ThingsBoard platform instance as attributes of the device. Also we will use path for finding corresponding node.

A Path type refers to the hierarchical address within the OPC-UA server’s namespace. It is used to navigate to specific nodes in the server. The path for the attribute/time series value can be absolute or relative (relative in our case).

Let's configure attribute section using the following steps:

• Click on the “pencil” icon in the “Attributes” section;
• In the opened window, click on the “Add attribute” button;
• Fill in the “Key” field with the “frequency”, select the “Type” field to the “Path”, and fill in the “Value” with the “${Frequency}”.

Let's add another attribute. Collapse the recently added “frequency” attribute, click the “Add attribute” button, and fill in the fields with the following values, using the same process as before:

Click the “Apply” button after you've completed the configuration.

We finish with the “Attributes” section, so let's move to the “Time series” section. The configuration in this unit provides settings for processing data from the OPC-UA server. These settings will be interpreted in ThingsBoard platform instance as time series of the device.

Let's configure time series section using the following steps:

• Click on the “pencil” icon in the “Time series” section;
• In the opened window, click on the “Add time series” button;
• Fill in the fields:
  • Fill in the “Key” field with the “temperature”;
  • Select the “Type” field to the “Path”;
  • Fill in the “Value” with “${Temperature}”.

Let's add another attribute. Collapse the recently added “temperature” time series, click the “Add time series” button, and fill in the fields with the following values, using the same process as before:

The final view of your configured connector will look like on the following image. Click the “Add” button after you've completed the configuration.

Finally, save the OPC-UA configuration by clicking the “Save” button.

Following the steps outlined, your gateway will receive and apply the new configuration. It will then synchronize its state with the remote server. You can view the synchronization status of the connector configuration in the “Configuration” column, which will indicate whether the gateway is successfully aligned with the remote settings.

Also, you can see the connector logs to make sure that the connector works, for this purpose, follow these steps:

• Click on logs icon to open connector logs page;

• You can see the “Logs” table that consists of “Created time”, “Status” and “Message” columns.

For now, the gateway is ready to process data through the newly created and configured OPC-UA connector.