Developing an MQTT-based Smart Street Light Online

Scenarios

This topic uses a smart street lamp as an example to describe how to use MQTT.fx device simulators to experience data reporting and command delivery.

Assume that:

A street light reports the light intensity (luminance) in JSON format. The command (switch) can be used to remotely control the street light status.

Prerequisites

• You have registered a Huawei Cloud account. If you have not registered, click here to complete the registration.
• You have subscribed to the IoTDA service. If you have not subscribed to the service, go to the IoTDA service page, and click Access Console to subscribe to the service.

Service Flow

The MQTT.fx simulator is used as an example to describe data reporting and command delivery.

Creating a Product

1. Log in to the console, choose Products in the navigation pane, and click Create Product in the upper right corner.
2. Set the parameters as prompted and click OK.

   Basic Information
   Resource Space	The platform automatically allocates the created product to the default resource space. If you want to allocate the product to another resource space, select the resource space from the drop-down list. If a resource space does not exist, create it first.
   Product Name	Customize the value. The name can contain letters, numbers, underscores (_), and hyphens (-).
   Protocol	Select MQTT.
   Data Type	Select JSON.
   Manufacturer	Customize the value. The name can contain letters, numbers, underscores (_), and hyphens (-).
   Industry	Select the industry to which the product model belongs.
   Device Type	If the product model preset on the platform is used, the device type is automatically matched.
   Advanced Settings
   Product ID	Set a unique identifier for the product. If this parameter is specified, the platform uses the specified product ID. If this parameter is not specified, the platform allocates a product ID.
   Description	Provide a description for the product. Set this parameter based on the site requirements.

Developing a Product Model

1. Click the product created in Creating a Product. The product details page is displayed.
2. On the Model Definition tab page of the product details page, click Custom Model to add services of the product.
3. Add the BasicData service.
   1. On the Add Service page, configure Service ID, Service Type, and Description, and click OK.
      • Service ID: Enter BasicData.
      • Service Type: You are advised to set this parameter to the same value as Service ID.
      • Description: Enter Reports street light data.
   2. In the BasicData service list on the right, click Add Property, enter related information, and click OK.
      • Property Name: Enter luminance.
      • Description: Enter light intensity.
      • Data Type: Select Integer.
      • Access Permissions: Select Read and Write.
      • Value Range: Set it to 0–65535.
      • Step: Enter 0.
      • Unit: Leave it blank.

4. Add the LightControl service.
   1. On the Model Definition tab page, click Add Service, configure Service ID, Service Type, and Description, and click OK.
      • Service ID: Enter LightControl.
      • Service Type: You are advised to set this parameter to the same value as Service ID.
      • Description: Enter Controls the street light.
   2. Choose LightControl, click Add Command, and enter the command name Switch.
   3. On the Add Command page, click Add Command Parameter, enter related information, and click OK.
      Figure 1 Adding a parameter
      

Registering a Device

1. On the management console, choose Devices > All Devices in the navigation pane, and click Individual Register in the upper right corner.
2. Set the parameters as prompted and click OK.

   Parameter	Description
   Resource Space	Ensure that the device and the product created in 1 belong to the same resource space.
   Product	Select the product created in 2.
   Node ID	Customize a unique physical identifier for the device. The value consists of letters and numbers.
   Device Name	Customize a device name, for example, streetlight.
   Authentication Type	Select Secret.
   Secret	If you do not set this parameter, IoTDA automatically generates a value.

   

   After the device is registered, the platform automatically generates a device ID and secret. Save the device ID and secret for device access.

   

Performing Connection Authentication

Use MQTT.fx to activate the device registered on IoTDA.

