nerves_hub v0.7.2 NervesHub.Client behaviour

A behaviour module for customizing if and when firmware updates get applied.

By default NervesHub applies updates as soon as it knows about them from the NervesHub server and doesn't give warning before rebooting. This let's devices hook into the decision making process and monitor the update's progress.

Example

defmodule MyApp.NervesHubClient do
  @behaviour NervesHub.Client

  # May return:
  #  * `:apply` - apply the action immediately
  #  * `:ignore` - don't apply the action, don't ask again.
  #  * `{:reschedule, timeout_in_milliseconds}` - call this function again later.

  @impl NervesHub.Client
  def update_available(data) do
    if SomeInternalAPI.is_now_a_good_time_to_update?(data) do
      :apply
    else
      {:reschedule, 60_000}
    end
  end
end

To have NervesHub invoke it, add the following to your config.exs:

config :nerves_hub, client: MyApp.NervesHubClient

Link to this section Summary

Types

Firmware update progress, completion or error report

Update that comes over a socket.

Supported responses from update_available/1

Functions

This function is called internally by NervesHub to notify clients of fwup errors.

This function is called internally by NervesHub to notify clients of fwup progress.

This function is called internally by NervesHub to notify clients.

Callbacks

Called when downloading a firmware update fails.

Called on firmware update reports.

Called to find out what to do when a firmware update is available.

Link to this section Types

Link to this type

fwup_message()
fwup_message() ::
  {:ok, non_neg_integer(), String.t()}
  | {:warning, non_neg_integer(), String.t()}
  | {:error, non_neg_integer(), String.t()}
  | {:progress, 0..100}

Firmware update progress, completion or error report

Link to this type

update_data()
update_data() :: map()

Update that comes over a socket.

Link to this type

update_response()
update_response() :: :apply | :ignore | {:reschedule, pos_integer()}

Supported responses from update_available/1

Link to this section Functions

Link to this function

handle_error(client, data)
handle_error(module(), any()) :: :ok

This function is called internally by NervesHub to notify clients of fwup errors.

Link to this function

handle_fwup_message(client, data)
handle_fwup_message(module(), fwup_message()) :: :ok

This function is called internally by NervesHub to notify clients of fwup progress.

Link to this function

update_available(client, data)
update_available(module(), update_data()) :: update_response()

This function is called internally by NervesHub to notify clients.

Link to this section Callbacks

Link to this callback

handle_error(any)
handle_error(any()) :: :ok

Called when downloading a firmware update fails.

The return value of this function is not checked.

Link to this callback

handle_fwup_message(fwup_message)
handle_fwup_message(fwup_message()) :: :ok

Called on firmware update reports.

The return value of this function is not checked.

Link to this callback

update_available(update_data)
update_available(update_data()) :: update_response()

Called to find out what to do when a firmware update is available.

May return one of:

  • apply - Download and apply the update right now.
  • ignore - Don't download and apply this update.
  • {:reschedule, timeout} - Defer making a decision. Call this function again in timeout milliseconds.