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.

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.

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.

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

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.

Sample utterances

Device ERRORS