Device socket & channel API

The websocket protocol devices use to talk to NervesHub: connection, authentication, channels, messages, and API versions.

Written By Josh Kalderimis

Last updated About 2 months ago

Devices talk to NervesHub over a long-lived websocket. This is the protocol the NervesHubLink client implements. You rarely need these details unless you're building your own client or debugging the connection.

Connecting and authenticating

A device connects to the device endpoint websocket and authenticates one of two ways:

Certificate (mTLS): the TLS client certificate presented during the handshake.
Shared secret: an HMAC token passed in connection headers.

See Device authentication & mTLS for how each is verified.

Channels

Once connected, the device joins channels:

Channel	Topic	Purpose
Device	`device:<id>`	Firmware updates, status, archives, scripts.
Console	console topic	Remote IEx and file transfer.
Extensions	extensions topic	Health and Geo reporting.

Device channel messages

Device → server

Event	Meaning
`fwup_progress`	Firmware update progress (percentage and stage).
`firmware_validated`	The applied firmware was validated.
`status_update`	General status report.
`connection_types`	Active network interface types.
`rebooting`	The device is rebooting.

Server → device

Event	Meaning
`updated` / `deployment_updated`	A new firmware update is available.
`archives/updated`	A new archive is available.
`scripts/run`	Run a support script and return output.

API versions

The client reports two internal version numbers so the server knows what it supports.

`device_api_version`

Version	Adds
`2.2.0`	Report which extensions are enabled and their versions.
`2.1.0`	Run scripts separate from the console; sync firmware and archive keys.
`2.0.0`	Device identify; archives.
`1.0.0`	Firmware updates, status updates, reboot.

`console_version`

Version	Adds
`2.0.0`	Send and receive files.
`1.0.0`	Remote IEx console.

NervesCloud