Smart Home Brightness Trait Schema

action.devices.traits.Brightness - This trait covers how to control the brightness of a device. Absolute brightness setting is in a normalized range from 0 to 100 (individual lights may not support every point in the range based on their LED configuration).

Device ATTRIBUTES

Attribute	Definition
commandOnlyBrightness	Boolean. Optional. Defaults to false. Indicates if the device operates using one-way (true) or two-way (false) communication. For example, if the controller can confirm the new device state after sending the request, this field would be false. If it's not possible to confirm if the request is successfully executed or to get the state of the device, set this field to true.

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.Brightness'
        ],
        name: {
          defaultNames: ['AAA bulb A19 color hyperglow'],
          name: 'lamp1',
          nicknames: ['reading lamp']
        },
        willReportState: 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);

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.Brightness")
          .setName(
              Collections.singletonList("AAA bulb A19 color hyperglow"),
              "lamp1",
              Collections.singletonList("reading lamp")
          )
          .setWillReportState(true)
          .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);
}

JSON

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "123",
        "type": "action.devices.types.LIGHT",
        "traits": [
          "action.devices.traits.Brightness"
        ],
        "name": {
          "defaultNames": [
            "AAA bulb A19 color hyperglow"
          ],
          "name": "lamp1",
          "nicknames": [
            "reading lamp"
          ]
        },
        "willReportState": 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
brightness	Integer. Current brightness level. Ideally, this is the number that was set versus the rounded point (for example, if the user sets it to 65%, but the device has to round to 10% increments, ideally this would still return 65%).

Sample QUERY Request and Response

What is the brightness level of my light?

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: {
          online: true,
          brightness: 65
        }
      }
    }
  };
});

// ...

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("online", true);
          put("brightness", 65);
      }});
  }});

  return new QueryResponse(queryRequest.getRequestId(), payload);
}

JSON

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "online": true,
        "brightness": 65
      }
    }
  }
}

Device COMMANDS

Command	Parameters/Definition
action.devices.commands.BrightnessAbsolute	brightness Integer. Required. New absolute brightness, from 0 to 100.

Sample EXECUTE Request and Response

Adjust my light to 65% brightness.

Request

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
          "customData": {
            "fooValue": 74,
            "barValue": true,
            "bazValue": "sheepdip"
          }
        }],
        "execution": [{
          "command": "action.devices.commands.BrightnessAbsolute",
          "params": {
            "brightness": 65
          }
        }]
      }]
    }
  }]
}

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: {
          brightness: 65
        }
      }]
    }
  };
});

// ...

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("brightness", 65);
          }},
          null
      )
  });
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}

JSON

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "brightness": 65
        }
      }
    ]
  }
}