Skip to content

IMMERSE Node Protocol — v0.1.0 (provisional)

This document defines the wire protocol that IMMERSE Runtime uses to control compute nodes (audio, video, GPIO, DMX). It is provisional — parts of it (audio, video) are not yet implemented in the runtime and are reserved for v0.2.

General principles

  • HTTP/1.1 over TCP port 80 on the node's IP (as configured in the .ishow file).
  • JSON request bodies, JSON responses.
  • 2-second timeout per request. Runtime does not retry automatically.
  • Status codes: 2xx = success, 4xx = client error (bad channel, unknown action), 5xx = node error.

GPIO nodes

POST /gpio/{channel}

Drive a GPIO channel.

Request body: 

{ "action": "pulse" | "set" | "clear", "ms": 250 }
- action: required. pulse = set high, wait ms, set low. set = set high. clear = set low. - ms: optional, only meaningful for pulse. Default 250.

Response: 200 OK with empty body on success.

DMX nodes

Not used by Runtime v0.1.0. DMX is sent as sACN (E1.31) multicast over the network; DMX nodes listen to sACN directly and do not need an HTTP API. A future protocol version may add an HTTP status endpoint so Runtime can verify DMX nodes are online.

Audio nodes — reserved for v0.2

Planned endpoints: - POST /audio/play { "file": "...", "volume": 0..1, "loop": false } - POST /audio/stop { "fadeMs": 500 } - GET /audio/status — what's playing, position, duration

Video nodes — reserved for v0.2

Planned endpoints: - POST /video/play { "file": "...", "output": "hdmi-0" } - POST /video/stop - POST /video/still { "file": "..." } — show a still image - GET /video/status

Health — planned for v0.2

Every node should expose: - GET /health — { "ok": true, "uptime_s": N, "roleClass": "gpio|dmx|audio|video" }

Runtime will poll this periodically and show node status in /status.

Implementation notes

The GPIO protocol is small enough to fit on a microcontroller (ESP32, RP2040, etc.) with a tiny HTTP server. A reference implementation in ~100 lines of Arduino or MicroPython is planned.

The audio/video protocol is implemented by IMMERSE Nodes shipped from us.