# 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`](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 |
|---|---|---|
| `maxTimerLimitSec` | *Integer* | **Required.** Indicates the longest timer setting available on the device, measured in seconds. Minimum value: `1`. |
| `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`](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 |
|---|---|---|
| `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`](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.TimerStart`

Start a new timer.

#### Parameters

| Parameters | Type | Description |
|---|---|---|
| `timerTimeSec` | *Integer* | **Required.** Duration of the timer in seconds; must be within \[1, `maxTimerLimitSec`\]. Minimum value: `1`. |

#### Examples

*Run device timer for five minutes.*

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

#### Related errors

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

#### Related errors

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": {}
}
```

#### Related errors

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": {}
}
```

#### Related errors

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": {}
}
```

#### Related errors

An error occurred when stopping the timer.

Supported values:

`noTimerExists`

## Device ERRORS

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