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. A device with this trait may support full spectrum color as an RGB or HSV value, color temperature as a value in Kelvin, or both (though not simultaneously). For example, a light cannot be set to both "green" and "9000 Kelvin" at the same time.

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

Attribute Definition
colorModel

String. Required if the device supports the full spectrum color model. Required if the colorTemperatureRange attribute is not set. Must be set to exactly one of the following values:

  • rgb Default model. The device supports the RGB color model.
  • hsv The device supports the HSV color model.
colorTemperatureRange

Object. Required if the device supports color temperature set by Kelvin. Required if the colorModel attribute is not set. Contains the minimum and maximum values in Kelvin supported by the device. Note that colorTemperatureRange may exist when colorModel is rgb or hsv if the device supports both temperature and a full spectrum color model.

  • temperatureMinK Integer. Minimum color temperature (in Kelvin) supported by the device.
  • temperatureMaxK Integer. Maximum color temperature (in Kelvin) supported by the device.
commandOnlyColorSetting Boolean. Defaults to false. Required if the device supports command-only execution. This attribute indicates if the device supports one-way or two-way communication (for example, two-way is supported if the controller reports the new state after sending the request). Must be set to true if the device cannot confirm successful execution of the request by reporting state.

Sample SYNC Request and Response

Request
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.SYNC"
    }]
}
Node.jsResponse
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onSync((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      agentUserId: '1836.15267389',
      devices: [{
        id: '123',
        type: 'action.devices.types.LIGHT',
        traits: [
          'action.devices.traits.ColorSetting'
        ],
        name: {
          defaultNames: ['AAA bulb A19 color hyperglow'],
          name: 'lamp1',
          nicknames: ['reading lamp']
        },
        willReportState: false,
        attributes: {
          colorModel: 'rgb',
          colorTemperatureRange: {
            temperatureMinK: 2000,
            temperatureMaxK: 9000
          },
          commandOnlyColorSetting: false
        },
        deviceInfo: {
          manufacturer: 'AAA',
          model: 'hg11',
          hwVersion: '1.2',
          swVersion: '5.4'
        },
        customData: {
          fooValue: 12,
          barValue: false,
          bazValue: 'dancing alpaca'
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
JavaResponse
@NotNull
@Override
public SyncResponse onSync(@NotNull SyncRequest syncRequest, @Nullable Map<?, ?> headers) {
  Payload payload = new Payload();
  payload.setAgentUserId("1836.15267389");
  payload.setDevices(new Device[] {
      new Device.Builder()
          .setId("123")
          .setType("action.devices.types.LIGHT")
          .addTrait("action.devices.traits.ColorSetting")
          .setName(
              Collections.singletonList("AAA bulb A19 color hyperglow"),
              "lamp1",
              Collections.singletonList("reading lamp")
          )
          .setWillReportState(true)
          .setAttributes(new JSONObject()
              .put("colorModel", "rgb")
              .put("colorTemperatureRange", new JSONObject()
                  .put("temperautreMinK", 2000)
                  .put("temperatureMaxK", 9000)
              )
              .put("commandOnlyColorSetting", false)
          )
          .setDeviceInfo("AAA", "hg11", "1.2", "5.4")
          .setCustomData(new JSONObject()
              .put("fooValue", 12)
              .put("barValue", false)
              .put("bazValue", "dancing alpaca")
              .toString()
          )
          .build()
  });
  return new SyncResponse(syncRequest.getRequestId(), payload);
}
JSONResponse
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "123",
        "type": "action.devices.types.LIGHT",
        "traits": [
          "action.devices.traits.ColorSetting"
        ],
        "name": {
          "defaultNames": [
            "AAA bulb A19 color hyperglow"
          ],
          "name": "lamp1",
          "nicknames": [
            "reading lamp"
          ]
        },
        "willReportState": false,
        "attributes": {
          "colorModel": "rgb",
          "colorTemperatureRange": {
            "temperatureMinK": 2000,
            "temperatureMaxK": 9000
          },
          "commandOnlyColorSetting": false
        },
        "deviceInfo": {
          "manufacturer": "AAA",
          "model": "hg11",
          "hwVersion": "1.2",
          "swVersion": "5.4"
        },
        "customData": {
          "fooValue": 12,
          "barValue": false,
          "bazValue": "dancing alpaca"
        }
      }
    ]
  }
}
Validator

Device STATES

State Definition
color

Object. The current color setting. Must contain exactly one of the following states (whichever is currently being used on the device):

  • temperatureK Integer. Value in Kelvin. Used if the device is currently set to a color temperature; for example, "cool white" at 4000 K.
  • spectrumRgb Integer. Used if colorModel is set to rgb. Spectrum value in RGB, which is a hex value converted to a decimal integer. For example, "blue", represented as #0000FF in hexadecimal, would map to decimal integer 255.
  • spectrumHsv Object. Used if colorModel is set to hsv. Must contain the following three parameters:
    • hue Float representing hue as positive degrees (for example, 300.0° rather than -60.0°) in the range of [0.0, 360.0).
    • saturation Float. Saturation as a percentage in the range [0.0, 1.0].
    • value Float. Value as a percentage in the range [0.0, 1.0]

The following is an example for a color setting of spectrumHsv:
"color": {
  "spectrumHsv": {
    "hue": 240.0,
    "saturation": 1.0,
    "value": 1.0
  }
}

Sample QUERY Request and Response

What color is the desk lamp?

Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": 'action.devices.QUERY',
    "payload": {
      "devices": [{
        "id": "123",
        "customData": {
          "fooValue": 74,
          "barValue": true,
          "bazValue": "foo"
        }
      }]
    }
  }]
}
Node.jsResponse
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onQuery((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      devices: {
        123: {
          online: true,
          spectrumRgb: 16711935
        }
      }
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
JavaResponse
@NotNull
@Override
public QueryResponse onQuery(@NotNull QueryRequest queryRequest, @Nullable Map<?, ?> map) {
  QueryResponse.Payload payload = new QueryResponse.Payload();
  payload.setDevices(new HashMap<String, Map<String, Object>>() {{    put("123", new HashMap<String, Object>() {{      put("online", true);
      put("spectrumRgb", 16711935);
    }});
  }});

  return new QueryResponse(queryRequest.getRequestId(), payload);
}
JSONResponse
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "online": true,
        "spectrumRgb": 16711935
      }
    }
  }
}

