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
2000Candle Light
2500Ultra Warm White
3000Soft White, Morning White, Reading White
4000Cool White
5000Day Light, White
6000Floral White
7000Cloudy Day Light, White Smoke
8000Blue Overcast
9000Blue Sky

Device ATTRIBUTES

Devices with this trait may report the following attributes as part of the SYNC operation. To learn more about handling SYNC intents, see Intent fulfillment.

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 operation. To learn more about handling QUERY intents, see Intent fulfillment.

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.
saturation Number

Saturation.
value Number

Value.

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
    }
  }
}

Device COMMANDS

Devices with this trait may respond to the following commands as part of the EXECUTE operation. To learn more about handling EXECUTE intents, see Intent fulfillment.

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 for details.
1 Object

Color RGB spectrum support.
spectrumRGB Integer

Required.

Spectrum RGB value as a decimal integer. See 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 for details.
hue Number

Hue.
saturation Number

Saturation.
value Number

Value.

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 and ColorTemperature traits.

Command State
temperature temperatureK
spectrumRGB spectrumRgb
spectrumHSV spectrumHsv

Sample utterances

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.