ThingsBoard Integration

How to integrate ThingsBoard with Connectware, including gateway authentication with a device access token, sending telemetry and attributes for multiple devices, and answering RPC commands.

This guide describes how to integrate ThingsBoard with Connectware. You configure a service commissioning file that sends telemetry and attributes for your shop floor equipment to ThingsBoard through its MQTT gateway API and receives remote procedure call (RPC) commands in return. A complete example file is available at the end of this guide.

Objectives

• Establishing an MQTT connection between Connectware and ThingsBoard, authenticated with a device access token.

• Sending telemetry for multiple shop floor devices over a single connection using the ThingsBoard gateway API.

• Sending client-side attributes for those devices.

• Receiving RPC commands from ThingsBoard in Connectware and publishing the responses.

Prerequisites

To follow this guide, you will need the following:

• A running instance of Cybus Connectware.

• Access to a ThingsBoard instance (Community Edition, Professional Edition, or ThingsBoard Cloud) with permission to create devices.

• A gateway device in ThingsBoard and its access token. To create one, open the Devices page in ThingsBoard, add a new device, and select the Is gateway checkbox. The access token is available in the device details.

• Access to the Admin UI with sufficient user permissions.

• Basic knowledge of MQTT and the Connectware services concept (for example, service commissioning files, connections, and endpoints).

Connectware and ThingsBoard Integration

ThingsBoard exposes an MQTT device API for telemetry, attributes, and RPC. A client authenticates with a device access token as the MQTT username and no password, on port 1883 for plain MQTT or port 8883 for MQTT over TLS. Each MQTT connection authenticates as exactly one device: everything published on the v1/devices/me/... topics is recorded against the device that owns the token. Connecting many machines this way would require one Connectware connection per ThingsBoard device.

Connectware usually represents many machines at once, so this guide uses the ThingsBoard gateway API instead. The gateway API works over a single MQTT connection, authenticated with the access token of one gateway device, and carries data for any number of devices. ThingsBoard creates a device automatically the first time the gateway publishes data for it and shows it as connected through the gateway.

The integration uses the following topics on the ThingsBoard broker:

• v1/gateway/telemetry: Publishes time series data for one or more devices.

• v1/gateway/attributes: Publishes client-side attributes for one or more devices.

• v1/gateway/connect: Announces a device to ThingsBoard so that it can receive RPC commands through the gateway.

• v1/gateway/rpc: Delivers RPC requests to the gateway and accepts the responses.

To connect a single device only, use the device API topics v1/devices/me/telemetry and v1/devices/me/attributes with the access token of that device instead. The connection setup in this guide stays the same.

The MQTT topics on the Connectware side follow an ISA-95-style equipment hierarchy (<enterprise>/<site>/<area>/<line>/<cell>). The mappings subscribe with wildcards across all levels, so any machine in the hierarchy is picked up without changing the integration. The last topic level becomes the device name in ThingsBoard.

ThingsBoard Connection Properties

The connection to ThingsBoard requires the hostname of your instance and the access token of the gateway device. We add them as parameters to the service commissioning file, so you can set them when you install the service.

Do not worry about copying the service commissioning file snippets together into one, the complete example file is available at the end of this guide.

• thingsboardHost: The hostname of your ThingsBoard instance, without the scheme. For example, thingsboard.example.com.

• accessToken: The access token of the gateway device in ThingsBoard.

• topicRoot: The root of the MQTT topic hierarchy. Defaults to enterprise.

parameters:
  thingsboardHost:
    description: Hostname of your ThingsBoard instance
    type: string
    default: thingsboard.example.com

  accessToken:
    description: Access token of the gateway device in ThingsBoard
    type: string

  topicRoot:
    description: Root of the MQTT topic hierarchy
    type: string
    default: enterprise

ThingsBoard Connection

To connect to the ThingsBoard broker, we set up a Cybus::Connection resource that uses the MQTT connector. ThingsBoard identifies the client by the access token in the username property, a password is not required. For all available connection properties, see MQTT Connection Properties.

resources:
  thingsboardConnection:
    type: Cybus::Connection
    properties:
      protocol: Mqtt
      connection:
        host: !ref thingsboardHost
        port: 8883
        scheme: mqtts
        username: !ref accessToken
        clientId: connectware-gateway
        keepalive: 60

The example connects with TLS on port 8883. For plain MQTT, set the port to 1883 and the scheme to mqtt. If your ThingsBoard instance uses a certificate that the Connectware host system cannot validate, add the issuing CA certificate with the caCert property.

