控制设备

控制设备协议说明

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

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