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

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