# 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`](https://developers.home.google.com/cloud-to-cloud/intents/sync) operation. To learn
more about handling `SYNC` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/sync).

| 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. At least one item with a `lang` value of `en` is required in order to provide language fallback. |
| `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. At least one item with a `lang` value of `en` is required in order to provide language fallback. |
| `lang` | *String* | **Required.** Language code (ISO 639-1). See [supported languages](https://developers.home.google.com/cloud-to-cloud/traits#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`](https://developers.home.google.com/cloud-to-cloud/intents/query) operation. To learn
more about handling `QUERY` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute).

| 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` Value must be between `0` and `100`. |

#### Examples

*What speed are the fans in the living room?*

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

> [!NOTE]
> **Note:** If a device also reports the `isRunning` state through the [StartStop](https://developers.home.google.com/cloud-to-cloud/traits/startstop) trait, Google uses this state to determine if a device is not running when responding to `FanSpeed` queries.

## Device COMMANDS

Devices with this trait may respond to the following
commands as part of the [`EXECUTE`](https://developers.home.google.com/cloud-to-cloud/intents/execute) operation. To learn
more about handling `EXECUTE` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute#handle_execute_intents).

### `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. Value must be between `0` and `100`. |

#### 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. Value must be between `-5` and `5`. |

#### Set relative speed by percentage.

| Parameters | Type | Description |
|---|---|---|
| `fanSpeedRelativePercent` | *Number* | **Required.** This value represents the percentage of speed to change. Value must be between `-100` and `100`. |

#### 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

> [!NOTE]
> This is a sample of the utterances supported by this device trait, make sure to also review other [supported languages](https://developers.home.google.com/cloud-to-cloud/traits#supported-languages).

### 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](https://developers.home.google.com/cloud-to-cloud/intents/errors-exceptions).

- `maxSpeedReached`: The device is already set to the maximum speed.
- `minSpeedReached`: The device is already set to the minimum speed.