Device COMMANDS

Command Parameters/Definition
action.devices.commands.ColorAbsolute

color Object. The new color setting.

  • name Optional. String representing the color name parsed from the user’s command (warm white, red, etc.); may not always be available (for example, relative commands such as Make the light warmer).

The color object must include exactly one of the following:

  • temperature Integer. Color temperature in Kelvin. May be sent if the colorTemperatureRange attribute is provided.
  • spectrumRGB Integer. Color value in RGB (hexadecimal value converted to decimal). May be sent if colorModel is rgb.
  • spectrumHSV Object. May be sent if colorModel is hsv. Must contain the following three parameters:
    • hue Float representing hue as positive degrees (for example, 300.0° rather than -60.0°) in the range of [0.0, 360.0).
    • saturation Float. Saturation as a percentage in the range [0.0, 1.0].
    • value Float. Value as a percentage in the range [0.0, 1.0]

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 EXECUTE Request and Response

Make the light magenta. (The colorModel attribute is set to rgb.)

Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
          "customData": {
            "fooValue": 74,
            "barValue": true,
            "bazValue": "lambtwirl"
          }
        }],
        "execution": [{
          "command": "action.devices.commands.ColorAbsolute",
          "params": {
            "color": {
              "name": "magenta",
              "spectrumRGB": 16711935
            }
          }
        }]
      }]
    }
  }]
}
Node.jsResponse
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onExecute((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      commands: [{
        ids: ['123'],
        status: 'SUCCESS',
        states: {
          online: true,
          color: {
            spectrumRgb: 16711935
          }
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
JavaResponse
@NotNull
@Override
public ExecuteResponse onExecute(@NotNull ExecuteRequest executeRequest, @Nullable Map<?, ?> map) {
  ExecuteResponse.Payload payload = new ExecuteResponse.Payload();
payload.setCommands(new Commands[] {
    new Commands(
        new String[] {"123"},
        "SUCCESS",
        new HashMap<String, Object>() {{            put("online", true);
            put("color", new HashMap<String, Object>() {{                put("spectrumRgb", 16711935);
            }});
        }},
        null
    )
});
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
JSONResponse
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "color": {
            "spectrumRgb": 16711935
          }
        }
      }
    ]
  }
}

Change the kitchen lamp to blue (The colorModel attribute is set to hsv.)

Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "456",
          "customData": {
            "fooValue": 74,
            "barValue": true,
            "bazValue": "lambtwirl"
          }
        }],
        "execution": [{
          "command": "action.devices.commands.ColorAbsolute",
          "params": {
            "color": {
              "spectrumHSV": {
                "hue": 240.0,
                "saturation": 1.0,
                "value": 1.0
              }
            }
          }
        }]
      }]
    }
  }]
}
Node.jsResponse
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onExecute((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      commands: [{
        ids: ['123'],
        status: 'SUCCESS',
        states: {
          online: true,
          color: {
            spectrumHsv: {
              hue: 240.0,
              saturation: 1.0,
              value: 1.0
            }
          }
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
JavaResponse
@NotNull
@Override
public ExecuteResponse onExecute(@NotNull ExecuteRequest executeRequest, @Nullable Map<?, ?> map) {
  ExecuteResponse.Payload payload = new ExecuteResponse.Payload();
payload.setCommands(new Commands[] {
    new Commands(
        new String[] {"123"},
        "SUCCESS",
        new HashMap<String, Object>() {{            put("online", true);
            put("color", new HashMap<String, Object>() {{                put("spectrumHsv", new HashMap<String, Object>() {{                    put("hue", 240);
                    put("saturation", 1);
                    put("value", 1);
                }});
            }});
        }},
        null
    )
});
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
JSONResponse
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "color": {
            "spectrumHsv": {
              "hue": 240,
              "saturation": 1,
              "value": 1
            }
          }
        }
      }
    ]
  }
}

Set the lamp to cool white (The colorTemperatureRange attribute is provided.)

Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "456",
          "customData": {
            "fooValue": 74,
            "barValue": true,
            "bazValue": "lambtwirl"
          }
        }],
        "execution": [{
          "command": "action.devices.commands.ColorAbsolute",
          "params": {
            "color": {
              "name": "warm white",
              "temperature": 4000
            }
          }
        }]
      }]
    }
  }]
}
Node.jsResponse
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onExecute((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      commands: [{
        ids: ['123'],
        status: 'SUCCESS',
        states: {
          online: true,
          color: {
            temperatureK: 4000
          }
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
JavaResponse
@NotNull
@Override
public ExecuteResponse onExecute(@NotNull ExecuteRequest executeRequest, @Nullable Map<?, ?> map) {
  ExecuteResponse.Payload payload = new ExecuteResponse.Payload();
payload.setCommands(new Commands[] {
    new Commands(
        new String[] {"123"},
        "SUCCESS",
        new HashMap<String, Object>() {{          put("online", true);
          put("color", new HashMap<String, Object>() {{            put("temperatureK", 4000);
          }});
        }},
        null
    )
});
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
JSONResponse
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "color": {
            "temperatureK": 4000
          }
        }
      }
    ]
  }
}