1. Download MQTT.fx (64-bit OS) or MQTT.fx (32-bit OS) and install it.
2. Go to the IoTDA client ID generator page, enter the device ID and secret generated after registering a device to generate connection information (including ClientId, Username, and Password).

   

   Parameter	Mandatory	Type	Description
   ClientId	Yes	String(256)	The value of this parameter consists of a device ID, device type, password signature type, and timestamp. They are separated by underscores (_). Device ID: A device ID uniquely identifies a device and is generated when the device is registered with IoTDA. The value usually consists of a device's product ID and node ID which are separated by an underscore (_). Device type: The value is fixed at 0, indicating a device ID. Password signature type: The length is 1 byte, and the value can be 0 or 1. 0: The timestamp is not verified using the HMAC-SHA256 algorithm. 1: The timestamp is verified using the HMAC-SHA256 algorithm. Timestamp: The UTC time when the device was connected to IoTDA. The format is YYYYMMDDHH. For example, if the UTC time is 2018/7/24 17:56:20, the timestamp is 2018072417.
   Username	Yes	String(256)	Device ID.
   Password	Yes	String(256)	Encrypted device secret. The value of this parameter is the device secret encrypted by using the HMAC-SHA256 algorithm with the timestamp as the key. The device secret is returned by IoTDA upon successful device registration.

   Each device performs authentication using the MQTT CONNECT message, which must contain all information of the client ID. After receiving a CONNECT message, IoTDA checks the authentication type and password digest algorithm of the device.

   The generated client ID is in the format Device ID_0_0_Timestamp. By default, the timestamp is not verified.

   • If the timestamp needs to be verified using the HMAC-SHA256 algorithm, the platform checks whether the message timestamp is consistent with the platform time and then checks whether the password is correct.
   • If the timestamp does not need to be verified using the HMAC-SHA256 algorithm, the timestamp must also be contained in the CONNECT message, but the platform does not check whether the time is correct. In this case, only the password is checked.

   If the authentication fails, the platform returns an error message and automatically disconnects the MQTT connections.

3. Open the MQTT.fx tool and click the setting icon.

   

4. Configure authentication parameters and click Apply.

   

   Parameter	Description
   Broker Address	Enter the device access address (domain name) obtained from the IoTDA console. For devices that cannot be connected to the platform using a domain name, run the ping Domain name command in the CLI to obtain the IP address. The IP address is variable and needs to be set using a configuration item.
   Broker Port	The default value is 1883.
   Cliend ID	Enter the device ClientId obtained in 2.
   User Name	Enter the DeviceId obtained in 2.
   Password	Enter the encrypted device secret obtained in 2.

5. Click Connect. If the device authentication is successful, the device is displayed online on the platform.

   

Reporting Data

Use MQTT.fx to report data to IoTDA.

If the device reports data through the MQTT channel, the data needs to be sent to a specific topic in the format $oc/devices/{device_id}/sys/properties/report. For devices that each has a different secret, set device_id to the device ID returned upon successful device registration.

1. Enter the API address in the format of "$oc/devices/{device_id}/sys/properties/report", for example, $oc/devices/5e4e2e92ac-164aefa8fouquan1/sys/properties/report.

   

2. Enter the reported data in the blank in the middle of the tool interface.

   Request parameters

   Parameter	Mandatory	Type	Description
   services	Yes	List<ServiceProperty>	Service data list. (For details, see the ServiceProperty structure below.)

   ServiceProperty structure

   Parameter	Mandatory	Type	Description
   service_id	Yes	String	Service ID.
   properties	Yes	Object	Service properties, which are defined in the product model of the device.
   eventTime	No	String	UTC time when the device reports data. The format is yyyyMMddTHHmmssZ, for example, 20161219T114920Z. If this parameter is not carried in the reported data or is in incorrect format, the time when IoTDA receives the data is used.

   Example request

   {
       "services": [{
               "service_id": "BasicData",
               "properties": {
                   "luminance": 30
           }
         }
      ]
   }

3. Click Publish. Then you can check whether the device successfully reports data on the platform.

   

Delivering a Command

Deliver a command on the management console to remotely control a device.

1. In the navigation pane, choose Devices > All Devices, locate the device created in Registering a Device, and click View to access its details.
2. Click the Commands tab and deliver a synchronization command.

   

   

   MQTT devices support only synchronous command delivery. NB-IoT devices support only asynchronous command delivery.

3. In the MQTT.fx simulator, select Subscribe and enter the command delivery topic. After the subscription, you can view the delivered command parameters.
   

   

   • Use the MQTT.fx simulator to view the delivered command parameters. The command delivery topic is in the format of $oc/devices/{device_id}/sys/commands/#, where {device_id} indicates the value of deviceId returned after the device is registered successfully.
   • If the system displays a message indicating that the command delivery fails, the device needs to respond to the synchronization command in a timely manner. For details about the response content, see Platform Delivering a Command.

Advanced Experience

After using MQTT.fx to connect a simulated MQTT device to the platform, you may understand how the MQTT device interacts with the platform through open APIs.

To better experience the IoTDA service, develop real-world applications and devices and connect them to the platform. For details, see Developer Guide.