Smart Home TemperatureSetting Trait Schema

action.devices.traits.TemperatureSetting - This trait covers handling both temperature point and modes.

Device ATTRIBUTES

Attribute Definition
availableThermostatModes Comma-separated list of modes supported by this specific device. Currently supports specific known modes from the following list; more and custom ones will be added as needed. These modes all have local expansion aliases (off == "standby", etc).
  • off Heating/Cooling activity disabled.
  • heat If the device supports heating.
  • cool If the device supports cooling.
  • on If off, on restores the previous mode of the device.
  • heatcool If the device supports maintaining heating/cooling to target a range.
  • auto If the device supports an "automatic" mode where the temperature is set based on a schedule, learned behavior, AI, or some other related mechanism.
  • fan-only If the device supports a mode where only the fan is on (not fan and another mode like cool.)
  • purifier If the device supports a purifying mode.
  • eco If the device supports an "eco" (that is, energy-saving) mode.
  • dry If the device supports a dry mode
thermostatTemperatureUnit C or F. The unit the device is set to by default. The device "speaks" using its display unit.
bufferRangeCelsius Double. Optional. If unset, defaults to 2 degrees Celsius. Specifies the minimum offset between heat-cool setpoints in Celsius, if heatcool mode is supported.
commandOnlyTemperatureSetting 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.
queryOnlyTemperatureSetting Boolean. Optional. Required if the device supports query-only execution. This attribute indicates if the device can only be queried for state information, and cannot be controlled. Sensors that can only report temperature should set this field to true. If this field is true, the availableThermostatModes attribute is optional.

Sample SYNC Request and Response

Initialize Thermostat setting.
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.THERMOSTAT',
        traits: [
          'action.devices.traits.TemperatureSetting'
        ],
        name: {
          defaultNames: ['Honeywell Thermostat T-1000'],
          name: 'Homer Simpson Thermostat',
          nicknames: ['living room thermostat']
        },
        willReportState: false,
        attributes: {
          availableThermostatModes: 'off,heat,cool,on',
          thermostatTemperatureUnit: 'F'
        },
        deviceInfo: {
          manufacturer: 'honeywell',
          model: 't-1000',
          hwVersion: '3.2',
          swVersion: '11.4'
        },
        customData: {
          fooValue: 74,
          barValue: true,
          bazValue: 'lambtwirl'
        }
      }]
    }
  };
});

// ...

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.THERMOSTAT")
          .addTrait("action.devices.traits.TemperatureSetting")
          .setName(
              Collections.singletonList("Honeywell Thermostat T-1000"),
              "Homer Simpson Thermostat",
              Collections.singletonList("living room thermostat")
          )
          .setWillReportState(true)
          .setAttributes(new JSONObject()
              .put("availableThermostatModes", "off,heat,cool,on")
              .put("thermostatTemperatureUnit", "F")
          )
          .setDeviceInfo("honeywell", "t-1000", "3.2", "11.4")
          .setCustomData(new JSONObject()
              .put("fooValue", 74)
              .put("barValue", true)
              .put("bazValue", "lambtwirl")
              .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.THERMOSTAT",
        "traits": [
          "action.devices.traits.TemperatureSetting"
        ],
        "name": {
          "defaultNames": [
            "Honeywell Thermostat T-1000"
          ],
          "name": "Homer Simpson Thermostat",
          "nicknames": [
            "living room thermostat"
          ]
        },
        "willReportState": false,
        "attributes": {
          "availableThermostatModes": "off,heat,cool,on",
          "thermostatTemperatureUnit": "F"
        },
        "deviceInfo": {
          "manufacturer": "honeywell",
          "model": "t-1000",
          "hwVersion": "3.2",
          "swVersion": "11.4"
        },
        "customData": {
          "fooValue": 74,
          "barValue": true,
          "bazValue": "lambtwirl"
        }
      }
    ]
  }
}
Validator

Device STATES

State Definition
thermostatMode Current mode of the device, with the same values as the attribute
thermostatTemperatureSetpoint Current temperature set point (single target), in C
thermostatTemperatureAmbient Current observe temperature, in C
thermostatTemperatureSetpointHigh Current high point if in heatcool mode, for a range
thermostatTemperatureSetpointLow Current low point if in heatcool mode, for a range
thermostatHumidityAmbient Float. 0-100. If available from the device.

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: {
          online: true,
          thermostatMode: 'cool',
          thermostatTemperatureSetpoint: 23.0,
          thermostatTemperatureAmbient: 25.1,
          thermostatHumidityAmbient: 45.3
        }
      }
    }
  };
});

// ...

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, Object>() {{      put("123", new HashMap<String, Object>() {{          put("online", true);
          put("thermostatMode", "cool");
          put("thermostatTemperatureSetpoint", 23);
          put("thermostatTemperatureAmbient", 25.1);
          put("thermostatHumidityAmbient", 45.3);
      }});
      put("status", "SUCCESS");
  }});

  return new QueryResponse(queryRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "online": true,
        "thermostatMode": "cool",
        "thermostatTemperatureSetpoint": 23,
        "thermostatTemperatureAmbient": 25.1,
        "thermostatHumidityAmbient": 45.3
      }
    }
  }
}

Device COMMANDS

Command Parameters/Definition
action.devices.commands.ThermostatTemperatureSetpoint thermostatTemperatureSetpoint Float (in speech we generally take 1 decimal point, for Celsius users).
action.devices.commands.ThermostatTemperatureSetRange thermostatTemperatureSetpointHigh
thermostatTemperatureSetpointLow
Floats. The high and low set points for a range. This works if and only if the device supports heatcool mode, and we will set that mode if a range is requested.
action.devices.commands.ThermostatSetMode thermostatMode One of the supported modes on the device.
action.devices.commands.TemperatureRelative

This command is only available if the commandOnlyTemperatureSetting attribute of the device is set to true. Only one of the following parameters will be set:

  • thermostatTemperatureRelativeDegree Float. The exact number of degrees of the temperature to change (for example, Turn down 5 degrees).

  • thermostatTemperatureRelativeWeight Integer in the range [-5, 5]. This indicates the amount of ambiguous temperature change from a small amount (Turn down a little), to a large amount (A lot warmer).

Sample EXECUTE Request and Response

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.ThermostatTemperatureSetpoint",
          "params": {
            "thermostatTemperatureSetpoint": 22.0
          }
        }]
      }]
    }
  }]
}
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: {
          thermostatMode: 'cool',
          thermostatTemperatureSetpoint: 22.0,
          thermostatTemperatureAmbient: 25.1,
          thermostatHumidityAmbient: 43.2
        }
      }]
    }
  };
});

// ...

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("thermostatMode", "cool");
              put("thermostatTemperatureSetpoint", 22);
              put("thermostatTemperatureAmbient", 25.1);
              put("thermostatHumidityAmbient", 45.3);
          }},
          null
      )
  });
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "thermostatMode": "cool",
          "thermostatTemperatureSetpoint": 22,
          "thermostatTemperatureAmbient": 25.1,
          "thermostatHumidityAmbient": 43.2
        }
      }
    ]
  }
}