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 operation. To learn more about handling QUERY intents, see Intent fulfillment.

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.

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.

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 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"
  }
}

Device ERRORS

See the full list of errors and exceptions.