Files
BetterDSPControl/PROTOCOL.md
T
GivouandClaude Opus 5.5 61400df667 Add device lock support and demo mode
Device lock (hardware lock of the DSP, independent of the app lock):
- detect a locked DSP from the 0x2C answer during connect and wait for the code
- unlock with 0x2D, optionally remember the code and unlock automatically
- set a new code (0x2F) from the device settings
- simulator: --lock CODE

Demo mode:
- switch in the settings starts a simulated DSP 204/408 inside the server
- real DSPs are disconnected and greyed out meanwhile and resume afterwards
- demo devices are never saved or exported; sim.py ships with the Pi image and EXEs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 21:14:04 +01:00

181 lines
8.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# t.racks DSP 204 / DSP 408 – control protocol
Documented for interoperability by observing the communication between the devices and their control software
and by testing on real devices. Both models speak the same protocol; only the number of channels and the size
of the memory image differ. Implementation: [`dsp/protocol.py`](dsp/protocol.py).
Status: the network transport and all commands below are implemented and tested against the simulator; links,
the limiter status bits and USB were verified on a real DSP 204 (firmware V0104P). Points marked *assumed* are
not verified yet.
## Transport
* **Network:** TCP, port **9761**. Factory default IP `192.168.1.101`.
* **USB:** HID class device, no driver needed, **VID 0x0168 / PID 0x0821** (both models). See [USB](#usb-hid).
* Request/response: send one command and wait for its answer before sending the next.
* The DSP accepts only **one** connection at a time.
## Frame
```
10 02 SRC DST LEN CMD PAYLOAD… 10 03 CHK
```
| Field | Meaning |
|-------|---------|
| SRC/DST | PC→DSP: `00 01`, DSP→PC: `01 00` (`01` = device ID) |
| LEN | `1 + len(PAYLOAD)` (includes CMD) |
| CHK | XOR from `02` to `03`, i.e. `0x01 ^ SRC ^ DST ^ LEN ^ CMD ^ PAYLOAD…` |
There is **no byte stuffing** – a payload may contain `10 03`, so always parse by LEN.
All 16-bit words are little endian.
## Read / system commands
| CMD | Direction | Payload | Meaning |
|-----|-----------|---------|---------|
| `10` | → | – | Handshake |
| `13` | → / ← | – / ASCII | Device info, answer starts with `DSP204` or `DSP408` |
| `2C` | → / ← | – / `[time lock][4 bytes][device lock]` | Lock state, see [Device lock](#device-lock) |
| `22`, `14` | → | – | Init queries (sent during connect, content unknown) |
| `29` | → / ← | `[idx]` / `[idx][name…]` | Preset name (idx 0-based) |
| `20` | → | `[idx+1]` | Recall preset |
| `26` | → | `name[14]` | Set name for the next store |
| `21` | → | `[idx+1]` | Store current state into preset |
| `27` | → | `[chunk]` | Request config chunk |
| `24` | ← | `[chunk][50 bytes]` | Config chunk; 204: chunks 0…14, 408: 0…28 |
| `12` | → | – | Status (sent after the dump) |
| `2D` | → / ← | `[0][code 4]` / `[0][result]` | Unlock with the lock code, result `1` = unlocked, `0` = wrong code |
| `2F` | → | `[code 4]` | Set a new lock code |
| `11` | → | – | Sent after setting a lock code (meaning not fully known) |
| `40` | → / ← | – / meters | Read levels (also serves as keepalive) |
### Meter answer
12 entries × 3 bytes `b0 b1 b2`, followed by 2 status bytes.
* Level = float32 from the bytes `00 b2 b0 b1` (little endian) → linear, dB = 20·log10.
* Positions: 0–3 = In A–D, 4–11 = Out 1–8. The 204 uses 0, 1 and 4–7.
* The level is measured before mute.
* **Limiter active**: the status bytes are a bit mask of the outputs (bit 0 = Out 1). Measured on a DSP 204:
`00 03` while Out 1+2 limit, `00 0C` for Out 3+4. That Out 5–8 of the 408 continue in the same 16-bit value
is *assumed*.
## Channel numbers
| Device | Inputs | Outputs |
|--------|--------|---------|
| DSP 204 | In A=0, In B=1 | Out 1–4 = 2–5 |
| DSP 408 | In A–D = 0–3 | Out 1–8 = 4–11 |
## Set commands
| CMD | Parameter | Payload |
|-----|-----------|---------|
| `34` | Gain | `[ch][u16 gain]` |
| `35` | Mute | `[ch][0/1]` |
| `36` | Polarity | `[ch][0/1]` |
| `38` | Delay | `[ch][u16 delay]` |
| `32` | High pass (low cut) | `[ch][u16 freq][slope]` |
| `31` | Low pass (high cut) | `[ch][u16 freq][slope]` |
| `33` | PEQ band | `[ch][band][u16 gain][u16 freq][q][type][bypass]` |
| `48` | GEQ band (inputs) | `[ch][band 0–30][u16 gain]` |
| `3E` | Gate (inputs) | `[ch][attack][release][hold][threshold]` (u16 each) |
| `30` | Compressor (outputs) | `[ch][ratio][attack][release][knee][threshold]` |
| `3F` | Limiter (outputs) | `[ch][attack][release][knee][threshold]` |
| `3A` | Routing matrix (outputs) | `[ch][bit mask of inputs]` |
| `41` | Mix level (outputs) | `[ch][input][u16 level]` |
| `3D` | Channel name | `[ch][name 8]` (printable ASCII) |
| `3B` | Link | `[ch][u16 link mask]` (see [Channel links](#channel-links)) |
| `15` | Delay unit | `[unit]` (display only) |
The format of the acknowledgement the DSP sends after a set command is not fully understood yet.
## Value encoding
| Parameter | Raw | Conversion |
|-----------|-----|------------|
| Gain / mix level | 0–400 (mix 0–280) | `r<80: r/2−60 dB`, else `(r−280)/10 dB` → −60…+12 dB |
| Frequency (PEQ, HP, LP) | 0–300 | `1000 · 2^((r−170)/30)` Hz → 19.7 Hz…20.16 kHz (1/30 octave) |
| PEQ/GEQ gain | 0–240 | `(r−120)/10` dB → ±12 dB |
| Q | 0–100 | table 0.4…128 (see `protocol.py`) |
| PEQ type | 0–8 | Peak, Low shelf, High shelf, HPF −6, HPF −12, LPF −6, LPF −12, Allpass 1, Allpass 2 |
| Slope | 0–20 | 0 = bypass, 1–20 = BW−6, BL−6, BW−12, BL−12, LK−12, … LK−48 |
| Delay | 0–65280 | `r/96` ms (max 680 ms) |
| Threshold (gate/comp/limit) | 0–220 | `(r−180)/2` dB (gate max 0 dB, comp/limit max +20 dB) |
| Attack | 0–998 | `r+1` ms |
| Release | 9–2999 | `r+1` ms |
| Hold | 9–998 | `r+1` ms |
| Ratio | 0–15 | 1.0, 1.1, 1.3, 1.5, 1.7, 2.0, 2.5, 3.0, 3.5, 4.0, 5.0, 6.0, 8.0, 10, 20, Limit |
| Knee | 0–12 | dB |
The absolute output level that corresponds to 0 dB limiter threshold is not published; the app assumes 0 dBu.
## Channel links
Measured on a DSP 204 (firmware V0104P). Every channel has a u16 mask (bit = channel index within the inputs
or within the outputs):
| Channel | Mask |
|---------|------|
| not linked | its own bit only (Out 3 = `04`) |
| first channel of a group | bits of all members (Out 3+4 = `0C`) |
| further members | `00` |
* Set with `3B [ch][mask]` – for every channel of the group (first channel first).
* When a group is formed, the DSP copies the settings of the first channel to the others.
* The DSP itself applies every change on a member to the whole group (gain, delay, polarity, HP/LP, PEQ, GEQ,
gate, compressor, limiter, mute) – but **not** channel name, routing matrix and mix levels.
* A member with mask `00` that is not part of a group ignores changes: when unlinking, give every channel its own
bit again.
## Device lock
The DSP can be protected with a 4-character code (digits and upper-case letters, e.g. `A1BA`, sent as ASCII).
* During connect, the answer to `2C` reports the lock state: byte 5 ≠ 0 means the device is locked. Byte 0 and
bytes 1–4 belong to a separate time-based lock that this app does not use.
* A locked device waits for `2D [00][code]` before the rest of the initialisation (`22`, `14`, preset names, dump).
The answer `2D [00][01]` means unlocked, `2D [00][00]` wrong code.
* `2F [code]` stores a new code; the control software sends `11` afterwards. The device asks for the new code from
the next connection on. A command to remove the lock is not known.
Status: derived from the behaviour of the control software and implemented against the simulator; **not yet
verified on a real device**.
## Config dump = memory image
Chunk `n` carries bytes `n·50 … n·50+49` of the device memory image.
```
0x00 u8[2] ?
0x02 char[14] preset name
0x10 Input[nIn] 140 bytes each
+0 name[8]
+8 gate: attack, release, hold, threshold (4×u16)
+16 geq[31] u16
+78 peq[8] {u16 gain, u16 freq, u8 q, u8 type}
+126 u16 hp_freq, u16 lp_freq, u8 hp_slope, u8 lp_slope
+132 u16 gain, u16 polarity, u16 delay, u16 link mask
Output[nOut] 96 + 2·nIn bytes each
+0 name[8]
+8 u16 matrix bit mask
+10 u16 mix[nIn]
… u16 hp_freq, u16 lp_freq, u8 hp_slope, u8 lp_slope
… peq[9] {u16 gain, u16 freq, u8 q, u8 type}
… comp: ratio, attack, release, knee, threshold (5×u16)
… limit: attack, release, knee, threshold (4×u16)
… u16 gain, u16 polarity, u16 delay, u16 link mask
u16 input mute bit mask, u16 output mute bit mask, then unknown fields
```
Total size: DSP 204 = 724 bytes (15 chunks), DSP 408 = 1448 bytes (29 chunks).
Where the PEQ bypass flag is stored in the image is not known yet.
## USB (HID)
* Both models: **VID 0x0168, PID 0x0821**, HID class, no driver.
* Send: report ID `00` + one complete frame (`10 02 … 10 03 CHK`), zero-padded to the output report length.
* Receive: every input report holds exactly one frame starting at byte 0, length = `LEN + 8`, then padding.
* The frames are identical to TCP; the longest (config chunk, 50 data bytes) is 60 bytes and fits a 64-byte report.