# 控制设备

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

* [TurnOnRequest](/dev-link-host/zhi-neng-jia-ju-xie-yi/kong-zhi-she-bei.md#turnonrequest)    打开设备
* [TurnOnConfirmation](/dev-link-host/zhi-neng-jia-ju-xie-yi/kong-zhi-she-bei.md#turnonconfirmation)    打开设备返回信息
* [TurnOffRequest](/dev-link-host/zhi-neng-jia-ju-xie-yi/kong-zhi-she-bei.md#turnoffrequest)   关闭设备
* [TurnOffConfirmation  ](/dev-link-host/zhi-neng-jia-ju-xie-yi/kong-zhi-she-bei.md#turnoffconfirmation)关闭设备返回信息
* [PauseRequest](/dev-link-host/zhi-neng-jia-ju-xie-yi/kong-zhi-she-bei.md#pauserequest)      暂停设备
* [PauseConfirmation     ](/dev-link-host/zhi-neng-jia-ju-xie-yi/kong-zhi-she-bei.md#pauseconfirmation)暂停设备返回信息
* [SetTemperatureRequest   ](/dev-link-host/zhi-neng-jia-ju-xie-yi/kong-zhi-she-bei.md#settemperaturerequest)设置温度
* [SetTemperatureConfirmation   ](/dev-link-host/zhi-neng-jia-ju-xie-yi/kong-zhi-she-bei.md#settemperatureconfirmation)设置温度返回信息
* [SetFanSpeedRequest ](/dev-link-host/zhi-neng-jia-ju-xie-yi/kong-zhi-she-bei.md#setfanspeedrequest)        设置风速
* [SetFanSpeedConfirmation](/dev-link-host/zhi-neng-jia-ju-xie-yi/kong-zhi-she-bei.md#setfanspeedconfirmation)
* [SetModeRequest](/dev-link-host/zhi-neng-jia-ju-xie-yi/kong-zhi-she-bei.md#setmoderequest)            设置模式
* [SetModeConfirmation   ](/dev-link-host/zhi-neng-jia-ju-xie-yi/kong-zhi-she-bei.md#setmodeconfirmation)
* [SetColorRequest ](/dev-link-host/zhi-neng-jia-ju-xie-yi/kong-zhi-she-bei.md#setcolorrequest)           设置颜色相关（亮度,饱和度，色相）
* [SetColorConfirmation](/dev-link-host/zhi-neng-jia-ju-xie-yi/kong-zhi-she-bei.md#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 | 设备属性信息，支持上报一个或多个属性信息。请查看[属性信息](https://dueros.baidu.com/didp/doc/dueros-bot-platform/dbp-smart-home/protocol/attributes.md)，了解设备的属性和上报方式。 | 否，当设备属性信息发生变化时，建议将属性变更信息上报给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 | 设备属性信息，支持上报一个或多个属性信息。请查看[属性信息](https://dueros.baidu.com/didp/doc/dueros-bot-platform/dbp-smart-home/protocol/attributes.md)，了解设备的属性和上报方式。 | 否，当设备属性信息发生变化时，建议将属性变更信息上报给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 | 设备属性信息，支持上报一个或多个属性信息。请查看[属性信息](https://dueros.baidu.com/didp/doc/dueros-bot-platform/dbp-smart-home/protocol/attributes.md)，了解设备的属性和上报方式。 | 否，当设备属性信息发生变化时，建议将属性变更信息上报给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                | 设备属性信息，支持上报一个或多个属性信息。请查看[属性信息](https://dueros.baidu.com/didp/doc/dueros-bot-platform/dbp-smart-home/protocol/attributes.md)，了解设备的属性和上报方式。 | 否，当设备属性信息发生变化时，建议将属性变更信息上报给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                   | 设备属性信息，支持上报一个或多个属性信息。请查看[属性信息](https://dueros.baidu.com/didp/doc/dueros-bot-platform/dbp-smart-home/protocol/attributes.md)，了解设备的属性和上报方式。 | 否，当设备属性信息发生变化时，建议将属性变更信息上报给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                      | 设备类型，详细信息请参见[设备类型表](https://dueros.baidu.com/didp/doc/dueros-bot-platform/dbp-smart-home/protocol/control-message_markdown#%E8%AE%BE%E5%A4%87%E7%B1%BB%E5%9E%8B%E4%B8%8E%E6%A8%A1%E5%BC%8F%E8%A1%A8)。                     | 是        |
| mode.value                           | 设备模式，与设备类型相关，不同设备类型的模式不同，详细信息请参见[设备模式表](https://dueros.baidu.com/didp/doc/dueros-bot-platform/dbp-smart-home/protocol/control-message_markdown#%E8%AE%BE%E5%A4%87%E7%B1%BB%E5%9E%8B%E4%B8%8E%E6%A8%A1%E5%BC%8F%E8%A1%A8)。 | 是        |

**应用举例**

用户说“小右小右，把空调调成制冷模式”，主机理解用户意图后，向智能家居服务发送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 | 设置前的设备模式，详细信息请参见[设备模式表](https://dueros.baidu.com/didp/doc/dueros-bot-platform/dbp-smart-home/protocol/control-message_markdown#%E8%AE%BE%E5%A4%87%E7%B1%BB%E5%9E%8B%E4%B8%8E%E6%A8%A1%E5%BC%8F%E8%A1%A8)。 | 是                                    |
| mode                     | 设置后的设备模式。                                                                                                                                                                                                 | 是                                    |
| mode.deviceType          | 设备类型，详细信息请参见[设备类型表](https://dueros.baidu.com/didp/doc/dueros-bot-platform/dbp-smart-home/protocol/control-message_markdown#%E8%AE%BE%E5%A4%87%E7%B1%BB%E5%9E%8B%E4%B8%8E%E6%A8%A1%E5%BC%8F%E8%A1%A8)。     | 是                                    |
| mode.value               | 设置后的设备模式，详细信息请参见[设备模式表](https://dueros.baidu.com/didp/doc/dueros-bot-platform/dbp-smart-home/protocol/control-message_markdown#%E8%AE%BE%E5%A4%87%E7%B1%BB%E5%9E%8B%E4%B8%8E%E6%A8%A1%E5%BC%8F%E8%A1%A8)。 | 是                                    |
| attributes               | 设备属性信息，支持上报一个或多个属性信息。请查看[属性信息](https://dueros.baidu.com/didp/doc/dueros-bot-platform/dbp-smart-home/protocol/attributes.md)，了解设备的属性和上报方式。                                                                 | 否，当设备属性信息发生变化时，建议将属性变更信息上报给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）颜色模型](https://en.wikipedia.org/wiki/HSL_and_HSV)。                                     | 是        |
| 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                 | 设备属性信息，支持上报一个或多个属性信息。请查看[属性信息](https://dueros.baidu.com/didp/doc/dueros-bot-platform/dbp-smart-home/protocol/attributes.md)，了解设备的属性和上报方式。 | 否，当设备属性信息发生变化时，建议将属性变更信息上报给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": []
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.youzhuan.net/dev-link-host/zhi-neng-jia-ju-xie-yi/kong-zhi-she-bei.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.