# 鸿蒙设备管理 #### 概述 鸿蒙分布式软总线是一种可以将不同设备利用局域网串联，实现设备内和设备间高吞吐、低时延、高可靠的流畅连接体验，为设备互联互通提供了统一的分布式通信能力。实现近场设备间统一的分布式通信能力，提供不区分链路的设备发现和传输接口，具备快速发现并连接设备，高效分发任务和传输数据的能力。对开发者而言，无需关注组网方式与底层协议。 软总线通过封装openHarmony安全子系统deviceauth组件提供的能力，实现了一组可用于设备间快速建立可信认证和连接的接口；在这基础上，为了更安全可靠的管理设备间互联的关系网，IoTDA平台可以通过预先定义并下发关系网，完成设备间的认证。 图1鸿蒙软总线流程图 ![](https://support.huaweicloud.com/usermanual-iothub/figure/zh-cn_image_0000002180115562.png "点击放大") #### 设备前提条件 1. 使用鸿蒙系统。 2. 可以与IoT平台进行MQTT协议通信。 #### 业务流程 图2鸿蒙软总线业务流程 ![](https://support.huaweicloud.com/usermanual-iothub/figure/zh-cn_image_0000002179959374.png "点击放大") 1. 创建鸿蒙群组：可以在IoTDA控制台界面创建软总线连接群组，通过该群组管理设备互联关系网。 2. 设备鉴权：设备侧发起MQTT/MQTTS协议设备鉴权。 3. 上报设备信息：客户端上线后，需要上报设备信息，比如说：软硬件版本、设备IP等信息。 4. 云端下发群组列表及PIN码：鉴权成功后，平台会主动下发对应的群组列表及PIN。 5. 响应：若是设备侧成功接收到软总线列表，需要返回响应，否则会导致云端重复下发。 6. 设备主动获取最新软总线信息：设备通过API接口主动查询软总线信息。 7. 平台返回最新软总线信息：当发起[6]的时候，平台会返回查询结果。 8. 使用云端下发PIN初始化软总线：云端下发PIN码包括群组中的设备ID及IP，以及连接密钥。 9. 校验客户端PIN码：通过校验连接密钥确定是否该设备有连接权限，可用于确保鸿蒙群组安全性。 10. 返回初始化结果：返回软总线初始化结果。 #### 设备鉴权\&上报设备信息 1. 在使用设备接入服务前，需要先进行设备注册，设备注册指南：[注册设备](https://support.huaweicloud.com/usermanual-iothub/iot_01_0028.html)。 2. 注册好设备后，客户端通过MQTT协议进行设备鉴权，鉴权指南：[使用MQTT.fx进行消息收发](https://support.huaweicloud.com/qs-iothub/iot_05_0010.html)。 3. 设备侧可以通过该接口上报设备信息，具体接口信息可见：[设备信息上报](https://support.huaweicloud.com/api-iothub/iot_06_v5_3042.html)。 #### 创建鸿蒙群组 1. 访问[设备接入服务](https://www.huaweicloud.com/product/iothub.html)，单击"管理控制台"进入设备接入控制台。选择您的实例，单击实例卡片进入。 2. 在左侧导航栏选择" 设备 \> 群组"，选择注册设备的所属资源空间，单击"添加根群组"，在弹出的页面中选择"静态群组"，群组名称可自定义，单击"确定"。 图3群组-添加静态群组 ![](https://support.huaweicloud.com/usermanual-iothub/figure/zh-cn_image_0000002186342158.png "点击放大") 3. 单击创建的群组名称，单击"绑定"，选择需要联动在一起的设备，单击"确定"。 图4群组-群组绑定设备 ![](https://support.huaweicloud.com/usermanual-iothub/figure/zh-cn_image_0000002186502106.png "点击放大") 4. 绑定成功后，创建鸿蒙软总线，单击"点击创建"，填入鸿蒙软总线名称，单击"确定"。 图5群组-创建鸿蒙软总线 ![](https://support.huaweicloud.com/usermanual-iothub/figure/zh-cn_image_0000002221600037.png "点击放大") 5. 创建成功后可以在平台看到软总线同步状态。其中，鸿蒙软总线的密钥是平台随机生成的。当群组中设备上线时会自动下发，也可以手动单击页面中的"同步鸿蒙软总线"进行下发。 图6群组-鸿蒙软总线配置 ![](https://support.huaweicloud.com/usermanual-iothub/figure/zh-cn_image_0000002221601121.png "点击放大") #### 云端下发软总线群组列表及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\ | **参数解释：** 事件服务列表。 | 表2ServiceEvent定义表 | 字段名 | 必选/可选 | 类型 | 参数描述 | |:---|:---|:---|:---| | service_id | 必选 | String | **参数解释：** 系统字段。 **取值范围：** 固定为："$oh_soft_bus"。 | | properties | 必选 | String | **参数解释：** 事件参数JSON对象。 | 表3properties参数列表 | 字段名 | 必选/可选 | 类型 | 参数描述 | |:---|:---|:---|:---| | 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\ | **参数解释：** 事件服务列表。 | 表6ServiceEvent定义表 | 字段名 | 必选/可选 | 类型 | 参数描述 | |:---|:---|:---|:---| | 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对象。 | 表7paras参数 | 字段名 | 必选/可选 | 类型 | 参数描述 | |:---|:---|:---|:---| | 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\ | **参数解释：** 事件服务列表。 | 表9ServiceEvent定义表 | 字段名 | 必选/可选 | 类型 | 参数描述 | |:---|:---|:---|:---| | 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对象。 | 表10paras参数列表 | 字段名 | 必选/可选 | 类型 | 参数描述 | |:---|:---|:---|:---| | bus_infos | 必选 | Object | **参数解释：** 软总线信息JSON列表。 | | bus_count | 必选 | Integer | **参数解释：** 软总线信息JSON列表个数。 | | error_info | 可选 | Object | **参数解释：** 错误信息JSON列表。当查询失败时下发该字段。 | 表11bus_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。 | 表12devices_info参数列表 | 字段名 | 必选/可选 | 类型 | 参数描述 | |:---|:---|:---|:---| | device_id | 必选 | String | **参数解释：** 设备id。 | | device_ip | 必选 | String | **参数解释：** 设备IP。 | 表13error_info参数列表 | 字段名 | 必选/可选 | 类型 | 参数描述 | |:---|:---|:---|:---| | error_code | 必选 | String | **参数解释：** 错误码。 | | error_msg | 必选 | String | **参数解释：** 错误描述。 | #### 设备侧SDK使用说明 在鸿蒙SDK中，具有软总线代码demo，代码获取地址：[OpenHarmony-sdk-c](https://gitee.com/openharmony-sig/iot_device_sdk_c)。 在目录[src/softBus_demo](https://gitee.com/openharmony-sig/iot_device_sdk_c/blob/master/src/softBus_demo/soft_bus_test.c)中，有软总线代码demo，具体使用可见demo。主要接口如下： 表14SDK主要接口 | 子函数名称 | 描述 | |:---|:---| | IOTA_ReportDeviceInfo | 上报设备信息，包括设备IP及软、硬件版本号等。 | | IOTA_SetEventCallback | 配置事件下发回调函数。 | | IOTA_PropertiesSetResponse | 响应平台下发软总线数据。 | | IOTA_GetLatestSoftBusInfo | 设备获取最新软总线信息。 | | getSoftBusTotal | 获取平台最新软总线信息解析后数据。是IOTA_GetLatestSoftBusInfo运行后平台返回值解析后的结构体数据。 | #### SDK套件使用说明 在鸿蒙系统中，本身具备软总线近端互联能力，使用时可以直接调用对应的初始化接口，通过华为云SDK获取到连接信息后，使用该信息初始化。SDK套件若要与华为云设备侧SDK配套使用，需要实现以下接口：[src/dconncaseone_interface.c](https://gitee.com/openharmony-sig/iot_device_sdk_c/blob/master/src/dconncaseone_interface.c)。在鸿蒙系统中，有[分布式软总线组件](https://gitee.com/openharmony/communication_dsoftbus)，可使用对应接口编写到SDK中，以实现软总线功能。具体示例可见：[近端安全互联样例使用指导](https://gitee.com/openharmony-sig/knowledge/tree/master/demo/hihope_rk3568_dconnectcaseone#环境准备)。 #### 相关最佳实践 [基于BearPi-HM_Nano开发板和OpenHarmony对接IoTDA](https://support.huaweicloud.com/bestpractice-iothub/iot_bp_0079.html)