This article aims to explain how MoibusFlow is used with Thingsboard. Covered in the article is the following:

1. Thingsboard APIs
2. Configuring Thingsboard for MobiusFlow
3. Setting up Connection to Thingsboard
4. Device and Asset Management
5. Publishing Device and Asset Data
6. Receiving Shared Attribute Updates
7. Example

Before utilising this article the user should understand the following:

• MobiusFlow Architecture
• MobiusFlow URIs
• Node-RED Flows
• Mobius Cloud Format Node

1. Thingsboard APIs

Thingsboard utilises multiple APIs for managing devices and assets and sending telemetry and attribute
data to and from Thingsboard. The IAConnects RESTful and MQTT API implementations described in
this document both use TLS and expect the ports to be 443 for REST and 8883 for MQTT.

1.1. RESTful API

The RESTful API is used to create devices and assets within Thingsboard, and to send asset telemetry data to Thingsboard.

1.2. MQTT API

The MQTT API is used to send device telemetry and attribute data to Thingsboard. It is also used to receive shared attribute updates from Thingsboard. Thingsboard has two main ways to send device telemetry and attribute data to Thingsboard via MQTT:

• Use a separate MQTT connection for each device. Each connection is authorised independently using the device’s token.
• Use a single, common (Thingsboard gateway) MQTT connection for all devices. This connection requires a gateway type device to be created in Thingsboard. This single
  connection is authorised using the gateway device’s token

2. Configuring Thingsboard for MobiusFlow

To enable MobiusFlow to correctly communicate with Thingsboards, a Mobius Gateway user group and associated Mobius Gateway role must be set up within Thingsboard.

2.1. Mobius Gateway Role

Within Thingsboard, roles are used to associate a set of permissions with a given user group. As such, a role associated with the Mobius Gateway user group is required. To create this role, navigate to the roles section within Thingsboard and click add. The Mobius Gateway role should be created with the following parameters:

Name: MobiusGatewayRole

Role type: Generic

The permission resources and associated operations should be added as follows:

Resource	Associated Operations
Device	Create Read Read Credentials Write Write Attributes Write Telemetry
Asset	Create Read Write Write Telemetry

This setup can also be seen in the following screenshot:

The following screenshot shows the resultant configuration of the new role once added:

This concludes the Mobius Gateway role setup process.

2.2. Mobius Gateway User Group

A Mobius Gateway user group must be created to encompass all registered Mobius Gateways within Thingsboard. Storing Mobius Gateways as a type of user within Thingsboard allows them to interact with Thingsboard as if they were a user. The associated Mobius Gateway role allows control of what Mobius Gateway users (Mobius Gateways) can do within Thingsboard.

2.2.1. User Group Creation

To create a new user group, navigate to the user groups section within Thingsboard, and press add. The new user group should be created with the following parameters:

Name: MobiusFlow Gateway Users

Description: (Any sensible description)

The creation is shown in the following screenshot:

Once the new user group has been created, the Mobius Gateway role can be associated.

2.2.2. Mobius Gateway Role Association

Select the new Mobius Gateway user group within Thingsboard. Associating a new role is shown in the screenshot below.

1. Open the details menu of the user group - Shown in red below
2. Navigate to the roles tab - Shown in blue below
3. Select the add role button to associate the Mobius Gateway role - Shown in orange below

The Mobius Gateway role can then be selected and added. The selection has the following parameters to match the previous created Mobius Gateway role:

Role type: Generic

Role: MobiusGatewayRole

This selection process is shown in the screenshot below:

Once added, this concludes the Mobius Gateway user group setup process.

2.3. Adding a Mobius Gateway User

Within the newly created Mobius Gateway user group, a new user instance must be created to allow for interfacing between MobiusFlow and Thingsboard. It is user preference to either create a single user to represent all MobiusFlow Gateways or create separate users for each MobiusFlow Gateway. The latter of these two options is recommended as this aids ease of disabling a given MobiusFlow Gateway if this is required.

