Star

ThingsBoard Documentation

Documentation for using ThingsBoard IoT Platform.

Getting started with ThingsBoard IoT Gateway

This guide covers initial IoT Gateway installation and configuration. We will connect IoT Gateway to ThingsBoard server and visualize some basic gateway statistics: the amount of devices connected and messages processed. We will also configure MQTT and OPC-UA extension in order to subscribe to device data feed from external devices or applications.

Prerequisites

If you don’t have access to a running ThingsBoard instance, use either Live Demo or Installation Guide to fix this.

NOTE ThingsBoard version 1.1 or greater is required.

Step 1: Choose installation option

Browse available gateway installation options and choose the most suitable installation guide.

Step 2: Follow installation steps

Follow steps (1-3) in the chosen gateway installation guide. The Gateway configuration steps are covered below.

Step 3: Gateway provisioning

In order to connect your IoT gateway to ThingsBoard server, you need to provision gateway credentials first. We will use access token credentials as the most simple one. See device authentication options for more details.

Login as tenant administrator. Use default credentials in case of local ThingsBoard server. Open Devices and click on big red “+” button in the bottom right corner.

image

Populate your gateway name and select “Is gateway” checkbox.

image

NOTE: Gateway and device names should be unique in the scope of a tenant.

Open new device card and click on “Copy Access Token” button.

image

Step 4: Gateway configuration

Thingsboard Gateway supports per-tenant configuration. This means that each tenant can have own connectivity and extensions configuration.

Navigate to the gateway configuration folder and edit tb-gateway.yml file.

Windows: YOUR_INSTALL_DIR/conf
Linux: /etc/tb-gateway/conf

Change gateway.connection.host and gateway.connection.port properties to your ThingsBoard host (leave without modifications in case of live demo instance).

Change gateway.connection.security.accessToken property to your access token that was copied during step 3.

You gateway configuration should look similar to this file:


gateways:
  tenants:
    -
      label: "Tenant"
      reporting:
        interval: 60000
      persistence:
        type: file
        path: storage
        bufferSize: 1000
      connection:
        host: "${GATEWAY_HOST:YOUR_HOST}"
        port: 1883
        retryInterval: 3000
        maxInFlight: 1000
        security:
          accessToken: "${GATEWAY_ACCESS_TOKEN:YOUR_TOKEN}"    
      remoteConfiguration: true

server:
  address: "0.0.0.0"
  port: "9090"
  
updates:
enabled: "${UPDATES_ENABLED:true}"

remoteConfiguration property specifies whether this tenant’s extensions configuration should be managed remotely (through ThingsBoard GUI) or locally (through current configuration file)

Step 5. Launch your gateway

Follow steps (5-6) in the chosen installation guide.

Step 6. Review gateway statistics

Open the web UI of your ThingsBoard server and review statistics that is uploaded from your thingsboard gateway. Login as Tenant Administrator and open Devices page. Click on the gateway device card. Open “Latest Telemetry” tab and review following statistics: “devicesOnline”, “attributesUploaded” and “telemetryUploaded”. All values should be set to “0”.

image

The presence of those values on the UI means that your gateway has successfully connected to ThingsBoard server.

Step 7. Choose your extension

Based on your use case, you can choose following options:

or follow instruction for all steps.

Step 8. Connect to external MQTT broker

In this step, we will connect to the external MQTT broker in order to start collecting data from third-party or legacy applications and devices.

There are two options available:

Step 8.1 MQTT broker file configuration

Navigate to gateway configuration folder and edit tb-gateway.yml file. Configuration folder location:

Windows: YOUR_INSTALL_DIR/conf
Linux: /etc/tb-gateway/conf

Change mqtt.enabled property value to true.

We will use Mosquitto MQTT broker for the demonstration purposes. See Mosquitto downloads page for instructions how to install this broker.

NOTE: Mosquitto and ThingsBoard use the same port (1883) for MQTT service by default. If you want to use ThingsBoard and Mosquitto on the same host, you need to change the mqtt port in one of the servers. See corresponding ThingsBoard or Mosquitto documentation for more details.

Since we use ThingsBoard demo instance hosted in the cloud, we will install Mosquitto MQTT broker locally and use the default service configuration.

If you decide to use other MQTT broker that is deployed to the external host or has specific security configuration, please edit mqtt-config.json file and modify connection parameters. See MQTT extension configuration guide for more details.

Restart your gateway using the following commands

