Device WebSocket
Last updated
Was this helpful?
Last updated
Was this helpful?
NervesHub exposes a WebSocket interface which utilizes 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://{host}/socket/websocket
. Once connected, you can then join any of the supported channel topics to start sending and receiving messages with NervesHub.
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 for more info on what each part of the message means)
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:
NervesHub currently supports the following channel topics:
device
- The main topic a device should join for receiving updates and other device specific events. There is a required payload of the device_api_version
when connecting, e.g. {'device_api_version': '2.0.0'}
. This is used to instruct NervesHub what messages it can send to the device.
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.
The supported events in messages coming from the server (NervesHub) to the client:
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
reboot
Request that device reboot. Typlically used for troubleshooting purposes
Payload is not used and can be ignored
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
phx_close
Channel was gracefully closed
Payload fields:
tbd
The supported event messages coming from the client to server (NervesHub)
rebooting
Tells the server that the device is rebooting
Payload is ignored server-side
fwup_progress
Progress update during a firmware update
Payload fields:
value
- percentage of update progress
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