View Source Nerves.Runtime (nerves_runtime v0.13.7)

Nerves.Runtime contains functions useful for almost all Nerves-based devices.

Summary

Functions

Run system command and log output into logger.

Return whether the firmware has been marked as valid

Halt the device (meaning hang, not power off, nor reboot).

Return the mix target that was used to build this firmware

Power off the device.

Reboot the device and gracefully shutdown the Erlang VM.

Revert the device to running the previous firmware

Return the device's serial number

Mark the running firmware as valid

Functions

Link to this function

cmd(cmd, params, log_level_or_return)

View Source
@spec cmd(binary(), [binary()], :debug | :info | :warn | :error | :return) ::
  {Collectable.t(), exit_status :: non_neg_integer()}

Run system command and log output into logger.

NOTE: Unlike System.cmd/3, this does not raise if the executable isn't found

@spec firmware_valid?() :: boolean()

Return whether the firmware has been marked as valid

Since "valid" means that the next boot will run the same firmware, this also returns true if firmware validation isn't in use.

See validate_firmware/0 for more information.

@spec halt() :: no_return()

Halt the device (meaning hang, not power off, nor reboot).

Note: this is different than :erlang.halt(), which exits BEAM, and may end up rebooting the device if erlinit.config settings allow reboot on exit.

@spec mix_target() :: atom()

Return the mix target that was used to build this firmware

If you're running on the development machine, this will return :host. If not, it will return whatever the user specified with the MIX_TARGET environment variable when building this firmware.

@spec poweroff() :: no_return()

Power off the device.

This calls :init.stop/0 internally. If :init.stop/0 takes longer than the erlinit.config's --graceful-powerdown setting (likely 10 seconds) then the system will be hard rebooted.

@spec reboot() :: no_return()

Reboot the device and gracefully shutdown the Erlang VM.

This calls :init.stop/0 internally. If :init.stop/0 takes longer than the erlinit.config's --graceful-powerdown setting (likely 10 seconds) then the system will be hard rebooted.

@spec revert(Nerves.Runtime.FwupOps.options()) ::
  :ok | {:error, reason :: any()} | no_return()

Revert the device to running the previous firmware

This switches the active firmware slot back to the previous one and then reboots. This fails if the slot is empty or partially overwritten to prevent accidents. It also requires the revert feature to be implemented in the Nerves system that's in use. See Nerves.Runtime.FwupOps for how this works.

Specifying reboot: false is allowed, but be sure to reboot. It's easy to get confused if you don't reboot afterwards and do a double revert or something else silly.

@spec serial_number() :: String.t()

Return the device's serial number

Serial number storage is device-specific and configurable. Serial numbers can be programmed in one-time programmable locations like in CPU ROM or cryptographic elements. They can also be in rewritable locations like a U-Boot environment block.

Nerves uses the boardid by default (set :boardid_path key in the application environment to another program to override). Boardid uses the /etc/boardid.config file to determine how to read the serial number. Official Nerves systems provide reasonable default mechanisms for getting started. Override this file in your application's rootfs_overlay to customize it.

This function never raises. If a serial number isn't available for any reason, it will return a serial number of "unconfigured".

@spec validate_firmware() :: :ok

Mark the running firmware as valid

A device cannot receive a new firmware if the current one has not been validated. In the official Nerves systems, this typically happens automatically. If you are handling the firmware validation in your app, then this function can be used as a helper to mark firmware as valid.

For systems that support automatic reverting, if the firmware is not marked as valid, then the next reboot will cause a revert to the old firmware