发现设备

发现设备消息用于查找用户可用的设备、可以使用的场景和设备分组信息,有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信息

设备信息

属性 描述说明 是否必须
discoveredAppliances 以对象数组返回客户关联设备云帐户的设备、场景。如客户关联帐户没有设备、场景则返回空数组。如果在发现过程中出现错误,字段值设置为null, 用户允许接入的最大的设备数量是300。
discoveredAppliance.applianceTypes 支持的设备、场景类型。目前支持以下设备。
  • LIGHT:电灯类设备
  • SWITCH:开关类设备
  • SOCKET:插座类设备
  • CURTAIN:窗帘类设备
  • CURT_SIMP:窗纱类设备
  • AIR_CONDITION:空调类设备
  • TV_SET:电视机
  • SET_TOP_BOX:机顶盒
  • AIR_MONITOR:空气监测器类设备
  • AIR_PURIFIER:空气净化器
  • WATER_PURIFIER:净水器
  • HUMIDIFIER:加湿器
  • FAN:电风扇
  • WATER_HEATER:热水器类设备
  • HEATER:电暖器类设备
  • WASHING_MACHINE:洗衣机类设备
  • CLOTHES_RACK:晾衣架
  • GAS_STOVE:燃气灶类设备
  • RANGE_HOOD:油烟机类设备
  • OVEN:烤箱设备
  • MICROWAVE_OVEN:微波炉
  • PRESSURE_COOKER:压力锅
  • RICE_COOKER:电饭煲
  • INDUCTION_COOKER:电磁炉
  • HIGH_SPEED_BLENDER:破壁机
  • SWEEPING_ROBOT: 扫地机器人
  • FRIDGE:冰箱
  • PRINTER: 打印机
  • AIR_FRESHER:新风机
  • KETTLE:热水壶
  • WEBCAM:摄像头
  • ROBOT:机器人
  • WINDOW_OPENER:开窗器
  • DISINFECTION_CABINET:消毒柜
  • DISHWASHER:洗碗机
  • ACTIVITY_TRIGGER:描述特定设备的组合场景。场景中的设备必须以指定顺序操作。如“观看优酷视频”场景中必须先打开电视机,然后打开HDMI1。
  • SCENE_TRIGGER:描述特定设备的组合场景,设备之间没有相互关联,无特定操作顺序。 例如“打开睡眠模式”包括关灯和锁上房门,但是关灯和锁上房门之间没有必然联系,可以先关灯然后锁上房门,也可以先锁上房门后关灯。
discoveredAppliance.applianceId 设备标识符。标识符在用户拥有的所有设备上必须是唯一的。此外,标识符需要在同一设备的多个发现请求之间保持一致。标识符可以包含任何字母或数字和以下特殊字符:_ - = # ; : ? @ &。标识符不能超过256个字符。
discoveredAppliance.modelName 设备型号名称,是字符串类型,长度不能超过128个字符。
discoveredAppliance.version 供应商提供的设备版本。是字符串类型,长度不能超过128个字符。
discoveredAppliance.friendlyName 用户用来识别设备的名称。 是字符串类型,不能包含特殊字符和标点符号,长度不能超过128个字符。
discoveredAppliance.friendlyDescription 设备相关的描述,描述内容提需要提及设备厂商,使用场景及连接方式,长度不超过128个字符。
discoveredAppliance.isReachable 设备当前是否能够到达。true表示设备当前可以到达,false表示当前设备不能到达。
discoveredAppliance.actions 设备支持的操作类型数组。详细情况请参见 设备操作类型
discoveredAppliance.additionalApplianceDetails 提供给设备云使用,存放设备或场景相关的附加信息,是键值对。DuerOS不了解或使用这些数据。该属性的内容不能超过5000字节。 是,内容可以为空
discoveredAppliance.manufacturerName 设备厂商的名字。
discoveredAppliance.attributes 设备的属性信息。当设备没有属性信息时,协议中不需要传入该字段。每个设备允许同步的最大的属性数量是10。详细信息请参考设备属性设备属性上报 否,建议将设备属性上报给DuerOS,方便用户查询。
discoveredAppliance.attribute.name 属性名称,支持数字、字母和下划线,长度不能超过128个字符。
discoveredAppliance.attribute.value 属性值,支持多种json类型。
discoveredAppliance.attribute.scale 属性值的单位名称,支持数字、字母和下划线,长度不能超过128个字符。
discoveredAppliance.attribute.timestampOfSample 属性值取样的时间戳,单位是秒。
discoveredAppliance.attribute.uncertaintyInMilliseconds 属性值取样的时间误差,单位是ms。如果设备使用的是轮询时间间隔的取样方式,那么uncertaintyInMilliseconds就等于时间间隔。如温度传感器每1秒取样1次,那么uncertaintyInMilliseconds的值就是1000。
设备操作类型

