控制设备

控制设备协议说明

控制消息是对智能家居设备进行控制的消息。目前支持以下设备控制消息。

TurnOnRequest 打开设备
TurnOnConfirmation 打开设备返回信息
TurnOffRequest 关闭设备
TurnOffConfirmation 关闭设备返回信息
PauseRequest 暂停设备
PauseConfirmation 暂停设备返回信息
SetTemperatureRequest 设置温度
SetTemperatureConfirmation 设置温度返回信息
SetFanSpeedRequest 设置风速
SetFanSpeedConfirmation
SetModeRequest 设置模式
SetModeConfirmation
SetColorRequest 设置颜色相关（亮度,饱和度，色相）
SetColorConfirmation

TurnOnRequest

当用户想打开指定设备时，右转主机会将该消息发送给智能家居服务。

Header信息

属性

取值

name

TurnOnRequest

namespace

YouZhuan.ConnectedHome.Control

Payload信息

属性

描述说明

是否必须

accessToken

设备云端获取的access token。

是

appliance

设备操作的具体对象，包括applianceId和additionalApplianceDetails。

是

appliance.applianceId

设备标识符。标识符在用户拥有的所有设备上必须是唯一的。此外，标识符需要在同一设备的多个发现请求之间保持一致。标识符可以包含任何字母或数字和以下特殊字符：_ - = # ; : ? @ &。标识符不能超过256个字符。

是

appliance.additionalApplianceDetails

提供给设备云使用，存放设备或场景相关的附加信息，是键值对。

是，内容可以为空

应用举例

当用户在右转主机操作打开设备时向智能家居服务发送TurnOnRequest消息，消息示例如下。

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

TurnOnConfirmation

当请求的设备成功打开时，智能家居服务需要返回该消息给右转主机。

Header信息

属性

取值

name

TurnOnConfirmation

namespace

YouZhuan.ConnectedHome.Control

Payload信息

属性

取值

是否必须

attributes

设备属性信息，支持上报一个或多个属性信息。请查看属性信息，了解设备的属性和上报方式。

否，当设备属性信息发生变化时，建议将属性变更信息上报给YouZhuan。

应用举例

当电视成功打开时，技能向YouZhuan发送TurnOnConfirmation消息，示例如下。

{
    "header": {
        "namespace": "YouZhuan.ConnectedHome.Control",
        "name": "TurnOnConfirmation",
        "messageId": "26fa11a8-accb-4f66-a272-8b1ff7abd722",
        "payloadVersion": "1"
    },
    "payload": {
        "attributes": []
    }
}

TurnOffRequest

当用户想关闭设备时，右转主机会发送该消息给智能家居服务，通知智能家居服务关闭该设备。

Header信息

属性

取值

name

TurnOffRequest

namespace

YouZhuan.ConnectedHome.Control

Payload信息

属性

描述说明

是否必须

accessToken

设备云端获取的access token。

是

appliance

设备操作的具体对象，包括applianceId和additionalApplianceDetails。

是

appliance.applianceId

是

appliance.additionalApplianceDetails

提供给设备云使用，存放设备或场景相关的附加信息，是键值对。YouZhuan不解析或使用这些数据。该属性的内容不能超过5000字节。

是，内容可以为空

应用举例

当用户说（或触发主机的关闭事件）“小右小右，帮我关闭灯光”，右转主机理解用户意图后，会向智能家居服务发送TurnOffRequest消息，示例如下。

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

TurnOffConfirmation

当请求的设备成功关闭时，智能家居服务会向右转主机发送该消息。

Header信息

属性

取值

name

TurnOffConfirmation

namespace

YouZhuan.ConnectedHome.Control

Payload信息

属性

描述说明

是否必须

attributes

设备属性信息，支持上报一个或多个属性信息。请查看属性信息，了解设备的属性和上报方式。

否，当设备属性信息发生变化时，建议将属性变更信息上报给YouZhuan。

应用举例

当灯光成功关闭时，智能家居服务会向右转主机发送TurnOffConfirmation消息，示例如下。

{
    "header": {
        "namespace": "YouZhuan.ConnectedHome.Control",
        "name": "TurnOffConfirmation",
        "messageId": "26fa11a8-accb-4f66-a272-8b1ff7abd722",
        "payloadVersion": "1"
    },
    "payload": {
        "attributes": []
    }
}

PauseRequest

当用户想暂停设备时，右转主机会发送该消息给智能家居服务。

Header信息

属性

取值

name

PauseRequest

namespace

YouZhuan.ConnectedHome.Control

Payload信息

属性

描述说明

是否必须

accessToken

设备云端获取的access token。

是

appliance

设备操作的具体对象，包括applianceId和additionalApplianceDetails。

是

appliance.applianceId

