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. 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.
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.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.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);

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.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);
}

JSONResponse

{
  "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

Note 1: States are only relevant if the attribute commandOnlyTemperatureSetting is set to false.

Note 2: Temperatures can be set in Fahrenheit by the user, but all temperature values in commands and states are in Celsius. Any required unit conversion is performed automatically.

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

// ...

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("thermostatMode", "cool");
          put("thermostatTemperatureSetpoint", 23);
          put("thermostatTemperatureAmbient", 25.1);
          put("thermostatHumidityAmbient", 45.3);
      }});
  }});

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

JSONResponse

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "online": true,
        "thermostatMode": "cool",
        "thermostatTemperatureSetpoint": 23,
        "thermostatTemperatureAmbient": 25.1,
        "thermostatHumidityAmbient": 45.3
      }
    }
  }
}

Device COMMANDS

Note: Temperatures can be set in Fahrenheit by the user, but all temperature values in commands and states are in Celsius. Any required unit conversion is performed automatically.

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

// ...

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("thermostatMode", "cool");
              put("thermostatTemperatureSetpoint", 22);
              put("thermostatTemperatureAmbient", 25.1);
              put("thermostatHumidityAmbient", 45.3);
          }},
          null
      )
  });
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}

JSONResponse

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "thermostatMode": "cool",
          "thermostatTemperatureSetpoint": 22,
          "thermostatTemperatureAmbient": 25.1,
          "thermostatHumidityAmbient": 43.2
        }
      }
    ]
  }
}