# `Nerves.Runtime.Heart`
[🔗](https://github.com/nerves-project/nerves_runtime/blob/v0.13.12/lib/nerves_runtime/heart.ex#L5)

Functions for querying Nerves Heart and the device's watchdog

Nerves Heart integrates Erlang's
[heart](https://www.erlang.org/doc/man/heart.html) process with a hardware
watchdog.  This makes it possible for a device to recover from a hang. The
way it works is that the Erlang runtime regularly checks that it's ok. If so,
it sends a message to `heart`. Nerves heart then pets the hardware watchdog.
If messages ever stop being sent to `heart`, the hardware watchdog will trip
and reboot the device. You can add additional health checks for your
application by providing a callback to `:heart.set_callback/2`.

See [nerves_heart](https://github.com/nerves-project/nerves_heart) for more
information.

# `info`

```elixir
@type info() :: info_v2() | info_v1()
```

Nerves Heart's current status

See [nerves_heart](https://github.com/nerves-project/nerves_heart) for more
information.

# `info_v1`

```elixir
@type info_v1() :: %{
  program_name: String.t(),
  program_version: Version.t(),
  identity: String.t(),
  firmware_version: non_neg_integer(),
  options: non_neg_integer() | [atom()],
  time_left: non_neg_integer(),
  pre_timeout: non_neg_integer(),
  timeout: non_neg_integer(),
  last_boot: :power_on | :watchdog,
  heartbeat_timeout: non_neg_integer()
}
```

Nerves Heart v1.x information

# `info_v2`

```elixir
@type info_v2() :: %{
  program_name: String.t(),
  program_version: Version.t(),
  heartbeat_timeout: non_neg_integer(),
  heartbeat_time_left: non_neg_integer(),
  init_handshake_happened: boolean(),
  init_handshake_timeout: non_neg_integer(),
  init_handshake_time_left: non_neg_integer(),
  init_grace_time_left: non_neg_integer(),
  snooze_time_left: non_neg_integer(),
  wdt_identity: String.t(),
  wdt_firmware_version: non_neg_integer(),
  wdt_last_boot: :power_on | :watchdog,
  wdt_options: non_neg_integer() | [atom()],
  wdt_pet_time_left: non_neg_integer(),
  wdt_pre_timeout: non_neg_integer(),
  wdt_timeout_left: non_neg_integer(),
  wdt_timeout: non_neg_integer()
}
```

Nerves Heart v2.x information

# `guarded_immediate_poweroff`

```elixir
@spec guarded_immediate_poweroff() :: :ok | {:error, atom()}
```

Immediately poweroff without any cleanup

WARNING: This function should be used with care since it can lose data.

Support with Nerves Heart v2.3 and later.

# `guarded_immediate_reboot`

```elixir
@spec guarded_immediate_reboot() :: :ok | {:error, atom()}
```

Immediately reboot without any cleanup

WARNING: This function should be used with care since it can lose data.

Support with Nerves Heart v2.3 and later.

# `guarded_poweroff`

```elixir
@spec guarded_poweroff() :: :ok | {:error, atom()}
```

Initiate a poweroff that's guarded by the hardware watchdog

Most users should call `Nerves.Runtime.poweroff/0` instead which calls this
and shuts down the Erlang VM.

Support with Nerves Heart v2.0 and later.

# `guarded_reboot`

```elixir
@spec guarded_reboot() :: :ok | {:error, atom()}
```

Initiate a reboot that's guarded by the hardware watchdog

Most users should call `Nerves.Runtime.reboot/0` instead which calls this and
shuts down the Erlang VM.

Support with Nerves Heart v2.0 and later.

# `init_complete`

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

Notify Nerves heart that initialization is complete

This can be used to ensure that the code that calls `:heart.set_callback/2`
gets run. To use, add the following to your projects `rel/vm.args.eex`:

```text
## Require an initialization handshake within 15 minutes
-env HEART_INIT_TIMEOUT 900
```

Then call `Nerves.Runtime.Heart.init_complete/0` after
`:heart.set_callback/2` is called.

Supported by Nerves Heart v2.0 and later

# `running?`

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

Return whether Nerves heart is running

If you're using a Nerves device, this always returns `true` except possibly
when porting Nerves to new hardware. It is a quick sanity check.

# `snooze`

```elixir
@spec snooze() :: :ok | {:error, atom()}
```

Snooze heart related reboots for the next 15 minutes

Run this to buy some time if reboots from heart or hardware watchdog are
getting in the way.

Support with Nerves Heart v2.2 and later.

# `status`

```elixir
@spec status() :: {:ok, info()} | {:error, atom()}
```

Return the current Nerves Heart status

Errors are returned when not running Nerves Heart

# `status!`

```elixir
@spec status!() :: info()
```

Raising version of status/0

---

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