是

appliance.additionalApplianceDetails

提供给设备云使用，存放设备或场景相关的附加信息，是键值对。

是，内容可以为空

应用举例

用户说“小右，暂停窗帘”时，右转主机了解用户意图后，会发送PauseRequest消息给智能家居服务。消息示例如下。

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

PauseConfirmation

设备成功暂停时，智能家居服务需要返回该消息。

Header信息

属性

取值

name

PauseConfirmation

namespace

YouZhuan.ConnectedHome.Control

Payload信息

属性

描述说明

是否必须

attributes

设备属性信息，支持上报一个或多个属性信息。请查看属性信息，了解设备的属性和上报方式。

否，当设备属性信息发生变化时，建议将属性变更信息上报给YouZhuan。

应用举例

当窗帘暂停后，智能家居服务需要返回PauseConfirmation消息，示例如下。

{
    "header": {        
        "namespace": "YouZhuan.ConnectedHome.Control",
        "name": "PauseConfirmation",
        "messageId": "26fa11a8-accb-4f66-a272-8b1ff7abd722",
        "payloadVersion": "1"
    },
    "payload": {
        "attributes": []
    }
}

SetTemperatureRequest

当用户需要设置设备温度时，智能主机向智能家居服务发送该消息，通知设备调整温度。

Header信息

属性

取值

name

SetTemperatureRequest

namespace

YouZhuan.ConnectedHome.Control

Payload信息

属性

描述说明

是否必须

accessToken

设备云端获取的access token。

是

appliance

设备操作的具体对象，包括applianceId和additionalApplianceDetails。

是

appliance.applianceId

是

appliance.additionalApplianceDetails

提供给设备云使用，存放设备或场景相关的附加信息，是键值对。YouZhuan不解析或使用这些数据。该属性的内容不能超过5000字节。

是，内容可以为空

targetTemperature

设备设定的目标温度。

是

targetTemperature.value

设备设定的目标温度值。

是

targetTemperature.scale

温度计量单位。有CELSIUS(摄氏温度)和FAHRENHEIT(华氏温度)两种计量单位，默认使用CELSIUS。

是

应用举例

用户说“小右小右，把客厅温度设置为23度”，主机了解用户意图，向智能家居服务发送SetTemperatureRequest消息，消息示例如下。

{
    "header": {
        "namespace": "YouZhuan.ConnectedHome.Control",
        "name": "SetTemperatureRequest",
        "messageId": "01ebf625-0b89-4c4d-b3aa-32340e894688",
        "payloadVersion": "1"
    },
    "payload": {
        "targetTemperature": {
            "value": 23,
            "scale": "CELSIUS"
        },
        "accessToken": "[OAuth token here]",
        "appliance": {
            "additionalApplianceDetails": {},
            "applianceId": "[Device ID]"
        }
    }
}

SetTemperatureConfirmation

当设备温度设置成功时，智能家居服务需要返回该消息。

Header信息

属性

取值

name

SetTemperatureConfirmation

namespace

YouZhuan.ConnectedHome.Control

Payload信息

属性

描述说明

是否必须

mode

温度设置成功后的设备模式。

否

temperature

温度设置成功后设备的温度，是double类型。

是

previousState object

温度设定之前的设备状态。

是

previousState.mode

温度设定之前的设备模式。

否

previousState.temperature

温度设定之前设备的温度，是double类型。

是

attributes

设备属性信息，支持上报一个或多个属性信息。请查看属性信息，了解设备的属性和上报方式。

否，当设备属性信息发生变化时，建议将属性变更信息上报给YouZhuan。

应用举例

当设备温度成功设置成23度时，智能家居服务需要返回SetTemperatureConfirmation消息，消息示例如下。

{
    "header": {
        "namespace": "YouZhuan.ConnectedHome.Control",
        "name": "SetTemperatureConfirmation",
        "messageId": "780013dd-99d0-4c69-9e35-db0457f9f2a7",
        "payloadVersion": "1"
    },
    "payload": {
        "previousState": {
            "mode": {
                "value": "AUTO"
            },
            "temperature": {
                "value": 25.0
            }
        },
        "temperature": {
            "value": 23.0
        },
        "mode": {
            "value": "AUTO"
        },
        "attributes": []
    }
}

SetFanSpeedRequest

当用户需要设置设备的风速时，主机会向智能家居服务发送该消息。

Header信息

属性

取值

name

SetFanSpeedRequest

namespace

YouZhuan.ConnectedHome.Control

Payload信息

属性

描述说明

是否必须

accessToken

设备云端获取的access token。

是

appliance

设备操作的具体对象，包括applianceId和additionalApplianceDetails。

是

appliance.applianceId

是

appliance.additionalApplianceDetails

