Add NervesHub to your project

Search…
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:
1
  defp deps(target) do
2
    [
3
      {:nerves_runtime, "~> 0.9"},
4
      {:nerves_hub_link, "~> 0.1"},
5
      {:nerves_time, "~> 0.2"},
6
      ...
7
    ] ++ system(target)
8
  end
Copied!
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:
1
config :nerves, :firmware,
2
  provisioning: :nerves_hub_link
Copied!
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.
1
config :nerves_hub_link,
2
  socket: [
3
    json_library: Jason,
4
    heartbeat_interval: 45_000
5
  ],
6
  ssl: [
7
    cert: "some_cert_der",
8
    keyfile: "path/to/keyfile"
9
  ]
Copied!
Note: The Application config is evaluated at compile time. Extra caution is needed when using file paths in the config as they might be referencing host paths instead of device paths. Another option would be to configure at runtime (see Runtime Configuration)
Using your own Signer CA
In some cases you may opt to use your own device signer CA when creating device certificates. If you do, there a few things needed for a successful connection:
1.
Your signer CA must be uploaded to NervesHub. You can do this a couple ways
From the web UI at https://www.nerves-hub.org/settings/{YOUR_ORG}/certificates/new
Via CLI with mix nerves_hub.ca_certificate register /path/to/signer-ca.pem
2.
The signer CA must be included in the connection request alongside the NervesHub intermediate CAs. If you're using NervesKey, then this is typically handled for you. If managing certificates more manually, it is usually best to read at runtime and appened to the CA list. Here's a basically example of what that step might look like:
1
signer_cert =
2
  File.read!("/path/to/signer.pem")
3
  |> NervesHubLink.Certificate.pem_to_der()
4
​
5
cacerts = [signer_cert | NervesHubLink.Certificate.ca_certs()]
Copied!
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:
1
defmodule MyApp.Configurator do
2
  @behaviour NervesHubLink.Configurator
3
​
4
  @impl true
5
  def build(config) do
6
    ssl = [certfile: "/root/ssl/cert.pem", keyfile: "/root/ssl/key.pem"]
7
    %{config | ssl: ssl}
8
  end
9
end
Copied!
Then you specify which configurator NervesHubLink should use in config.exs:
1
config :nerves_hub_link, configurator: MyApp.Configurator
Copied!
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
1
defmodule MyApp.NervesHubLinkClient do
2
  @behaviour NervesHubLink.Client
3
  # May return:
4
  #  * `:apply` - apply the action immediately
5
  #  * `:ignore` - don't apply the action, don't ask again.
6
  #  * `{:reschedule, timeout_in_milliseconds}` - call this function again later.
7
  @impl NervesHubLink.Client
8
  def update_available(data) do
9
    if SomeInternalAPI.is_now_a_good_time_to_update?(data) do
10
      :apply
11
    else
12
      {:reschedule, 60_000}
13
    end
14
  end
15
end
Copied!
To have NervesHubLink invoke it, add the following to your config.exs:
1
config :nerves_hub_link, client: MyApp.NervesHubLinkClient
Copied!
Creating an account
Firmware signing keys
Last modified 9mo ago
Copy link
Contents
Connection Setup
Using your own Signer CA
Runtime Configuration
Client Setup
Example