companion-module-digico-s31/tools/README.md

# Developer tools

Two small, dependency-free Node.js tools (Node 22+) for developing the S31 module
without a console. They share `osc-lite.js`, a tiny OSC encoder/decoder.

`tools/package.json` pins this folder to CommonJS, because the module's own
`package.json` is `"type": "module"` and would otherwise make Node load these
files as ESM. Keep it.

Both tools speak two OSC dialects, chosen with `--dialect`:

| Dialect | What it is |
| --- | --- |
| `sseries` (default) | The lowercase S-Series command list: `/console/ping`, `/channel/N/fader`, ... |
| `sd` | The "DiGiCo Pad" dialect the **real S31 iPad extension actually speaks**: `/Console/Name/?`, `/Input_Channels/N/fader/?`, ... Verified against a live console (`tools/catalog/s31-catalog.md`); this is the dialect the Companion module uses. |

## `mock-s31.js` - fake S31 console

Emulates the console's OSC extension. It listens on one UDP port and sends
**all** feedback to **one** configured controller IP:port, whoever asked and
from whichever source port, like the real desk.

```
node tools/mock-s31.js [--dialect sseries|sd] [--listen 8000] [--reply-to IP:PORT]
                       [--channels N] [--auxes N] [--bool-int] [--live]
                       [--delay MS] [--types] [--quiet]
```

