HarmonyOS Device Management

Overview

HarmonyOS distributed soft bus (DSoftBus) facilitates seamless intra-device and inter-device distributed communications by connecting various devices over a local area network (LAN). It ensures high throughput, reliability, and low latency. For nearby devices, DSoftBus offers device discovery and transport interfaces that streamline device connection, task distribution, and data transmission without the need for developers to manage networking modes or protocols.

The soft bus leverages the deviceauth component of the OpenHarmony security subsystem to create interfaces for efficiently establishing trusted authentication and connections between devices. To enhance the security and reliability of device relationships, IoTDA can be utilized to define and transmit the relationship network for seamless device authentication.

Figure 1 Usage of HarmonyOS DSoftBus

Device Requirements

1. The device uses HarmonyOS.
2. The device can communicate with the platform using MQTT.

Service Flow

Figure 2 HarmonyOS soft bus service process

1. Creating a HarmonyOS group: You create a soft bus connection group on the IoTDA console to manage the device interconnection network.
2. Authenticating the device: The device initiates MQTT/MQTTS device authentication.
3. Reporting device information: The client goes online and reports device information, such as the software and hardware versions and device IP address.
4. Delivering the group list from the cloud: After the authentication is successful, the platform delivers the corresponding group list and PIN.
5. Responding: If the device receives the soft bus list, it needs to return a response. Otherwise, the cloud will deliver the list repeatedly.
6. Obtaining the latest soft bus information: The device queries the soft bus information through the API.
7. Returning the latest soft bus information: When 6 occurs, the platform returns the query result.
8. Delivering the PIN data from the cloud to initialize the soft bus: The platform delivers the PIN data, including the device ID, IP address, and connection key.
9. Verifying the client PIN: The connection key is verified to check whether the device has the connection permission, enhancing security within the HarmonyOS group.
10. Returning the initialization result: The soft bus initialization result is returned.

Device Authentication and Information Reporting

1. You need to register a device before using IoTDA.
2. The client uses the MQTT protocol to authenticate the device. For details, see Using MQTT.fx to Send and Receive Messages.
3. The device reports device information through the API for reporting device information.

HarmonyOS Group Creation

1. Access the IoTDA service page and click Access Console. Click the target instance card.
2. In the navigation pane, choose Devices > Groups. On the displayed page, select the resource space to which the registered device belongs, and click Add Root Group. In the displayed dialog box, select Static and click OK.
   Figure 3 Group - Adding a static group
   
3. Click the name of the created group, click Bind, select the devices to be associated, and click OK.
   Figure 4 Group - Binding a device to a group
   
4. After the binding is successful, click the button for creating a HarmonyOS soft bus, enter the soft bus name, and click OK.
   Figure 5 Group - Creating a HarmonyOS soft bus
   
5. The soft bus synchronization status is displayed on the platform. The key of the soft bus is randomly generated by the platform. The settings are automatically delivered when devices in the group go online. You can also click the button for synchronization to manually deliver the settings.
   Figure 6 Group - Configuring the HarmonyOS soft bus
   

Soft Bus Group List and PIN Delivery from the Cloud

1. The platform automatically delivers the soft bus group list.
   Example format:

   Topic: $oc/devices/{device_id}/sys/properties/set/request_id={request_id}
   Data format:
   {
       "object_device_id": "{object_device_id} ",
       "services": [{
           "service_id": "$oh_soft_bus",
           "properties": {
               "bus_id1": {
                   "version": 1
               },
               "bus_id2": {
                   "version": 2
               }
           }
       }]
   }

   Table 1 Parameters for soft bus group list delivery from the cloud

   Parameter	Mandatory	Type	Description
   object_device_id	No	String	Explanation: For a gateway child device: The value is the child device ID in the topic. For a directly connected device: The value is the same that of device_id in the topic.
   services	No	List<ServiceEvent>	Explanation: List of services that an event is about.

   Table 2 ServiceEvent definition

   Parameter	Mandatory	Type	Description
   service_id	Yes	String	Explanation: System field. Value range: The value is fixed at $oh_soft_bus.
   properties	Yes	String	Explanation: Event parameters in JSON format.

   Table 3 properties parameters

   Parameter	Mandatory	Type	Description
   bus_id	Yes	String	Explanation: Soft bus ID.
   version	Yes	Object	Explanation: Version number. When a group is updated, the version number is increased by 1 and the initial version number is 0. If the group is deleted, the version number is -1.

2. The device responds to the automatic delivery of the soft bus group list from the cloud.

   Example format:

   Topic: $oc/devices/{device_id}/sys/properties/set/response/request_id={request_id}
   Data format:
   {
       "result_code": 0,
       "result_desc": "success" 
   }  

   Table 4 Response parameters

   Parameter	Mandatory	Type	Description
   result_code	No	Integer	Explanation: Execution result. 0 indicates success, and other values indicate failure. If this parameter is not carried, the execution is considered successful.
   result_desc	No	String	Explanation: Response description, which is user-defined.

Device Obtaining the Latest Soft Bus Information

After a device goes online, it can obtain the data of the soft bus through the corresponding API.

