View Source Nerves.Runtime.Heart (nerves_runtime v0.13.7)

Functions for querying Nerves Heart and the device's watchdog

Nerves Heart integrates Erlang's heart 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 for more information.

Summary

Types

info()

Nerves Heart's current status

info_v1()

Nerves Heart v1.x information

info_v2()

Nerves Heart v2.x information

Functions

guarded_immediate_poweroff()

Immediately poweroff without any cleanup

guarded_immediate_reboot()

Immediately reboot without any cleanup

guarded_poweroff()

Initiate a poweroff that's guarded by the hardware watchdog

guarded_reboot()

Initiate a reboot that's guarded by the hardware watchdog

init_complete()

Notify Nerves heart that initialization is complete

running?()

Return whether Nerves heart is running

snooze()

Snooze heart related reboots for the next 15 minutes

status()

Return the current Nerves Heart status

status!()

Raising version of status/0

Types

info()

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

Nerves Heart's current status

See nerves_heart for more information.

info_v1()

@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()

@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

Functions

guarded_immediate_poweroff()

@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()

@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()

@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()

@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()

@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:

## 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?()

@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()

@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()

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

Return the current Nerves Heart status

Errors are returned when not running Nerves Heart

status!()

@spec status!() :: info()

Raising version of status/0