Smart Home Timer Trait Schema

action.devices.traits.Timer - The Timer trait represents a timer on a device.

For instance, a smart sprinkler controller or smart light switch may have a built-in timer. This trait can be used to control a built-in timer on devices, such as starting a new timer as well as pausing and canceling a running timer, and asking how much time is remaining.

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
maxTimerLimitSec Integer

Required.

Indicates the longest timer setting available on the device, measured in seconds.
commandOnlyTimer 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.

Examples

Device with two hours timer limit.

{
  "maxTimerLimitSec": 7200
}

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
timerRemainingSec Integer

Required.

Current time remaining in seconds, -1, or [0, maxTimerLimitSec]. Set to -1 to indicate no timer is running.
timerPaused Boolean

True if a active timer exists but is currently paused.

Examples

How much time is left on device timer? (not running).

{
  "timerRemainingSec": -1
}

How much time is left on device timer? (running).

{
  "timerRemainingSec": 60
}

How much time is left on device timer? (paused).

{
  "timerRemainingSec": 30,
  "timerPaused": true
}

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.TimerStart

Start a new timer.

Parameters

Parameters Type Description
timerTimeSec Integer

Required.

Duration of the timer in seconds; must be within [1, maxTimerLimitSec].

Examples

Run device timer for five minutes.

{
  "command": "action.devices.commands.TimerStart",
  "params": {
    "timerTimeSec": 300
  }
}

An error occurred starting the timer.

Supported values:

noTimerExists
timerValueOutOfRange
aboveMaximumTimerDuration
belowMinimumTimerDuration

action.devices.commands.TimerAdjust

Adjust the timer duration.

Parameters

Parameters Type Description
timerTimeSec Integer

Required.

Positive or negative adjustment of the timer in seconds; must be within [-maxTimerLimitSec, maxTimerLimitSec].

Examples

Add one minute to device timer.

{
  "command": "action.devices.commands.TimerAdjust",
  "params": {
    "timerTimeSec": 60
  }
}

Subtracts 30 seconds from device timer.

{
  "command": "action.devices.commands.TimerAdjust",
  "params": {
    "timerTimeSec": -30
  }
}

An error occurred adjusting the timer.

Supported values:

noTimerExists
timerValueOutOfRange
aboveMaximumTimerDuration
belowMinimumTimerDuration

action.devices.commands.TimerPause

Pause timer.

Parameters

Parameters Type Description

No properties

Examples

Pause the device timer.

{
  "command": "action.devices.commands.TimerPause",
  "params": {}
}

An error occurred when pausing the timer.

Supported values:

noTimerExists

action.devices.commands.TimerResume

Resume timer.

Parameters

Parameters Type Description

No properties

Examples

Resume the device timer.

{
  "command": "action.devices.commands.TimerResume",
  "params": {}
}

An error occurred resuming the timer.

Supported values:

noTimerExists

action.devices.commands.TimerCancel

Cancel the timer.

Parameters

Parameters Type Description

No properties

Examples

Stop the device timer.

{
  "command": "action.devices.commands.TimerCancel",
  "params": {}
}

An error occurred when stopping the timer.

Supported values:

noTimerExists

Device ERRORS

See the full list of errors and exceptions.