Using ROMA Connect for Device Integration

Overview

ROMA Connect uses the standard Message Queue Telemetry Transport (MQTT) protocol to connect devices and implement quick and easy device management on the cloud.

This chapter provides a configuration example to help you get familiarized with the device integration process.

The steps for integrating devices with ROMA Connect are as follows:

• Step 1: Define a Product
• Step 2: Register a Device
• Step 3: Configure Data Forwarding Rules
• Step 4: Debug the Device

Prerequisites

Before performing this operation, complete the following preparations:

Step 1: Define a Product

A product is a device model. You can define a product to determine the function attributes of a device. Each device belongs to a product.

1. Create an integration application.
   1. Log in to the ROMA Connect console. On the Instances page, click View Console next to a specific instance.
   2. In the navigation pane on the left, choose Integration Applications. In the upper right corner of the page, click Create Integration Application.
   3. In the dialog box displayed, set Name and Description, and click OK.
2. Create a product.
   1. In the navigation pane on the left, choose LINK > Product Management. On the page displayed, click Create Product in the upper right corner.
   2. In the Create Product dialog box, set product parameters and click OK.

      Table 1 Parameters for creating a product

      Parameter	Description
      Product Type	Select Common as the product type.
      Protocol Type	Select MQTT as the protocol type.
      Integration Application	Select the integration application created in 1.
      Product Template	You do not need to set this parameter.
      Product Name	Enter a product name, which can be user-defined.
      Manufacturer Name	Enter a manufacturer name of the device, which can be user-defined.
      Manufacturer ID	Enter a manufacturer ID of the device, which can be user-defined.
      Product Model	Enter a product model of the device, which can be user-defined.
      Device Type	Select Default Type as the type of the access device.
      Model Version	Enter a device model version, which can be user-defined.
      Description	Enter a brief description of the product.

3. Add a thing model service for the product.
   1. On the Product Management page, click the Products tab and click the name of the product created in 2 to access the product details page.
   2. On the Thing Model tab page, click Create.
   3. In the Create Thing Model Service dialog box, set thing model service parameters and click OK.
      Assume that the device is a temperature sensor. Create a temperature service Temperature for the product.

      Table 2 Parameters for creating a thing model service

      Parameter	Description
      Name	Enter Temperature as the name of the thing model service.
      Status	This parameter specifies whether to enable the thing model service. Retain the default value, that is, the thing model service is enabled.
      Description	Enter a brief description of the thing model service.

4. Add an attribute for the thing model service.
   1. In the left pane of the Thing Model tab page, select the thing model service added in 3.
   2. On the Attributes tab page, click Create.
   3. In the Create Attribute dialog box, set attribute parameters and click OK.
      Assume that the device reports only the attribute temperature whose data type is String.

      Table 3 Parameters for creating an attribute

      Parameter	Description
      Name	Enter temperature as the attribute name.
      Data Type	Select String as the data type of the attribute parameter reported by the device.
      Mandatory	This parameter specifies whether the attribute must be reported by a device. Retain the default value, that is, the attribute must be reported by a device.
      Description	Enter a brief description of the attribute.
      Data Length	Enter 32 as the maximum length of the attribute value.
      Enumerated Value	You do not need to set this parameter.

5. Add a command for the thing model service.
   1. On the Commands tab page, click Create.
   2. In the Create Command dialog box, set command parameters and click OK.
      Assume that a device has the SET_STATUS command for setting the status, the command field is status, the data type is String, and the enumerated values are on and off.

      Table 4 Parameters for creating a command

      Parameter	Description
      Name	Enter SET_STATUS as the command name.
      Description	Enter a brief description of the command.

   3. Locate the created command in the command list and click on the left of the command name to expand the command fields.
   4. Click Create Field.
   5. In the Create Delivery Command Field dialog box, set field parameters and click OK.

      Table 5 Parameters for creating a command field

      Parameter	Description
      Name	Enter status as the command field name.
      Data Type	Select String as the data type of the command field.
      Mandatory	This parameter specifies whether the field must be carried in a delivered command. Retain the default value.
      Description	Enter a brief description of the command field.
      Data Length	Enter 32 as the maximum length of the command field value.
      Enumerated Value	Set this parameter to on,off, indicating that the device can be enabled or disabled.

Step 2: Register a Device

After a device is registered with ROMA Connect, a unique ID and key are allocated to the device so that the device can connect to ROMA Connect.

1. In the navigation pane on the left, choose LINK > Device Management. On the page displayed, click Create Device in the upper right corner.
2. In the Create Device dialog box, set device parameters and click OK.

   Table 6 Parameters for creating a device

   Parameter	Description
   Integration Application	Select the integration application created in 1.
   Associated Product	Select the product created in Step 1: Define a Product.
   Device ID	Enter a device ID, which is the unique identifier of the device and can be user-defined.
   Device Name	Enter a device name, which can be user-defined.
   Password	Enter the access password of the device. If you do not specify this parameter, the system automatically generates a value.
   Confirm Password	Enter the confirm password of the device. If you do not specify this parameter, the system automatically generates a value.
   Status	This parameter specifies whether to enable the device. The device can connect to ROMA Connect only after being enabled. Retain the default value, that is, the device is enabled.
   Device Tag	You do not need to set this parameter.
   Description	Enter a brief description of the device.

3. On the Device Management page, click the name of the created device to access the device details page. On the Topics tab page, view the topic information about the device.

Step 3: Configure Data Forwarding Rules

ROMA Connect does not directly store data reported by devices. You need to configure data forwarding rules to forward device data to other services for storage. The following section uses ROMA Connect MQS as an example to describe how to forward data to the destination.

