Smart Home FanSpeed Trait Schema
action.devices.traits.FanSpeed - This trait belongs to devices that support setting the speed of
a fan (that is, blowing air from the device at various levels, which may be part of an air
conditioning or heating unit, or in a car), with settings such as low, medium, and high.
Device ATTRIBUTES
| Attribute |
Definition |
availableFanSpeeds |
speeds Array containing the name of each speed and a subarray for
speed_values with language-specific synonyms. For example, the speed_name "S4" could
correspond to the speed_synonym strings "highest" and "maximum" given the language code
"en".
speed_name String. Internal name of the mode, which will be used in
commands and states. This can be non-user-friendly, and will be shared
across all languages.speed_values Contains names and supported languages:
speed_synonym Strings. User-friendly names for the speed,
in each language supported.lang String. Supported language for the names (see Supported Languages/Language Codes).
ordered Boolean. If set to true, additional grammar for increase/decrease
logic will apply, in the order (increasing) of the speeds array.
|
reversible | Boolean. If set to true, this device supports blowing the fan in both
directions and can accept the command to reverse fan direction. |
commandOnlyFanSpeed |
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:
{
"availableFanSpeeds": {
"speeds": [{
"speed_name": "S1",
"speed_values": [{
"speed_synonym": ["low", "speed 1", ... ],
"lang": "en" } , … ]
},
{
"speed_name": "S2",
"speed_values": [{
"speed_synonym": ["high", "speed 2", ... ],
"lang": "en" } , … ]
}, ...
],
"ordered": true
}
"reversible": true
}
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.FAN',
traits: [
'action.devices.traits.FanSpeed'
],
name: {
defaultNames: ['Sirius Cybernetics Corporation 33321'],
name: 'Fan',
nicknames: ['wall fan']
},
willReportState: false,
attributes: {
availableFanSpeeds: {
speeds: [{
speed_name: 'Low',
speed_values: [{
speed_synonym: ['low', 'slow'],
lang: 'en'
}, {
speed_synonym: ['niedrig', 'schleppend'],
lang: 'de'
}]
}, {
speed_name: 'High',
speed_values: [{
speed_synonym: ['high'],
lang: 'en'
}, {
speed_synonym: ['hoch'],
lang: 'de'
}]
}],
ordered: true
},
reversible: true
},
deviceInfo: {
manufacturer: 'Sirius Cybernetics Corporation',
model: '233451',
hwVersion: '3.2',
swVersion: '11.4'
},
customData: {
fooValue: 74,
barValue: true,
bazValue: 'lambtwirl'
}
}]
}
};
});
// ...
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 SyncResponse.Payload.Device[] {
new SyncResponse.Payload.Device.Builder()
.setId("123")
.setType("action.devices.types.FAN")
.addTrait("action.devices.traits.OnOff")
.addTrait("action.devices.traits.FanSpeed")
.setName(
Collections.singletonList("Sirius Cybernetics Corporation 33321"),
"Fan",
Collections.singletonList("wall fan")
)
.setWillReportState(true)
.setAttributes(new JSONObject()
.put("availableFanSpeeds", new JSONObject()
.put("speeds", new JSONObject[] {
new JSONObject()
.put("speed_name", "Low")
.put("speed_values", new JSONObject[] {
new JSONObject()
.put("speed_synonym", new String[] {"low", "slow"})
.put("lang", "en"),
new JSONObject()
.put("speed_synonym", new String[] {"niedrig", "schleppend"})
.put("lang", "de")
}),
new JSONObject()
.put("speed_name", "High")
.put("speed_values", new JSONObject[] {
new JSONObject()
.put("speed_synonym", new String[] {"high"})
.put("lang", "en"),
new JSONObject()
.put("speed_synonym", new String[] {"hoch"})
.put("lang", "de")
})
})
.put("ordered", true)
)
.put("reversible", true)
)
.setDeviceInfo("Sirius Cybernetics Corporation", "492134", "3.2", "11.4")
.setCustomData(new JSONObject()
.put("fooValue", 74)
.put("barValue", true)
.put("bazValue", "lambtwirl")
.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.FAN",
"traits": [
"action.devices.traits.FanSpeed"
],
"name": {
"defaultNames": [
"Sirius Cybernetics Corporation 33321"
],
"name": "Fan",
"nicknames": [
"wall fan"
]
},
"willReportState": false,
"attributes": {
"availableFanSpeeds": {
"speeds": [
{
"speed_name": "Low",
"speed_values": [
{
"speed_synonym": [
"low",
"slow"
],
"lang": "en"
},
{
"speed_synonym": [
"niedrig",
"schleppend"
],
"lang": "de"
}
]
},
{
"speed_name": "High",
"speed_values": [
{
"speed_synonym": [
"high"
],
"lang": "en"
},
{
"speed_synonym": [
"hoch"
],
"lang": "de"
}
]
}
],
"ordered": true
},
"reversible": true
},
"deviceInfo": {
"manufacturer": "Sirius Cybernetics Corporation",
"model": "233451",
"hwVersion": "3.2",
"swVersion": "11.4"
},
"customData": {
"fooValue": 74,
"barValue": true,
"bazValue": "lambtwirl"
}
}
]
}
}
Device STATES
| State |
Definition |
currentFanSpeedSetting |
String. Required. This represents the name of the current speed setting of the device with
the action.devices.traits.FanSpeed trait (for example, "S2").
|
Sample QUERY Request and Response
What speed are the fans in the living room?
{
"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,
currentFanSpeedSetting: 'S2'
},
456: {
on: true,
online: true,
currentFanSpeedSetting: 'S1'
}
}
}
};
});
// ...
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("currentFanSpeedSetting", "S2");
}});
put("456", new HashMap<String, Object>() {{ put("on", true);
put("online", true);
put("currentFanSpeedSetting", "S1");
}});
put("status", "SUCCESS");
}});
return new QueryResponse(queryRequest.getRequestId(), payload);
}
{
"requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
"payload": {
"devices": {
"123": {
"on": true,
"online": true,
"currentFanSpeedSetting": "S2"
},
"456": {
"on": true,
"online": true,
"currentFanSpeedSetting": "S1"
}
}
}
}
Device COMMANDS
| Command |
Parameters/Definition |
action.devices.commands.SetFanSpeed |
fanSpeed String representing the name of the requested speed of the fan
(for example, "S2").
|
action.devices.commands.Reverse |
Reverse fan direction. |
|
Sample EXECUTE Request and Response
Set the fan to low.
{
"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.SetFanSpeed",
"params": {
"fanSpeed": "S1"
}
}]
}]
}
}]
}
'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: {
currentFanSpeedSetting: 'S1'
}
}]
}
};
});
// ...
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("currentFanSpeedSetting", "S1");
}},
null
)
});
return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
{
"requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
"payload": {
"commands": [
{
"ids": [
"123"
],
"status": "SUCCESS",
"states": {
"currentFanSpeedSetting": "S1"
}
}
]
}
}
Turn the bedroom fan to maximum.
{
"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.SetFanSpeed",
"params": {
"fanSpeed": "S2"
}
}]
}]
}
}]
}
'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: {
currentFanSpeedSetting: 'S2'
}
}]
}
};
});
// ...
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("currentFanSpeedSetting", "S2");
}},
null
)
});
return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
{
"requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
"payload": {
"commands": [
{
"ids": [
"123"
],
"status": "SUCCESS",
"states": {
"currentFanSpeedSetting": "S2"
}
}
]
}
}
