# Smart Home RunCycle Trait Schema

`action.devices.traits.RunCycle` - This trait represents any device that has an ongoing duration for its operation which can be queried.

Devices like these will report their total number of cycles at the start of operation,
and each cycle the device is currently in while running. This allows the user to make queries, such as the following:

- *What cycle is my dryer on?*
- *How many cycles does the dishwasher have left?*
- *What is the dryer doing?*
- *When will the wash be done?*

Certain devices include a duration in a non-cyclical format. Any device
that runs for a specific amount of time can report its time remaining, without
cycles. This also handles cases where cycles may not be consistent (for example,
dishwashers may not always use all cycles). For instance a user could ask, *How much longer will my vacuum run?* which will return the amount of time in units
proportional to the time remaining. This also applies to the devices listed
above; *How much longer will my clothes be drying?* will return a duration in minutes.

Devices can return what they know, and the Assistant TTS response will form the
best answer with the data available (for example, *The dishwasher is running and will complete in about 20 minutes.*)

RunCycle is currently a read-only trait - it has no commands, only states to
query. In the future, there may be mechanisms for rerunning cycles or skipping
cycles (good for sprinklers, bad for washing machines).

## Device ATTRIBUTES

None.

## 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 |
|---|---|---|
| `currentRunCycle` | *Array* | **Required.** Contains the synonyms for the current cycle in each supported language. |
| `[*item, ...*]` | *Object* | Cycle synonym names. |
| `currentCycle` | *String* | **Required.** Current cycle being performed. |
| `nextCycle` | *String* | Optional. Next cycle to perform. |
| `lang` | *String* | **Required.** Language code for the given cycle names. See [Supported languages](https://developers.home.google.com/cloud-to-cloud/traits#supported-languages). |
| `currentTotalRemainingTime` | *Integer* | **Required.** Time remaining on operation, in seconds. |
| `currentCycleRemainingTime` | *Integer* | **Required.** Time remaining on current cycle, in seconds. |

#### Examples

*The device is in rinse for another 5 minutes, and will be done in 20 minutes.*

```
{
  "currentRunCycle": [
    {
      "currentCycle": "rinse",
      "lang": "en"
    }
  ],
  "currentTotalRemainingTime": 1200,
  "currentCycleRemainingTime": 300
}
```

*The device is in rinse for another 5 minutes, before moving to spin.*

```
{
  "currentRunCycle": [
    {
      "currentCycle": "rinse",
      "nextCycle": "spin",
      "lang": "en"
    }
  ],
  "currentTotalRemainingTime": 600,
  "currentCycleRemainingTime": 300
}
```

## Device COMMANDS

None.

## Device NOTIFICATIONS

Devices with this trait may return the following
notification payload as part of a device state change. To learn
more about implementing notifications, see
[Notifications for smart home Actions](https://developers.home.google.com/cloud-to-cloud/integration/notifications).

| Fields | Type | Description |
|---|---|---|
| `RunCycle` |   | **Required.** Notification payload. |
| *Supports one of the following:* |||
| `*0*` | *Object* | Success |
| `priority` | *Integer* | **Required.** Represents the notification level. The currently supported value is 0, which indicates that the notification should be spoken aloud. |
| `status` | *String* | **Required.** Result of the operation. Supported values: `SUCCESS` |
| `currentCycleRemainingTime` | *Integer* | **Required.** Time remaining on current cycle, in seconds. |
| `*1*` | *Object* | Failure |
| `priority` | *Integer* | **Required.** Represents the notification level. The currently supported value is 0, which indicates that the notification should be spoken aloud. |
| `status` | *String* | **Required.** Result of the operation. Supported values: `FAILURE` |
| `errorCode` | *String* | **Required.** The value can be any [error code](https://developers.home.google.com/cloud-to-cloud/intents/errors-exceptions#error_list) for this trait, for example, `deviceStuck`. |

#### Examples

*The device has finished running.*

```
{
  "RunCycle": {
    "priority": 0,
    "status": "SUCCESS",
    "currentCycleRemainingTime": 0
  }
}
```

*An error occurred completing the current cycle.*

```
{
  "RunCycle": {
    "priority": 0,
    "status": "FAILURE",
    "errorCode": "deviceStuck"
  }
}
```

> [!NOTE]
> **Note:** Notifications with `status`: `SUCCESS` are only spoken aloud if `currentCycleRemainingTime` is set to `0`.

## Device ERRORS

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