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.

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

Devices 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.

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

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

Device ERRORS

See the full list of errors and exceptions.