Nerves.Runtime.FwupOps (nerves_runtime v0.13.9)

Functions for managing firmware slots via an ops.fw file

The /usr/share/fwup/ops.fw is provided by the Nerves system for handling some eMMC/MicroSD card operations. Look for fwup-ops.conf in the Nerves system source tree for more details. It used to be called revert.fw/fwup-revert.conf when it only handled reverting which firmware image was active.

This is a GenServer to maintain state and serialize firmware slot operations.

Summary

Types

options()

Options for calling fwup

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

factory_reset(opts \\ [])

Reset the application data partition to its original state

prevent_revert(opts \\ [])

Make it impossible to revert to the other partition

revert(opts \\ [])

Revert to the previous firmware

start_link(init_args)

Start the FwupOps GenServer

status(opts \\ [])

Return boot status

validate(opts \\ [])

Validate the active partition

Types

options()

@type options() :: [
  devpath: String.t(),
  fwup_env: %{required(String.t()) => String.t()},
  fwup_path: String.t(),
  ops_fw_path: String.t(),
  reboot: boolean()
]

Options for calling fwup

:devpath - The location of the storage device (defaults to "/dev/rootdisk0")
:fwup_env - Additional environment variables to pass to fwup
:fwup_path - The path to the fwup utility
:ops_fw_path - The path to the ops.fw file (defaults to "/usr/share/fwup/ops.fw")
:reboot - Call Nerves.Runtime.reboot/0 after running (defaults to true on destructive operations)

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

factory_reset(opts \\ [])

@spec factory_reset(options()) :: :ok | {:error, reason :: any()}

Reset the application data partition to its original state

This clears out the application data partition at a low level so that it will be reformatted on the next boot. If all application settings are stored on the partition, then this will be like a factory reset. Be aware that many settings are stored on the application data partition including network settings like WiFi SSIDs and passwords. Factory reset devices may not connect to the network afterwards.

prevent_revert(opts \\ [])

@spec prevent_revert(options()) :: :ok | {:error, reason :: any()}

Make it impossible to revert to the other partition

This wipes the opposite firmware partition and clears out metadata for it. Attempts to revert will fail. This is useful if loading a special firmware temporarily that shouldn't be used again even accidentally.

revert(opts \\ [])

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

Revert to the previous firmware

This invokes the "revert" task in the ops.fw and then reboots (unless told otherwise). The revert task switches the active firmware partition to the opposite one so that future reboots use the previous firmware.

start_link(init_args)

@spec start_link(options()) :: GenServer.on_start()

Start the FwupOps GenServer

Pass in the default options for running fwup. They can be overridden on a one-off basis by passing options to other functions.

status(opts \\ [])

@spec status(options()) ::
  {:ok, %{active: String.t(), next: String.t()}} | {:error, reason :: any()}

Return boot status

This invokes the "status" task in the ops.fw to report the active firmware slot and what slot will be tried on the next reboot. The ops.fw is expected to print the slot name or two slot names separated by "->".

validate(opts \\ [])

@spec validate(options()) :: :ok | {:error, reason :: any()}

Validate the active partition

For Nerves systems that support automatic rollback of firmware versions, this marks the partition as good so that it will continue to be used on future boots.

Call Nerves.Runtime.validate_firmware/0 instead.