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"
}
}
]
}
}