Nyx Stream

Nyx Stream

Nyx Stream is the Nyx server responsible for real-time data streaming used for live visualization in Nyx Lab (charts, waterfall, ...). It implements a Nyx-specific streaming specification. INDI focuses on device control and standard properties, while Nyx Stream provides a dedicated, high-throughput channel for continuous data streaming.

Specifications

Nyx Stream uses a binary framing format to transport stream messages.

Stream Frame Format

Total frame size:

\[ \mathrm{FRAME\_SIZE} = 12 + \mathrm{PAYLOAD\_SIZE}\]

All integer fields are encoded as little-endian.

Payload Format

The payload is a concatenation of \(n_{\mathrm{fields}}\) field blocks:

Payload size:

\[ \mathrm{PAYLOAD\_SIZE} = \sum_{i=0}^{n_{\mathrm{fields}}-1} \left(8 + \mathrm{FIELD\_SIZE}_i\right)\]

All integer fields are encoded as little-endian.

Installing Nyx Stream

See the “Insallation” page.

Configuring Nyx Stream

In /etc/nyx-stream/config.json:

{
        "tcp_url": "tcp://0.0.0.0:8888",
        "http_url": "http://0.0.0.0:9999",
        "mqtt_url": "mqtt://127.0.0.1:1883",
        "mqtt_username": "",
        "mqtt_password": "",
        "poll_ms": 10
}

• tcp_url: Network endpoint used by Nyx Node to publish data streams to Nyx Stream.
• http_url: Network endpoint used by Nyx Lab to discover and subscribe to streams (REST API and WebSocket interface).
• mqtt_url: Network endpoint of the MQTT broker.
• mqtt_username: Username for authenticating to the MQTT broker (empty means “no username”).
• mqtt_password: Password for authenticating to the MQTT broker (empty means “no password”).
• poll_ms: Server processing interval, in milliseconds. It defines the maximum effective update rate of the streaming system.

Nyx nodes must not publish samples at a higher frequency than poll_ms.

Nyx Stream API

Base URL: http://<host>:<port>

Authentication is optional and depends on server configuration.
When enabled, all requests must include a token query parameter.

Authentication

Authentication is derived from the MQTT credentials configured on the server. mqtt_username and mqtt_password are used to compute the HTTP / WebSocket access token.

Query parameter

Token computation

The token is computed as follows:

1. Concatenate the MQTT credentials using the form: <username>:<password>.
2. Compute the SHA-256 hash of this string.
3. Take the first 8 bytes of the hash.
4. Encode them as 16 lowercase hexadecimal characters.

Example (pseudocode)

token = hex(sha256(mqtt_username + ":" + mqtt_password)[0: 8])

Subscribe to a Stream (WebSocket)

Subscribe to a real-time data stream and receive binary frames over WebSocket.

Endpoint

GET /streams/{device}/{stream}

Path parameters

Query parameters

Response

• HTTP 101 Switching Protocols
• WebSocket connection established
• Binary messages containing stream data

Get Poll Interval

Retrieve the current server poll interval.

Endpoint

GET /config/poll

Query parameters

Response

• 200 OK
• Body: integer value (milliseconds)

Set Poll Interval

Update the server poll interval.

Endpoint

POST /config/poll

Query parameters

Request body

• Plain text integer representing the poll interval in milliseconds

Response

• 200 OK
• Body: updated integer value (milliseconds)

Stop Server

Request a graceful shutdown of the Nyx Stream server.

Endpoint

GET /stop

Query parameters

Response

• 200 OK
• Body: OK

Error Responses