# Smart Home ColorSetting Trait Schema

`action.devices.traits.ColorSetting` - This trait applies to devices, such as smart lights, that can change color or color temperature.

## RGB, HSV, and color temperature

**RGB** represents colors as a (red, green, blue) triplet. RGB is
the default color model. Any RGB triplet may be represented as a hexcode, equivalent to the
hexadecimal values for the triplet concatenated. For example, "blue" is (0, 0, 255) and #0000FF.
You can use any value within the RGB color space; that is, RGB(x, y, z) where x, y, z are within
the range \[0, 255\], inclusive.

**HSV** represents colors as a (hue, saturation, value) triplet. Any color value in
HSV may be converted to RGB, and vice versa. Hue has a range of \[0, 360) degrees (exclusive
of 360, since it wraps around to 0 degrees). Saturation and value are represented by floats in the
range \[0.0, 1.0\].

**Color temperature** represents *some* colors as non-negative decimal values in Kelvin.
This attribute describes "white" or "warmth" lights, with color names such as "cool white"
or "overcast daylight." Smart lights supporting color temperature typically have a range of
\[2000, 9000\] Kelvin, which corresponds to conventional lights with fixed Kelvin. Color
temperature is a linear scale and a subset of the RGB/HSV full spectrum color models. See the
table below for some example temperatures and corresponding color names.

| Temperature (Kelvin) | Color Name |
|---|---|
| 2000 | Candle Light |
| 2500 | Ultra Warm White |
| 3000 | Soft White, Morning White, Reading White |
| 4000 | Cool White |
| 5000 | Day Light, White |
| 6000 | Floral White |
| 7000 | Cloudy Day Light, White Smoke |
| 8000 | Blue Overcast |
| 9000 | Blue Sky |

## Device ATTRIBUTES

Devices with this trait may report the following
attributes as part of the [`SYNC`](https://developers.home.google.com/cloud-to-cloud/intents/sync) operation. To learn
more about handling `SYNC` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/sync).

| Attributes | Type | Description |
|---|---|---|
| `commandOnlyColorSetting` | *Boolean* | (Default: `false`) Indicates if the device supports using one-way (true) or two-way (false) communication. Set this attribute to true if the device cannot respond to a QUERY intent or Report State for this trait. |
| *Contains any of the following items:* |||
| `*0*` | *Object* | Color model support. |
| `colorModel` | *String* | **Required.** Full spectrum color model supported by the device. Supported values: `rgb` `hsv` |
| `*1*` | *Object* | Color temperature support. |
| `colorTemperatureRange` | *Object* | **Required.** Supported color temperature range in Kelvin. |
| `temperatureMinK` | *Integer* | **Required.** Minimum supported color temperature in Kelvin. |
| `temperatureMaxK` | *Integer* | **Required.** Maximum supported color temperature in Kelvin. |

#### Examples

*Device that supports both RGB spectrum color model and color temperature.*

```
{
  "colorModel": "rgb",
  "colorTemperatureRange": {
    "temperatureMinK": 2000,
    "temperatureMaxK": 9000
  }
}
```

*Device that only supports HSV spectrum color model.*

```
{
  "colorModel": "hsv"
}
```

*Device that only supports color temperature.*

```
{
  "colorTemperatureRange": {
    "temperatureMinK": 2000,
    "temperatureMaxK": 9000
  }
}
```

*Device that only supports HSV color model commands.*

```
{
  "colorModel": "hsv",
  "commandOnlyColorSetting": true
}
```

## Device STATES

Entities with this trait may report the following
states as part of the [`QUERY`](https://developers.home.google.com/cloud-to-cloud/intents/query) operation. To learn
more about handling `QUERY` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute).

| States | Type | Description |
|---|---|---|
| `color` | *Object* | **Required.** The current color setting currently being used on the device. |
| *Contains one of the following items:* |||
| `*0*` | *Object* | Color temperature support. |
| `temperatureK` | *Integer* | **Required.** Temperature value in Kelvin. |
| `*1*` | *Object* | Color RGB spectrum support. |
| `spectrumRgb` | *Integer* | **Required.** Spectrum RGB value as a decimal integer. |
| `*2*` | *Object* | Color HSV spectrum support. |
| `spectrumHsv` | *Object* | **Required.** Spectrum HSV value. |
| `hue` | *Number* | Hue. Minimum value: `0`. |
| `saturation` | *Number* | Saturation. Value must be between `0` and `1`. |
| `value` | *Number* | Value. Value must be between `0` and `1`. |

#### Examples

*What is the color of the light? (Warm White)*

```
{
  "color": {
    "temperatureK": 3000
  }
}
```

*What is the color of the light? (Magenta)*

```
{
  "color": {
    "spectrumRgb": 16711935
  }
}
```

*What is the color of the light? (Magenta)*

