NervesHubLink.Client behaviour (nerves_hub_link v2.9.0)

View Source

The primary integration point for customizing your applications connection with NervesHub.

The following callbacks are supported:

A default Client is included (NervesHubLink.Client.Default) which :applys firmware updates, :ignores archives, logs firmware update messages, and logs a message when the identify/0 callback is used.

The recommended way to implement your own Client is to create your own module and add use NervesHubLink.Client, which will allow you to use the same defaults included in NervesHubLink.Client.Default, while also being able to customize any of the current callback implementations.

Otherwise you can add @behaviour NervesHubLink.Client, but you will need to implement the following required functions:

Example

defmodule MyApp.NervesHubLinkClient do
  use NervesHubLink.Client

  # override only the functions you want to customize

  @impl NervesHubLink.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 NervesHubLink use your client, add the following to your config.exs:

config :nerves_hub_link, client: MyApp.NervesHubLinkClient

Summary

Types

archive_data()

Archive that comes over a socket.

archive_response()

Supported responses from archive_available/1

fwup_message()

Firmware update progress, completion or error report

update_data()

Update that comes over a socket.

update_response()

Supported responses from update_available/1

Callbacks

archive_available(archive_data)

Called when an archive is available for download

archive_ready(archive_data, t)

Called when an archive has been downloaded and is available for the application to do something

connected()

Called when the connection to NervesHub has been established.

firmware_auto_revert_detected?()

Optional callback to check if an auto firmware revert just occurred.

firmware_validated?()

Optional callback to check if the current firmware has been validated.

handle_error(any)

Called when downloading a firmware update fails.

handle_fwup_message(fwup_message)

Called on firmware update reports.

identify()

Callback to identify the device from NervesHub.

reboot()

Optional callback to reboot the device when a firmware update completes

reconnect_backoff()

Optional callback when the socket disconnected, before starting to reconnect.

update_available(update_data)

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

Functions

archive_available(data)
archive_ready(data, file_path)
connected()
firmware_auto_revert_detected?()

The common logic to determine if an auto revert occurred is to check if the previous firmware is not validated. This is because, for example, if a device boots into firmware slot A and isn't able to validate the slot within the initialization callback time, the device will reboot into the previous firmware slot, B, and now firmware slot A will be shown as not validated.

firmware_validated?()

A wrapper function which calls firmware_validated?/0 on the configured NervesHubLink.Client.

handle_error(data)

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

handle_fwup_message(data)

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

identify()

This function is called internally by NervesHubLink to identify a device.

initiate_reboot()

This function is called internally by NervesHubLink to initiate a reboot.

reconnect_backoff()

This function is called internally by NervesHubLink to notify clients of disconnects.

update_available(data)

This function is called internally by NervesHubLink to notify clients.

Types

archive_data()

@type archive_data() :: NervesHubLink.Message.ArchiveInfo.t()

Archive that comes over a socket.

archive_response()

@type archive_response() :: :download | :ignore | {:reschedule, pos_integer()}

Supported responses from archive_available/1

fwup_message()

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

update_data()

@type update_data() :: NervesHubLink.Message.UpdateInfo.t()

Update that comes over a socket.

update_response()

@type update_response() ::
  :apply
  | :ignore
  | {:ignore, String.t()}
  | {:reschedule, pos_integer()}
  | {:reschedule, pos_integer(), String.t()}

Supported responses from update_available/1

Callbacks

archive_available(archive_data)

@callback archive_available(archive_data()) :: archive_response()

Called when an archive is available for download

May return one of:

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

archive_ready(archive_data, t)

@callback archive_ready(archive_data(), Path.t()) :: :ok

Called when an archive has been downloaded and is available for the application to do something

connected()

(optional) 
@callback connected() :: any()

Called when the connection to NervesHub has been established.

The return value of this function is not checked.

firmware_auto_revert_detected?()

(optional) 
@callback firmware_auto_revert_detected?() :: boolean()

