The first step is to add nerves_hub_link to your target dependencies in your project's mix.exs. Since NervesHub uses SSL certificates, the time must be set on the device or certificate validity checks will fail. If you're not already setting the time, add nerves_time to your dependencies. For example:

​

  defp deps(target) do
    [
      {:nerves_runtime, "~> 0.9"},
      {:nerves_hub_link, "~> 0.1"},
      {:nerves_time, "~> 0.2"},
      ...
    ] ++ system(target)
  end

Next, update your config.exs so that the nerves_hub_link library can help provision devices. Do this by adding provisioning: :nerves_hub_link to the :nerves, :firmware option like this:

config :nerves, :firmware,
  provisioning: :nerves_hub_link

Adding this library will start a long-lived websocket connection with NervesHub for communicating device updates. If you'd rather use HTTP polling, use nerves_hub_link_http instead.

Connection Setup

See the NervesKey: NervesHubLink Integration section for connection setup if you are using NervesKey

If you aren't using NervesKey, you can also provide your own options to use for the NervesHub socket connection via the :socketand :ssl keys, which are forwarded on to phoenix_client when creating the socket connection (see PhoenixClient.Socketmodule for supported options.)

Any valid Erlang ssl socket option can go in the :ssl key.

config :nerves_hub_link,
  socket: [
    json_library: Jason,
    heartbeat_interval: 45_000
  ],
  ssl: [
    cert: "some_cert_der",
    keyfile: "path/to/keyfile"
  ]

Runtime Configuration

Some cases require that connection configuration happens at runtime like selectively choosing which cert/key to use based on device, or reading a file stored on device which isn't available during compilation.

Whatever the reason, NervesHubLink also supports runtime configuration via the NervesHubLink.Configurator behavior. This is called during application startup to build the configuration that is to be used for the connection. When implementing the behavior, you'll receive the initial default config read in from the application environment and you can modify it however you need.

For example:

defmodule MyApp.Configurator do
  @behaviour NervesHubLink.Configurator
​
  @impl true
  def build(config) do
    ssl = [certfile: "/root/ssl/cert.pem", keyfile: "/root/ssl/key.pem"]
    %{config | ssl: ssl}
  end
end

Then you specify which configurator NervesHubLink should use in config.exs:

config :nerves_hub_link, configurator: MyApp.Configurator

Client Setup

By default NervesHubLink applies updates as soon as it knows about them from the NervesHubLink server and doesn't give warning before rebooting. Optionally, you can override this behavior if desired by implementing the NervesHubLink.Client behaviour.

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