Windows: 
net stop tb-gateway
net start tb-gateway
Linux: 
sudo service tb-gateway restart

The mqtt-config.json contains sample configuration that allows mapping of JSON messages from external MQTT broker to ThingsBoard device attributes and telemetry.

Step 8.2 MQTT broker GUI configuration

To configure ThingsBoard Gateway through ThingsBoard GUI, remoteConfiguration must be enabled in tb-gateway.yaml:

gateways:
  tenants:
    -
      label: "Tenant"
      # Some configuration omitted
      remoteConfiguration: true

If remoteConfiguration is set to false, GUI configuration will not take effect and ThingsBoard Gateway will look for configuration in config files.

We will use Mosquitto MQTT broker for the demonstration purposes. See Mosquitto downloads page for instructions how to install this broker.

NOTE: Mosquitto and ThingsBoard use the same port (1883) for MQTT service by default. If you want to use ThingsBoard and Mosquitto on the same host, you need to change the mqtt port in one of the servers. See corresponding ThingsBoard or Mosquitto documentation for more details.

Since we use ThingsBoard demo instance hosted in the cloud, we will install Mosquitto MQTT broker locally and use the default service configuration.

If you decide to use other MQTT broker that is deployed to the external host or has specific security configuration, please edit mqtt-config.json file and modify connection parameters. See MQTT extension configuration guide for more details.

Go to Devices, select your Gateway and click on Extensions tab.

At this point we recommend to download and import sample MQTT configuration file mqtt-gui-extension-configuration.json.

You may as well configure MQTT extension step-by-step, but this is recommended for users who are already experienced with ThingsBoard IoT Gateway.

Click Import extension configuration and upload the downloaded mqtt-gui-extension-configuration.json file:

image

When the configuration is imported, click on Edit extension button to review the imported configuration.

image

MQTT Extension configuration contains one or more broker configurations:

image

Each broker configuration has the following sections:

NOTE Broker connection settings ARE NOT ThingsBoard server connection parameters. These settings are for an external MQTT broker, which ThingsBoard IoT Gateway collects data from and then sends them to ThingsBoard server. The Gateway takes ThingsBoard server connection settings from tb-gateway.yml file as was described before.

Mapping described in detail in MQTT Extension Configuration Details section

Step 8.3 MQTT Extension Configuration Details

The following section describes each part of MQTT Extension configuration settings, both file and GUI-based.

Step 8.3.1 Basic mapping example

As an example, the default mapping listed below will force gateway to subscribe to the sensors topic and use serialNumber from incoming json message as a device name. Similar, model and temperature json object fields will be mapped to corresponding ThingsBoard device attribute and telemetry fields.

{
  "topicFilter": "sensors",
  "converter": {
    "type": "json",
    "filterExpression": "",
    "deviceNameJsonExpression": "${$.serialNumber}",
    "attributes": [
      {
        "type": "string",
        "key": "model",
        "value": "${$.model}"
      }
    ],
    "timeseries": [
      {
        "type": "double",
        "key": "temperature",
        "value": "${$.temperature}"
      }
    ]
  }
}

The same mapping configured via GUI:

image

Let’s see this mapping in action. We will use mosquitto_pub command to emulate data from device that is connected to external mqtt broker:

mosquitto_pub -h localhost -p 1883 -t "sensors" -m '{"serialNumber":"SN-001", "model":"T1000", "temperature":36.6}'