提供给设备云使用，存放设备或场景相关的附加信息，是键值对。

是，内容可以为空

fanSpeed

设备的风速对象，包含一个属性值value或者一个属性值level，取决于用户自然表达。

是

fanSpeed.value

设备的风速值，是int类型，取值范围是1～10。用户表达具体风速值时，会出该字段。

否

fanSpeed.level

设备的风速档位级别，是string类型，取值范围是(min、low、middle、high、max、auto))。用户表达风速级别时，会出该字段。

否

应用举例

用户说“小右小右，把空调的风速设为2档”，YouZhuan接收用户意图后，向技能发送SetFanSpeedRequest消息，消息示例如下。

{
    "header": {
        "namespace": "YouZhuan.ConnectedHome.Control",
        "name": "SetFanSpeedRequest",
        "messageId": "01ebf625-0b89-4c4d-b3aa-32340e894688",
        "payloadVersion": "1"
    },
    "payload": {
        "fanSpeed": {
            "value": 2
        },
        "accessToken": "[OAuth token here]",
        "appliance": {
            "additionalApplianceDetails": {},
            "applianceId": "[Device ID]"
        }
    }
}

用户说“小右小右，把空调的风速设为高速风”，YouZhuan接收用户意图后，向技能发送SetFanSpeedRequest消息，消息示例如下。

{
    "header": {
        "namespace": "YouZhuan.ConnectedHome.Control",
        "name": "SetFanSpeedRequest",
        "messageId": "01ebf625-0b89-4c4d-b3aa-32340e894688",
        "payloadVersion": "1"
    },
    "payload": {
        "fanSpeed": {
            "level": "high"
        },
        "accessToken": "[OAuth token here]",
        "appliance": {
            "additionalApplianceDetails": {},
            "applianceId": "[Device ID]"
        }
    }
}

SetFanSpeedConfirmation

设备风速设定成功时，智能家居服务会需要返回SetFanSpeedConfirmation消息。

Header信息

属性

取值

name

SetFanSpeedConfirmation

namespace

YouZhuan.ConnectedHome.Control

Payload信息

属性

描述说明

是否必须

fanSpeed

设备的风速对象，包含一个属性值value。

是

fanSpeedvalue

设备的风速值，是int类型，取值范围是1～10。

是

previousState

设备风速变化前的设备状态。

是

previousState.fanSpeed

设备风速变化前的风速。

是

previousState.fanSpeed.value

设备风速变化前的风速值。

是

attributes

设备属性信息，支持上报一个或多个属性信息。请查看属性信息，了解设备的属性和上报方式。

否，当设备属性信息发生变化时，建议将属性变更信息上报给YouZhuan。

应用举例

当空调风速设定为2档成功时，智能家居服务需要返回SetFanSpeedConfirmation消息，消息示例如下。

{
    "header": {
        "namespace": "YouZhuan.ConnectedHome.Control",
        "name": "SetFanSpeedConfirmation",
        "messageId": "780013dd-99d0-4c69-9e35-db0457f9f2a7",
        "payloadVersion": "1"
    },
    "payload": {
        "previousState": {
            "fanSpeed": {
                "value": 1
            }
        },
        "fanSpeed": {
            "value": 2
        },
        "attributes": []
    }
}

SetModeRequest

当用户需要设置设备的模式时，主机会向智能家居服务发送该消息。

Header信息

属性

取值

name

SetModeRequest

namespace

YouZhuan.ConnectedHome.Control

Payload信息

属性

描述说明

是否必须

accessToken

设备云端获取的access token。

是

appliance

设备操作的具体对象，包括applianceId和additionalApplianceDetails。

是

appliance.applianceId

是

appliance.additionalApplianceDetails

提供给设备云使用，存放设备或场景相关的附加信息，是键值对。

是，内容可以为空

mode

设备的模式信息。

是

mode.deviceType

设备类型，详细信息请参见设备类型表。

是

mode.value

设备模式，与设备类型相关，不同设备类型的模式不同，详细信息请参见设备模式表。

是

应用举例

用户说“小右小右，把空调调成制冷模式”，主机理解用户意图后，向智能家居服务发送SetModeRequest消息，消息示例如下。

{
    "header": {
        "namespace": "YouZhuan.ConnectedHome.Control",
        "name": "SetModeRequest",
        "messageId": "01ebf625-0b89-4c4d-b3aa-32340e894688",
        "payloadVersion": "1"
    },
    "payload": {
        "mode": {
            "deviceType": "AIR_CONDITION",
            "value": "COOL"
        },
        "accessToken": "[OAuth token here]",
        "appliance": {
            "additionalApplianceDetails": {},
            "applianceId": "[Device ID]"
        }
    }
}

SetModeConfirmation