智能家居设备支持以下操作类型。

  • turnOn: 打开
  • timingTurnOn: 定时打开
  • turnOff: 关闭
  • timingTurnOff: 定时关闭
  • pause: 暂停
  • continue: 继续
  • setBrightnessPercentage: 设置灯光亮度
  • incrementBrightnessPercentage: 调亮灯光
  • decrementBrightnessPercentage: 调暗灯光
  • incrementColorTemperature: 增高灯光色温
  • decrementColorTemperature: 降低灯光色温
  • setColorTemperature: 设置灯光色温
  • incrementTemperature: 升高温度
  • decrementTemperature: 降低温度
  • setTemperature: 设置温度
  • incrementVolume: 调高音量
  • decrementVolume: 调低音量
  • setVolume: 设置音量
  • setVolumeMute: 设置设备静音状态
  • incrementFanSpeed: 增加风速
  • decrementFanSpeed: 减小风速
  • setFanSpeed: 设置风速
  • setMode: 设置模式
  • unSetMode: 取消设置的模式
  • timingSetMode: 定时设置模式
  • timingUnsetMode: 定时取消设置的模式
  • setColor: 设置颜色
  • getAirQualityIndex: 查询空气质量
  • getAirPM25: 查询PM2.5
  • getTemperatureReading: 查询温度
  • getTargetTemperature: 查询目标温度
  • getHumidity: 查询湿度
  • getTimeLeft: 查询剩余时间
  • getRunningTime: 查询运行时间
  • getRunningStatus: 查询运行状态
  • getWaterQuality: 查询水质
  • setHumidity: 设置湿度模式
  • setLockState: 上锁解锁
  • getLockState: 查询锁状态
  • incrementPower: 增大功率
  • decrementPower: 减小功率
  • returnTVChannel: 返回上个频道
  • decrementTVChannel: 上一个频道
  • incrementTVChannel: 下一个频道
  • setTVChannel: 设置频道
  • decrementHeight: 降低高度
  • incrementHeight: 升高高度
  • chargeTurnOn: 开始充电
  • chargeTurnOff: 停止充电
  • submitPrint: 打印
  • getTurnOnState: 查询设备打开状态
  • setSuction: 设置吸力
  • setDirection: 设置移动方向
  • getElectricityCapacity: 查询电量
  • getOilCapacity: 查询油量
  • engineStartUp: 设备启动
  • setTimer: 设备定时

分组信息

属性 描述说明 是否必须
discoveredGroups discoveredGroups 对象的数组,该对象包含可发现分组,与用户设备帐户相关联的。 如果没有与用户帐户关联的分组,此属性应包含一个空数组。 如果发生错误,该属性可以为空数组[]。阵列中允许的最大项目数量为10。
discoveredGroups.groupName 用户用来识别分组的名称, 不应包含特殊字符或标点符号,长度不超过20字符。
discoveredGroups.applianceIds 分组所包含设备ID的数组,要求设备ID必须是已经发现的设备中的ID,否则会同步失败,每个分组设备ID数量不超过50。
discoveredGroups.groupNotes 分组备注信息,不能超过128个字符。
discoveredGroups.additionalGroupDetails 提供给技能使用的分组相关的附加信息的键值对。该属性的内容不能超过2000字符。而且DuerOS也不了解或使用这些数据。 是,但可以为空数组[]

说明:

  • 如果没有找到设备或相关场景,此时返回的discoveredAppliances是一个空数组。如果查找设备过程中发生了错误,该字段值设置为null。
  • 当applianceTypes=ACTIVITY_TRIGGER/SCENE_TRIGGER时,场景和模式不支持通过分组来控制,比如只支持“打开回家模式”,而不支持“打开客厅的回家模式”。

应用举例

当查找到设备及相关场景或分组时,技能向DuerOS发送DiscoverAppliancesResponse消息,消息样例如下。

