Grizzly.FirmwareUpdates.OTWUpdateRunner (grizzly v9.1.0)

State machine for managing an OTW update for a Z-Wave controller module.

Only 700-series and later modules are supported.

State Diagram

stateDiagram-v2
  [*] --> startup_delay
  startup_delay --> run_prechecks: delay complete
  run_prechecks --> [*]: no update needed
  run_prechecks --> init: update available
  state if_init <<choice>>
  init --> if_init
  if_init --> reboot_to_bootloader: prechecks ok
  if_init --> detect_bootloader_menu: prechecks failed
  reboot_to_bootloader --> detect_bootloader_menu: menu detected
  detect_bootloader_menu --> [*]: menu not detected
  detect_bootloader_menu --> uploading
  state uploading_if <<choice>>
  uploading --> uploading_if
  uploading_if --> upload_complete: success
  uploading_if --> run_prechecks: first timeout
  uploading_if --> [*]: second timeout
  upload_complete --> [*]

Summary

Types

start_opt()

Options for configuring the OTW update runner.

state()

update_status()

The various status of a firmware update of the Z-Wave module

Functions

busy?()

Returns true if an OTW update is in progress (the state is not :startup_delay or :done).

child_spec(opts)

Returns a specification to start this module under a supervisor.

get_state()

Gets the current state of the OTW update runner process. Returns nil if the process is not started.

start_link(opts \\ [])

Start the OTW update runner.

Types

start_opt()

@type start_opt() ::
  {:serial_port, binary()}
  | {:startup_delay, non_neg_integer()}
  | {:upload_timeout, timeout()}
  | {:update_specs, [struct()]}
  | {:module_reset_fun, {module(), atom(), [term()]} | (-> term())}

Options for configuring the OTW update runner.

Options

:serial_port (String.t/0) - Required. The path to serial port where the Z-Wave module is connected.
:startup_delay (non_neg_integer/0) - Time to wait after starting the runner before beginning the update process. The default value is 60000.
:upload_timeout (timeout/0) - Timeout for the GBL upload. The default value is 90000.
:update_specs (list of struct of type Grizzly.FirmwareUpdates.OTW.UpdateSpec) - A list of Grizzly.FirmwareUpdates.OTW.UpdateSpec structs that define the available firmware updates. The default value is [].
:module_reset_fun - A function that performs a hard reset of the Z-Wave module, typically via GPIO or power cycle. If not provided, recovering from a failed upload may not work as expected.

state()

@type state() ::
  :startup_delay
  | :run_prechecks
  | :init
  | :reboot_to_bootloader
  | :detect_bootloader_menu
  | :uploading
  | :upload_complete
  | :done

update_status()

@type update_status() :: :started | {:done, :success | :skipped} | {:error, atom()}

The various status of a firmware update of the Z-Wave module

:started - the firmware update has been initiated and all validation of the firmware update is complete.
{:done, :success} - the firmware update of the Z-Wave module is successful.
{:done, :skipped} - no firmware update was applied.
{:error, reason} - A firmware update of the Z-Wave module was attempted but failed for some reason.

Functions

busy?()

@spec busy?() :: boolean()

Returns true if an OTW update is in progress (the state is not :startup_delay or :done).

child_spec(opts)

@spec child_spec(args :: keyword()) :: Supervisor.child_spec()

Returns a specification to start this module under a supervisor.

See Supervisor.

get_state()

@spec get_state() :: state() | nil

Gets the current state of the OTW update runner process. Returns nil if the process is not started.

start_link(opts \\ [])

@spec start_link([start_opt()]) :: GenServer.on_start()

Start the OTW update runner.

See start_opt/0 for available options.