Sending Telemetry

The gateway API expects telemetry as a JSON object with one key per device name. Each key holds an array of entries with a ts timestamp in milliseconds and a values object containing the readings.

We define a write endpoint for the v1/gateway/telemetry topic and a mapping that feeds it from the MQTT topic hierarchy. The transform rule builds the gateway envelope: the named wildcard +cell is available as $context.vars.cell and becomes the device name, and $millis() sets the current time as the timestamp. Machines publish their readings as plain JSON without knowing about this convention.

telemetryEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Mqtt
    connection: !ref thingsboardConnection
    write:
      topic: v1/gateway/telemetry

telemetryMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          topic: !sub '${topicRoot}/+site/+area/+line/+cell/telemetry'
        publish:
          endpoint: !ref telemetryEndpoint
        rules:
          - transform:
              expression: |
                {
                  $context.vars.cell: [
                    {
                      "ts": $millis(),
                      "values": $
                    }
                  ]
                }

A machine that publishes the following payload to enterprise/hamburg/assembly/line-1/press-01/telemetry now appears in ThingsBoard as the device press-01, with temperature and pressure as telemetry keys:

{
  "temperature": 42.1,
  "pressure": 5.2
}

If your machines deliver their own timestamps, map them into the ts field instead of calling $millis().

Device names must be unique within your ThingsBoard tenant. If the same cell name occurs in more than one line, build a qualified device name in the transform expression, for example $join([$context.vars.line, $context.vars.cell], '-').

Sending Device Attributes

Attributes hold slowly changing metadata, such as a firmware version or a serial number, while telemetry holds time series data. The gateway API expects attributes as a JSON object with one key per device name and the attribute key-value pairs as the value. The endpoint uses the same connection and the v1/gateway/attributes topic.

attributesEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Mqtt
    connection: !ref thingsboardConnection
    write:
      topic: v1/gateway/attributes

attributesMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          topic: !sub '${topicRoot}/+site/+area/+line/+cell/attributes'
        publish:
          endpoint: !ref attributesEndpoint
        rules:
          - transform:
              expression: '{ $context.vars.cell: $ }'

A message published to enterprise/hamburg/assembly/line-1/press-01/attributes with the payload { "firmwareVersion": "1.0.3", "serialNumber": "SN-0001" } sets these values as client-side attributes of the device press-01.

Receiving and Answering RPC Commands

ThingsBoard dashboards and rule chains send RPC commands to devices, for example to change a setpoint or to trigger an action. For devices behind a gateway, ThingsBoard delivers these commands on the v1/gateway/rpc topic. ThingsBoard only routes RPC commands for devices that the gateway has announced on the v1/gateway/connect topic.

We define a write endpoint for the connect topic and a mapping that feeds it from Connectware. To announce a device, publish its name to the internal topic, for example with an MQTT client or the Admin UI:

deviceConnectEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Mqtt
    connection: !ref thingsboardConnection
    write:
      topic: v1/gateway/connect

deviceConnectMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          topic: !sub '${topicRoot}/thingsboard/connect'
        publish:
          endpoint: !ref deviceConnectEndpoint

Publishing { "device": "press-01" } to enterprise/thingsboard/connect marks the device press-01 as connected through the gateway.

For the commands themselves, a subscribe endpoint receives every RPC request from ThingsBoard, and a mapping forwards it to an internal topic where any other Connectware service can pick it up, for example to write the command to a PLC:

rpcRequestEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Mqtt
    connection: !ref thingsboardConnection
    subscribe:
      topic: v1/gateway/rpc

rpcRequestMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          endpoint: !ref rpcRequestEndpoint
        publish:
          topic: !sub '${topicRoot}/thingsboard/rpc/request'

Each request contains the target device, a request ID, the method name, and the parameters:

{
  "device": "press-01",
  "data": {
    "id": 1,
    "method": "setFanSpeed",
    "params": { "speed": 80 }
  }
}

For two-way RPC commands, ThingsBoard waits for a response with the same request ID. The service that handles the command publishes the response to the internal response topic, and a mapping sends it back to ThingsBoard on the same v1/gateway/rpc topic. One-way RPC commands do not require a response. ThingsBoard delivers responses to the caller of the RPC command, it does not echo them back to the gateway subscription.

rpcResponseEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Mqtt
    connection: !ref thingsboardConnection
    write:
      topic: v1/gateway/rpc

rpcResponseMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          topic: !sub '${topicRoot}/thingsboard/rpc/response'
        publish:
          endpoint: !ref rpcResponseEndpoint

The response must echo the device name and the request ID:

{
  "device": "press-01",
  "id": 1,
  "data": { "success": true }
}

Verifying the Integration

1. Install the service and set the parameters with the hostname of your ThingsBoard instance and the access token of the gateway device.

2. Check that the connection is in the Connected state on the service details page in the Admin UI. If the access token is wrong, ThingsBoard rejects the connection and it does not reach the connected state.

3. Publish a test message, for example { "temperature": 42.1 }, to enterprise/hamburg/assembly/line-1/press-01/telemetry with an MQTT client or the Admin UI.

4. Open the Devices page in ThingsBoard and check that the device press-01 has been created. The Latest telemetry tab of the device shows the published values.

5. To test RPC, publish { "device": "press-01" } to enterprise/thingsboard/connect, then send an RPC command from ThingsBoard, for example with an RPC widget on a dashboard. Use the Data Explorer to check that the request arrives on enterprise/thingsboard/rpc/request.

Service Commissioning File Example

thingsboard-example.yml

4KB

Open

thingsboard-example.yml

---
# ----------------------------------------------------------------------------
# Service Commissioning File
# ----------------------------------------------------------------------------
# Copyright: Cybus GmbH
# Contact: [e-mail]
# ----------------------------------------------------------------------------
# ThingsBoard Integration (Example)
# ----------------------------------------------------------------------------

description: >
  Service commissioning file for the integration between Connectware and
  ThingsBoard using the MQTT gateway API (Example)

metadata:
  name: ThingsBoard Integration
  provider: cybus
  homepage: https://www.cybus.io
  version: 1.0.0

parameters:
  thingsboardHost:
    description: Hostname of your ThingsBoard instance
    type: string
    default: thingsboard.example.com

  accessToken:
    description: Access token of the gateway device in ThingsBoard
    type: string

  topicRoot:
    description: Root of the MQTT topic hierarchy
    type: string
    default: enterprise

resources:
  # Connection to the ThingsBoard broker, authenticated as the gateway device
  thingsboardConnection:
    type: Cybus::Connection
    properties:
      protocol: Mqtt
      connection:
        host: !ref thingsboardHost
        port: 8883
        scheme: mqtts
        username: !ref accessToken
        clientId: connectware-gateway
        keepalive: 60

  # Sends telemetry for any device in the topic hierarchy
  telemetryEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Mqtt
      connection: !ref thingsboardConnection
      write:
        topic: v1/gateway/telemetry

  telemetryMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            topic: !sub '${topicRoot}/+site/+area/+line/+cell/telemetry'
          publish:
            endpoint: !ref telemetryEndpoint
          rules:
            - transform:
                expression: |
                  {
                    $context.vars.cell: [
                      {
                        "ts": $millis(),
                        "values": $
                      }
                    ]
                  }

  # Sends client-side attributes for any device in the topic hierarchy
  attributesEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Mqtt
      connection: !ref thingsboardConnection
      write:
        topic: v1/gateway/attributes

  attributesMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            topic: !sub '${topicRoot}/+site/+area/+line/+cell/attributes'
          publish:
            endpoint: !ref attributesEndpoint
          rules:
            - transform:
                expression: '{ $context.vars.cell: $ }'

  # Announces a device to ThingsBoard so that it can receive RPC commands
  deviceConnectEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Mqtt
      connection: !ref thingsboardConnection
      write:
        topic: v1/gateway/connect

  deviceConnectMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            topic: !sub '${topicRoot}/thingsboard/connect'
          publish:
            endpoint: !ref deviceConnectEndpoint

  # Receives RPC requests from ThingsBoard
  rpcRequestEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Mqtt
      connection: !ref thingsboardConnection
      subscribe:
        topic: v1/gateway/rpc

  rpcRequestMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            endpoint: !ref rpcRequestEndpoint
          publish:
            topic: !sub '${topicRoot}/thingsboard/rpc/request'

  # Sends RPC responses back to ThingsBoard
  rpcResponseEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Mqtt
      connection: !ref thingsboardConnection
      write:
        topic: v1/gateway/rpc

  rpcResponseMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            topic: !sub '${topicRoot}/thingsboard/rpc/response'
          publish:
            endpoint: !ref rpcResponseEndpoint