Device Reporting Properties

Overview

Property reporting is a method by which IoTDA parses, caches, and forwards data to applications or other Huawei Cloud services through data forwarding. Product models need to be established on the platform. The platform records the latest reported property value and stores the data that complies with the product model definition. The device can obtain the latest device properties from the platform through device shadow.

Figure 1 Device Reporting Properties

Scenarios

• Data of devices and applications needs to be converted, managed, and cached by the platform.
• Data needs to be forwarded to other Huawei Cloud services for storage and processing based on data forwarding rules.

Constraints

• Max. size of a single message: 64 KB.
• A product model is required. The reported data must match the properties defined in the product model.
• Max. child devices of which properties can be reported by a gateway at a time: 100.

Process

1. Product and device creation and product model definition: For details, see Creating a Product, Registering an Individual Device, and Product Model Definition.
2. Device authentication: The platform checks whether the device has the access permission.
3. Device property reporting: Devices report property data using protocols such as MQTT, HTTP, and LwM2M.

   Use different APIs for different protocols.

   • MQTT: Use the property reporting APIs for MQTT devices. The following is an example of reporting MQTT device property.

     Topic: $oc/devices/{device_id}/sys/properties/report
     Data format example:
     {
         "services": [
             {
                 "service_id": "Temperature",
                 "properties": {
                     "value": 57,
                     "value2": 60
                 }
             }
         ]
     }
   • HTTPS: Use the property reporting APIs for HTTP devices. To obtain access_token for HTTP devices, see Authenticating a Device. The following is an example of reporting HTTPS device property.

     POST https://{endpoint}/v5/devices/{device_id}/sys/properties/report 
     Content-Type: application/json 
     access_token: ******** 
     {
         "services": [
             {
                 "service_id": "serviceId",
                 "properties": {
                     "Height": 124,
                     "Speed": 23.24
                 }
             }
         ]
     }
   • LwM2M/CoAP: Use the property reporting APIs for devices using LwM2M over CoAP. The following is an example of property reporting for devices using LwM2M over CoAP.

     // Assume that the data content (value) reported by the device is c4 0d 5a 6e 96 0b c3 0e 2b 30 37.
      NON-2.05   MID=48590, Token=********, OptionSet={"Observe":22, "Content-Format":"application/octet-stream"}, c4 0d 5a 6e 96 0b c3 0e 2b 30 37
   NOTE:

   • The reported device properties must match the properties defined in the product model.
   • For details about devices using different protocols, see MQTT Device Reporting Properties, HTTP Device Reporting Properties, and LwM2M/CoAP Device Reporting Properties.

4. The platform stores the latest data snapshot. If the reported data complies with the product model definition, log in to the IoTDA console, choose Devices > All Devices, and select a device to access its details page. The latest data snapshot is displayed on the Device Info tab page. The following figure is as an example.
   Figure 3 Property reporting - Viewing data
   

5. Data forwarding: With the data forwarding function, data can be forwarded to applications or other Huawei Cloud services for storage and processing.

Property Reporting Using Java SDK

This section describes how to use Java SDKs for the development of property reporting. JDK 1.8 or later is used.

The reported properties must match the properties defined in the product model corresponding to the device. The following figure provides the information of the example product model used in the SDK code.

Figure 4 Model definition - smokeDetector

Configure the SDK on the device side:

1. Download an SDK.
2. Configure the Maven dependency of the SDK on devices.

   <dependency>
   	<groupId>com.huaweicloud</groupId>
   	<artifactId>iot-device-sdk-java</artifactId>
   	<version>1.1.4</version>
   </dependency>

3. Configure the SDK and device connection parameters on devices.

   // Load the CA certificate of the IoT platform. For details about how to obtain the certificate, visit https://support.huaweicloud.com/intl/en-us/devg-iothub/iot_02_1004.html.
   URL resource = BroadcastMessageSample.class.getClassLoader().getResource("ca.jks");
   File file = new File(resource.getPath());
   
   // The format is ssl://Domain name:Port number.
   // To obtain the domain name, log in to the Huawei Cloud IoTDA console. In the navigation pane, choose Overview and click Access Details in the Instance Information area. Select the access domain name corresponding to port 8883.
   String serverUrl = "ssl://localhost:8883";
   // Device ID created on the IoT platform
   String deviceId = "deviceId";
   // Secret corresponding to the device ID
   String deviceSecret = "secret";
   // Create a device.
   IoTDevice device = new IoTDevice(serverUrl, deviceId, deviceSecret, file);
   if (device.init() != 0) {
       return;
   }

4. Report device properties.

   Map<String ,Object> json = new HashMap<>();
   Random rand = new Random();
   
   // Set properties based on the product model.
   json.put("alarm", alarm);
   json.put("temperature", rand.nextFloat()*100.0f);
   json.put("humidity", rand.nextFloat()*100.0f);
   json.put("smokeConcentration", rand.nextFloat() * 100.0f);
   
   ServiceProperty serviceProperty = new ServiceProperty();
   serviceProperty.setProperties(json);
   serviceProperty.setServiceId("smokeDetector");// The service ID must be consistent with that defined in the product model.
   
   device.getClient().reportProperties(Arrays.asList(serviceProperty), new ActionListener() {
       @Override
       public void onSuccess(Object context) {
           log.info("reportProperties success" );
       }
   
       @Override
       public void onFailure(Object context, Throwable var2) {
           log.error("reportProperties failed" + var2.toString());
       }   
   });

Verify the setting:

1. Run the SDK code on the device. The following figure provides an example of the property reporting log.
   Figure 5 Java SDK property reporting result log
   

2. Log in to the IoTDA console, choose Devices > All Devices, and click a device to access its details page. The latest reported data is displayed on the Device Info tab page.
   Figure 6 Property reporting - Viewing data