1. In the navigation pane on the left, choose LINK > Rule Engine. On the page displayed, click Create Rule in the upper right corner.
2. In the Create Rule dialog box, set rule parameters and click OK.
   Figure 1 Creating a rule
   

   Table 7 Rule parameters

   Parameter	Description
   Application Name	Select the integration application created in 1.
   Name	Enter a rule name, which can be user-defined.
   Description	Enter a brief description of the rule.
   Status	This parameter specifies whether to enable the rule. Retain the default value, that is, the rule is enabled.

3. In the rule list, click the name of the rule created in 2 to access the rule details page.
4. In the Source area, click Create Source, set related parameters and click Save.
   Figure 2 Creating a source
   

   Table 8 Source parameters

   Parameter	Description
   Product Name	Select the product created in Step 1: Define a Product.
   Device Name	Select the device created in Step 2: Register a Device.
   Topic Name	Select the topic to which the device sends messages. The topic name is in the format of {Product ID}/out/{Device ID}.
   Topic Level	Select a topic level. The value is automatically adapted based on the value of Device Name. If you do not specify Device Name, Topic Level is Product. If you select a specific device from the Device Name drop-down list box, Topic Level is Device.
   Base64 Encoding	Specifies whether Base64 encoding is performed on the forwarded device data. You do not need to enable this option.
   Include Device Data	Specifies whether the forwarded data includes device data. To facilitate subsequent identification of the device to which the forwarded data belongs, enable this option.

5. In the Destination area, click Create Destination, set related parameters and click Save.
   Figure 3 Creating a destination
   

   Table 9 Destination parameters

   Parameter	Description
   Destination	Select ROMA MQS to integrate messages forwarded to ROMA Connect MQS.
   Connection Address	Select the MQS intranet address of the current ROMA Connect instance. You can view the address on the Instance Information page of the ROMA Connect console.
   Topic Name	Select the topic created for message integration in Prerequisites.
   Username	This parameter is available only if MQS SASL_SSL is enabled for the ROMA Connect instance. Enter the key of the integration application to which the topic defined in Topic Name belongs.
   Password	This parameter is available only if MQS SASL_SSL is enabled for the ROMA Connect instance. Enter the secret of the integration application to which the topic defined in Topic Name belongs.

Step 4: Debug the Device

A device can access ROMA Connect by integrating the MQTT.fx client or SDK. Use the MQTT.fx client to simulate a device to connect and send messages to ROMA Connect.

1. Obtain device access information.

   In the device list on the Device Management page, view and record the values of MQTT Connection Address, Client ID, Username, and Password of the device created in Step 2: Register a Device.

   Figure 4 Device access information
   
2. Open the MQTT.fx client installed on your local PC and click on the client.
   Figure 5 MQTT.fx client
   
3. On the page for editing connection attributes, enter the connection attribute configuration information and click OK.
   Figure 6 Configuring connection attributes
   

   Table 10 Connection attribute configuration

   Parameter	Description
   Profile Name	Enter a name for the connection configuration.
   Profile Type	Select MQTT Broker.
   Broker Address	Enter the IP address in MQTT Connection Address obtained in 1.
   Broker Port	Enter the port number in MQTT Connection Address obtained in 1.
   Client ID	Enter the client ID obtained in 1.
   User Credentials - User Name	Enter the username obtained in 1.
   User Credentials - Password	Enter the password obtained in 1.

4. Click Connect to connect to ROMA Connect.

   If the connection is successful, the connection status in the upper right corner of the MQTT.fx client will be displayed in green. On the ROMA Connect console, choose LINK > Device Management. On the page displayed, Status of the device will be displayed as Online.

   Figure 7 Device online
   
5. Enable the device to send data to ROMA Connect.
   1. On the MQTT.fx client, click the Publish tab, enter the device topic and message content, and click Publish to send a message to ROMA Connect.
      • Enter the topic of the message sent by the device in the text box on the left of the Publish button. The topic name is in the format of {Product ID}/out/{Device ID}. You can choose LINK > Device Management on the ROMA Connect console to view the topic.
      • Enter the message content in JSON format in the message text box.
      Figure 8 Enabling a device to send a message
      
   2. On the ROMA Connect console, choose Message Queue Service > Message Query.
   3. Click Advanced Search to expand advanced search options.
   4. Enter search criteria and click Search to query the messages sent by the client.
      • Select the message topic created in Step 3: Configure Data Forwarding Rules for Topic Name.
      • Select Creation time for Search By and select the time segment for the device to send messages to ROMA Connect.
   5. Click Message Body and check whether the value of the data field in the message reported by the device is the same as that sent by the MQTT.fx client.
      Figure 9 Viewing the message body
      
6. Enable the device to receive a command from ROMA Connect.
   1. On the MQTT.fx client, click the Subscribe tab, enter the topic (in the format of /v1/devices/{Device ID}/command) of the command delivery request, and click Subscribe.

      You can choose LINK > Device Management on the ROMA Connect console to view the topic.

      Figure 10 Subscribing to device messages
      
   2. On the ROMA Connect instance console, choose LINK > Device Management. In the Operation column of the device, choose More > Deliver Command.
   3. In the Deliver Command dialog box, set the command to be delivered and click OK.
      Figure 11 Delivering a command
      

      Table 11 Parameters for delivering a command

      Parameter	Description
      Thing Model Service	Select the thing model service added in 3. In this example, select Temperature.
      Synchronous Communication	Retain the default value Disable.
      Command	Select the command added in 5. In this example, select SET_STATUS.
      status	This parameter varies according to the command field added in 5. In this example, the status field is displayed and set to on, indicating that the device is enabled.

   4. On the Subscribe tab page of the MQTT.fx client, you can view the command delivered by ROMA Connect to the device. Check whether the values of cmd and paras in the command are the same as those set on the ROMA Connect console.
      Figure 12 Command received by the device