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

Entities 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": {}
}

Sample utterances

de-DE

  • stell die Geschwindigkeit vom Ventilator auf hoch

en-US

  • drop the AC fan speed to medium

es-ES

  • cambia la velocidad del ventilador a medio

fr-FR

  • mets la ventilation au maximum

hi-IN

  • बेडरूम में पंखे की गति मीडियम करें

it-IT

  • metti il condizionatore in salotto a velocità media

ja-JP

  • エアコン の風量を 高速 にセット

ko-KR

  • 선풍기 강풍 으로 틀어 줘

nl-NL

  • zet de snelheid van de ventilator op medium

pt-BR

  • definir a velocidade do ventilador para baixa
  • põe a ventoinha no máximo

sv-SE

  • Ställ in fläkten på medel

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.