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

1. Copy this folder, including node_modules, to the Companion computer, e.g. ~/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.

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.