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
{
"requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
"inputs": [{
"intent": "action.devices.SYNC"
}]
}
'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);
@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);
}
{
"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"
}
}
]
}
}
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?
{
"requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
"inputs": [{
"intent": 'action.devices.QUERY',
"payload": {
"devices": [{
"id": "123",
"customData": {
"fooValue": 74,
"barValue": true,
"bazValue": "foo"
}
}]
}
}]
}
'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);
@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);
}
{
"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.
{
"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
}
}]
}]
}
}]
}
'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);
@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);
}
{
"requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
"payload": {
"commands": [
{
"ids": [
"123"
],
"status": "SUCCESS",
"states": {
"temperatureSetpointCelsius": 177,
"temperatureAmbientCelsius": 140
}
}
]
}
}