# Smart Home LightEffects Trait Schema

`action.devices.traits.LightEffects` - This trait belongs to devices that can support complex lighting commands to change state, such as looping through various colors.

## 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 |
|---|---|---|
| `defaultColorLoopDuration` | *Integer* | (Default: `1800`) The default duration, in seconds, for the effect triggered by the `action.devices.commands.ColorLoop` command. Value must be between `300` and `3600`. |
| `defaultSleepDuration` | *Integer* | (Default: `1800`) The default duration, in seconds, for the effect triggered by the `action.devices.commands.Sleep` command. Value must be between `300` and `3600`. |
| `defaultWakeDuration` | *Integer* | (Default: `1800`) The default duration, in seconds, for the effect triggered by the `action.devices.commands.Wake` command. Value must be between `300` and `3600`. |
| `supportedEffects` | *Array* | **Required.** List of the effects that the device supports. |
| `[*item, ...*]` | *String* | Supported effect. Supported values: `colorLoop` :   Loops through various colors randomly. `sleep` :   Gradually lowers brightness and, optionally, adjusts the color temperature over a period of time. `wake` :   Gradually increases brightness and, optionally, adjusts the color temperature over a period of time. |

#### Examples

*Device supporting color loop effect.*

```
{
  "supportedEffects": [
    "colorLoop"
  ]
}
```

*Device supporting sleep/wake effects.*

```
{
  "defaultSleepDuration": 300,
  "defaultWakeDuration": 600,
  "supportedEffects": [
    "sleep",
    "wake"
  ]
}
```

## 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 |
|---|---|---|
| `activeLightEffect` | *String* | Currently active light effect if any. One of `supportedEffects`. Supported values: `colorLoop` `sleep` `wake` |
| `lightEffectEndUnixTimestampSec` | *Integer* | Unix timestamp when the effect is expected to end, if the effect ends on its own. |

#### Examples

*What is the current effect on my device?*

```
{
  "activeLightEffect": "colorLoop"
}
```

*What is the current effect on my device?*

```
{
  "activeLightEffect": "sleep",
  "lightEffectEndUnixTimestampSec": 1595286869
}
```

*No light effect currently active.*

```
{}
```

## 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.ColorLoop`

Request the device to cycle through a set of colors.
This command requires the following attributes:

```
{
  "supportedEffects": [
    "colorLoop"
  ]
}
```

#### Parameters

| Parameters | Type | Description |
|---|---|---|
| `duration` | *Integer* | Duration for the color loop command, in seconds. Value must be between `300` and `3600`. |

#### Examples

*Colorloop my lights for 60 minutes.*

```
{
  "command": "action.devices.commands.ColorLoop",
  "params": {
    "duration": 3600
  }
}
```

### `action.devices.commands.Sleep`

Gradually lower the device's brightness and, optionally, adjusts the color temperature over a duration of time.
This command requires the following attributes:

```
{
  "supportedEffects": [
    "sleep"
  ]
}
```

#### Parameters

| Parameters | Type | Description |
|---|---|---|
| `duration` | *Integer* | Duration for the sleep command, in seconds, in the range of 300 to 3600. Value must be between `300` and `3600`. |

#### Examples

*Make my lights sleep for 60 minutes.*

```
{
  "command": "action.devices.commands.Sleep",
  "params": {
    "duration": 3600
  }
}
```

### `action.devices.commands.StopEffect`

Stop the current light effect.

#### Parameters

| Parameters | Type | Description |
|---|---|---|
| No properties |||

#### Examples

*Stop the effect on my light.*

```
{
  "command": "action.devices.commands.StopEffect",
  "params": {}
}
```

### `action.devices.commands.Wake`

Gradually increase the device's brightness and, optionally, adjusts the color temperature over a duration of time.
This command requires the following attributes:

```
{
  "supportedEffects": [
    "wake"
  ]
}
```

#### Parameters

| Parameters | Type | Description |
|---|---|---|
| `duration` | *Integer* | Duration for the wake command, in seconds, in the range of 300 to 3600. Value must be between `300` and `3600`. |

#### Examples

*Make my lights wake for 60 minutes.*

```
{
  "command": "action.devices.commands.Wake",
  "params": {
    "duration": 3600
  }
}
```

### Light effects emulation

If your device implements the [`Brightness`](https://developers.home.google.com/cloud-to-cloud/traits/brightness) trait but not the
[`LightEffects`](https://developers.home.google.com/cloud-to-cloud/traits/lighteffects) trait, the
platform supports emulated "sleep" and "wake" effects, without the need for additional code.
The platform emulates the effects by sending a series of EXECUTE intents.

> [!NOTE]
> During the duration of the emulated effect, your integration can expect a higher frequency of EXECUTE and QUERY intents from the platform (up to 80 calls per instance of sleep or wake command).

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

- Den Aufwacheffekt *der Lampen* starten.
- Einschlafmodus *im Schlafzimmer* aktivieren.
- synchronisiere meine Geräte

### en-US

- Begin the sleep effect on *my lights* .
- I want you to start wake effect on *the lights*

### es-ES

- pon la luz de despertarse lentamente *durante 45 minutos*
- pon *las luces* de dormir

### fr-FR

- Allume doucement *les lumières* .
- Éteins progressivement *les lumières* .

### hi-IN

- *बेडरूम* में धीरे-धीरे रोशनी बढ़ाओ
- *लाइट* को स्लीप मोड में डाल दो

### it-IT

- Accendi *le luci* gradualmente
- Avvia *le luci* per dormire

### ja-JP

- *ライト* を徐々に明るくなる設定にして
- *照明* を少しずつ暗くして

### ko-KR

- *안방 전등* 기상 모드 시작해
- *조명* 에서 수면 모드 실행

### nl-NL

- Dim *de lichten* langzaam.
- Laat *mijn lamp* langzaam feller worden.

### pt-BR

- Acenda lentamente *as luzes do quarto* *por 1 hora* .
- Ativa *as luzes* de despertar no *quarto dos miudos* .
- Iniciar o modo dormir *por 1 hora* nas *luzes do quarto* .
- Liga a função adormecer das *luzes* .

### sv-SE

- Starta insomningsläge på *lamporna*
- Tänd *lamporna* långsamt

## Device ERRORS

See the full list of [errors and exceptions](https://developers.home.google.com/cloud-to-cloud/intents/errors-exceptions).