# 控制设备

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

* [TurnOnRequest](#turnonrequest)    打开设备
* [TurnOnConfirmation](#turnonconfirmation)    打开设备返回信息
* [TurnOffRequest](#turnoffrequest)   关闭设备
* [TurnOffConfirmation  ](#turnoffconfirmation)关闭设备返回信息
* [PauseRequest](#pauserequest)      暂停设备
* [PauseConfirmation     ](#pauseconfirmation)暂停设备返回信息
* [SetTemperatureRequest   ](#settemperaturerequest)设置温度
* [SetTemperatureConfirmation   ](#settemperatureconfirmation)设置温度返回信息
* [SetFanSpeedRequest ](#setfanspeedrequest)        设置风速
* [SetFanSpeedConfirmation](#setfanspeedconfirmation)
* [SetModeRequest](#setmoderequest)            设置模式
* [SetModeConfirmation   ](#setmodeconfirmation)
* [SetColorRequest ](#setcolorrequest)           设置颜色相关（亮度,饱和度，色相）
* [SetColorConfirmation](#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": []
    }
}
```