Waters-Church/companion-module-digico-s31
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v2: generic S-Series module with live discovery, dynamic options and meters

Browse Source 
Rewrite of the module around what the console itself reports:

- Settings cut to console address/ports, the iPad relay and debug logging;
  nothing site-specific remains. An upgrade script carries v1 configs and
  remaps v1 actions/feedbacks whose ids were reused.
- On connect the module reads every name, buss type (aux/group), stereo
  mode, fader/mute/solo/pan and the snapshot list; entities that never
  answer are hidden. Definitions rebuild (debounced, skipped when
  identical) when names, buss types or snapshots change.
- Every entity option is a searchable dropdown of live names. 70 actions
  cover inputs, aux sends, group assigns, busses, matrix outputs and sends,
  control groups, graphic EQs, channel-strip switches, trim/gain/filters and
  snapshots, each level with set and encoder-friendly adjust variants.
- Boolean, value and bar feedbacks for every state, input level and
  gain-reduction meters via the console's meter subscription protocol, and
  about 2800 presets including rotary knob presets with live level text.
- A write guard keeps fast encoder turns from being undone by delayed
  echoes; feedbacks are re-checked per instance.
- Relay: the client table survives config changes, idle iPads are kept for
  an hour by default (0 = forever), bind failures retry and show in status.

npm test: 326 checks pass on Node 25 and on Companion's Node 22.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
michael
2026-10-15 17:11:17 -04:00
co-authored by Claude Opus 5.5
parent 8693fe924a
commit dad8010239
20 changed files with 5102 additions and 1327 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+47 -21
View File
@@ -1,42 +1,68 @@
# companion-module-digico-s31
Bitfocus Companion (5.0+) connection module for the DiGiCo S21/S31: per-channel control of
one buss (the Apollo Beach "Studio" group by default), aux send level/on/pan, mutes, faders,
snapshots — plus a UDP relay so several DiGiCo iPad apps can share the console's single iPad slot.
Bitfocus Companion (5.0+) connection module for DiGiCo S-Series consoles (S21 / S31). It discovers the
console over the iPad extension's OSC interface (names, busses, matrix, control groups, graphic EQs,
snapshots), builds dropdowns, variables and presets from the live names, and controls faders, mutes,
solos, pans, aux sends, group assigns, matrix sends, per-channel switches and snapshots, with feedbacks,
rotary-encoder presets and input meters. It also relays the DiGiCo iPad app: the console accepts exactly
one iPad, Companion takes that slot, and any number of iPad apps connect through it.
User-facing documentation (console + iPad setup, variables, the verified protocol table) is in
[companion/HELP.md](companion/HELP.md); Companion shows it on the connection's help button.
User documentation (console and iPad setup, actions, feedbacks, variables, presets, meters and the
protocol table) is in [companion/HELP.md](companion/HELP.md); Companion shows it on the connection's help button.
Repository: <http://chronicles-ab.waterschurch.org:3000/Waters-Church/companion-module-digico-s31>
## Layout
| Path | Purpose |
| --- | --- |
| `src/main.js` | the `InstanceBase` subclass (config, lifecycle, state, learn log) |
| `src/definitions.js` | actions, feedbacks, variables, presets |
| `src/dialects.js` | address builders/parsers: `sd` (iPad extension, verified), `sseries` (OSC Control extension), `raw` |
| `src/main.js` | the `InstanceBase` subclass: config, lifecycle, load/keepalive/reconnect, paced query queue, actions' operations, meters, debug learn log, upgrade script |
| `src/state.js` | everything known about the console, dropdown choice builders, load plans |
| `src/protocol.js` | the iPad-extension OSC tree: address builders, message parser, value formatting |
| `src/image.js` | tiny RGBA drawing helpers for the bar feedbacks |
| `src/definitions/` | `actions.js`, `feedbacks.js`, `variables.js`, `presets.js` |
| `src/console-link.js` | one UDP socket to the console (fixed local port) |
| `src/relay.js` | iPad relay: tracks clients, forwards verbatim, fans out |
| `src/osc.js` | tolerant OSC codec |
| `tools/` | `mock-s31.js` (console emulator, both dialects), `fake-ipad.js`, see `tools/README.md` |
| `test/selftest.js` | end-to-end check: mock console ↔ link/relay ↔ fake iPad |
| `tools/` | `mock-s31.js` (console emulator), `fake-ipad.js`, the probe and the console's address catalog, see `tools/README.md` |
| `test/selftest.js` | end-to-end check: the real module against the mock console and a fake iPad |
| `docs/` | design notes |
## Develop
```bash
npm install # @companion-module/base ~2.1.3 (2.2.x is rejected by Companion 5.0.x)
npm test # runs test/selftest.js against the mock console
npm test # runs test/selftest.js against the mock console on 127.0.0.1 (ports 18000-19001)
```
## Install as a developer module (how it runs on AB-ProPresenter)
The module only uses `node:dgram` and `node:events`, so it runs under Companion's `--permission`
sandbox on its bundled Node 22 (no file writes, no child processes). No other dependencies.
To try it without a console, run the mock and point a connection at it:
```bash
node tools/mock-s31.js --dialect sd --listen 8000 --reply-to 127.0.0.1:9000
```
## Install as a developer module
1. Copy this folder, including `node_modules`, to the Companion computer, e.g.
`~/Apps/companion-dev-modules/companion-module-digico-s31/`.
2. In the Companion launcher → Developer, enable developer modules and set the path to the
*parent* folder (`~/Apps/companion-dev-modules`); the launcher restarts Companion with
`--extra-module-path`. (On AB this was done by editing `dev_modules_path` in
`~/Library/Application Support/companion/config.json` and relaunching Companion.)
3. Connections → Add → "DiGiCo: S21; S31" (version *Dev*). Later file changes hot-reload the
connection.
`~/companion-dev-modules/companion-module-digico-s31/`.
2. In the Companion launcher, open Developer, enable developer modules and set the path to the
*parent* folder (`~/companion-dev-modules`); the launcher restarts Companion with
`--extra-module-path`. Alternatively set `dev_modules_path` in Companion's `config.json` and relaunch.
3. Connections, Add, "DiGiCo: S21; S31" (version *Dev*). Later file changes hot-reload the connection.
The console side (Extensions → iPad) must point at the Companion computer's IP with
Send Port 9000 / Receive Port 8000 (the module defaults).
On the console, Extensions > iPad must point at the Companion computer's IP address, with the console's
Send port set to the connection's *Local receive port* (default 9000) and its Receive port set to the
connection's *Console receive port* (default 8000).
## Upgrading from 0.1
The connection settings are kept: an upgrade script maps the v1 config to the new eight settings
(`verboseLog` becomes *Debug logging*, the old 180 s iPad idle timeout becomes the new 3600 s default,
everything else is dropped). The v1 actions and feedbacks whose ids v2 reuses with different options
(`send_on`, `send_level`, `send_nudge`, `send_pan`, `group_assign`, `snapshot_fire`, `buss_mute`, `buss_fader`,
`mute`, `fader`, `muted`, `send_on` / `group_assigned` feedbacks) and the single-buss `mon_*` ones (using the old
single-buss number and type, `auto` read as aux) are rewritten to their v2 form; anything without an equivalent is
left as it was.