{
    "header": {
        "namespace": "DuerOS.ConnectedHome.Discovery",
        "name": "DiscoverAppliancesResponse",
        "messageId": "ff746d98-ab02-4c9e-9d0d-b44711658414",
        "payloadVersion": "1"
    },
    "payload": {
        "discoveredAppliances": [
            {
                "actions": [
                    "turnOn",
                    "turnOff",
                    "incrementBrightnessPercentage",
                    "decrementBrightnessPercentage"
                ],
                "applianceTypes": [
                    "LIGHT"
                ],
                "additionalApplianceDetails": {
                    "extraDetail1": "optionalDetailForSkillAdapterToReferenceThisDevice",
                    "extraDetail2": "There can be multiple entries",
                    "extraDetail3": "but they should only be used for reference purposes",
                    "extraDetail4": "This is not a suitable place to maintain current device state"
                },
                "applianceId": "uniqueLightDeviceId",
                "friendlyDescription": "展现给用户的详细介绍",
                "friendlyName": "卧室的灯",
                "isReachable": true,
                "manufacturerName": "设备制造商的名称",
                "modelName": "fancyLight",
                "version": "your software version number here.",
                "attributes": [
                    {
                        "name": "name",
                        "value": "卧室的灯",
                        "scale": "",
                        "timestampOfSample": 1496741861,
                        "uncertaintyInMilliseconds": 10
                    },
                    {
                        "name": "connectivity",
                        "value": "REACHABLE",
                        "scale": "",
                        "timestampOfSample": 1496741861,
                        "uncertaintyInMilliseconds": 10
                    },
                    {
                        "name": "color",
                        "value": {
                            "hue": 350.5,
                            "saturation": 0.7138,
                            "brightness": 0.6524
                        },
                        "scale": "",
                        "timestampOfSample": 1496741861,
                        "uncertaintyInMilliseconds": 10
                    },
                    {
                        "name": "powerState",
                        "value": "ON",
                        "scale": "",
                        "timestampOfSample": 1496741861,
                        "uncertaintyInMilliseconds": 0
                    },
                    {
                        "name": "brightness",
                        "value": "50",
                        "scale": "",
                        "timestampOfSample": 1496741861,
                        "uncertaintyInMilliseconds": 100
                    }
                ]
            },
            {
                "actions": [
                    "turnOn",
                    "turnOff"
                ],
                "applianceTypes": [
                    "CURTAIN"
                ],
                "additionalApplianceDetails": {
                    "extraDetail1": "optionalDetailForSkillAdapterToReferenceThisDevice",
                    "extraDetail2": "There can be multiple entries",
                    "extraDetail3": "but they should only be used for reference purposes",
                    "extraDetail4": "This is not a suitable place to maintain current device state"
                },
                "applianceId": "uniqueSwitchDeviceId",
                "friendlyDescription": "展现给用户的详细介绍",
                "friendlyName": "卧室的窗帘",
                "isReachable": true,
                "manufacturerName": "设备制造商的名称",
                "modelName": "fancyCurtain",
                "version": "your software version number here",
                "attributes": [
                    {
                        "name": "name",
                        "value": "卧室的窗帘",
                        "scale": "",
                        "timestampOfSample": 1496741861,
                        "uncertaintyInMilliseconds": 10
                    },
                    {
                        "name": "connectivity",
                        "value": "REACHABLE",
                        "scale": "",
                        "timestampOfSample": 1496741861,
                        "uncertaintyInMilliseconds": 10
                    },
                    {
                        "name": "turnOnState",
                        "value": "ON",
                        "scale": "",
                        "timestampOfSample": 1496741861,
                        "uncertaintyInMilliseconds": 10
                    }
                ]
            },
            {
                "actions": [
                    "turnOn",
                    "turnOff"
                ],
                "applianceTypes": [
                    "SCENE_TRIGGER"
                ],
                "additionalApplianceDetails": {
                    "extraDetail1": "detail about the scene",
                    "extraDetail2": "another detail about scene",
                    "extraDetail3": "only be used for reference purposes"
                },
                "applianceId": "uniqueDeviceId",
                "friendlyDescription": "来自设备商的场景",
                "friendlyName": "回家模式",
                "isReachable": true,
                "manufacturerName": "yourManufacturerName",
                "modelName": "提供场景的设备型号",
                "version": "your software version number here",
                "attributes": [
                    {
                        "name": "name",
                        "value": "回家模式",
                        "scale": "",
                        "timestampOfSample": 1496741861,
                        "uncertaintyInMilliseconds": 10
                    },
                    {
                        "name": "turnOnState",
                        "value": "ON",
                        "scale": "",
                        "timestampOfSample": 1496741861,
                        "uncertaintyInMilliseconds": 0
                    }
                ]
            }
        ],
        "discoveredGroups": [
            {
                "groupName": "客厅",
                "applianceIds": [
                    "001",
                    "002",
                    "003"
                ],
                "groupNotes": "客厅照明分组控制",
                "additionalGroupDetails": {
                    "extraDetail1": "detail about the group",
                    "extraDetail2": "another detail about group",
                    "extraDetail3": "only be used for reference group"
                }
            },
            {
                "groupName": "卧室",
                "applianceIds": [
                    "004",
                    "005",
                    "006"
                ],
                "groupNotes": "卧室空调的分组控制",
                "additionalGroupDetails": {
                    "extraDetail1": "detail about the group",
                    "extraDetail2": "another detail about group",
                    "extraDetail3": "only be used for reference group"
                }
            }
        ]
    }
}