@snap-calliope/bridge

Snap!Out main-process IPC handler for the Calliope mini v3 USB serial transport.

This package is the main-process peer of @snap-calliope/extension: the extension runs in the renderer and communicates with this module (running in Electron's main process) via the calliope:* IPC channels.

Responsibilities

• Detect and open the Calliope serial port (USB VID 0x0D28 / PID 0x0204 — DAPLink / nRF52820).
• Perform the Microbit More v2 serial handshake and validate the firmware version against the expected hardware/protocol constants.
• Parse the incoming byte stream with a state-machine frame parser that mirrors CalliopeSerial.cpp.
• Forward decoded frames to the renderer via executeJavaScript(__snapCalliopeEmit …).
• Accept outgoing command frames from the renderer via IPC and write them to the serial port.

Wire format

Device → host:  [ 0xFF | RES_READ(0x01)  | ch_hi | ch_lo | len | payload... | chk8 ]
Host → device:  [ 0xFF | REQ_WRITE(0x10) | ch_hi | ch_lo | len | payload... | chk8 ]

The checksum is sum(all preceding bytes) % 0xFF. Identical to the Python serial_test.py reference implementation. Channel IDs and payload layouts are defined in firmware/src/CalliopeCommon.h.

IPC channels

| Channel | Direction | Payload | Description | |---|---|---|---| | calliope:connect | renderer → main | — | Open serial port; performs version handshake | | calliope:disconnect | renderer → main | — | Close serial port | | calliope:command | renderer → main | { frames: number[][] } | Write command frames to device | | calliope:frame | main → renderer | { channel: number, data: number[] } | Incoming sensor / event frame | | calliope:disconnected | main → renderer | — | Port closed unexpectedly |

The renderer-bound channels (calliope:frame, calliope:disconnected) are delivered by calling window.__snapCalliopeEmit(channel, payload) via executeJavaScript, following the same pattern used by the Snap!Net bridge.

Usage

In the Snap!Out main process (typically main.js):

const calliopeIpc = require('@snap-calliope/bridge');

// Register IPC handlers once at startup; pass an optional logger.
calliopeIpc.register(logger);

// Release the serial port cleanly on app quit.
app.on('will-quit', () => calliopeIpc.shutdown());

The renderer-side window.__SNAP_CALLIOPE_IPC__ bridge object (assembled by inject.js) must be injected before the extension is loaded so that transport/usb.js can find it.

File structure

src/
  calliope-ipc.js   — IPC handler, serial port management, frame parser / dispatcher

Dependencies

• serialport — Node.js serial port access (peer dependency of Electron's main process).

License

AGPL-3.0-or-later