| Flag | Meaning |
| --- | --- |
| `--dialect` | `sseries` (default) or `sd`. |
| `--listen` | UDP port to bind (the console's receive port). Default 8000. |
| `--reply-to` | Fixed feedback destination, e.g. `127.0.0.1:9000`. If omitted, locks onto the first sender's IP with port 9000 and prints that. |
| `--channels` | Input count, 1-60. Default 48 (`sseries`) or 60 (`sd`). |
| `--auxes` | Aux busses / sends per channel. Default 16, max 16 (`sseries`); default 25, max 25 (`sd`). |
| `--bool-int` | `sseries` only: send booleans as int 0/1 instead of OSC `T`/`F`. |
| `--delay MS` | `sd`: answer and echo every message MS milliseconds late (0-5000, default 0), to test a slow console and stale echoes. |
| `--live` | Every 3 s, change a random send level or send on/off and emit it. |
| `--types` | Also print each message's OSC type tags, e.g. `/Input_Channels/1/fader ,f [-1.4375]`. |
| `--quiet` | Don't print every message. |

Traffic is printed as `<- ADDRESS [args] from IP:PORT` and `-> ADDRESS [args]`.
Whole-number floats print with a decimal (`-10.0`) so you can tell int from float.

### sseries dialect
No args at a readable address = query (reply with the value); with an arg =
set (store, then echo to the controller). `/console/resend` dumps the whole
state at ~2 ms per packet. Values are clamped (fader -150..10, send level
-90..10, pan -1..1). Addresses: `/console/{ping,channel/counts,resend}`,
`/channel/N/{name,fader,mute,solo,pan}`, `/channel/N/total/gain` (send-only,
sent with fader changes), `/channel/N/send/M/{level,enabled,pan}`, and
`/digico/snapshots/fire[/next|/previous]` (logged only). Inputs are 1-60, aux
busses 70..70+auxes-1.

### sd dialect
A **query** is the address plus a trailing `/?` and no args; the reply is the same address without `/?`
plus the value. A **set** is the address without `/?` and one arg; it is stored and echoed back in the
console's reply types. The mock answers the addresses listed in `tools/catalog/s31-catalog.md` (the real
console's answers) with the catalog's reply types. Entity numbers are 1-based, **control groups
included** (`/Control_Groups/1/name` is the first); snapshot indexes are 0-based. `--channels N` limits the
inputs, `--auxes N` the busses (default 25), and the matrix (8 outputs, 10 inputs), 10 control groups and
16 graphic EQs are fixed.

| Address | Reply type |
| --- | --- |
| `/Console/Name/?`, `/Console/Session/Filename/?` | `s` |
| `/Console/{Matrix_Outputs,Matrix_Inputs,Control_Groups,Graphic_EQ,Talkback_Outputs,Multis}/?` | `i` |
| `/Console/{Input_Channels,Aux_Outputs,Group_Outputs}/?` | **silent**, like the real console. All nine counts are pushed once, ~200 ms after the first datagram it receives |
| `/Console/Aux_Outputs/types/?` | one `i` per buss, 1 = aux, 0 = group (a buss named only on the Group side is a group) |
| `/Console/{Aux_Outputs,Group_Outputs}/modes/?`, `/Console/Input_Channels/modes/?` | one `i` per buss / input (2 = stereo, 1 = mono, captured) |
| `/Input_Channels/N/Channel_Input/name/?`, `/Aux_Outputs/N/Buss_Trim/name/?`, `/Group_Outputs/N/Buss_Trim/name/?`, `/Matrix_Outputs/N/Buss_Trim/name/?`, `/Control_Groups/N/name/?`, `/Graphic_EQ/N/name/?` | `s`. Only input names accept a write here (not verified on the real console); the others are read-only. The 25 busses appear under both Aux_Outputs and Group_Outputs; a buss reports its name on the side matching its mode and `""` on the other. Matrix inputs have no name address |
| `/{Input_Channels,Aux_Outputs,Group_Outputs,Matrix_Outputs,Control_Groups}/N/fader/?` | `f`, dB, -150 = -inf, max +10 |
| `/{...}/N/mute/?`, `/{...}/N/solo/?` | `f` 0/1 (a float, not an int); a SET must be a float too, see below |
| `/Input_Channels/N/Panner/pan/?` | `f`, 0..1, 0.5 = centre |
| `/Input_Channels/N/Aux_Send/M/{send_level,send_on,send_pan}/?` | `f` (level dB -150..10, on 0/1, pan 0..1) |
| `/Input_Channels/N/Aux_Send/M/send_pre-post/?` | `i` (captured as an int, default 0; settable 0..1, which value means "pre" is an assumption; the Companion module does not use it) |
| `/Input_Channels/N/Group_Send/M/group/?` | `f` 0/1 group assign. Default: inputs 1-8 and 18-21 on group 24. The wire type is the constant `SD_GROUP_ASSIGN_WIRE_TYPE` |
| `/Matrix_Inputs/N/Matrix_Send/M/{send_level,send_on}/?` | `f` (default -90 and 0, captured). A matrix send floors at -90 dB (verified on an S31): level writes are clamped to -90..10, never -150 as for faders and aux sends |
| `/Graphic_EQ/N/{geq_in,geq_gain_1..32}/?` | `f` |
| `/Input_Channels/N/{Channel_Input/{trim,phase,phantom,analog_gain,input_pad},Filters/{hi,lo}_filter_{in,freq},Channel_Delay/{delay_on,delay},EQ/eq_in,Dynamics/{comp_in,gate_in},Insert/insert_{A,B}_in}/?` | `f` (switches 0/1) |
| `/{Aux_Outputs,Group_Outputs}/N/{Buss_Trim/{trim,phase},EQ/eq_in,Dynamics/{comp_in,gate_in},Channel_Delay/{delay_on,delay},Insert/insert_{A,B}_in}/?`, `/Matrix_Outputs/N/Buss_Trim/trim/?` | `f` |
| `/Snapshots/Current_Snapshot/?`, `/Snapshots/count/?` | `i` |
| `/Snapshots/names/?` | one `/Snapshots/name ,iiis [index, cue*100, 0, "name"]` per snapshot. `/Snapshots/name/?` without an argument stays silent (unreliable on the real console) |
| `/Snapshots/Fire_Snapshot_number [i]`, `/Snapshots/Fire_Next_Snapshot`, `/Snapshots/Fire_Prev_Snapshot` | write-only triggers; the mock moves its current snapshot and pushes `/Snapshots/Current_Snapshot` |
| `/Macros/Buttons/press [i]` | logged only (no macro query is answered) |

**Meters.** Subscribe with `/Input_Channels/N/Channel_Input/post_meter ,ii [id, 1]` (post-fader level) or
`/Input_Channels/N/Dynamics/GR_meter ,ii [id, 1|4]` (gate / compressor gain reduction), where the client
chooses `id`. Every subscribed id then gets a random value 0..127 about five times a second, as
`/Meters/values ,ii... [id, v, id, v, ...]` (only ids whose value changed). `/Meters/clear` drops every
subscription, like the real console.

A 0/1 switch (mute, solo, send on, group assign, matrix send on, `geq_in` and every channel-strip switch) is both
reported **and written as a float** 0.0 / 1.0, verified on a real S31 on 2026-10-15 (the 2014 DiGiCo list says
int). Exactly like the console, the mock accepts only a float write (stored, echoed as `,f`) and silently
ignores an int `i` or `T`/`F` write: no echo, no state change. Levels, pans and values are clamped to
their ranges. Like the real console the mock stays **silent** on everything else: all lowercase S-Series
addresses, `/Console/Resend`, `/Console/Channels/?`, whole-send queries, out-of-range entity numbers,
sets of read-only names. (`--bool-int` has no effect in `sd`.)

## `fake-ipad.js` - stand-in for the DiGiCo iPad app

Binds the receive port, sends its opening requests, repeats a keepalive every
5 s, prints everything it receives and a packet-count summary every 10 s.

```
node tools/fake-ipad.js --console IP --send-port 8000 --receive-port 9000
                        [--dialect sseries|sd] [--name A] [--types] [--quiet]
```

- `sseries`: sends `/console/ping`, then `/console/resend`; keepalive `/console/ping`; `/console/pong` counts as a pong.
- `sd`: sends `/Console/Name/?`, `/Console/Input_Channels/?`, `/Console/Aux_Outputs/?`, `/Console/Aux_Outputs/modes/?`, names of inputs 1-8 and aux outputs 1-4, then `/Snapshots/names/?` (20 ms apart); keepalive `/Console/Name/?`; a `/Console/Name` reply counts as a pong.

Type `ADDRESS [arg ...]` lines on stdin to send your own messages
(`true`/`false` = boolean, `5` = int, `5.0` or `-12.5` = float, anything else or
`"quoted"` = string; `quit` exits):

```
/channel/3/send/2/level -12.5                     # sseries set
/Input_Channels/3/Aux_Send/2/send_on 1            # sd set (echo comes back as ,f [1])
/Input_Channels/3/Aux_Send/2/send_level/?         # sd query
/channel/3/name "Lead Vox"
```

## End-to-end loops on one machine

The module sits between the console and the iPad: the console's feedback goes
to the module (port 9000), and the module relays to and from the iPad. Use the
ports the module is actually configured with; `9100` and `9200` below are just
examples for "the relay's iPad-facing port" and "where the relay forwards
feedback to the iPad".

### S-Series dialect

```sh
# 1. Mock console: listens on 8000, replies to whatever listens on 9000
node tools/mock-s31.js --listen 8000 --reply-to 127.0.0.1:9000

# 2. Start the Companion module (or any relay) listening on 9000, sending to 127.0.0.1:8000

# 3. Fake iPad pointed at the relay (sends to 9100, receives the relayed feedback on 9200)
node tools/fake-ipad.js --console 127.0.0.1 --send-port 9100 --receive-port 9200
```

### SD dialect (what the real S31 speaks)

```sh
# 1. Mock console in SD mode: listens on 8000, replies to 127.0.0.1:9000
node tools/mock-s31.js --dialect sd --listen 8000 --reply-to 127.0.0.1:9000 --types

# 2. Start the Companion module (or any relay) listening on 9000, sending to 127.0.0.1:8000

# 3. Fake iPad (SD) pointed at the relay
node tools/fake-ipad.js --dialect sd --console 127.0.0.1 --send-port 9100 --receive-port 9200 --types
```

No module yet? Skip step 2 and point the iPad straight at the mock to check the
tools themselves, e.g.
`node tools/fake-ipad.js --dialect sd --console 127.0.0.1 --send-port 8000 --receive-port 9000`.