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.
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"
  }]
}
Response
{
  "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": ["low", "slow"],
                  "lang": "de"
                }
              ]
            },
            {
              "speed_name": "High",
              "speed_values": [{
                  "speed_synonym": ["high"],
                  "lang": "en"
                },
                {
                  "speed_synonym": ["high"],
                  "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"
      },{
        "id": "456"
      }]
    }
  }]
}
Response
{
  "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"
            }
          }
        }]
      }]
    }
  }]
}
Response
{
  "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"
            }
          }
        }]
      }]
    }
  }]
}
Response
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
         "currentFanSpeedSetting": "S2"
         } 
      }
    }]
  }
}