NOTE On Windows the JSON string may not be interpreted correctly by Gateway. You may see the following error in the Gateway log:

 com.fasterxml.jackson.core.JsonParseException: Unexpected character (''' (code 39)): was expecting double-quote to start field name

If this is the case, use double quotes on the outside and escaping double quotes on the inside of the message, like:

 "{\"serialNumber\":\"SN-001\", \"model\":\"T1000\", \"temperature\":36.6}"

You should observe following log message in the gateway logs:

... INFO  o.t.g.service.MqttGatewayService - [SN-001] Device Connected!

Logs are located in the following folder:

Windows: YOUR_INSTALL_DIR/logs
Linux: /var/log/tb-gateway

Now you can navigate to the ThingsBoard Web UI and observe new device SN-001 on the Devices page. You can click on the device card and observe delivered attributes and telemetry in the corresponding tabs.

image

Step 8.3.2 Mapping JSON arrays

By default, gateway supports mapping of json arrays, by mapping each array element as a separate entity. For example, following command will create or update two devices: SN-002 and SN-003.

mosquitto_pub -h localhost -p 1883 -t "sensors" -m '[{"serialNumber":"SN-002", "model":"M2", "temperature":42.0}, {"serialNumber":"SN-003", "model":"M3", "temperature":73.0}]'

Step 8.3.3 Mapping MQTT topic to device name

In some cases, the device name is a part of the MQTT topic. In this case, you are able to use the regular expression to extract device name value. This regular expression is configured in the deviceNameTopicExpression field.

See example publish command and mapping (already present in default configuration) below:

mosquitto_pub -h localhost -p 1883 -t "sensor/SN-004/temperature" -m '{"value":36.6}'
{
  "topicFilter": "sensor/+/temperature",
  "converter": {
    "type": "json",
    "filterExpression": "",
    "deviceNameTopicExpression": "(?<=sensor\/)(.*?)(?=\/temperature)",
    "timeseries": [
      {
        "type": "double",
        "key": "temperature",
        "value": "${$.value}"
      }
    ]
  }
}

The same configuration in GUI:

image

Step 8.3.4 Advanced mapping syntax and filtering

Gateway MQTT extension uses JsonPath library to provide the ability of flexible mapping and filtering of JSON structures. You can define filterExpression based on the path and filter examples.

Step 8.3.5 Custom MQTT message mappers

As a gateway developer, you are able to fork and add custom mappers using following interface. Feel free to submit PRs with your custom mapper implementations if you believe that they may be useful for the ThingsBoard community.

Step 9. Connect to external OPC-UA server

This example will demonstrate how to

We assume that KEPServerEX is already installed on your Windows machine. We will use Windows 10 and Free Demo server.

Step 9.1. Provision gateway credentials to KEPServerEX

Open KEPServerEX “OPC UA Configuration Manager” application and navigate to “Trusted Clients” page.

Import example.der certificate from the gateway configuration folder. Configuration folder location:

Windows: YOUR_INSTALL_DIR/conf
Linux: /etc/tb-gateway/conf

NOTE This certificate is added to the configuration folder for the demonstration purposes. Both the certificate and the key are in public access, thus it is not secure and is not for production usage. You can create and configure your own certificate pair for production usage.

NOTE If the provided example.der certificate has expired or you decide to generate a new certificate, you can use the following commands to get a new example.der:

keytool -genkeypair -v -alias gateway -dname "CN=Thingsboard Gateway, OU=TB, O=ThingsBoard, L=San Francisco, ST=CA, C=US" -keystore example.jks -keypass secret -storepass secret -keyalg RSA -keysize 2048 -validity 9999

keytool -importkeystore -srckeystore example.jks -destkeystore example.pfx  -srcstoretype JKS -deststoretype PKCS12 -srcstorepass secret -deststorepass secret -srcalias gateway -destalias gateway -srckeypass secret -destkeypass secret -noprompt

keytool -exportcert -alias gateway -keypass secret -keystore example.pfx -storepass secret -file example.der  

image

Step 9.2. Add server endpoint KEPServerEX

This step is required if you want to deploy ThingsBoard IoT Gateway and KEPServerEX on different hosts.

KEPServerEX needs to be configured to accept remote connections. Open KEPServerEX “OPC UA Configuration Manager” application and navigate to “Server Endpoints” page.

image

NOTE KEPServerEX restart is required.

Step 9.3 Enable OPC-UA extension

Step 9.3.1 OPC-UA extension file configuration

If you are using file-based configuration, navigate to gateway configuration folder and edit tb-gateway.yml file. Configuration folder location:

Windows: YOUR_INSTALL_DIR/conf
Linux: /etc/tb-gateway/conf

Change opc.enabled property value to true.

If you decide to use different OPC-UA server that is deployed to external host or has specific security configuration, please edit opc-config.json file and modify connection parameters. See OPC-UA extension configuration guide for more details.

The opc-config.json contains sample configuration that allows mapping of OPC-UA tags to ThingsBoard device attributes and telemetry. Once started, OPC-UA extension will monitor your OPC-UA server using this pre-defined configuration.

Restart your gateway using following commands

Windows: 
net stop tb-gateway
net start tb-gateway

Linux: 
sudo service tb-gateway restart

Step 9.3.2 OPC-UA extension GUI configuration

You can import sample configuration:
opc-ua-gui-extension-configuration.json

or configure OPC-UA extension manually. In GUI the extension configuration looks like:

image

NOTE When using remote configuration, the keystore file is not looked up by the Gateway on the file system, but it is read directly from the configuration that is received from ThingsBoard server. The sample opc-ua-gui-extension-configuration.json does not contain the keystore data. After importing the sample configuration, you need to add the keystore manually by clicking Edit Extension:

image

and then Drop a file or click to select a file to upload:

image

Step 9.4. Explore data from devices

The default mapping listed below will force gateway to treat all OPC-UA tags that match deviceNodePattern as ThingsBoard devices. Gateway will use deviceNamePattern to calculate the device name based on values of different tags using relative to the device node tag (For example, _System._DeviceId). Similar, Tag1 and Tag2 relative OPC-UA tags will be mapped to corresponding ThingsBoard device attribute and telemetry fields.

{
  "deviceNodePattern": "Channel1\\.Device\\d+$",
  "deviceNamePattern": "Device ${_System._DeviceId}",
  "attributes": [
    {"key":"Tag1", "type": "string", "value": "${Tag1}"}
  ],
  "timeseries": [
    {"key":"Tag2", "type": "long", "value": "${Tag2}"}
  ]
}

The same mapping in GUI looks like:

image

You should observe following log message in the gateway logs:

... INFO  o.t.g.service.MqttGatewayService - [Device 1] Device Connected!

Logs are located in the following folder:

Windows: YOUR_INSTALL_DIR/logs
Linux: /var/log/tb-gateway

Now you can navigate to the ThingsBoard Web UI and observe new device Device 1 on the Devices page. You can click on the device card and observe delivered attributes and telemetry in the corresponding tabs.

image

image

Step 10. Connect to Sigfox Backend

In this step, we will connect to Sigfox Backend in order to start collecting data from sigfox modules.

Step 10.1 Sigfox Extension file configuration:

Navigate to gateway configuration folder and edit tb-gateway.yml file. Configuration folder location:

Windows: YOUR_INSTALL_DIR/conf
Linux: /etc/tb-gateway/conf

Change sigfox.enabled property value to true.

Restart your gateway using following commands

Windows: 
net stop tb-gateway
net start tb-gateway

Linux: 
sudo service tb-gateway restart

The sigfox-config.json contains configuration that allows mapping of JSON messages from Sigfox Backend to ThingsBoard telemetry.

Step 10.2 Sigfox Extension GUI configuration:

You can import sample Sigfox Extension configuration file:
sigfox-gui-extension-configuration.json

Step 10.3 Sigfox Backend configuration

Let’s assume we want to publish coordinates, temperature and humidity data from your Sigfox module to ThingsBoard. In order to achieve this, you will need to select device type and configure custom callback from Sigfox Backend to our IoT Gateway.

image

Few things to notice:

We assume you have deployed the gateway on some cloud server to get the static IP address or hostname.

Step 10.4 Basic mapping example

The default mapping listed below will allow to convert data from Sigfox Backend and publish it to ThingsBoard.

{
  "deviceTypeConfigurations": [
    {
      "deviceTypeId": "YOUR_DEVICE_TYPE_ID",
      "token": "SECURITY_TOKEN",
      "converter": {
        "deviceNameJsonExpression": "${$.device}",
        "attributes": [
          {
            "type": "string",
            "key": "lat",
            "value": "${$.lat}"
          },
          {
            "type": "string",
            "key": "lng",
            "value": "${$.lng}"
          }
        ],
        "timeseries": [
          {
            "type": "double",
            "key": "temperature",
            "value": "${$.data.temperature}",
            "transformer": {
              "type": "intToDouble"
            }
          },
          {
            "type": "double",
            "key": "humidity",
            "value": "${$.data.humidity}",
            "transformer": {
              "type": "intToDouble"
            }
          }
        ]
      }
    }
  ]
}

Few things to notice:

Step 10.5 Dry Run

Once your Sigfox Beckend callback is configured, you may observe incoming messages in ThingsBoard IoT Gateway logs. If everything is configured correctly, you will see new devices in your Tenant Administrator device list.

image

You are able to open a particular device and check that telemetry values arrived successfully.

Step 10.6 Custom Data type transformers

As a gateway developer, you are able to fork and add custom transformers using following interface. Feel free to submit PRs with your custom transformer implementations if you believe that they may be useful for the ThingsBoard community.

Step 11. Connect to Modbus slave

Modbus Extension configuration is covered on the corresponding extension page.

See Also

Explore guides related to main ThingsBoard features:

Next steps