Add architecture/data-model/protocol reference docs

Human-facing reference documentation, split from AGENTS.md's agent-facing domain rules and bug history (which stays there, not duplicated here): - docs/architecture.md: layer diagram, module responsibilities, config storage location, the three GUI modes, and the port-exclusivity / multi-process caveats around concurrent access - docs/data-model.md: the combined and legacy JSON formats, the binary SDeviceConfig/SDeviceProfile/SMacroTable NVM layout byte-for-byte, action types, LED fields, macro-slot conventions, button grid geometry - docs/protocol.md: the 8-byte serial packet format, command/event tables, the read/write/status-poll flows, connection lifecycle, and error states README.md now links to all three from a new "Dokumentation" section, and AGENTS.md's outdated "docs/ tree isn't warranted yet" note is removed now that it exists on explicit user request.
2026-08-14 23:19:13 +02:00 · 2026-08-14 23:19:13 +02:00 · 83429363c1
commit 83429363c1
parent 7d40fdaa60
5 changed files with 550 additions and 11 deletions
--- a/docs/architecture.md
+++ b/docs/architecture.md
@ -0,0 +1,185 @@
+# Architektur
+
+Überblick über die Schichten, Prozesse und Datenflüsse von VersaPad Viewer.
+Für Domänenregeln, bekannte Bugs und Implementierungsdisziplin siehe
+[`AGENTS.md`](../AGENTS.md); für Installation/Nutzung siehe
+[`README.md`](../README.md). Für die genauen Datenformate siehe
+[`data-model.md`](data-model.md), für das Serial-Wire-Protokoll
+[`protocol.md`](protocol.md).
+
+## Ziel und Kontext
+
+VersaPad Viewer ist ein eigenständiges Python-Tool für das VersaPad-Makropad
+(4×5-Button-Grid + 4 Encoder, SAMD21-Firmware). Es ergänzt die offizielle
+VersaGUI (C#/.NET) um eine schlankere, plattformunabhängigere Alternative
+zum Anzeigen, Live-Synchronisieren und Neuprogrammieren der Belegung, plus
+einen MCP-Server, der dieselbe Programmierung KI-gesteuert per Tool-Aufruf
+erlaubt. Beide GUIs (die offizielle VersaGUI und dieses Tool) konkurrieren
+um denselben exklusiven USB-CDC-Port — siehe „Nebenläufigkeit" unten.
+
+## Schichtenmodell
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Frontends                                                       │
+│  ┌────────────┐   ┌──────────────────┐   ┌────────────────────┐ │
+│  │ server.py  │   │ desktop_viewer.py │   │ versapad_mcp_       │ │
+│  │ (Browser,  │   │ (Tkinter, Tray,   │   │ server.py           │ │
+│  │  read-only)│   │  Live-Sync, Edit) │   │ (KI-Tool-Aufrufe)   │ │
+│  └─────┬──────┘   └────────┬──────────┘   └─────────┬──────────┘ │
+│        │                   │                          │          │
+│        └───────────┬───────┴──────────────┬───────────┘          │
+│                     ▼                      ▼                      │
+│           versapad_combined.py    versapad_data.py                │
+│           (Ein-Datei-Format,      (Decoding fürs Anzeigen,        │
+│            Board-Sync, Auto-      Legacy-Einzel-JSONs)            │
+│            Create)                                                │
+│                     │                                              │
+│                     ▼                                              │
+│           versapad_protocol.py (pack/unpack, CRC16)               │
+│                     │                                              │
+│                     ▼                                              │
+│           versapad_serial.py (VersaPadLink, 8-Byte-Pakete)        │
+│                     │                                              │
+└─────────────────────┼──────────────────────────────────────────────┘
+                       ▼
+              VersaPad-Board (USB-CDC, VID:PID 239A:0042)
+```
+
+`action_dialog.py` ist ein UI-Hilfsmodul von `desktop_viewer.py`
+(Bearbeiten-Dialoge für den Programmiermodus) und taucht oben nicht separat
+auf.
+
+### Read-only-Schicht
+
+- **`versapad_data.py`** — decodiert JSON-Rohdaten (Keycodes, Consumer-IDs,
+  Modifier-Bits) zu lesbarem Text, kennt die Grid-Geometrie
+  (`index = spalte*5 + reihe`). Liest wahlweise:
+  - die klassischen `versapad_config1/2/3.json` (`CONFIG_PATHS`) — Export
+    der offiziellen VersaGUI, kein von diesem Tool geschriebenes Format;
+  - oder (über `versapad_combined.py`) die kombinierte Datei.
+  - `app_dir()` liefert das Basisverzeichnis für die eigene Config, siehe
+    „Config-Speicherort" unten.
+- **`server.py`** — generiert bei jedem HTTP-Request frisch HTML aus dem
+  aktuellen Zustand (`vcomb.load_or_fetch()`), Auto-Reload alle 4s per
+  `<meta http-equiv="refresh">`. Rein lesend, kein eigener Zustand zwischen
+  Requests, daher nie „veraltet" im Sinne von In-Memory-Staleness.
+
+### Binär-/Serial-Schicht
+
+- **`versapad_protocol.py`** — pack/unpack für `SDeviceConfig` (740B, alle
+  3 Profile) und `SMacroTable` (512B, 32 Slots), plus CRC16. 1:1 aus den
+  Firmware-Structs übernommen, siehe [`data-model.md`](data-model.md).
+- **`versapad_serial.py`** — `VersaPadLink`: öffnet bei Bedarf den COM-Port
+  (per VID/PID-Erkennung), spricht das 8-Byte-Paket-Protokoll, siehe
+  [`protocol.md`](protocol.md). **Schließt die Verbindung nicht von selbst**
+  nach einem Befehl — Aufrufer müssen das selbst tun, wenn sie den Port
+  nicht dauerhaft blockieren wollen (siehe „Nebenläufigkeit" unten).
+- **`versapad_combined.py`** — das Ein-Datei-Format: alle 3 Profile +
+  Makro-Tabelle + lokale Profilnamen in einer JSON
+  (`versapad_config_all.json`). Bindeglied zwischen den JSON-Strukturen und
+  den Binärblobs aus `versapad_protocol.py`. Zentrale Funktionen:
+  - `load_or_fetch()` — bevorzugt die lokale Datei, baut sie bei Bedarf
+    automatisch neu auf (erst Board-Versuch, sonst leere Default-Config).
+  - `save_file()`/`load_file()` — reines Lesen/Schreiben der JSON.
+  - `fetch_from_board()`/`to_binary()` — Konvertierung zu/von den
+    Binärblobs für Board-Lese-/Schreibvorgänge.
+  - `read_profile_names()` — liest nur die Profilnamen, ohne Board-Zugriff
+    (für Tab-Beschriftungen im Nur-Lese-Modus).
+
+### UI
+
+- **`desktop_viewer.py`** — Tkinter-Fenster mit drei unabhängig
+  umschaltbaren Modi (siehe „Modi" unten), Tray-Icon, Info-Dialog mit
+  MCP-Doku.
+- **`action_dialog.py`** — modale Bearbeiten-Dialoge (`ActionEditDialog`,
+  `MacroStepsDialog`) für den Programmiermodus.
+
+### MCP-Server
+
+- **`versapad_mcp_server.py`** — registriert als projektgebundener
+  MCP-Server "versapad" (`.mcp.json`) oder wahlweise user-scope
+  (`claude mcp add -s user versapad -- <python> versapad_mcp_server.py`).
+  Hält einen eigenen In-Memory-Zustand (`_state["combined"]`,
+  unabhängig von jeder laufenden GUI), der explizit per `save_local()` /
+  `load_local()` mit der Datei bzw. `load_from_board()` / `write_to_board()`
+  mit dem Board synchronisiert wird. Board-Serial-Tools schließen die
+  Verbindung nach jedem Aufruf wieder (siehe unten).
+
+## Config-Speicherort
+
+`versapad_data.app_dir()` bestimmt das Basisverzeichnis für die eigene
+Config-Datei (`versapad_combined.DEFAULT_PATH` =
+`app_dir()/versapad_config_all.json`):
+
+- **Gebaute `.exe`** (PyInstaller `--onedir`): `sys.executable`s Ordner —
+  die Config liegt also neben `VersaPadViewer.exe`, in welchem
+  Installationsverzeichnis sie auch liegt.
+- **Start aus dem Quellcode** (`py desktop_viewer.py`, `py server.py`,
+  `py versapad_mcp_server.py`): der Projektordner (`__file__`-Verzeichnis).
+
+Fehlt die Datei, legt `load_or_fetch()` sie automatisch an — zuerst per
+Serial-Versuch vom Board (das ist die eigentliche Quelle der Wahrheit, die
+Datei nur ein Lesecache dafür), sonst als leere Default-Config
+(`default_combined()`). Das Tool ist damit auch ganz ohne vorhandene
+Config oder angeschlossenes Board sofort benutzbar.
+
+Die klassischen `versapad_config1/2/3.json` (`versapad_data.CONFIG_PATHS`)
+bleiben bewusst getrennt hartkodiert auf `~\OneDrive\Desktop` — das ist
+optionale Lese-Interop mit einem JSON-Export der offiziellen VersaGUI,
+kein von diesem Tool selbst gepflegtes Format, und daher nicht Teil der
+„portablen Installation".
+
+## Modi in `desktop_viewer.py`
+
+Drei Checkboxen, unabhängig voneinander:
+
+| Modus | Zweck | Zustand |
+|---|---|---|
+| Nur-Lesen (Default) | Zeigt das aktuelle Profil an | Liest bei jedem Poll (alle 1,5s) frisch über `_current_profile_view()` → `vcomb.load_or_fetch()`. Kein eigener In-Memory-Snapshot, daher nie veraltet. |
+| Live-Sync | Fragt per Serial das aktuell aktive Profil ab, schaltet die Ansicht mit | Hintergrund-Thread pollt `read_active_profile()`, hält dafür den COM-Port dauerhaft offen, solange die Checkbox an ist. Schließt sich mit VersaGUI/Programmiermodus/MCP-Board-Zugriff gegenseitig aus (exklusiver Port). |
+| Programmiermodus | Zellen anklicken zum Bearbeiten | Lädt `self.combined` **einmalig pro Prozesslauf** beim ersten Aktivieren (bevorzugt `DEFAULT_PATH`, sonst `default_combined()`). Jede Bearbeitung speichert sofort automatisch (`_autosave_combined()`). **Achtung:** Da der Snapshot nur einmal geladen wird, sieht der Programmiermodus externe Änderungen (z.B. per MCP) erst nach einem Neustart der exe oder einem expliziten „Datei laden…“. |
+
+Tk-Aufrufe passieren nie direkt aus dem Serial- oder Tray-Hintergrundthread
+— Ergebnisse landen in einer `queue.Queue`, der Main-Thread holt sie per
+`after()`-Polling ab (Absturzrisiko bei Cross-Thread-Tk-Zugriff, siehe
+`AGENTS.md`).
+
+## Nebenläufigkeit / Prozessmodell
+
+Der USB-CDC-Port ist **exklusiv** — nur eine Verbindung gleichzeitig. Drei
+potenzielle Halter existieren parallel und wissen nichts voneinander:
+
+1. Die offizielle VersaGUI (C#/.NET), läuft dauerhaft als Tray-App.
+2. `desktop_viewer.py`, wenn Live-Sync an ist (hält den Port dauerhaft) oder
+   während eines Board-Lese-/Schreibvorgangs im Programmiermodus (hält ihn
+   nur kurz).
+3. `versapad_mcp_server.py`, während eines Board-Tool-Aufrufs — schließt
+   die Verbindung danach explizit wieder (`finally: _link.close()` in
+   `get_board_status()`, `load_from_board()`, `write_to_board()`), damit ein
+   einzelner MCP-Aufruf nicht dauerhaft blockiert, was Live-Sync/VersaGUI
+   sonst mit „busy“ aussperren würde.
+
+**Mehrere MCP-Server-Prozesse:** Je nach Host-Umgebung können mehrere
+unabhängige `versapad_mcp_server.py`-Prozesse gleichzeitig laufen (z.B.
+durch wiederholte Tool-Ladevorgänge/Reconnects), jeder mit eigenem,
+nicht geteiltem In-Memory-Zustand. Ein `write_to_board()`-Aufruf kann daher
+auf einem anderen Prozess landen als vorherige `set_*`-Aufrufe und einen
+veralteten/leeren Zustand schreiben, obwohl die Antwort `{"ok": true}`
+meldet. Empfohlenes Muster: vor `write_to_board()` immer `load_local()`
+aufrufen (liest die Datei prozessunabhängig frisch von der Platte) und
+nach dem Schreiben mit `load_from_board()` + `get_profile()` gegenlesen,
+statt dem ACK allein zu vertrauen. Details siehe „Bug beobachtet
+2026-08-14“ in `AGENTS.md`.
+
+## Build/Deploy
+
+`build_and_deploy.ps1` installiert `requirements.txt` selbst
+(`pip install -r`), baut mit PyInstaller (`--onedir --windowed`, nur
+`desktop_viewer.py` wird gebündelt) und kopiert das Ergebnis nach
+`dist\VersaPadViewer\` im Projektordner. `--onedir` statt `--onefile`, um
+AV-Fehlalarme zu verringern. Läuft komplett in try/catch mit
+Exit-Code-Prüfung und pausiert am Ende (Erfolg wie Fehler) auf
+Tastendruck, außer bei `-NoPause`. Muss lokal laufen, nicht auf einem
+Netzlaufwerk (Pfadlängen-/DLL-Ladeprobleme, siehe `AGENTS.md`). Details:
+[`README.md`](../README.md#als-eigenständige-exe-windows).
--- a/docs/data-model.md
+++ b/docs/data-model.md
@ -0,0 +1,205 @@
+# Datenmodell
+
+Alle Formate, die VersaPad Viewer liest/schreibt: die JSON-Repräsentationen
+und das binäre NVM-Layout des Boards. Das binäre Layout ist 1:1 aus den
+VersaMCU-Firmware-Quellen übernommen und gegen ein echtes Board validiert
+(Read → unpack → pack ist bytegenau identisch zum Original, inklusive
+CRC) — siehe `versapad_protocol.py` und die „Existing-Codebase-Regel“ in
+[`AGENTS.md`](../AGENTS.md), bevor hier etwas geändert wird.
+
+## Geometrie
+
+```
+index = spalte * 5 + reihe
+```
+
+4 Spalten (`GRID_COLS`), 5 Reihen (`GRID_ROWS`), Reihe 0 = oben, Reihe 4 =
+unten. Firmware-Reihenfolge, nicht neu herleiten. Damit ergeben sich die
+20 Button-Indizes so auf dem physischen Grid:
+
+| | Spalte 0 | Spalte 1 | Spalte 2 | Spalte 3 |
+|---|---|---|---|---|
+| Reihe 0 (oben) | 0 | 5 | 10 | 15 |
+| Reihe 1 | 1 | 6 | 11 | 16 |
+| Reihe 2 | 2 | 7 | 12 | 17 |
+| Reihe 3 | 3 | 8 | 13 | 18 |
+| Reihe 4 (unten) | 4 | 9 | 14 | 19 |
+
+## Action
+
+Eine `Action` beschreibt, was ein Button oder eine Encoder-Bewegung
+auslöst. Sowohl in JSON als auch binär ein `{type, data}`-Paar
+(binär: `SAction`, 3 Byte — 1 Byte Typ + 2 Byte `data`, little-endian).
+
+| `type` | Enum-Index | `data`-Bedeutung |
+|---|---|---|
+| `None` | 0 | ungenutzt (0) |
+| `HidKey` | 1 | `data = keycode \| (modifier << 8)` — Keycode HID Usage Page 0x07 im unteren Byte, Modifier-Bitmaske im oberen Byte |
+| `HidConsumer` | 2 | `data` = HID-Consumer-Usage-ID (Usage Page 0x0C), z.B. `0x00CD` = Play/Pause |
+| `HostCommand` | 3 | Enum-Wert existiert in der Firmware, wird von diesem Tool aktuell nicht gesetzt/editiert (kein `set_button_hostcommand`-Äquivalent) |
+| `Macro` | 4 | `data` = Makro-Slot-Index (0-31) |
+| `ProfileSwitch` | 5 | `data` = Ziel-Profil (0/1/2) oder `0xFFFF`/`0x00FF` = „nächstes Profil“ (Zyklus) |
+
+Modifier-Bitmaske (für `HidKey`, gilt **nicht** 1:1 für Makro-Schritte,
+siehe unten):
+
+| Bit | Modifier |
+|---|---|
+| `0x01` | Strg |
+| `0x02` | Shift |
+| `0x04` | Alt |
+| `0x08` | Win |
+
+## LED
+
+Pro MX-Button (nicht pro Encoder — Encoder haben keine eigene LED):
+
+| Feld | Typ | Bedeutung |
+|---|---|---|
+| `r`, `g`, `b` | uint8 (0-255) | Farbe |
+| `brightness` | uint8 (0-255) | Helligkeit |
+| `anim` | Enum-String (JSON) / Enum-Index (binär) | `Static`, `Blink`, `Pulse`, `FadeIn`, `FadeOut`, `ColorCycle`, `ColorFade` |
+| `period_ms` | uint16 (little-endian) | Animationsperiode in ms (Pulse braucht `>= 2`) |
+
+## Makro-Schritt
+
+Ein Makro-Schritt ist **kein** `Action` — Keycode und Modifier stehen in
+zwei getrennten Bytes (nicht in einem gepackten 16-Bit-`data`-Feld wie bei
+`HidKey`):
+
+| Feld | Typ | Bedeutung |
+|---|---|---|
+| `keycode` | uint8 | HID-Keycode. `0` beendet die Sequenz (Firmware-Konvention — keine Lücken vor dem letzten belegten Schritt lassen) |
+| `modifier` | uint8 | Bitmaske, aber **nur Strg/Shift/Alt** (kein Win — passend zu `ActionDialog.cs` im Original) |
+
+Eine Makro-Tabelle hat 32 Slots (`MACRO_SLOTS`) mit je bis zu 8 Schritten
+(`MACRO_MAX_STEPS`). Sie ist **eine einzige globale Tabelle**, nicht pro
+Profil — zwei Profile, die per `Macro`-Action denselben Slot referenzieren,
+spielen dieselben Schritte ab. Konvention für die Slot-Zuordnung (von den
+Tools/der GUI benutzt, nicht von der Firmware erzwungen):
+
+- Slot `0`–`19` = MX-Button-Index (Button `i` → Slot `i`)
+- Slot `20`–`31` = `20 + enc*3 + act_idx` (Encoder `enc`, `act_idx`:
+  0=Druck/`sw`, 1=`cw`, 2=`ccw`)
+
+## JSON: kombiniertes Format (`versapad_config_all.json`)
+
+Das von diesem Tool selbst gepflegte Format (`versapad_combined.py`) — alle
+3 Profile + Makro-Tabelle + lokale Profilnamen in einer Datei. Passt zum
+Wire-Protokoll: `CONFIG_BEGIN/COMMIT` überträgt ohnehin immer den
+kompletten 740B-Block, nie nur ein Profil.
+
+```jsonc
+{
+  "active_profile": 0,
+  "global_brightness": 255,
+  "enc_sensitivity": [1, 1, 1, 1],
+  "profile_names": ["Windows", "Fusion 360", "BricsCAD"],
+  "profiles": [
+    {
+      "buttons": [
+        {
+          "index": 0,
+          "action": { "type": "HidKey", "data": 30 },
+          "led": { "r": 80, "g": 40, "b": 0, "brightness": 255,
+                    "anim": "Static", "period_ms": 4000 }
+        }
+        // ... 20 Buttons (index 0-19)
+      ],
+      "encoders": [
+        {
+          "index": 0,
+          "sw": { "type": "ProfileSwitch", "data": 65535 },
+          "cw": { "type": "None", "data": 0 },
+          "ccw": { "type": "None", "data": 0 }
+        }
+        // ... 4 Encoder (index 0-3)
+      ]
+    }
+    // ... 3 Profile
+  ],
+  "macros": [
+    [{ "keycode": 30, "modifier": 0 }, { "keycode": 39, "modifier": 0 }]
+    // ... 32 Slots, jeweils eine Liste mit 0-8 Schritten
+  ]
+}
+```
+
+Profilnamen (`profile_names`) sind **rein lokal** — die Firmware-Structs
+haben keinen Platz für einen String (Header exakt 32B, jedes Profil exakt
+236B, alles verplant), sie landen nie aufs Board, egal welcher
+Schreibpfad benutzt wird.
+
+## JSON: Legacy-Einzeldatei-Format (`versapad_config1/2/3.json`)
+
+Kein von diesem Tool geschriebenes Format — optionaler Export der
+offiziellen VersaGUI, gelesen von `versapad_data.load_profile()`. Enthält
+nur ein einzelnes Profil, keine Makro-Schritte, keinen Profilnamen:
+
+```jsonc
+{
+  "buttons": [ /* wie oben, 20 Eintraege */ ],
+  "encoders": [ /* wie oben, 4 Eintraege */ ]
+}
+```
+
+## MCP-Tool-Grenzfläche (`set_macro`, `set_button_key`, …)
+
+Die MCP-Tools nehmen **menschenlesbare** Namen entgegen, keine Rohwerte —
+`versapad_data.py` übersetzt:
+
+```jsonc
+// set_button_key(profile=0, index=0, key="S", modifiers=["Strg"])
+// set_macro(slot=7, steps=[{"key": "1", "modifiers": []}, {"key": "0", "modifiers": []}])
+```
+
+`hid_key_code_for_name()` / `consumer_id_for_name()` / `modifier_bits_for_names()`
+übersetzen Namen → Rohwerte (werfen `ValueError` mit einer Liste gültiger
+Namen bei Tippfehlern). Zeichentasten-Labels sind eine US-Layout-Näherung
+(keine `GetKeyNameText()`-Auflösung wie im C#-Original).
+
+## Binäres NVM-Layout
+
+### `SDeviceConfig` (740 Byte, `versapad_protocol.CONFIG_SIZE`)
+
+| Offset | Größe | Feld |
+|---|---|---|
+| 0 | 4B (uint32 LE) | Magic (`0x56503203`, `NVM_CONFIG_MAGIC`) |
+| 4 | 1B | Version (`3`, `NVM_CONFIG_VERSION`) |
+| 5 | 2B (uint16 LE) | CRC16 über Byte 7-739 |
+| 7 | 1B | `active_profile` (0-2) |
+| 8 | 1B | `global_brightness` (0-255) |
+| 9 | 4B | `enc_sensitivity` (4× uint8, einer je Encoder) |
+| 13 | 19B | reserviert/ungenutzt (Padding) |
+| 32 | 236B | Profil 0 (`SDeviceProfile`) |
+| 268 | 236B | Profil 1 |
+| 504 | 236B | Profil 2 |
+
+### `SDeviceProfile` (236 Byte)
+
+| Offset (relativ) | Größe | Feld |
+|---|---|---|
+| 0 | 60B (20× 3B `SAction`) | MX-Button-Actions, Index 0-19 |
+| 60 | 36B (4× 3× 3B `SAction`) | Encoder-Actions: je Encoder `sw`, `cw`, `ccw` |
+| 96 | 20B | LED `r` je Button |
+| 116 | 20B | LED `g` je Button |
+| 136 | 20B | LED `b` je Button |
+| 156 | 20B | LED `brightness` je Button |
+| 176 | 20B | LED `anim` (Enum-Index) je Button |
+| 196 | 40B (20× uint16 LE) | LED `period_ms` je Button |
+
+Die LED-Felder liegen **spaltenweise** (struct-of-arrays: alle 20
+`r`-Werte, dann alle 20 `g`-Werte, …), nicht verschachtelt pro Button —
+`pack_profile()`/`unpack_profile()` bauen das entsprechend um.
+
+### `SMacroTable` (512 Byte, `versapad_protocol.MACRO_SIZE`)
+
+32 Slots × 8 Schritte × 2 Byte (`keycode`, `modifier`) = 512 Byte, flach
+hintereinander: `offset = (slot_idx * 8 + step_idx) * 2`.
+
+### CRC16
+
+`crc16()` in `versapad_protocol.py`: CRC-CCITT, Polynom `0x1021`, Init
+`0xFFFF`, MSB-first, kein XOR-Out — exakt `nvm_config_crc()` aus der
+Firmware (`nvm_config.cpp`). Wird über Byte 7-739 der Config berechnet
+(alles nach Magic/Version/CRC-Header selbst).
--- a/docs/protocol.md
+++ b/docs/protocol.md
@ -0,0 +1,136 @@
+# Serial-Wire-Protokoll
+
+Beschreibt, wie `versapad_serial.VersaPadLink` mit dem Board spricht. 1:1
+aus `VersaGUI/src/Protocol.cs` und `VersaMCU/doc/07_serial_protocol.md`
+übernommen (siehe „Existing-Codebase-Regel“ in
+[`AGENTS.md`](../AGENTS.md) — bei Änderungen gegen die Firmware-/
+C#-Quellen abgleichen, nicht aus dem Gedächtnis rekonstruieren). Für die
+Bedeutung der übertragenen Bytes (Config/Makro-Layout) siehe
+[`data-model.md`](data-model.md).
+
+## Transport
+
+- USB-CDC (virtueller COM-Port), 115200 Baud.
+- Board-Erkennung über USB VID:PID `239A:0042` (`versapad_serial.find_port()`
+  durchsucht `serial.tools.list_ports.comports()`).
+- Der Port ist **exklusiv** — siehe „Nebenläufigkeit“ in
+  [`architecture.md`](architecture.md).
+- Jedes Paket ist exakt **8 Byte**:
+
+  | Byte | Bedeutung |
+  |---|---|
+  | `[0]` | Command-/Event-ID |
+  | `[1]` | je nach Befehl: Chunk-Index, Chunk-Anzahl, oder ungenutzt |
+  | `[2..7]` | Payload, 6 Byte (`PAYLOAD_SIZE`) |
+
+## Befehle (Host → Board)
+
+| Konstante | Wert | Zweck |
+|---|---|---|
+| `CMD_READ_STATUS` | `0x06` | Leichtgewichtiger Status-Poll (aktives Profil) |
+| `CMD_CONFIG_BEGIN` | `0x10` | Start eines Config-Schreibvorgangs |
+| `CMD_CONFIG_DATA` | `0x11` | Ein Config-Datenpaket |
+| `CMD_CONFIG_COMMIT` | `0x12` | Config committen (NVM-Schreiben nach Validierung) |
+| `CMD_CONFIG_READ` | `0x13` | Komplette Config vom Board anfordern |
+| `CMD_MACRO_BEGIN` | `0x20` | Start eines Makro-Schreibvorgangs |
+| `CMD_MACRO_DATA` | `0x21` | Ein Makro-Datenpaket |
+| `CMD_MACRO_COMMIT` | `0x22` | Makros committen |
+| `CMD_MACRO_READ` | `0x23` | Komplette Makro-Tabelle vom Board anfordern |
+
+## Events (Board → Host)
+
+| Konstante | Wert | Zweck |
+|---|---|---|
+| `EVT_STATUS` | `0x86` | Antwort auf `CMD_READ_STATUS` |
+| `EVT_CONFIG_ACK` | `0x90` | Config-Commit erfolgreich |
+| `EVT_CONFIG_NACK` | `0x91` | Config-Commit abgelehnt (Validierung fehlgeschlagen) |
+| `EVT_CONFIG_BEGIN` | `0x92` | Board beginnt, Config-Dump zu senden |
+| `EVT_CONFIG_DATA` | `0x93` | Ein Config-Datenpaket (Antwort auf `CMD_CONFIG_READ`) |
+| `EVT_CONFIG_END` | `0x94` | Config-Dump vollständig |
+| `EVT_MACRO_ACK` | `0x95` | Makro-Commit erfolgreich |
+| `EVT_MACRO_BEGIN` | `0x96` | Board beginnt, Makro-Dump zu senden |
+| `EVT_MACRO_DATA` | `0x97` | Ein Makro-Datenpaket |
+| `EVT_MACRO_END` | `0x98` | Makro-Dump vollständig |
+| `EVT_MACRO_NACK` | `0x99` | Makro-Commit abgelehnt |
+
+## Ablauf: Lesen (`CONFIG_READ` / `MACRO_READ`)
+
+Genutzt von `read_full_config()` (740B, ⌈740/6⌉ = 124 Datenpakete) und
+`read_macros()` (512B, ⌈512/6⌉ = 86 Datenpakete). Deadline 3s.
+
+```
+Host  → [CMD_CONFIG_READ, 0, 0,0,0,0,0,0]
+Board → [EVT_CONFIG_BEGIN, ...]
+Board → [EVT_CONFIG_DATA, chunk_idx=0, <=6B Payload]
+Board → [EVT_CONFIG_DATA, chunk_idx=1, <=6B Payload]
+        ... (124 Pakete insgesamt für Config, 86 für Makros)
+Board → [EVT_CONFIG_END, ...]
+```
+
+`chunk_idx` (Byte `[1]`) bestimmt den Ziel-Offset im Empfangspuffer:
+`offset = chunk_idx * 6`. Kommt `EVT_END`, ohne dass zuvor `EVT_BEGIN`
+gesehen wurde, gilt das als Timeout (unvollständige/verpasste Antwort).
+
+## Ablauf: Schreiben (`CONFIG_BEGIN/DATA/COMMIT` bzw. `MACRO_*`)
+
+Genutzt von `write_full_config()`/`write_macros()`. Deadline 5s. Anzahl
+Chunks maximal 255 (ein Byte) — bei größeren Blobs schlägt der Aufruf mit
+`"too_large"` fehl, bevor überhaupt gesendet wird.
+
+```
+Host  → [CMD_CONFIG_BEGIN, chunk_count, 0,0,0,0,0,0]
+Host  → [CMD_CONFIG_DATA, 0, <=6B Payload (zero-padded)]
+Host  → [CMD_CONFIG_DATA, 1, <=6B Payload]
+        ... (ein Paket je Chunk)
+Host  → [CMD_CONFIG_COMMIT, 0, 0,0,0,0,0,0]
+Board → [EVT_CONFIG_ACK, ...]   -- oder EVT_CONFIG_NACK bei fehlgeschlagener Validierung
+```
+
+**Sicherheitsnetz:** Die Firmware prüft Magic/Version/CRC (Config) bzw.
+Keycode-Bereich (Makros) **vor** jedem NVM-Schreiben und antwortet sonst
+nur mit NACK — ein fehlerhafter Schreibversuch kann das Board laut
+Firmware-Design nicht in einen inkonsistenten Zustand bringen, siehe
+`nvm_config_validate()` in den Firmware-Quellen.
+
+## Ablauf: Leichtgewichtiger Status-Poll (`READ_STATUS`)
+
+Genutzt von `read_active_profile()` für kontinuierliches Live-Sync-Polling
+(alle 1,5s). Deadline 1s.
+
+```
+Host  → [CMD_READ_STATUS, 0, 0,0,0,0,0,0]
+Board → [EVT_STATUS, active_profile (0-2), ...]
+```
+
+Ein einzelnes Antwortpaket statt eines vollen `CONFIG_READ`-Dumps (124
+Pakete) — Letzterer blockiert die Firmware in `poll_vendor()` lang genug,
+dass laufende LED-Pulse-Animationen sichtbar stottern. Ältere Firmware
+ohne `CMD_READ_STATUS` antwortet einfach gar nicht → sauberer Timeout,
+kein Absturz (siehe `AGENTS.md`, Eintrag „4215323“ in der Historie).
+
+## Verbindungsaufbau (`VersaPadLink._ensure_open()`)
+
+1. Board per VID/PID finden (`find_port()`).
+2. `serial.Serial(port, 115200, timeout=0.5)` öffnen.
+3. DTR auf `True` setzen, 0,2s warten (Board braucht kurz, bis es nach dem
+   Öffnen/DTR-Toggle wieder reagiert).
+4. Input-Buffer leeren.
+
+**Wichtig:** `VersaPadLink` schließt die Verbindung nicht automatisch nach
+einem Befehl — nur bei `serial.SerialException` (Fehlerfall) oder
+explizitem `.close()`-Aufruf. Aufrufer, die den exklusiven Port nicht
+dauerhaft blockieren wollen, müssen selbst schließen (siehe
+`versapad_mcp_server.py`, das nach jedem Board-Tool-Aufruf `_link.close()`
+in einem `finally`-Block aufruft).
+
+## Fehlerzustände (`VersaPadLink.last_error`)
+
+| Wert | Bedeutung |
+|---|---|
+| `None` | kein Fehler |
+| `"no_pyserial"` | Paket `pyserial` nicht installiert |
+| `"not_found"` | kein Gerät mit passender VID/PID gefunden |
+| `"busy"` | Port gefunden, aber Öffnen fehlgeschlagen (von woanders gehalten — VersaGUI, Live-Sync, ein anderer Prozess) |
+| `"timeout"` | keine (gültige) Antwort innerhalb der Deadline |
+| `"nack"` | Board hat den Commit explizit abgelehnt (Validierung fehlgeschlagen) |
+| `"too_large"` | zu sendender Blob braucht mehr als 255 Chunks |