IoTDA管理鸿蒙设备

概述

鸿蒙分布式软总线是一种可以将不同设备利用局域网串联，实现设备内和设备间高吞吐、低时延、高可靠的流畅连接体验，为设备互联互通提供了统一的分布式通信能力。实现近场设备间统一的分布式通信能力，提供不区分链路的设备发现和传输接口，具备快速发现并连接设备，高效分发任务和传输数据的能力。对开发者而言，无需关注组网方式与底层协议。

软总线通过封装openHarmony安全子系统deviceauth组件提供的能力，实现了一组可用于设备间快速建立可信认证和连接的接口；在这基础上，为了更安全可靠的管理设备间互联的关系网，IoTDA平台可以通过预先定义并下发关系网，完成设备间的认证。

图1 鸿蒙软总线流程图

设备前提条件

1. 使用鸿蒙系统。
2. 可以与IoT平台进行MQTT协议通信。

业务流程

图2 鸿蒙软总线业务流程

1. 创建鸿蒙群组：可以在IoTDA控制台界面创建软总线连接群组，通过该群组管理设备互联关系网。
2. 设备鉴权：设备侧发起MQTT/MQTTS协议设备鉴权。
3. 上报设备信息：客户端上线后，需要上报设备信息，比如说：软硬件版本、设备IP等信息。
4. 云端下发群组列表及PIN码：鉴权成功后，平台会主动下发对应的群组列表及PIN。
5. 响应：若是设备侧成功接收到软总线列表，需要返回响应，否则会云端导致重复下发。
6. 设备主动获取最新软总线信息：设备通过API接口主动查询软总线信息。
7. 平台返回最新软总线信息：当发起6的时候，平台会返回查询结果。
8. 使用云端下发PIN初始软总线：云端下发PIN码包括群组中的设备ID及IP，以及连接密钥。
9. 校验客户端PIN码：通过校验连接密钥确定是否该设备有连接权限，可用于确保鸿蒙群组安全性。
10. 返回初始化结果：返回软总线初始化结果。

设备鉴权&上报设备信息

1. 在使用设备接入服务前，需要先进行设备注册，设备注册指南：注册设备。
2. 注册好设备后，客户端通过MQTT协议进行设备鉴权，鉴权指南：使用MQTT.fx进行消息收发。
3. 设备侧可以通过该接口上报设备信息，具体接口信息可见：设备信息上报 。

创建鸿蒙群组

1. 访问设备接入服务，单击“管理控制台”进入设备接入控制台。选择您的实例，单击实例卡片进入。
2. 在左侧导航栏选择“ 设备 > 群组”，选择注册设备的所属资源空间，单击“添加根群组”，在弹出的页面中选择“静态群组”，群组名称可自定义，单击“确定”。
   图3 群组-添加静态群组
   
3. 单击创建的群组名称，单击“绑定”，选择需要联动在一起的设备，单击“确定”。
   图4 群组-群组绑定设备
   
4. 绑定成功后，创建鸿蒙软总线，单击“点击创建”，填入鸿蒙软总线名称，单击“确定”。
   图5 群组-创建鸿蒙软总线
   
5. 创建成功后可以在平台看到软总线同步状态。其中，鸿蒙软总线的密钥是平台随机生成的。当群组中设备上线时会自动下发，也可以手动单击页面中的“同步鸿蒙软总线”进行下发。
   图6 群组-鸿蒙软总线配置
   

云端下发软总线群组列表及PIN码

1. 云端自动下发软总线群组列表。
   云端下发格式示例：

   Topic: $oc/devices/{device_id}/sys/properties/set/request_id={request_id}
   数据格式：
   {
       "object_device_id": "{object_device_id} ",
       "services": [{
           "service_id": "$oh_soft_bus",
           "properties": {
               "bus_id1": {
                   "version": 1
               },
               "bus_id2": {
                   "version": 2
               }
           }
       }]
   }

   表1 云端自动下发软总线群组列表参数说明

   字段名	必选/可选	类型	参数描述
   object_device_id	可选	String	参数解释： 平台下发时，若为网关子设备，该参数为Topic中设备的子设备Id。 平台下发时，若为直连设备，该参数会与Topic中的device_id一致。
   services	可选	List<ServiceEvent>	参数解释： 事件服务列表。

   表2 ServiceEvent定义表

   字段名	必选/可选	类型	参数描述
   service_id	必选	String	参数解释： 系统字段。 取值范围： 固定为："$oh_soft_bus"。
   properties	必选	String	参数解释： 事件参数JSON对象。

   表3 properties参数列表

   字段名	必选/可选	类型	参数描述
   bus_id	必选	String	参数解释： 软总线ID。
   version	必选	Object	参数解释： 版本号。当群组更新时，version版本+1，初始版本为0。若是该群组被删除，version版本为-1。

2. 设备侧响应云端自动下发软总线群组列表。

   设备响应格式示例：

   Topic：$oc/devices/{device_id}/sys/properties/set/response/request_id={request_id} 
   数据格式：   
   {
       "result_code": 0,
       "result_desc": "success" 
   }  

   表4 响应参数

   字段名	必选/可选	类型	参数描述
   result_code	可选	Integer	参数解释： 命令的执行结果，0表示成功，其他表示失败。不带默认认为成功。
   result_desc	可选	String	参数解释： 用户自定义，响应描述。

