- 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>
6.3 KiB
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 onasyncio.start_server(no framework). JSON API under/api/…, live updates as server-sent events on/api/events(App.broadcast).Appholds 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 cookiedspsess(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– oneDeviceper DSP: connect (TCP orusbhid.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 (SPECinapp.js).dsp/preset.py– preset files (dsp-control-presetJSON with state + raw image), validation, and the minimal command sequence for an import. Undo backups go tobackups/next toconfig.json(last 20 per device).dsp/usbhid.py– HID via ctypes only: Windowshid.dll/SetupAPI, macOS IOKit, Linux/dev/hidraw*.HidStreamadapts a blocking reader thread to the asyncio stream interfacedevice.pyexpects.static/– single-page app in vanilla JS.h()builds DOM,Sis the global state,render()redraws the current view (mixer,channel,routing,link,limiter,settings). Live widgets register inliveand are updated without a full redraw. All UI text goes throught("English text", {vars}); German lives instatic/i18n.js(DE, plusDE_PATTERNSfor server messages with variables, applied bytrMsg()).sim.py– simulated DSP 204/408 speaking the same protocol (meters, limiter flags, links). Use it for all tests.desktop.py– startsserver.Appon 127.0.0.1 with a random port in a thread and opens a pywebview window.Apiexposes 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 aninstall.shthat 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 instatic/i18n.js; server error messages that reach the UI need one too (exact text inDE, or a regex inDE_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.mdandPROTOCOL.mdare English. The Pi Writer UI is still German.
Testing
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.