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

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.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);
JavaResponse
@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);
}
JSONResponse
{
  "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"
        }
      }
    ]
  }
}
Validator

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?
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,
          currentFanSpeedSetting: 'S2'
        },
        456: {
          on: true,
          online: true,
          currentFanSpeedSetting: 'S1'
        }
      }
    }
  };
});

// ...

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("currentFanSpeedSetting", "S2");
      }});
      put("456", new HashMap<String, Object>() {{          put("on", true);
          put("online", true);
          put("currentFanSpeedSetting", "S1");
      }});
  }});

  return new QueryResponse(queryRequest.getRequestId(), payload);
}
JSONResponse
{
  "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.
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.SetFanSpeed",
          "params": {
            "fanSpeed": "S1"
          }
        }]
      }]
    }
  }]
}
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: {
          currentFanSpeedSetting: 'S1'
        }
      }]
    }
  };
});

// ...

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("currentFanSpeedSetting", "S1");
        }},
        null
    )
});
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
JSONResponse
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "currentFanSpeedSetting": "S1"
        }
      }
    ]
  }
}
Turn the bedroom fan to maximum.
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.SetFanSpeed",
          "params": {
            "fanSpeed": "S2"
          }
        }]
      }]
    }
  }]
}
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: {
          currentFanSpeedSetting: 'S2'
        }
      }]
    }
  };
});

// ...

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