设备主动获取最新软总线信息

设备上线后，设备侧可以通过该接口主动获取软总线的数据信息。

1. 设备主动获取最新软总线信息。

   设备获取软总线信息API示例：

   Topic: $oc/devices/{device_id}/sys/events/up 
   数据格式：   
   {
       "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"
           }
       }]
   }

   表5 设备主动获取最新软总线信息参数

   字段名	必选/可选	类型	参数描述
   object_device_id	可选	String	参数解释： 网关设备上报时，子设备进行上报需填写该参数。object_device_id为Topic中设备的子设备Id，否则将请求失败。 直连设备上报时，object_device_id需与Topic中的device_id一致。 若为空则默认该参数与Topic中的device_id一致。
   services	可选	List<ServiceEvent>	参数解释： 事件服务列表。

   表6 ServiceEvent定义表

   字段名	必选/可选	类型	参数描述
   service_id	必选	String	参数解释： 系统字段。 取值范围： 固定为："$oh_soft_bus"。
   event_type	必选	String	参数解释： 系统字段。 取值范围： 固定为："soft_bus_config_request"。
   event_time	可选	String	参数解释： 事件时间。UTC时间，格式：yyyyMMdd'T'HHmmss'Z'。 设备上报数据不带该参数或参数格式错误时，则数据上报时间以平台时间为准。
   event_id	可选	String	参数解释： 事件请求Id，唯一标识这次事件请求。如果不携带该参数，该参数由物联网平台自动生成，生成规则为数字、字母、中划线组成的36位随机字符串。
   paras	必选	Object	参数解释： 事件参数JSON对象。

   表7 paras参数

   字段名	必选/可选	类型	参数描述
   bus_id	可选	String	参数解释： 软总线ID。若不携带，返回该设备涉及的所有软总线信息。

2. 平台返回最新软总线信息。
   查询正常示例：

   Topic: $oc/devices/{device_id}/sys/events/down  
   数据格式为：
   {
       "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            
           } 
       }]
   }

   查询异常示例：

   {
       "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." 
              }
           }
       }]
   }

   表8 平台返回最新软总线信息参数说明

   字段名	必选/可选	类型	参数描述
   object_device_id	可选	String	参数解释： 平台下发时，若为网关子设备，该参数为Topic中设备的子设备Id。 平台下发时，若为直连设备，该参数会与Topic中的device_id一致。
   services	可选	List<ServiceEvent>	参数解释： 事件服务列表。

   表9 ServiceEvent定义表

   字段名	必选/可选	类型	参数描述
   service_id	必选	String	参数解释： 系统字段。 取值范围： 固定为："$oh_soft_bus"。
   event_type	必选	String	参数解释： 系统字段。 取值范围： 固定为："soft_bus_config_response"。
   event_time	可选	String	参数解释： 事件时间。UTC时间，格式：yyyyMMdd'T'HHmmss'Z'。
   event_id	可选	String	参数解释： 事件请求Id，唯一标识这次事件请求。如果不携带该参数，该参数由物联网平台自动生成，生成规则为数字、字母、中划线组成的36位随机字符串。
   paras	必选	Object	参数解释： 事件参数JSON对象。

   表10 paras参数列表

   字段名	必选/可选	类型	参数描述
   bus_infos	必选	Object	参数解释： 软总线信息JSON列表。
   bus_count	必选	Integer	参数解释： 软总线信息JSON列表个数。
   error_info	可选	Object	参数解释： 错误信息JSON列表。当查询失败时下发该字段。

   表11 bus_infos参数列表

   字段名	必选/可选	类型	参数描述
   bus_id	必选	String	参数解释： 软总线ID。若不携带，返回该设备涉及的所有软总线信息。
   version	必选	String	参数解释： 版本号。当群组更新时，version版本+1，初始版本为0。若是该群组被删除，version版本为-1。
   bus_name	必选	String	参数解释： 软总线名称。
   bus_key	必选	String	参数解释： 密钥。
   devices_info	必选	Object	参数解释： 群组设备信息JSON列表。
   device_count	必选	Integer	参数解释： 群组中设备个数。 取值范围： 0-100。

   表12 devices_info参数列表

   字段名	必选/可选	类型	参数描述
   device_id	必选	String	参数解释： 设备id。
   device_ip	必选	String	参数解释： 设备IP。

   表13 error_info参数列表

   字段名	必选/可选	类型	参数描述
   error_code	必选	String	参数解释： 错误码。
   error_msg	必选	String	参数解释： 错误描述。

设备侧SDK使用说明

在鸿蒙SDK中，具有软总线代码demo，代码获取地址：OpenHarmony-sdk-c。

在目录src/softBus_demo中，有软总线代码demo，具体使用可见demo。主要接口如下：

SDK套件使用说明

在鸿蒙系统中，本身具备软总线近端互联能力，使用时可以直接调用对应的初始化接口，通过华为云SDK获取到连接信息后，使用该信息初始化。SDK套件若要与华为云设备侧SDK配套使用，需要实现以下接口：src/dconncaseone_interface.c。在鸿蒙系统中，有分布式软总线组件，可使用对应接口编写到SDK中，以实现软总线功能。具体示例可见：近端安全互联样例使用指导。