小度音箱对接之DuerOS开放平台智能家居技能协议分析

最新推荐文章于 2025-10-25 19:35:17 发布

原创

最新推荐文章于 2025-10-25 19:35:17 发布 · 7.7k 阅读

20 ·

CC 4.0 BY-SA版权

文章标签：

#小度 #DuerOS

本文详细解析了DuerOS开放平台中的智能家居技能协议，包括发现设备、控制消息、查询消息、错误消息、设备属性主动上报等核心内容，帮助开发者理解和应用DuerOS智能家居技能。

本文，旨在分析DuerOS开放平台中智能家居技能协议。
参考的官方地址： https://dueros.baidu.com/didp/doc/dueros-bot-platform/dbp-smart-home/protocol/intro-protocol_markdown
文中仅摘取了几条协议举例，具体参照官方文档。

文章目录

协议简介

智能家居协议是DuerOS与智能家居技能之间的通讯协议。通过这些协议您可以轻松的通过语音控制家里的智能设备，与设备进行交互。
智能家居协议使用HTTPS传输，协议采用JSON消息格式。

协议格式

智能家居协议指令（directives）由Header和Payload两部分组成。

举例如下：

{
   
   
    "header": {
   
   
        "namespace": "DuerOS.ConnectedHome.Control",
        "name": "TurnOnRequest",
        "messageId": "01ebf625-0b89-4c4d-b3aa-32340e894688",
        "payloadVersion": "1"
    },
    "payload": {
   
   
        "accessToken": "[OAuth token here]",
        "appliance": {
   
   
            "additionalApplianceDetails": {
   
   },
            "applianceId": "[Device ID for Light]"
        },
        "function": "light"
    }
}

Header信息

Header包含消息标识符、指令名称、命令空间和payload版本信息。

消息格式

{
   
   
    "header": {
   
           
        "namespace": "DuerOS.ConnectedHome.Discovery",
        "name": "DiscoverAppliancesRequest",
        "messageId": "6d6d6e14-8aee-473e-8c24-0d31ff9c17a2",
        "payloadVersion": "1"
    }
}

属性说明

Header包含的属性及属性说明。

属性	属性说明	是否必须
namespace	指令的类别。目前支持的类别有： DuerOS.ConnectedHome.Discovery：发现设备指令。 DuerOS.ConnectedHome.Control：控制设备指令。 DuerOS.ConnectedHome.Query：查询设备指令。	是
name	指令的名称。	是
messageId	消息的唯一标识符，长度小于128个字符。 messageId仅用于标识消息，无其他使用。建议使用随机生成的UUID作为messageId。	是
payloadVersion	payload的版本号。	是

Payload信息

Payload的内容与Header中的name值相关，不同类型的指令，其payload内容也不相同。

举例如下：

{
   
   
    "payload": {
   
   
        "accessToken": "[OAuth token here]",
        "appliance": {
   
   
            "additionalApplianceDetails": {
   
   },
            "applianceId": "[Device ID for Light]"
        },
        "function": "light"
    }
}

协议详述

DuerOS对控制、查询、属性上报等消息进行了分类。根据不同的流程，使用不同的消息。

大致说明如下：

消息类型	说明	控制方向	举例
发现设备	小度平台向设备云发现用户的设备列表	小度–请求–>设备云	小度，发现设备
控制消息	用户对设备的控制类消息由小度音箱或APP发起，发送到设备云进行解析	小度–请求–>设备云	小度，打开油烟机小度，回家模式
查询消息	用户查询设备的状态数据由小度音箱或APP发起，发送到设备云进行解析	小度–请求–>设备云	小度，查询烟机风速小度，查询PM2.5
错误消息	控制、查询消息，操作失败时，响应给小度的错误消息	设备云–响应–>小度
设备属性主动上报	当手动或其他非小度平台操作了设备后，通知到小度有属性更新小度收到通知后，再向设备云请求设备属性信息。	设备云–请求–>小度小度–请求–>设备云
设备信息同步消息	用户设备信息发生变化时，通知给小度音箱	设备云–请求–>小度
技能解绑消息通知	当用户在技能商店解绑智能家居技能时，通知设备云	小度–请求–>设备云

发现设备

发现设备消息用于查找用户可用的设备、可以使用的场景和设备分组信息，有DiscoverAppliancesRequest和DiscoverAppliancesResponse两个指令。DiscoverAppliancesRequest指令是发出查找设备请求，DiscoverAppliancesResponse指令回复查找到的设备。如果你的技能应用中的用户设备信息变更时,可以通过DuerOS提供的异步接口发送通知，触发用户设备信息同步到DuerOS。

DiscoverAppliancesRequest

当用户查找设备时，DuerOS会将该消息发送给技能。另外，用户每次在DuerOS技能商店启用你的技能时，此消息会自动触发一次。

Header信息

属性	取值
name	DiscoverAppliancesRequest
namespace	DuerOS.ConnectedHome.Discovery

Payload信息

属性	描述	是否必须
accessToken	设备云端获取的access token。	是
openUid	被授权的百度账号开放ID，与设备云账号一一对应。设备云端需要将该字段与用户账号一一对应起来存储其它协议中如果需要携带openUid字段时，则需要返回用户账号对应的openUid值。	是

应用举例
当用户说“小度小度，发现设备”，DuerOS理解用户为发现设备意图时或者当用户在DuerOS技能商店里启用技能并授权完成之后会向技能发送该DiscoverAppliancesRequest消息。消息示例如下：

{
   
   
    "header": {
   
   
        "namespace": "DuerOS.ConnectedHome.Discovery",
        "name": "DiscoverAppliancesRequest",
        "messageId": "6d6d6e14-8aee-473e-8c24-0d31ff9c17a2",
        "payloadVersion": "1"
    },
    "payload": {
   
   
        "accessToken": "[OAuth Token here]",
        "openUid": "27a7d83c2d3cfbad5d387cd35f3ca17b"
    }
}

DiscoverAppliancesResponse

当DuerOS请求技能查找可用设备或可用场景时，技能会返回DiscoverAppliancesResponse消息。如果查找到设备时，会返回设备的相关信息，包括actions、applianceTypes、additionalApplianceDetails、applianceId、friendlyDescription、friendlyName等属性信息。如果没有找到设备时，会返回空数组。

Header信息

属性	取值
name	DiscoverAppliancesResponse
namespace	DuerOS.ConnectedHome.Discovery

Payload信息

1. 设备信息

属性	描述说明	是否必须
discoveredAppliances	以对象数组返回客户关联设备云帐户的设备、场景。如客户关联帐户没有设备、场景则返回空数组。如果在发现过程中出现错误，字段值设置为null, 用户允许接入的最大的设备数量是300。	是
discoveredAppliance.applianceTypes	支持的设备、场景类型。	是
discoveredAppliance.applianceId	设备标识符。标识符在用户拥有的所有设备上必须是唯一的。此外，标识符需要在同一设备的多个发现请求之