The host link¶

The host link lets another controller run the board over a wire: an Arduino or MarcDuino, a dome controller, another ESP32, or a Raspberry Pi. It plays scenes, shows clips, sets the LEDs and moves the holo, and hears back when a clip or scene has ended.

It uses three spare pins on the P2 header, and doesn't touch the USB console or Wi-Fi: all three work at once.

Choosing a transport¶

CAN (with Cyphal) and plain GPIO triggers are planned for later.

JSON lines are the HTTP API, one request a line:

POST /scenes/apply {"name":"cantina"}
200 {"screen":{...},"leds":{...},"holo":{...}}

Native frames are small binary messages with a CRC, for hosts with little memory. The protocol reference specifies both.

Pins¶

A GND wire, P2 pin 1 or 5, goes with every transport. The pins can be changed in the settings, to any of the free GPIOs that the LEDs and servos aren't using. While the link holds a pin, the gpio command refuses to drive it.

Everything is 3.3 V, and no pin takes 5 V. Each transport's page says what to put between the board and a 5 V host.

Turning it on¶

The link is off until it's given a transport. The settings are saved, and can be changed from the USB console, the HTTP API, or the web app.

On the console:

link mode uart -b 115200
restart

After the restart, link shows it running:

link: uart on GPIO21 (TX), GPIO33 (RX), 115200 baud, protocol auto, address 1
  requests 0, events given 0, bad lines 0, framing errors 0, overruns 0, ignored 0; last request never
  events: [], pushed, 0 pending

Over the HTTP API:

curl -X PATCH -H "Content-Type: application/json" \
  -d '{"mode":"uart","baud":115200}' http://holo-2db0.local/api/v1/link

In the web app: the Host link card on the Settings page.

Changing the transport, the pins, attn, the I2C address or general_call waits for a restart, and the reply says so with "restart_required": true. The rest applies at once: the baud rate, the address and groups, the protocol, and the events it starts with. A new baud rate takes effect after the reply, which is sent at the old one.

The link command¶

What a host can do¶

Over JSON lines, most of the HTTP API: the screen, the LEDs, the holo and servos, scenes, settings, the board's information, and the link itself. The protocol reference lists the paths. Files, firmware updates, the network and servo calibration stay on the USB console and Wi-Fi.

Over native frames, less, but what a show needs: apply a scene by its slot, end it, the screen's colour and backlight, the LEDs, a holo motion, and the board's status.

Scenes do the heavy lifting. Set up the scenes on the web app, give each one a slot, and a host needs only "scene 3" to change what the screen, the LEDs and the holo are all doing.

Events¶

A host can hear about things as they happen, rather than asking. They are the board's own events, the same ones the web app follows:

• what happened: clip_started, clip_ended, scene_started, scene_ended, and touch (when touch reporting is on);
• what changed: screen, leds, holo, scene, scenes, settings, network, ota and system, each with the resource as its GET returns it;
• ready: the link has started (always sent once on UART, after a restart).

Nothing but ready is sent until the host asks, with PATCH /link/events or the native EVENTS_SET. On UART, the board sends events as they happen, with no extra wire. On RS485 and I2C, the host fetches what happened, and every reply says how many are waiting. Events has the details.

Status¶

link on the console, and GET /api/v1/link, count what the link has seen:

A host that gets no reply at all is usually a wiring or baud-rate problem: link log on shows whether anything arrives. Each transport's page has a first test to try.