The user or users should be created and activated accordingly. The email address and password of each account should be known as these will be used when setting up the connection between Thingsboard and MobiusFlow in section 3.

2.4. Adding a Gateway Device

For a Mobius Gateway to communicate with Thingsboads, an equivalent instance of the Mobius Gateway must be created as a device within Thingsboard. Once added, the device's access token can be viewed and copied for later use. This section explains both the device add process and how the device's access token is viewed.

The creation of a Mobius Gateway device is not necessary if a separate MQTT connection for all devices is being used.

2.4.1. Add Process

Within Thingsboard, navigate to the device groups and then add a new device to the desired group. The new device should be configured as follows:

Name: (The Hub ID of the Mobius Gateway you're using, A00000 in the example below)

Device Type: Mobius Gateway

Label: (Any sensible label)

Is gateway:  Checked

Description: (Any sensible description)

After adding the new device, the Mobius Gateway now appears within the device list. The example below shows this new device within the 'all' device group.

This concludes the device creation process.

2.4.2. Acquiring the Access Token

The access token can be acquired by first selecting the device. Once on the device has been selected, ensure the details tab is selected. The device access token can then be copied to the user's clipboard by selecting 'copy access token', outlined in red in the screenshot below.

The access token is necessary when setting up the connection between a Mobius Gateway and Thingsboard. This setup process is explained in the following section.

3. Setting up Connection to Thingsboard

Setting up the connection between MobiusFlow and Thingsboard requires the configuration of both the RESTful and MQTT APIs. Both APIs can be configured through the Thingsboard manager node.

Within the node edit window, select the configure option to begin the connection configuration process. This is shown in the red box in the screenshot below. Note, this connection is shared by all Thingsboad related nodes, and as such, the connection configuration can be accessed in the same manner through all Thingsboard nodes.

Once presented with the configuration window, the connection should be configured as follows:

Site: (The instances of the Thingsboard site being used, poral-001.mobiusflow.io in the example below)

Gateway ID: (The Hub ID of the Mobius Gateway being used, A00000 in the example below)

Access Token: (The access token of the Mobius Gateway device within Thingsboard, see section 2.4.2, or the access token of the device within Thingsboard if using a separate MQTT connection for each device)

Username: (The username of the previously created gateway user, see section 2.3)

Password: (The password of the previously created gateway user, see section 2.3)

Allow Self Signed Certificates: (Boolean checkbox to allow self-signed authentication certificates from trusted sources)

The screenshot below shows an example connection configuration:

This concludes the connection setup process.

4. Device & Asset Management

Within Thingsboard, devices and assets can be created through 3 mechanisms

• Manual creation within Thingsboard
• Through the Thingsboard RESTful API
• Automatic creation, through sending telemetry or attribute data to Thingsboard

The latter of these three mechanisms is not desirable for the following reasons:

• If devices or assets don’t exist within Thingsboard, and Thingsboard receives telemetry or
  attribute data for a device or asset, it is created automatically and its details such as Device
  Type, Label, and Description are set to the default values. These properties cannot be
  changed later using the Thingsboard API, so they need to be edited manually within
  Thingsboard.
• All created devices and assets count toward the total used against the Thingsboard license.
  Sending telemetry or attributes for devices or assets that you do not want created within
  Thingsboard will create these devices and assets, using up your license allowance.

As Thingsboard does not have a mechanism to prevent this automatic creation, the MobiusFlow gateway filters all telemetry and attribute messages destined for Thingsboard by comparing the Mobius object IDs against a registered list, blocking all messages for unregistered object IDs. The list of registered object IDs is maintained within the MobiusFlow Thingsboard Manager node. The node allows two functions to be performed:

• Register Object - Registers the given object within the Thingsboard Manager's maintained list
• Provision Object - Registers the given object within the Thingsboard Manager's maintained list (if not registered already) then uses the RESTful API to create the device or asset within Thingsboard

4.1. Object Registration

The Thingsboard Manager node will register object IDs when it is passed an array of MobiusFlow objects with the topic register-objects. The Thingsboard Manager node is most commonly coupled with a discover object list to allow for ease of sending the Manager node an array of MobiusFlow objects. An example flow is shown in the screenshot below.

In the above flow, the nodes are configured as follows:

Node	Explanation	Configuration Screenshot
Inject node	Inject node used to initiate the message and set it's topic to be register-objects. Note, the node has been set to inject once at the beginning of the flow. This is to pre-register any required objects when the flow starts or restarts.
Discover Object list	Once the incoming message is received, the node is used to determine which Moibus objects are to be compiled into the outgoing array. In this instance, all objects with URI A00000/020/0031/# will be returned. This relates to Temperature and Humidity sensors of type A5-04-01 that are associated with this Mobius Gateway.
Thingsboard Manager	The Thingsboard Manager node will take the incoming array of MobiusFlow objects and register all contained objects ID within its internal storage. The manager is connected to Thingsboard through the connection set up in section 3. This connection is necessary for object provisioning (see the following section).

Once the Thingsboard Manager node has successfully registered the array of incoming objects, this will be shown just below the node:

4.2. Object Provision

The Thingsboard Manager node will provision devices or assets when it is passed an array of MobiusFlow objects with the topic provision-devices or provision-assets respectively. The Thingsboard Manager node is most commonly coupled with a discover object list node to allow for ease of sending the Manager node an array of MobiusFlow objects. An example of registering devices is shown in the flow below.

In the above flow, the nodes are configured as follows:

Node	Explanation	Configuration Screenshot
Inject node	Inject node used to initiate the message and set it's topic to be provision-devices.
Discover Object list	Once the incoming message is received, the node is used to determine which Moibus objects are to be compiled into the outgoing array. In this instance, all objects with URI A00000/020/0031/# will be returned. This relates to Temperature and Humidity sensors of type A5-04-01 that are associated with this Mobius Gateway.
Thingsboard Manager	The Thingsboard Manager node will take the incoming array of Mobius objects and register all contained objects ID within its internal storage as well as creating these objects as devices within Thingsboard. The manager is connected to Thingsboard through the connection set up in section 3.

Once the message is injected, if successful the Thingsboard Manager node will provision the objects and create them within Thingabord as a device or asset. The result of the above flow within Thingsboard is shown in the following screenshot.

In this instance, there was only one object matching the specification, and hence a single device was created within Thingsboard. During provisioning, devices and assets are created with the following properties:

Name: The MobiusFlow object ID

Device Type: The MobiusFlow object type

Label: The MobiusFlow object name. If this is left as the default in MobiusFlow, the label is left blank
in Thingsboard.

Description: The MobiusFlow object description

4.3. Provisioning vs Registering

As explained previously, using the provision object functionality will register objects within the Thingsboard Manager and then will proceed to create the objects as devices or assets within Thingsboard. The register functionality will only register objects within the Thingsboard Manger.

A typical use case for these two options would be as follows. If flows are redeployed, the Thingsboard Manager will clear the list of registered objects. This may not be desirable to the user. Having the functionality to simply register objects without attempting to re-create them in Thingsboard is therefore required. In this situation, it may be desirable to set an inject node to run once each time the flow is deployed. This would allow the flow to re-register any objects within the Thingsboard Manager before any further logic can run. This system ensures two key conditions are met:

• Relevant objects are registered within the Thingsboard Manager before Thingsboard-related logic involving these objects begins (the manager would block this logic if not registered).
• Devices or Assets are not re-created or overwritten within Thingsboard when objects are re-registered

5. Publishing Device and Asset Data

Both telemetry and attribute data can be passed into Thingsboard. Data can be published into either devices or assets. Devices and assets are subject to different rules regarding which type of data can be published to them. This is shown in the table below.

Entity Type	Allowed Data Types
Device	Telemetry Attributes
Asset	Telemetry

Publishing data to both devices and assets is covered in the following two sections.

5.1. Device Data

Publishing data to devices utilises the Thingsboard Device Publish node. The node allows the user to define if either telemetry data, attribute data, or both telemetry and attribute data is to be published. The node accepts incoming data as MobiusFlow objects in the MobiusFlow cloud format. The example flow below shows how the Thingsboard Device Publish node could be used.

In the above flow, the nodes are configured as follows:

Node	Explanation	Configuration
Mobius Flow Inject	The Mobius Flow Inject node is set to output a MobiusFlow object whenever a change to that object is detected. In this case, the node has been set up to subscribe to changes of any Temperature and Humidity sensors of type A5-04-01 (URI: A00000/020/0031/#).
Mobius Cloud Format	The Mobius Cloud Format node prepares the data for publishing. The verbosity must be set to 'Verbose' to ensure correct data preparation. It is recommended the publish setting is set to 'Changed Resources' to ensure the minimum data is sent.
Thingsboard Device Publish	The node publishes incoming data to Thingsboard. The node has been set to use the Thingsboard connection set up in section 3. In this example, the selection has been made to publish both telemetry and attribute data. It is recommended the 'Use MQTT' option is checked to allow for telemetry data to be updated in a timely manner.

This flow allows any changes to telemetry or attributes of subscribed objects to be published to devices. The flow assumes the devices have already been created within Thingsboard and the objects are currently registered within the Thingsboard Manager. For more information on device creation and object registration, see section 4.

5.2. Asset Data

Publishing telemetry to assets utilises the Thingsboard Asset Publish node. The node accepts incoming telemetry changes as MobiusFlow objects in the Mobius cloud format. The example flow below shows how the Thingsboard Asset Publish node could be used.

In the above flow, the nodes are configured as follows.

Node	Explanation	Configuration
Mobius Flow Inject	The Mobius Flow Inject node is set to output a MobiusFlow object whenever a change to that object is detected. In this case, the node has been set up to subscribe to changes of any Temperature and Humidity sensors of type A5-04-01 (URI: A00000/020/0031/#).
Mobius Cloud Format	The Mobius Cloud Format node prepares the data for publishing. The verbosity must be set to 'Verbose' to ensure correct data formatting. It is recommended the publish setting is set to 'Changed Resources' to ensure the minimum data is sent.
Thingsboard Device Publish	The node publishes incoming telemetry to Thingsboard. The node has been set to use the Thingsboard connection set up in section 3.

This flow allows the telemetry of subscribed objects to be published to assets. The flow assumes the assets have already been created within Thingsboard and the objects are currently registered within the Thingsboard Manager. For more information on asset creation and object registration, see section 4.

6. Receiving Shared Attribute Updates

MobiusFlow is only able to subscribe to shared Attribute changes within Thingsboard. Server attributes are not accessible because only Thingsboard has access to these. Accessing client attributes in this manner is not necessary because client attributes are already stored by MobiusFlow.

To detect attribute changes that occur within Thingsboard and use this information within MobiusFlow, the Thingsboard Attribute Node is required. This is shown below:

The node is simply used to subscribe to all changes to any attributes that occur within a selected Thingsboard site. The node will output a message containing information regarding the device in which an attribute change has occurred, as well as the change itself. Message objects will be outputted in the following format:

"msg": {
     "topic": (The URI of the object subject to change),
     "payload": {
          "Example_Changed_Attribute" : (New value of attribute),
     }
}

 

An example flow is shown below:

The node configuration is as follows:

Node	Explanation	Configuration
Thingsboard Attribute Subscribe	Node is used to subscribe to any shared attribute changes within a given Thingsboard site. Within this example, the portal-001.mobiusflow.io site is subscribed to.
Debug	The debug node is set to display the full message object of any incoming messages containing attribute changes.

When a 'Test Attribute' changes within Thingsboard, the result from the debug node is shown below:

The topic indicates the device subject to the change was of URI A00000/020/0031/0001. The new value of the 'Test Attribute' is shown to be 125.

7. Example

This example assumes the following:

• A Mobius Gateway Role has been set up in Thingsboard (section 2.1)
• A Mobius Gateway user group has been set up in Thingsboard (section 2.2)
• A Mobius Gateway user has been set up within the Mobius Gateway user group and the account has been activated (section 2.3)
• A Mobius Gateway Device has been added in Thingsboard (section 2.4)

In this example, the user has three sensors within a residential home. The three sensors are positioned in the kitchen, lounge, and study. Each sensor is an EnOcean A5-04-01 temperature and humidity sensor and all are within a MobiusFlow object store of URI  A00000/020/0031.

7.1. Flow Setup

The user wishes to view telemetry from the three sensors within Thingsboard so sets up the following flow to do so:

The connection to Thingsboard is set up through the Thingsboard Manager node (see section 3) with the site name portal-001.mobiusflow.io. The configuration of all nodes within the above flow is explained in the table below:

Node	Explanation	Configuration
Inject (Provision-Devices)	Injects a message with the topic provision-devices. This node allows the user to begin a message to create devices within Thingsboard.
Inject (Register-Objects)	Injects a message with the topic register-objects. This node is set to inject once when the flow is deployed. This will begin a message to register objects within the Thingsboard Manager node.
Discover Object List	Once a message is received from either inject node, this node will send an array of objects of URI A00000/020/0031/#. This includes the user's three sensors.
Thingsboard Manager	The Thingsboard Manager node is set to connect to the user's Thingsboard site. The node receives an array of objects to either be provisioned or registered depending on the topic of the incoming message. If the message is to provision, the manager will create the three devices within Thingsboard, as well as registering them within the manager.
Mobius Flow Inject	This node is used to check for any change of values of any resources to any included objects. A message is outputted when a change is detected. The node has been set up to include objects of URI A00000/020/0031/# which includes the user's three devices.
Mobius Cloud Format	Once incoming messages are received, the Mobius Cloud Format node prepares the message for publishing. The verbosity is set to verbose as required and the node has been set to only forward changed resources to minimise data transfer.
Thingsboard Device Publish	Once incoming messages have been received which contain changed telemetry data, the node will publish this data to Thingsboard. For speed of data transfer, the 'Use MQTT' option has been checked. The node has been set to publish telemetry only as no attributes are present for the user's three sensors.

7.2. Usage

To create the objects within Thingsboard, the user injects a message using the provision-devices inject node. The flow shows the following to notify the user:

Furthermore, the three temperature and humidity sensor devices have been created within Thingsboard:

Viewing Temperature and Humidity Sensor 1 reveals the sensor is located in the kitchen and reads a humidity of 50%. This is shown in the screenshots below:

Suppose the humidity in the kitchen is then reduced to 45%. MobiusFlow detects this within the flow and the telemetry of this sensor is then updated within Thingsboard accordingly. The flow shows this:

The publishing of this telemetry is possible because all three sensors were already registered within the Thingsboad Manager when the devices were initially provisioned. The updated humidity value within Thingsboard is shown in the screenshot below:

7.3. Updating or Changing the Flow

Suppose the user must update or change the flow in some way. After the changes have been made, re-deploying the flow will clear the list of registered devices. As the three devices are already created in Thingsboard, it is not desirable for the user to re-provision the objects. This is why the user set up the flow to automatically inject a message to register the objects when the flow is started. This means the flow automatically re-registers any objects with the Thingsboard Manager whenever the flow is re-deployed following changes or updates. As a result, telemetry updates can continue to function correctly and are not blocked due to lack of registration.