设备属性上报

在设备正常运行过程中，DuerOS不会感知到设备的属性。只有当技能上报设备属性给DuerOS时，DuerOS才会记录存储设备属性。在以下三种情况下，技能会上报设备属性信息。

• 发现设备时，在返回消息DiscoverAppliancesResponse中上报设备所有的属性信息。
• 当用户下发智能家居控制请求消息，技能成功处理请求消息时，会在confirmation消息中返回发生变化的属性信息。
• 当用户没有通过发送DuerOS控制消息，而是使用手动或其他方式对设备进行操作来修改属性信息时，技能主动上报设备属性信息。

发现设备时上报设备属性

当用户查找设备或者在技能商店中启用技能时，DuerOS会向技能发送DiscoverAppliancesRequest请求。当技能收到请求时，将设备属性信息通过消息DiscoverAppliancesResponse上报给DuerOS。

在DiscoverAppliancesResponse消息中携带了属性的所有信息，包括name、value、scale、timestampOfSample、uncertaintyInMilliseconds。具体的上报方式请参照DiscoverAppliancesResponse消息。

说明：

• 如果设备的某个属性在发现设备过程中，没有上报给DuerOS，后续在技能主动上报该属性或控制消息中上报该属性，DuerOS会新增该属性。

控制消息中上报设备属性

当用户通过语音控制设备，如用户说“打开厨房灯”，DuerOS收到用户请求时，会向技能发送控制请求消息，技能执行完相应的指令后会向DuerOS发送confirmation信息并上报设备属性信息。如成功打开厨房灯时技能会发送TurnOnConfirmation信息，并上报厨房灯的属性信息。

示例1

用户请求打开厨房灯，当厨房灯成功打开时，技能会发送TurnOnConfirmation消息，并在消息中上报name、brightness、turnOnState属性信息。

{
    "header": {
        "namespace": "DuerOS.ConnectedHome.Control",
        "name": "TurnOnConfirmation",
        "messageId": "26fa11a8-accb-4f66-a272-8b1ff7abd722",
        "payloadVersion": "1"
    },
    "payload": {
        "attributes": [
            {
                "name": "name",
                "value": "电灯",
                "scale": "",
                "timestampOfSample": 1496741861,
                "uncertaintyInMilliseconds": 10
            }，
            {
                "name": "brightness",
                "value": "50",
                "scale": "%",
                "timestampOfSample": 1496741861,
                "uncertaintyInMilliseconds": 10
            }，
            {
                "name": "turnOnState",
                "value": "ON",
                "scale": "",
                "timestampOfSample": 1496741861,
                "uncertaintyInMilliseconds": 10
            }
        ]
    }
}

示例2

在车载场景中，当技能收到“把车内温度调低一点”的指令时，会向DuerOS发送该DecrementTemperatureConfirmation消息，并上报temperature属性信息。

{
    "header": {
        "namespace": "DuerOS.ConnectedHome.Control",
        "name": "DecrementTemperatureConfirmation",
        "messageId": "780013dd-99d0-4c69-9e35-db0457f9f2a7",
        "payloadVersion": "1"
    },
    "payload": {
        "previousState": {
            "mode": {
                "value": "AUTO"
            },
            "temperature": {
                "value": 23.0
            }
        },
        "temperature": {
            "value": 20.0
        },
        "mode": {
            "value": "AUTO"
        },
        "attributes": [
            {
                "name": "temperature",
                "value": 20.0,
                "scale": "CELSIUS",
                "timestampOfSample": 1496741861,
                "uncertaintyInMilliseconds": 10
            }
        ]
    }
}

说明

• 技能在控制消息中上报设备属性时，可以上报变化的属性信息，也可以上报设备所有的属性信息。如示例1中，打开厨房灯时，厨房灯的brightness和turnOnState属性发生变化，厨房灯的name属性没有变化，此时可以仅上报brightness和turnOnState属性，也可以上报name属性。建议至少将变化的属性信息上报给DuerOS。

技能主动上报设备属性

当用户手动操作设备或者通过第三方app修改设备状态，如手动关闭厨房灯，手动切换电风扇模式，使用第三方app修改设备名称等，这些情况下DuerOS不会感知到设备属性变化，需要设备云主动上报设备属性。

技能主动向DuerOS发送请求消息，请求DuerOS同步设备属性信息。DuerOS收到请求后向技能发送ReportStateRequest消息，请求技能上报相应的属性信息，技能收到请求后，将向DuerOS发送ReportStateResponse消息，上报属性信息。

主动上报请求消息

当用户手动操作设备或者通过第三方app修改设备状态时，技能会主动上报属性信息，发送上报请求消息。

接口地址

https://xiaodu.baidu.com/saiya/smarthome/changereport

请求方式

POST请求方式。

Head说明

参数信息

Header信息

Payload信息

请求示例

curl -v "https://xiaodu.baidu.com/saiya/smarthome/changereport" -H 'Content-Type:application/json' -d
'{
    "header": {
        "namespace": "DuerOS.ConnectedHome.Control",
        "name": "ChangeReportRequest",
        "messageId": "01ebf625-0b89-4c4d-b3aa-32340e894688",
        "payloadVersion": "1"
    },
    "payload": {
        "botId": "5385e18b-619a-abcd-ed10-33a7d69780a6",
        "openUid": "27a7d83c2d3cfbad5d387cd35f3ca17b",
        "appliance": {
            "applianceId": "[Device ID for Light]",
            "attributeName": "powerState"
        }
    }
}'

说明

• 这里主动上报的属性，属性值是通过ReportStateRequest查询到的，所以需要在ReportStateRequest协议实现中支持上对于上报属性的查询。

请求返回消息

当技能主动发起上报属性请求后，DuerOS返回确认信息。

参数说明

返回示例

{
    “status”: 0, 
    "msg": "update 3 attributes", 
    "messageId": "请求消息中的messageId", 
    "data": {
        "updated_attribute_num": 3
    }
}

ReportStateRequest消息

当DuerOS收到技能主动上报设备属性的请求时，会向技能发送ReportStateRequest消息，请求技能上报属性的完整信息。

Header信息

Payload信息

应用举例

当手动将关上厨房灯时，厨房灯的属性发生变化，技能主动向DuerOS发送请求，DuerOS收到请求后，向技能发送ReportStateRequest消息，消息示例如下。

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

ReportStateResponse消息

当技能收到ReportStateRequest请求消息时，会主动上报请求消息中属性的完整信息，并向技能发送ReportStateResponse消息。

Header信息

Payload信息

应用举例

技能获取到厨房灯的turnOnState属性时，向DuerOS发送ReportStateResponse消息，消息示例如下。

{
    "header": {
        "namespace": "DuerOS.ConnectedHome.Query",
        "name": "ReportStateResponse",
        "messageId": "780013dd-99d0-4c69-9e35-db0457f9f2a7",
        "payloadVersion": "1"
    },
    "payload": {
        "attributes": [
            {
                "name": "turnOnState",
                "value": "OFF",
                "scale": "",
                "timestampOfSample": 1496741861,
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

说明

• 技能主动上报属性时，在主动上报请求消息中每次仅请求上报一个属性，在ReportStateResponse消息中除了返回请求的属性外，还可以返回设备的其他属性信息，最多支持返回10个属性信息。