Files
BetterDSPControl/CLAUDE.md
T
GivouandClaude Opus 5.5 fe13f261f7 Add BetterDSPControl: web UI, desktop app and Pi writer for t.racks DSP 204/408
- Python stdlib server with SSE live updates, PIN login, remote access
- Vanilla JS web UI (English/German): mixer, channel, routing, links, limiter calculator
- Preset file export/import with undo, settings backup, lock for the desktop app
- Network (TCP 9761) and USB HID transport (Windows, macOS, Linux)
- Desktop app via pywebview, Raspberry Pi SD card writer, simulator and protocol tests
- README with import guide for Claude Code, CLAUDE.md, protocol documentation

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 20:24:33 +01:00

90 lines
6.3 KiB
Markdown
Raw Permalink 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.
# CLAUDE.md – guide for AI coding assistants
BetterDSPControl controls t.racks DSP 204 / DSP 408 loudspeaker processors. Read `README.md` (features, usage) and
`PROTOCOL.md` (wire protocol) first. This file explains how the code is built and what to watch out for.
## Architecture
```
browser / phone ──HTTP + SSE──► server.py (asyncio, stdlib only) ──► dsp/device.py ──TCP 9761 or USB HID──► DSP
▲
desktop.py (pywebview window, logs in with a one-time token, no PIN)
pi_writer.py → pi_image.py (cloud-init SD card, installs server.py as a systemd service on a Raspberry Pi)
```
* **`server.py`** – own HTTP server on `asyncio.start_server` (no framework). JSON API under `/api/…`, live updates as
server-sent events on `/api/events` (`App.broadcast`). `App` holds devices, auth, limiter data, remote access,
backups. Config is one JSON file (`config.json`, gitignored) – `load()` / `apply_config()` / `save()`.
* **Auth** – 4-digit PIN, PBKDF2 hash in `config.json`, session cookie `dspsess` (30 days), lockout after 5 failures.
The desktop app logs in via `/app-login?t=<one-time token>`; app sessions live in memory only, skip the PIN and may
toggle remote access (`/api/remote`) and the lock (`/api/lock`, server answers 423 while locked). Remote clients
always need the PIN.
* **`dsp/device.py`** – one `Device` per DSP: connect (TCP or `usbhid.open_stream`), handshake, config dump
(50-byte chunks), command queue (one request in flight), meter polling (also keepalive), auto-reconnect.
Mirrors changes within link groups locally and re-reads the config ~1.5 s after the last change (resync).
* **`dsp/protocol.py`** – frames, checksum, value scales, model layouts (`MODELS["204"|"408"]`), memory image ↔ state
dict (`parse_state` / `build_state_buffer`), parameter → command (`param_command`), link masks, meter/limiter decoding.
State values are **raw device values**; conversion to dB/Hz/ms happens in the UI (`SPEC` in `app.js`).
* **`dsp/preset.py`** – preset files (`dsp-control-preset` JSON with state + raw image), validation, and the minimal
command sequence for an import. Undo backups go to `backups/` next to `config.json` (last 20 per device).
* **`dsp/usbhid.py`** – HID via ctypes only: Windows `hid.dll`/SetupAPI, macOS IOKit, Linux `/dev/hidraw*`.
`HidStream` adapts a blocking reader thread to the asyncio stream interface `device.py` expects.
* **`static/`** – single-page app in vanilla JS. `h()` builds DOM, `S` is the global state, `render()` redraws the
current view (`mixer`, `channel`, `routing`, `link`, `limiter`, `settings`). Live widgets register in `live` and are
updated without a full redraw. **All UI text goes through `t("English text", {vars})`**; German lives in
`static/i18n.js` (`DE`, plus `DE_PATTERNS` for server messages with variables, applied by `trMsg()`).
* **`sim.py`** – simulated DSP 204/408 speaking the same protocol (meters, limiter flags, links). Use it for all tests.
* **`desktop.py`** – starts `server.App` on 127.0.0.1 with a random port in a thread and opens a pywebview window.
`Api` exposes native file dialogs to the page (`window.pywebview.api.save_file/open_file`). Single instance via a
named mutex (Windows) or lock file (macOS). Data in `%APPDATA%\DSP Control` / `~/Library/Application Support/DSP Control`.
* **`pi_writer.py` / `pi_image.py` / `win_disk.py`** – Windows-only tkinter tool that downloads Raspberry Pi OS Lite
(official image list), writes it raw to an SD card (`\\.\PhysicalDriveN`, verify by SHA-256) and adds cloud-init
files (`user-data`, `network-config`, `meta-data`) plus an `install.sh` that installs the app on first boot.
## Conventions
* **Server and `dsp/` use the Python standard library only.** pywebview/PyInstaller/Pillow are only for the desktop
builds. No build step for the web UI.
* Source texts are English. Every new `t("…")` string needs a German entry in `static/i18n.js`; server error messages
that reach the UI need one too (exact text in `DE`, or a regex in `DE_PATTERNS`). Technical terms (Gain, Threshold,
Mixer, Routing, Link, Limiter) stay English in German too.
* Native/desktop apps never ask for the PIN; the web UI and remote access always do.
* Channel names: max 8 printable ASCII characters (umlauts are transliterated), and they must fit the mixer strip.
* Keep comments sparse and factual, match the surrounding style.
* `README.md` and `PROTOCOL.md` are English. The Pi Writer UI is still German.
## Testing
```bash
python tests/test_protocol.py
python sim.py --model 204 --port 9761
python sim.py --model 408 --port 9762
python server.py --port 8080 --config <some temp file>.json
```
Log in with PIN `1234`, add devices `127.0.0.1:9761` / `:9762`. Check both languages after UI changes (⚙ →
Language / Sprache). For the desktop app run `python desktop.py` (needs `pywebview`).
**Never change values on a real DSP permanently while testing.** Export a preset file first (File… → Export) and
restore it afterwards; prefer the simulator. The DSP accepts only one connection – close other control software.
## Verified vs. unverified
Verified on a real DSP 204 (firmware V0104P, USB on macOS): connect/dump/meters, set commands, link command `0x3B`
and the DSP's own mirroring inside groups, limiter-active bit mask, preset import writing only differences.
Not verified yet – ask for a log (`python server.py -v`) from real hardware before changing protocol code here:
* **DSP 408 on real hardware** (layout and frames match published captures, limiter bits for Out 5–8 assumed)
* USB on Windows and Linux against a real DSP (only tested against a fake HID device)
* Where the PEQ bypass flag lives in the memory image; format of the set-command acknowledgement; payload of the
preset-count answer (`0x2C`)
* Limiter calculator reference level (assumes limiter 0 dB = 0 dBu at the output; adjustable per device)
* Pi Writer: raw write to a real SD card and first boot on a real Pi (only tested with an image file)
## Legal notes for contributors
Do not add code, binaries, firmware, screenshots, manuals or internal symbol names/addresses from the manufacturer's
software. Document protocol facts only as observed behaviour. Use "t.racks"/"Thomann" only to name the supported
devices and keep the "not affiliated" notice in the README.