Waters-Church/companion-module-digico-s31

Files

T

michaelandClaude Opus 5.5 dad8010239 v2: generic S-Series module with live discovery, dynamic options and meters

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>

2026-10-15 17:11:17 -04:00

3.9 KiB

Raw Blame History

companion-module-digico-s31

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 documentation (console and iPad setup, actions, feedbacks, variables, presets, meters and the protocol table) is in 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, 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), `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

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 on 127.0.0.1 (ports 18000-19001)

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:

node tools/mock-s31.js --dialect sd --listen 8000 --reply-to 127.0.0.1:9000

Install as a developer module

Copy this folder, including node_modules, to the Companion computer, e.g. ~/companion-dev-modules/companion-module-digico-s31/.
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.
Connections, Add, "DiGiCo: S21; S31" (version Dev). Later file changes hot-reload the connection.

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.