```
{
  "color": {
    "spectrumHsv": {
      "hue": 300,
      "saturation": 1,
      "value": 1
    }
  }
}
```
**Note:** When using Report State for the ColorSetting trait, make sure you specify the RGB state as `spectrumRGB` and the HSV state as `spectrumHsv`. (You must use this exact capitalization for the state names.)

## Device COMMANDS

Devices with this trait may respond to the following
commands as part of the [`EXECUTE`](https://developers.home.google.com/cloud-to-cloud/intents/execute) operation. To learn
more about handling `EXECUTE` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute#handle_execute_intents).

### `action.devices.commands.ColorAbsolute`

Set the absolute color value.

#### Parameters

| Parameters | Type | Description |
|---|---|---|
| `color` | *Object* | **Required.** Color to set. |
| `name` | *String* | Color name parsed from the user's command; may not always be available (i.e. when using relative commands). |
| *Contains one of the following items:* |||
| `*0*` | *Object* | Color temperature support. |
| `temperature` | *Integer* | **Required.** Temperature value in Kelvin. See [RGB, HSV, and color temperature](https://developers.home.google.com/cloud-to-cloud/traits/colorsetting#rgb,-hsv,-and-color-temperature) for details. |
| `*1*` | *Object* | Color RGB spectrum support. |
| `spectrumRGB` | *Integer* | **Required.** Spectrum RGB value as a decimal integer. See [RGB, HSV, and color temperature](https://developers.home.google.com/cloud-to-cloud/traits/colorsetting#rgb,-hsv,-and-color-temperature) for details. |
| `*2*` | *Object* | Color HSV spectrum support. |
| `spectrumHSV` | *Object* | **Required.** Spectrum HSV value. See [RGB, HSV, and color temperature](https://developers.home.google.com/cloud-to-cloud/traits/colorsetting#rgb,-hsv,-and-color-temperature) for details. |
| `hue` | *Number* | Hue. Minimum value: `0`. |
| `saturation` | *Number* | Saturation. Value must be between `0` and `1`. |
| `value` | *Number* | Value. Value must be between `0` and `1`. |

#### Examples

*Make the light warm white.*

```
{
  "command": "action.devices.commands.ColorAbsolute",
  "params": {
    "color": {
      "name": "Warm White",
      "temperature": 3000
    }
  }
}
```

*Make the light magenta.*

```
{
  "command": "action.devices.commands.ColorAbsolute",
  "params": {
    "color": {
      "name": "Magenta",
      "spectrumRGB": 16711935
    }
  }
}
```

*Make the light magenta.*

```
{
  "command": "action.devices.commands.ColorAbsolute",
  "params": {
    "color": {
      "name": "Magenta",
      "spectrumHSV": {
        "hue": 300,
        "saturation": 1,
        "value": 1
      }
    }
  }
}
```

Note that parameter names differ slightly between command and state parameters. This avoids
collisions with the state parameters for the deprecated [ColorSpectrum](https://developers.home.google.com/cloud-to-cloud/traits/colorspectrum)
and [ColorTemperature](https://developers.home.google.com/cloud-to-cloud/traits/colortemperature) traits.

| Command | State |
|---|---|
| `temperature` | `temperatureK` |
| `spectrumRGB` | `spectrumRgb` |
| `spectrumHSV` | `spectrumHsv` |

## Sample utterances

> [!NOTE]
> This is a sample of the utterances supported by this device trait, make sure to also review other [supported languages](https://developers.home.google.com/cloud-to-cloud/traits#supported-languages).

### de-DE

- Stell die Farbe *der Lampe* auf *blau*
- Stelle die Farbtemperatur auf *3000 Kelvin* ein.

### en-US

- can you adjust *my lights* color to *4000 kelvins*
- set *the lights* to *blue*

### es-ES

- pon *azul* *la luz de la cocina*
- pon *la luz* a *2000 k* de temperatura de color

### fr-FR

- Allume *la lampe de la chambre* à *3500 kelvins* .
- mets *les lampes* en *rose* dans *la chambre*

### hi-IN

- तुम *लाइट* को *ब्लू* कर दो
- *लैम्प* *2000 केल्विन* पर लगाओ।

### it-IT

- Imposta *la lampada* a *2000 K* .
- metti *la luce* *gialla*

### ja-JP

- *照明* の色を *青* にして
- *照明* の色温度を *5000K* にセットして

### ko-KR

- *조명* 색깔 *흰색* 으로 바꿔 줘
- *주방 전등* 색 온도를 *5000 켈빈* 으로 설정해

### nl-NL

- Zet *de keukenlamp* op *2000 Kelvin* .
- maak *het licht* *rood*

### pt-BR

- Colocar *a lâmpada* em *2000 K* .
- Define *a lâmpada* para *2000 K* .
- colocar *a luz da sala* em *azul*
- põe *a luz da sala* a *vermelho*

### sv-SE

- Ställ in *lampan* på *2000 Kelvin*
- tänd *blått* *ljus i köket*

## Device ERRORS

See the full list of [errors and exceptions](https://developers.home.google.com/cloud-to-cloud/intents/errors-exceptions).