nerves-hub
Search…
Phoenix Channel
NervesHub exposes a WebSocket interface which utilizes Phoenix channels for long lived connections. NervesHub uses SSL peer verification so the device's certificate and applicable CA certificates must be included in the connection request. The device's SSL certificate is also used to determine organization and serial number.
The connection URI is wss://device.nerves-hub.org/socket/websocket. Once connected, you can then join any of the supported channel topics to start sending and receiving messages with NervesHub.

Message Structure

NervesHub utilizes the Phoenix message structure for all WebSocket communications. In its raw form, the message is a simple list expected to be structured as [join_ref, ref, topic, event, payload] . (See the Phoenix.Socket.Message documetation for more info on what each part of the message means)
1
# Example messages
2
["join_123", "ref-453", "some_topic", "update", "some_payload"]
3
[null, "another-ref", "diff_topic", "response", {"key": "val"}]
4
[null, null, "topic3", "wat", [1, 2, 3, 4]]
Copied!

Joining a Channel

To communicate with NervesHub, you must join a channel on a supported topic once the websocket has been connected. This requires sending a message with the phx_join event to the desired topic:
1
['arbitrary_join_ref', 'ref1', 'devices', 'phx_join', {}]
Copied!

Supported Topics

NervesHub currently supports the following channel topics:
    device - The main topic a device should join for receiving updates and other device specific events.
    console - topic for the device to send IO requests to and from NervesHub for supporting remote console interaction. For Nerves, this is the topic used from remote IEx sessions.

Server Events

The supported events in messages coming from the server (NervesHub) to the client:

device

    update
      Specifies that an update is available for the device
      Payload fields:
        update_available - Boolean stating update availability
        deployment_id - ID of the deployment triggering the update
        firmware_url - URL where the firmware file can be downloaded. Note: this has a default TTL of 10 minutes. Using the URL after that time will fail and a new update request will need to be sent for a new URL
        firmware_meta - Contains a map of the various metadata elements for the firmware
          uuid
          architecture
          platform
          product
          version
          author
          description
          vcs_identifier
          misc
1
[
2
null,
3
"some-ref-1",
4
"devices",
5
"update",
6
{
7
"update_available": true,
8
"deployment_id": 12,
9
"firmware_url": "https://some-url.com",
10
"firmware_meta": {
11
"uuid": "12345-6789-0129435",
12
"architecture": "arm",
13
"platform": "rpi0",
14
"product": "MyProduct",
15
"version": "1.1.10",
16
"author": "Ron Swanson",
17
"description": "baconator 3000",
18
"vcs_identifier": "some_version_control_sha",
19
"misc": "random data"
20
}
21
}
22
]
Copied!
    reboot
      Request that device reboot. Typlically used for troubleshooting purposes
      Payload is not used and can be ignored
1
[null, "some-ref-1", "devices", "reboot", {}]
Copied!
    phx_err
      Error case, such as a channel process crashing, or when attempting to join an already joined channel
      Payload fields:
        reason - text of failure reason
1
[null, "some-ref-1", "devices", "phx_err", {"reason": "some reason"}]
Copied!
    phx_close
      Channel was gracefully closed
      Payload fields:
        tbd
1
[null, "some-ref-1", "devices", "phx_close", {}]
Copied!

Client Events

The supported event messages coming from the client to server (NervesHub)

device

    rebooting
      Tells the server that the device is rebooting
      Payload is ignored server-side
1
[null, "some-ref-1", "devices", "rebooting", {}]
Copied!
    fwup_progress
      Progress update during a firmware update
      Payload fields:
        value - percentage of update progress
1
[
2
null,
3
"some-ref-1",
4
"devices",
5
"fwup_progress",
6
{"value": 42}
7
]
Copied!
    status_update
      Current status of the device as it relates to a firmware update
      Payload fields:
        status - One of the supported statuses for a device
          idle - waiting for an update
          fwup_error - error occurred in the fwup process
          update_failed
          update_rescheduled
          unknown - generic status for unhandled states
1
[
2
null,
3
"some-ref-1",
4
"devices",
5
"status_update",
6
{"state": "update_rescheduled"}
7
]
Copied!
Last modified 1yr ago