NervesHubLink.Client behaviour (nerves_hub_link v0.11.0) View Source
A behaviour module for customizing if and when firmware updates get applied.
By default NervesHubLink applies updates as soon as it knows about them from the NervesHubLink 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.NervesHubLinkClient do
@behaviour NervesHubLink.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 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 invoke it, add the following to your config.exs
:
config :nerves_hub, client: MyApp.NervesHubLinkClient
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 NervesHubLink to notify clients of fwup errors.
This function is called internally by NervesHubLink to notify clients of fwup progress.
This function is called internally by NervesHubLink to initiate a reboot.
This function is called internally by NervesHubLink to notify clients.
Callbacks
Called when downloading a firmware update fails.
Called on firmware update reports.
Optional callback to reboot the device when a firmware update completes
Called to find out what to do when a firmware update is available.
Link to this section Types
Specs
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
Specs
update_data() :: map()
Update that comes over a socket.
Specs
update_response() :: :apply | :ignore | {:reschedule, pos_integer()}
Supported responses from update_available/1
Link to this section Functions
Specs
handle_error(any()) :: :ok
This function is called internally by NervesHubLink to notify clients of fwup errors.
Specs
handle_fwup_message(fwup_message()) :: :ok
This function is called internally by NervesHubLink to notify clients of fwup progress.
Specs
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
.
Specs
update_available(update_data()) :: update_response()
This function is called internally by NervesHubLink to notify clients.
Link to this section Callbacks
Specs
handle_error(any()) :: :ok
Called when downloading a firmware update fails.
The return value of this function is not checked.
Specs
handle_fwup_message(fwup_message()) :: :ok
Called on firmware update reports.
The return value of this function is not checked.
Specs
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.
Specs
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 intimeout
milliseconds.