# 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/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

```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 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:

```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.
   `~/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.