1. The device proactively obtains the latest soft bus information.

   Example:

   Topic: $oc/devices/{device_id}/sys/events/up 
   Data format:
   {
       "object_device_id": "{object_device_id}",
       "services": [{
           "service_id": "$oh_soft_bus",
           "event_type": "soft_bus_config_request",
           "event_time": "20151212T121212Z",
           "event_id": "40cc9ab1-3xxxxxxx-c18941c99eb4",
          "paras": {
                "bus_id":"04ed32xxxxxxxx3c01a27c2babc"
           }
       }]
   }

   Table 5 Parameters for the device to obtain the latest soft bus information

   Parameter	Mandatory	Type	Description
   object_device_id	No	String	Explanation: Mandatory when the child device reports data during the gateway device data reporting. Specify object_device_id as the child device ID of the device in the topic. Otherwise, the request fails. When a directly connected device reports data, the value of object_device_id must be the same as that of device_id in the topic. If this parameter is left blank, the value of this parameter is the same as that of device_id in the topic by default.
   services	No	List<ServiceEvent>	Explanation: List of services that an event is about.

   Table 6 ServiceEvent definition

   Parameter	Mandatory	Type	Description
   service_id	Yes	String	Explanation: System field. Value range: The value is fixed at $oh_soft_bus.
   event_type	Yes	String	Explanation: System field. Value range: The value is fixed at soft_bus_config_request.
   event_time	No	String	Explanation: Event time. UTC time format: yyyyMMdd'T'HHmmss'Z'. If this parameter is not carried in the reported data or is in incorrect format, the time when the platform receives the data is used.
   event_id	No	String	Explanation: Unique event ID. If this parameter is not carried, an event ID will be generated by the platform. An event ID is a random string of 36 characters consisting of letters, numbers, and hyphens (-).
   paras	Yes	Object	Explanation: Event parameters in JSON format.

   Table 7 paras parameters

   Parameter	Mandatory	Type	Description
   bus_id	No	String	Explanation: Soft bus ID. If this parameter is not carried, all soft bus information of the device is returned.

2. The platform returns the latest soft bus information.
   Normal query example:

   Topic: $oc/devices/{device_id}/sys/events/down  
   Data format:
   {
       "object_device_id": "{object_device_id}",
       "services": [{
           "service_id": "$oh_soft_bus",
           "event_type": "soft_bus_config_response",
           "event_time": "20151212T121212Z",
           "event_id": "40cc9ab1-3579-488c-95c6-c18941c99eb4",
           "paras": {
               "bus_infos": [{
                       "bus_id": "04ed32dc1b0025b52fe3c01a27c2babc",
                       "version": 2,
                       "bus_name": "GroupA",
                       "bus_key": "Y9BZ8fvnY9BZ8fvn1111",
                       "devices_info": [{
                           "device_id": "device_id1",
                           "device_ip": "127.0.0.1"
                       }, {
                           "device_id": "device_id2",
                           "device_ip": "127.0.0.2"
                       }],
                       "device_count": 2
                  }],
               "bus_count": 1            
           } 
       }]
   }

   Abnormal query example:

   {
       "object_device_id": "{object_device_id}",
       "services": [{
           "service_id": "$oh_soft_bus",
           "event_type": "soft_bus_config_response",
           "event_time": "20151212T121212Z",
           "event_id": "40cc9ab1-3579-488c-95c6-c18941c99eb4",
           "paras": {
               "bus_infos": [],
               "bus_count": 0,
               "error_info":{
                   "error_code": "IOTDA.003002",
                   "error_msg":"The soft bus group does not exist." 
              }
           }
       }]
   }

   Table 8 Parameters for the platform to return the latest soft bus information

   Parameter	Mandatory	Type	Description
   object_device_id	No	String	Explanation: For a gateway child device: The value is the child device ID in the topic. For a directly connected device: The value is the same that of device_id in the topic.
   services	No	List<ServiceEvent>	Explanation: List of services that an event is about.

   Table 9 ServiceEvent definition

   Parameter	Mandatory	Type	Description
   service_id	Yes	String	Explanation: System field. Value range: The value is fixed at $oh_soft_bus.
   event_type	Yes	String	Explanation: System field. Value range: The value is fixed at soft_bus_config_response.
   event_time	No	String	Explanation: Event time. UTC time format: yyyyMMdd'T'HHmmss'Z'.
   event_id	No	String	Explanation: Unique event ID. If this parameter is not carried, an event ID will be generated by the platform. An event ID is a random string of 36 characters consisting of letters, numbers, and hyphens (-).
   paras	Yes	Object	Explanation: Event parameters in JSON format.

   Table 10 paras parameters

   Parameter	Mandatory	Type	Description
   bus_infos	Yes	Object	Explanation: JSON list of soft bus information.
   bus_count	Yes	Integer	Explanation: Number of JSON lists for soft bus information.
   error_info	No	Object	Explanation: JSON list of error information. This field is delivered when the query fails.

   Table 11 bus_infos parameters

   Parameter	Mandatory	Type	Description
   bus_id	Yes	String	Explanation: Soft bus ID. If this parameter is not carried, all soft bus information of the device is returned.
   version	Yes	String	Explanation: Version number. When a group is updated, the version number is increased by 1 and the initial version number is 0. If the group is deleted, the version number is -1.
   bus_name	Yes	String	Explanation: Soft bus name.
   bus_key	Yes	String	Explanation: Key.
   devices_info	Yes	Object	Explanation: JSON list of group device information.
   device_count	Yes	Integer	Explanation: Number of devices in a group. Value range: 0 to 100.

   Table 12 devices_info parameters

   Parameter	Mandatory	Type	Description
   device_id	Yes	String	Explanation: Device ID.
   device_ip	Yes	String	Explanation: Device IP address.

   Table 13 error_info parameters

   Parameter	Mandatory	Type	Description
   error_code	Yes	String	Explanation: Error code.
   error_msg	Yes	String	Explanation: Error description.

Device-side SDK Usage

HarmonyOS SDKs provide soft bus code demos (OpenHarmony-sdk-c).

Directory: src/softBus_demo. The following table lists the main APIs.

SDK Suite Usage

HarmonyOS provides local interconnection capability of DSoftBus. By calling the initialization API through the Huawei Cloud SDK, you can obtain connection information and use it for initialization.