Smart Home FanSpeed Trait Schema

action.devices.traits.FanSpeed - This trait belongs to devices that support setting the speed of a fan.

Fan speeds (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), may include settings such as low, medium, and high or a percentage.

Device ATTRIBUTES

Devices with this trait may report the following attributes as part of the SYNC operation. To learn more about handling SYNC intents, see Intent fulfillment.

Attributes Type Description
reversible Boolean

(Default: false)

If set to true, this device supports blowing the fan in both directions and can accept the command to reverse fan direction.

commandOnlyFanSpeed Boolean

(Default: false)

Indicates if the device supports using one-way (true) or two-way (false) communication. Set this attribute to true if the device cannot respond to a QUERY intent or Report State for this trait.

Contains any of the following items:
0 Object

Support for speed settings.

availableFanSpeeds Object

Required.

Speed settings supported by the device.

speeds Array

Required.

List of speed settings.

[item, ...] Object

Speed setting.

speed_name String

Required.

Internal name of the speed setting. This can be non-user-friendly, and will be shared across all languages.

speed_values Array

Required.

Synonyms for the speed setting in each supported languages.

[item, ...] Object

Synonym for the speed setting in a given language.

speed_synonym Array

Required.

Synonyms for the speed setting, should include both singular and plural forms, if applicable. The first synonym in the list will be considered the canonical name of the speed setting.

[item, ...] String

Synonym.

lang String

Required.

Language code (ISO 639-1). See supported languages.

ordered Boolean

Required.

If set to true, additional grammar for increase or decrease logic will apply, in the order (increasing) of the speeds array.

1 Object

Support for speed percentage.

supportsFanSpeedPercent Boolean

Required.

(Default: false)

If set to true, this device will accept commands for adjusting the speed using a percentage from 0.0 to 100.0.

Examples

Device with two speed settings, support for reverse direction and percentage adjustments.

{
  "availableFanSpeeds": {
    "speeds": [
      {
        "speed_name": "speed_low",
        "speed_values": [
          {
            "speed_synonym": [
              "low",
              "slow"
            ],
            "lang": "en"
          }
        ]
      },
      {
        "speed_name": "speed_high",
        "speed_values": [
          {
            "speed_synonym": [
              "high",
              "fast"
            ],
            "lang": "en"
          }
        ]
      }
    ],
    "ordered": true
  },
  "reversible": true,
  "supportsFanSpeedPercent": true
}

Device STATES

Devices with this trait may report the following states as part of the QUERY operation. To learn more about handling QUERY intents, see Intent fulfillment.

States Type Description
currentFanSpeedSetting String

This represents the internal name of the current speed setting from the availableFanSpeeds attribute.

currentFanSpeedPercent Number

Indicates the current fan speed by percentage. Required if supportsFanSpeedPercent attribute is set to true

Examples

What speed are the fans in the living room?

{
  "currentFanSpeedSetting": "speed_low",
  "currentFanSpeedPercent": 10
}

Device COMMANDS

Devices with this trait may respond to the following commands as part of the EXECUTE operation. To learn more about handling EXECUTE intents, see Intent fulfillment.

action.devices.commands.SetFanSpeed

Set speed.

Parameters

The payload contains one of the following:

Set speed by settings.

Parameters Type Description
fanSpeed String

Required.

The requested speed settings of the fan.

Set speed by percentage.

Parameters Type Description
fanSpeedPercent Number

Required.

The requested speed setting percentage.

Examples

Set the fan to high.

{
  "command": "action.devices.commands.SetFanSpeed",
  "params": {
    "fanSpeed": "speed_high"
  }
}

Set the fan to 50%.

{
  "command": "action.devices.commands.SetFanSpeed",
  "params": {
    "fanSpeedPercent": 50
  }
}

action.devices.commands.SetFanSpeedRelative

Set relative speed.

This command requires the following attributes:
{
  "commandOnlyFanSpeed": true
}

Parameters

The payload contains one of the following:

Set relative speed by weight.

Parameters Type Description
fanSpeedRelativeWeight Integer

Required.

This value indicates the relative amount of the speed change. The absolute value indicates the scaled amount while the numerical sign indicates the direction of the change.

Set relative speed by percentage.

Parameters Type Description
fanSpeedRelativePercent Number

Required.

This value represents the percentage of speed to change.

Examples

Lower the fan speed little.

{
  "command": "action.devices.commands.SetFanSpeedRelative",
  "params": {
    "fanSpeedRelativeWeight": -1
  }
}

Raise the fan speed by 10 percent.

{
  "command": "action.devices.commands.SetFanSpeedRelative",
  "params": {
    "fanSpeedRelativePercent": 10
  }
}

action.devices.commands.Reverse

Reverse fan direction.

This command requires the following attributes:
{
  "reversible": true
}

Parameters

Parameters Type Description

No properties

Examples

Reverse the fan direction.

{
  "command": "action.devices.commands.Reverse",
  "params": {}
}

Device ERRORS

See the full list of errors and exceptions.
  • maxSpeedReached: The device is already set to the maximum speed.
  • minSpeedReached: The device is already set to the minimum speed.