# `NestGen2.Power`
[🔗](https://github.com/integration-technology/nest_gen2_sdk/blob/v0.6.6/lib/nest_gen2/power.ex#L1)

Screen wake and sleep.

The screen wakes on any configured source (dial, button, motion, light) and
sleeps after the idle timeout with no activity. Publishes `:power` events
(`:awake` / `:asleep`).

To keep the screen on (an alarm, a settings screen), take a hold:

    {:ok, hold} = NestGen2.Power.keep_awake(:alarm)
    # ... the screen is on and won't sleep from idleness ...
    :ok = NestGen2.Power.release(hold)

Holds stack: idle sleep resumes once every hold is released, starting a fresh
idle timeout then. A hold is released automatically if the process that took
it exits, so a crash can't leave the screen on for good. `sleep/0` still turns
the screen off when asked, holds or not.

## Deep sleep

With `deep_sleep` on (config, or `set_deep_sleep/1`), once the screen has been
asleep for `deep_sleep_after_ms` (10 s) with no holds, the whole system
suspends to RAM, as Nest's own software does: the processor, radios and every
process stop, and carry on exactly where they were when it wakes. That's what
lets the battery charge on the base, which supplies only about 120 mA; awake
all the time, the Nest drains its battery even on the base.

It wakes on the button, on the base (which wakes it for motion), or after
`deep_sleep_max_s` (270 s) to keep in touch with the base. A wake-up that
doesn't wake the screen goes back to sleep after `deep_sleep_awake_ms` (8 s).
While suspended nothing runs: timers pause (they count awake time only), Wi-Fi
drops and reconnects within a few seconds of waking. Apps that show changing
data should refresh it on `{:nest_gen2, :power, :awake}`.

# `awake?`

```elixir
@spec awake?() :: boolean()
```

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `holds`

```elixir
@spec holds() :: [%{ref: reference(), reason: term(), owner: pid()}]
```

Current holds, for debugging.

# `keep_awake`

```elixir
@spec keep_awake(term()) :: {:ok, reference()}
```

Wakes the screen and keeps it from sleeping when idle until `release/1`, or
until the calling process exits. `reason` is any term, shown by `holds/0`.

# `release`

```elixir
@spec release(reference()) :: :ok
```

Releases a hold from `keep_awake/1`. Releasing an unknown hold is a no-op.

# `set_deep_sleep`

```elixir
@spec set_deep_sleep(boolean()) :: :ok
```

Turns deep sleep (suspend to RAM while the screen is asleep) on or off.

# `set_idle_timeout`

```elixir
@spec set_idle_timeout(pos_integer() | :infinity) :: :ok
```

Milliseconds without activity before sleeping, or :infinity (default 30_000).

# `set_wake_sources`

```elixir
@spec set_wake_sources([:dial | :button | :motion | :light]) :: :ok
```

Which events wake the screen and count as activity.

# `sleep`

```elixir
@spec sleep() :: :ok
```

# `start_link`

# `wake`

```elixir
@spec wake() :: :ok
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*