Smart Home LightEffects Trait Schema

action.devices.traits.LightEffects - This trait belongs to devices that can support complex lighting commands to change state, such as looping through various colors.

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
defaultSleepDuration Integer

(Default: 1800)

The default duration, in seconds, for the effect triggered by the action.devices.commands.Sleep command.

defaultWakeDuration Integer

(Default: 1800)

The default duration, in seconds, for the effect triggered by the action.devices.commands.Wake command.

supportedEffects Array <String>

List of the effects that the device supports.

Supported effect.

Supported values:

colorLoop
Loops through various colors randomly.
sleep
Gradually lowers brightness and, optionally, adjusts the color temperature over a period of time.
wake
Gradually increases brightness and, optionally, adjusts the color temperature over a period of time.

Required:

  • supportedEffects
Examples

Device supporting color loop effect.

{
  "supportedEffects": [
    "colorLoop"
  ]
}

Device supporting sleep/wake effects.

{
  "defaultSleepDuration": 300,
  "defaultWakeDuration": 600,
  "supportedEffects": [
    "sleep",
    "wake"
  ]
}

Sample SYNC Request and Response

Request
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.SYNC"
    }]
}
Node.js
'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.OnOff',
          'action.devices.traits.LightEffects'
        ],
        name: {
          defaultNames: ['AAA bulb A19 color hyperglow'],
          name: 'Lamp',
          nicknames: ['Reading lamp']
        },
        willReportState: true,
        attributes: {
          supportedEffects: [
            'colorLoop',
            'sleep',
            'wake'
          ],
        },
        deviceInfo: {
          manufacturer: 'BrandX',
          model: 'hg11',
          hwVersion: '1.2',
          swVersion: '5.4'
        },
        customData: {
          fooValue: 12,
          barValue: false,
          bazValue: 'goatjive'
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@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.OnOff")
            .addTrait("action.devices.traits.LightEffects")
            .setName(
                Collections.singletonList("AAA bulb A19 color hyperglow"),
                "Lamp",
                Collections.singletonList("Reading lamp"))
            .setWillReportState(true)
            .setAttributes(
                new JSONObject()
                    .put("supportedEffects", new String[] {"colorLoop", "sleep", "wake"}))
            .setDeviceInfo("BrandX", "hg11", "1.2", "5.4")
            .setCustomData(
                new JSONObject()
                    .put("fooValue", 12)
                    .put("barValue", false)
                    .put("bazValue", "goatjive")
                    .toString())
            .build()
      });
  return new SyncResponse(syncRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "123",
        "type": "action.devices.types.LIGHT",
        "traits": [
          "action.devices.traits.OnOff",
          "action.devices.traits.LightEffects"
        ],
        "name": {
          "defaultNames": [
            "AAA bulb A19 color hyperglow"
          ],
          "name": "Lamp",
          "nicknames": [
            "Reading lamp"
          ]
        },
        "willReportState": true,
        "attributes": {
          "supportedEffects": [
            "colorLoop",
            "sleep",
            "wake"
          ]
        },
        "deviceInfo": {
          "manufacturer": "BrandX",
          "model": "hg11",
          "hwVersion": "1.2",
          "swVersion": "5.4"
        },
        "customData": {
          "fooValue": 12,
          "barValue": false,
          "bazValue": "goatjive"
        }
      }
    ]
  }
}
Validator

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
activeLightEffect String

Currently active light effect. One of supportedEffects.

Supported values:

colorLoop
sleep
wake

Required:

  • activeLightEffect
Examples

What is the current effect on my device?

{
  "activeLightEffect": "colorLoop"
}

Sample QUERY Request and Response

Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": 'action.devices.QUERY',
    "payload": {
      "devices": [{
        "id": "123",
        "customData": {
          "fooValue": 74,
          "barValue": true,
          "bazValue": "foo"
        }
      }]
    }
  }]
}
Node.js
'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: {
          on: true,
          activeLightEffect: 'colorLoop',
          online: true,
          status: 'SUCCESS'
        }
      }
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@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("on", true);
                  put("activeLightEffect", "colorLoop");
                  put("online", true);
                  put("status", "SUCCESS");
                }
              });
        }
      });

  return new QueryResponse(queryRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "on": true,
        "activeLightEffect": "colorLoop",
        "online": true,
        "status": "SUCCESS"
      }
    }
  }
}

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

Parameters

Request the device to cycle through a set of colors.

Parameters Type Description
duration Integer

Duration for the color loop command, in seconds.

Examples

Colorloop my lights for 60 minutes.

{
  "duration": 3600
}

action.devices.commands.Sleep

Parameters

Gradually lower the device's brightness and, optionally, adjusts the color temperature over a duration of time.

Parameters Type Description
duration Integer

Duration for the sleep command, in seconds.

Examples

Make my lights sleep for 60 minutes.

{
  "duration": 3600
}

action.devices.commands.StopEffect

Parameters

Stop the current light effect.

Parameters
No properties.
Examples

Stop the effect on my light.

action.devices.commands.Wake

Parameters

Gradually increase the device's brightness and, optionally, adjusts the color temperature over a duration of time.

Parameters Type Description
duration Integer

Duration for the wake command, in seconds.

Examples

Make my lights wake for 60 minutes.

{
  "duration": 3600
}

Light effects emulation

If your device implements the Brightness trait but not the LightEffects trait, the platform supports emulated "sleep" and "wake" effects, without the need for additional code. The platform emulates the effects by sending a series of EXECUTE intents.

Sample EXECUTE Request and Response

Color loop command example

User Start color loop on the desk lamp.
Google Assistant Sure, starting color loop on the desk lamp.
Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
          "customData": {
            "fooValue": 74,
            "barValue": true,
            "bazValue": "goatjive"
          }
        }],
        "execution": [{
          "command": "action.devices.commands.ColorLoop"
        }]
      }]
    }
  }]
}
Node.js
'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: {
          on: true,
          activeLightEffect: 'colorLoop'
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@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("activeLightEffect", "colorLoop");
                put("online", true);
              }
            },
            null,
            null)
      });
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "on": true,
          "activeLightEffect": "colorLoop"
        }
      }
    ]
  }
}

Sleep command example

User Make my lights sleep for 60 minutes.
Google Assistant Sure, setting the lights to sleep for 60 minutes.
Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
          "customData": {
            "fooValue": 74,
            "barValue": true,
            "bazValue": "goatjive"
          }
        }],
        "execution": [{
          "command": "action.devices.commands.Sleep",
          "params": {
            "duration": 1800
          }
        }]
      }]
    }
  }]
}
Node.js
'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: {
          on: true,
          activeLightEffect: 'sleep'
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@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("activeLightEffect", "sleep");
                put("online", true);
              }
            },
            null,
            null)
      });
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "on": true,
          "activeLightEffect": "sleep"
        }
      }
    ]
  }
}

Wake command example

User Make my lights wake for 60 minutes.
Google Assistant Sure, setting the lights to wake for 60 minutes.
Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
          "customData": {
            "fooValue": 74,
            "barValue": true,
            "bazValue": "goatjive"
          }
        }],
        "execution": [{
          "command": "action.devices.commands.Wake",
          "params": {
            "duration": 1800
          }
        }]
      }]
    }
  }]
}
Node.js
'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: {
          on: true,
          activeLightEffect: 'wake'
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@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("activeLightEffect", "wake");
                put("online", true);
              }
            },
            null,
            null)
      });
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "on": true,
          "activeLightEffect": "wake"
        }
      }
    ]
  }
}

Device ERRORS

See the full list of errors and exceptions.