Smart Home TemperatureControl Trait Schema

action.devices.traits.TemperatureControl - Trait for devices (other than thermostats) that support controlling temperature, either within or around the device. This includes devices such as ovens and refrigerators. This differs from the TemperatureSetting trait, which is specifically for thermostat control.

Device ATTRIBUTES

Attribute Definition
temperatureRange Defines the temperature range.
  • minThresholdCelsius Float. Minimum temperature for the range, in Celsius.
  • maxThresholdCelsius Float. Maximum temperature for the range, in Celsius.
temperatureStepCelsiusFloat. Optional. Specifies the relative temperature step. For example, this might be 5 degrees on an oven or 1 degree on a kettle.
temperatureUnitForUXValid values include "C" or "F". This unit will be used in responses to the user.
queryOnlyTemperatureControlBoolean. Optional. Indicates if the device can only be queried for state information, and cannot be controlled. Sensors that can only report temperature should set this attribute to true. If this attribute is true, the temperatureRange attribute is optional.
commandOnlyTemperatureControl 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.
The following is an example:
{
  "temperatureRange": {
    "minThresholdCelsius": 65.5,
    "maxThresholdCelsius": 288
  },
  "temperatureStepCelsius": 2.778,
  "temperatureUnitForUX": "F"
}

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.KETTLE',
        traits: [
          'action.devices.traits.OnOff',
          'action.devices.traits.TemperatureControl'
        ],
        name: {
          defaultNames: ['Smart Kettle 1'],
          name: 'Smart Kettle 1',
          nicknames: ['Little teapot']
        },
        willReportState: false,
        attributes: {
          temperatureRange: {
            minThresholdCelsius: 30,
            maxThresholdCelsius: 100
          },
          temperatureStepCelsius: 1,
          temperatureUnitForUX: 'C'
        },
        deviceInfo: {
          manufacturer: 'Smart Home Provider',
          model: 'g1340',
          swVersion: '1.0.31',
          hwVersion: '1.1'
        },
        customData: {
          smartHomeProviderId: 'fiGgZ0vrhFRgwf5XJkna2GRwO8z80J'
        }
      }]
    }
  };
});

// ...

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.KETTLE")
          .addTrait("action.devices.traits.TemperatureControl")
          .setName(
              Collections.singletonList("Smart Kettle 1"),
              "Smart Kettle 1",
              Collections.singletonList("Little teapot")
          )
          .setWillReportState(true)
          .setAttributes(new JSONObject()
              .put("temperatureRange", new JSONObject()
                  .put("minThresholdCelsius", 30)
                  .put("maxThresholdCelsius", 100)
              )
              .put("temperatureStepCelsius", 1)
              .put("temperatureUnitForUX", "C")
          )
          .setDeviceInfo("Smart Home Provider", "g1340", "1.0.31", "1.1")
          .setCustomData(new JSONObject()
              .put("smartHomeProviderId", "fiGgZ0vrhFRgwf5XJkna2GRwO8z80J")
              .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.KETTLE",
        "traits": [
          "action.devices.traits.OnOff",
          "action.devices.traits.TemperatureControl"
        ],
        "name": {
          "defaultNames": [
            "Smart Kettle 1"
          ],
          "name": "Smart Kettle 1",
          "nicknames": [
            "Little teapot"
          ]
        },
        "willReportState": false,
        "attributes": {
          "temperatureRange": {
            "minThresholdCelsius": 30,
            "maxThresholdCelsius": 100
          },
          "temperatureStepCelsius": 1,
          "temperatureUnitForUX": "C"
        },
        "deviceInfo": {
          "manufacturer": "Smart Home Provider",
          "model": "g1340",
          "swVersion": "1.0.31",
          "hwVersion": "1.1"
        },
        "customData": {
          "smartHomeProviderId": "fiGgZ0vrhFRgwf5XJkna2GRwO8z80J"
        }
      }
    ]
  }
}
Validator

Device STATES

State Definition
temperatureSetpointCelsius Float. Required. The current temperature setpoint, in Celsius.
temperatureAmbientCelsius Float. Optional. The currently observed temperature, in Celsius.

Sample QUERY Request and Response

What temperature is the oven set to?
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: {
          on: true,
          online: true,
          temperatureSetpointCelsius: 177,
          temperatureAmbientCelsius: 150
        }
      }
    }
  };
});

// ...

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("on", true);
          put("online", true);
          put("temperatureSetpointCelsius", 177);
          put("temperatureAmbientCelsius", 150);
      }});
  }});

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

Device COMMANDS

Command Parameters/Definition
action.devices.commands.SetTemperature temperature Float. The temperature to set, in Celsius.

Sample EXECUTE Request and Response

Set the oven to 350 degrees.
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.SetTemperature",
          "params": {
            "temperature": 176.67
          }
        }]
      }]
    }
  }]
}
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: {
          temperatureSetpointCelsius: 177,
          temperatureAmbientCelsius: 140
        }
      }]
    }
  };
});

// ...

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("temperatureSetpointCelsius", 177);
              put("temperatureAmbientCelsius", 140);
          }},
          null
      )
  });
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
JSONResponse
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "temperatureSetpointCelsius": 177,
          "temperatureAmbientCelsius": 140
        }
      }
    ]
  }
}