Optional callback to check if an auto firmware revert just occurred.

The default behavior is to check if the previous firmware slots:

  • nerves_fw_validated value is 0
  • and nerves_fw_platform is not empty
  • and nerves_fw_architecture is not empty

If there is custom logic built into fwup-ops.conf around prevent-revert, this should be reflected here.

firmware_validated?()

(optional) 
@callback firmware_validated?() :: boolean()

Optional callback to check if the current firmware has been validated.

The default behavior is to delegate to Nerves.Runtime.firmware_valid?/0.

If there is custom logic built into your fwup.conf and fwup-ops.conf files, you should implement this callback in your NervesHubLink.Client.

handle_error(any)

@callback handle_error(any()) :: :ok

Called when downloading a firmware update fails.

The return value of this function is not checked.

handle_fwup_message(fwup_message)

@callback handle_fwup_message(fwup_message()) :: :ok

Called on firmware update reports.

The return value of this function is not checked.

identify()

@callback identify() :: :ok

Callback to identify the device from NervesHub.

reboot()

(optional) 
@callback reboot() :: no_return()

Optional callback to reboot the device when a firmware update completes

The default behavior is to call Nerves.Runtime.reboot/0 after a successful update. This is useful for testing and for doing additional work like notifying users in a UI that a reboot will happen soon. It is critical that a reboot does happen.

reconnect_backoff()

(optional) 
@callback reconnect_backoff() :: [integer()] | nil

Optional callback when the socket disconnected, before starting to reconnect.

The return value is used to reset the next socket's retry timeout. nil asks NervesHubLink to calculate a set of random backoffs to use.

You may wish to use this to dynamically change the reconnect backoffs. For instance, during a NervesHub deploy you may wish to change the reconnect based on your own logic to not create a thundering herd of reconnections. If you have a particularly flaky connection you can increase how fast the reconnect happens to avoid overloading your server.

update_available(update_data)

@callback 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.

Functions

archive_available(data)

@spec archive_available(archive_data()) :: archive_response()

archive_ready(data, file_path)

@spec archive_ready(archive_data(), Path.t()) :: :ok

connected()

@spec connected() :: any()

firmware_auto_revert_detected?()

@spec firmware_auto_revert_detected?() :: boolean()

The common logic to determine if an auto revert occurred is to check if the previous firmware is not validated. This is because, for example, if a device boots into firmware slot A and isn't able to validate the slot within the initialization callback time, the device will reboot into the previous firmware slot, B, and now firmware slot A will be shown as not validated.

We also need to account for the logic used by prevent-revert in fwup-ops.conf, which can be different/custom per Nerves system. The common pattern is to unset nerves_fw_platform and nerves_fw_architecture.

The default implementation checks if the previous firmware slot is not validated, and that nerves_fw_platform and nerves_fw_architecture are not empty.

Clears platform and architecture uboot env vars

Clears platform, architecture, and validated uboot env vars

firmware_validated?()

@spec firmware_validated?() :: boolean()

A wrapper function which calls firmware_validated?/0 on the configured NervesHubLink.Client.

If the function isn't implemented, the default logic of delegating to Nerves.Runtime.firmware_valid?/0 is used.

handle_error(data)

@spec handle_error(any()) :: :ok

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

handle_fwup_message(data)

@spec handle_fwup_message(fwup_message()) :: :ok

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

identify()

@spec identify() :: :ok

This function is called internally by NervesHubLink to identify a device.

initiate_reboot()

@spec initiate_reboot() :: :ok

This function is called internally by NervesHubLink to initiate a reboot.

After a successful firmware update, NervesHubLink calls this to start the reboot process. It calls reboot/0 if supplied or Nerves.Runtime.reboot/0.

reconnect_backoff()

@spec reconnect_backoff() :: [integer()]

This function is called internally by NervesHubLink to notify clients of disconnects.

update_available(data)

@spec update_available(update_data()) :: update_response()

This function is called internally by NervesHubLink to notify clients.