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.

Note: All conversions between Fahrenheit and Celsius will be rounded to the nearest degree or half-degree respectively, in input/output to the user. All temperatures are transmitted in Celsius.

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.
temperatureStepCelsius	Float. Optional. Specifies the relative temperature step. For example, this might be 5 degrees on an oven or 1 degree on a kettle.
temperatureUnitForUX	Valid values include "C" or "F". This unit will be used in responses to the user.
queryOnlyTemperatureControl	Boolean. 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.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.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);

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

JSON

{
  "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.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,
          online: true,
          temperatureSetpointCelsius: 177,
          temperatureAmbientCelsius: 150
        }
      }
    }
  };
});

// ...

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

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

JSON

{
  "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.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: {
          temperatureSetpointCelsius: 177,
          temperatureAmbientCelsius: 140
        }
      }]
    }
  };
});

// ...

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("temperatureSetpointCelsius", 177);
              put("temperatureAmbientCelsius", 140);
          }},
          null
      )
  });
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}

JSON

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "temperatureSetpointCelsius": 177,
          "temperatureAmbientCelsius": 140
        }
      }
    ]
  }
}