当设备的模式设置成功时，智能家居服务返回该消息。

Header信息

属性

取值

name

SetModeConfirmation

namespace

YouZhuan.ConnectedHome.Control

Payload信息

属性

描述说明

是否必须

previousState

设置前的设备状态信息。

是

previousState.mode

设置前的设备模式。

是

previousState.mode.value

设置前的设备模式，详细信息请参见设备模式表。

是

mode

设置后的设备模式。

是

mode.deviceType

设备类型，详细信息请参见设备类型表。

是

mode.value

设置后的设备模式，详细信息请参见设备模式表。

是

attributes

设备属性信息，支持上报一个或多个属性信息。请查看属性信息，了解设备的属性和上报方式。

否，当设备属性信息发生变化时，建议将属性变更信息上报给YouZhuan。

应用举例

设备模式设置成功时，智能家居服务返回SetModeConfirmation消息，消息示例如下。

{
    "header": {
        "namespace": "YouZhuan.ConnectedHome.Control",
        "name": "SetModeConfirmation",
        "messageId": "780013dd-99d0-4c69-9e35-db0457f9f2a7",
        "payloadVersion": "1"
    },
    "payload": {
        "previousState": {
            "mode": {
                "value": "AUTO"
            }
        },
        "mode": {
            "deviceType": "AIR_CONDITION",
            "value": "COOL"
        },
        "attributes": []
    }
}

SetColorRequest

用户需要设置灯光颜色时，主机会向智能家居服务发送该消息，通知技能调整灯光颜色。

Header信息

属性

取值

name

SetColorRequest

namespace

DuerOS.ConnectedHome.Control

Payload信息

属性

描述说明

是否必须

accessToken

设备云端获取的access token。

是

appliance

设备操作的具体对象，包括applianceId和additionalApplianceDetails。

是

appliance.applianceId

是

appliance.additionalApplianceDetails

提供给设备云使用，存放设备或场景相关的附加信息，是键值对。DuerOS不解析或使用这些数据。该属性的内容不能超过5000字节。

是，内容可以为空

color

灯设置的颜色。包括色相、饱和度、亮度（HSB）颜色模型。

是

color.hue

灯光设置的色相，是double类型，取值范围为0.00〜360.00。

是

color.saturation

灯光设置饱和度，是double类型，取值范围为0.0000〜1.0000。

是

color.brightness

灯光设置的亮度，是double类型，取值范围为0.0000〜1.0000。

是

应用举例

用户说：“小右小右（或者面板操作），把卧室的灯设置为红色”，主机了解到该意图时，会向智能家居服务发送SetColorRequest消息，消息示例如下。

{
    "header": {
        "namespace": "YouZhuan.ConnectedHome.Control",
        "name": "SetColorRequest",
        "messageId": "01ebf625-0b89-4c4d-b3aa-32340e894688",
        "payloadVersion": "1"
    },
    "payload": {
        "accessToken": "[OAuth token here]",
        "appliance": {
            "additionalApplianceDetails": {},
            "applianceId": "[Device ID]"
        },
        "color": {
            "hue": 0.0,
            "saturation": 1.0000,
            "brightness": 1.0000
        }
    }
}

SetColorConfirmation

当灯光颜色成功设定时，智能家居服务需要返回该消息。

Header信息

属性

取值

name

SetColorConfirmation

namespace

DuerOS.ConnectedHome.Control

Payload信息

属性

描述说明

是否必须

achievedState

颜色更改后设备的状态，该对象是必需的，当无法查询设备的状态或者避免查询引起的额外延迟，则可以返回SetColorRequest中发送的值。

是

achievedState.color object

颜色变化后设备的颜色。

是

color.hue

灯光设置的色相，是double类型，取值范围为0.00〜360.00。

是

color.saturation

灯光设置饱和度，是double类型，取值范围为0.0000〜1.0000。

是

color.brightness

灯光设置的亮度，是double类型，取值范围为0.0000〜1.0000。

是

attributes

设备属性信息，支持上报一个或多个属性信息。请查看属性信息，了解设备的属性和上报方式。

否，当设备属性信息发生变化时，建议将属性变更信息上报给DuerOS。

应用举例

当卧室灯光成功调成红色时，智能家居服务返回SetColorConfirmation消息，消息示例如下。

{
    "header": {
        "namespace": "YouZhuan.ConnectedHome.Control",
        "name": "SetColorConfirmation",
        "messageId": "780013dd-99d0-4c69-9e35-db0457f9f2a7",
        "payloadVersion": "1"
    },
    "payload": {
        "achievedState": {
            "color": {
                "hue": 0.0,
                "saturation": 1.0000,
                "brightness": 1.0000
            }
        },
        "attributes": []
    }
}

最后更新于4年前