更新时间:2025-06-18 GMT+08:00

鸿蒙设备管理

概述

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

软总线通过封装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。主要接口如下:

表14 SDK主要接口

子函数名称

描述

IOTA_ReportDeviceInfo

上报设备信息,包括设备IP及软、硬件版本号等。

IOTA_SetEventCallback

配置事件下发回调函数。

IOTA_PropertiesSetResponse

响应平台下发软总线数据。

IOTA_GetLatestSoftBusInfo

设备获取最新软总线信息。

getSoftBusTotal

获取平台最新软总线信息解析后数据。是IOTA_GetLatestSoftBusInfo运行后平台返回值解析后的结构体数据。

SDK套件使用说明

在鸿蒙系统中,本身具备软总线近端互联能力,使用时可以直接调用对应的初始化接口,通过华为云SDK获取到连接信息后,使用该信息初始化。