Initial commit: VersaPad viewer + programming mode

AGENTS.md

@@ -0,0 +1,127 @@
+# versapad-viewer
+
+Eigenes kleines Tool (Grovy311-Kontext, nicht Teil der fremden jappel-Repos
+VersaGUI/VersaMCU). Zeigt die Steuermatrix (4x5 Button-Grid + 4 Encoder) als
+Browser-Live-Seite oder natives Tkinter-Fenster. Inzwischen mehr als ein
+reiner Viewer: der Tkinter-Desktop-Viewer hat einen vollen Programmiermodus
+(Action-Editor, Serial-Schreibzugriff aufs Board, Makro-Editor) bekommen —
+faktisch ein schlankes Python-Pendant zu VersaGUI. Der Browser-Server
+(`server.py`) blieb bewusst read-only/einfach.
+
+## Architektur
+
+**Read-only-Schicht (JSON, beide Frontends):**
+- `versapad_data.py` — Decoding fuer Anzeige: JSON laden, HID-Keycode/
+  Consumer-Usage/Modifier → lesbarer Text, Grid-Geometrie (index =
+  spalte*5+reihe), `hid_key_choices()`/`consumer_choices()` fuer Dropdowns.
+- `server.py` — stdlib `http.server`, generiert HTML bei jedem Request neu,
+  Profil-Wechsel über `?profile=0|1|2`, Auto-Reload alle 4s. Rein lesend,
+  kein Programmiermodus (bewusst einfach gehalten).
+
+**Binaer-/Serial-Schicht (fuer den Programmiermodus):**
+- `versapad_protocol.py` — pack/unpack fuer `SDeviceConfig`(740B, alle 3
+  Profile) und `SMacroTable`(512B, 32 Slots) + CRC16 (Poly 0x1021, Init
+  0xFFFF), 1:1 aus den Firmware-Structs (`nvm_config.h`, `action.h`,
+  `macro_config.h`, `CButton.h`-LEDAnim-Enum, `nvm_config.cpp`-CRC).
+  **Gegen echtes Board validiert:** read → unpack → pack → byte-identisch
+  zum Original, inkl. CRC — siehe Git-Historie dieser Datei / Sessionlog.
+- `versapad_serial.py` — `VersaPadLink`: liest/schreibt komplette Config +
+  Makros per 8-Byte-Paket-Protokoll (`CmdConfigRead/Begin/Data/Commit`,
+  `CmdMacroRead/Begin/Data/Commit`), Board-Identifikation per VID/PID
+  `239A:0042`. Schreiben ist sicher im Sinne von "kann NVM nicht zerlegen"
+  — Firmware prueft Magic/CRC/Keycode-Bereich vor jedem Save und antwortet
+  sonst nur mit NACK (kein Datenmuell moeglich).
+- `versapad_combined.py` — kombiniertes Ein-Datei-Format (alle 3 Profile +
+  Makros + **nur lokal gespeicherte** Profilnamen) statt der 3 Einzel-JSONs.
+  Passt besser zum Wire-Protokoll: `CONFIG_BEGIN/COMMIT` ueberträgt ohnehin
+  immer den kompletten 740B-Block auf einmal, nie nur ein Profil.
+  Default-Pfad: `~\OneDrive\Desktop\versapad_config_all.json`.
+
+**UI:**
+- `desktop_viewer.py` — Tkinter, flaches Design (Label-Flächen, keine
+  Canvas-Formen/Anti-Aliasing). Zellen nutzen `.place()` mit festen
+  Pixel-Positionen statt `.pack()` (mit pack sah das Grid je nach leerer/
+  belegter Zelle ungleichmäßig aus). Drei unabhängige Modi:
+  - **Nur lesen** (Default): pollt die 3 JSONs alle 1.5s.
+  - **Live-Sync**: pollt per Serial das aktive Profil vom Board, schaltet
+    Tabs automatisch mit. Laeuft in einem Hintergrundthread, der NUR ueber
+    eine `queue.Queue` mit dem Main-Thread kommuniziert (`self.after()`
+    direkt aus einem Fremdthread aufrufen ist in Tkinter nicht threadsicher
+    und hat den Prozess in einer frueheren Version lautlos abstuerzen
+    lassen — `pyw` hat kein Konsolenfenster, der Crash war unsichtbar).
+  - **Programmiermodus**: Zellen anklicken → `action_dialog.py`
+    (`ActionEditDialog`/`MacroStepsDialog`) bearbeitet Action-Typ, HID-Taste
+    (Dropdown statt Tastendruck-Capture — kein WinAPI-Hook, um nicht wieder
+    einen AV-Fehlalarm wie bei den Fensterverstecktricks zu riskieren),
+    Consumer, Makro-Slot+Schritte, ProfileSwitch, LED-Farbe/Animation.
+    "Vom Board laden"/"Zum Board übertragen" nutzen die Binaer-Schicht.
+    Schaltet Live-Sync automatisch aus (ein `VersaPadLink` kann nicht von
+    zwei Konsumenten gleichzeitig genutzt werden).
+- `action_dialog.py` — die beiden Bearbeiten-Dialoge, importiert nur
+  `versapad_data` (fuer Dropdown-Inhalte).
+
+## Quelle der Wahrheit — nicht raten
+
+Bei Aenderungen am Schema/Decoding/Binaerformat immer gegen die Firmware-
+und GUI-Quellen abgleichen, nie aus dem Gedaechtnis rekonstruieren:
+- `VersaGUI/src/ActionDialog.cs` (HidKeyName, s_consumer, Modifier-Bits)
+- `VersaGUI/src/Protocol.cs` (Paket-IDs, Chunk-Groessen)
+- `VersaMCU/src/config/nvm_config.h` + `.cpp` (SDeviceConfig-Layout, CRC)
+- `VersaMCU/src/config/action.h` (SAction, ActionType-Enum-Werte)
+- `VersaMCU/src/config/macro_config.h` + `.cpp` (SMacroTable-Layout)
+- `VersaMCU/src/CButton.h` (LEDAnim-Enum-Werte)
+- `VersaMCU/src/CMainController.cpp` (welche Commands die Firmware
+  tatsaechlich behandelt — Protocol.cs definiert mehr Konstanten als die
+  Firmware zwingend implementiert, immer hier gegenchecken)
+
+Zeichentasten (A-Z, Ziffern, Satzzeichen) zeigen US-Layout-Näherung, da die
+echte GUI das über `GetKeyNameText()` layoutabhängig auflöst — das bilden
+wir ohne WinAPI-Call nicht nach.
+
+**Korrektur einer frueheren Annahme:** Anders als zuerst notiert, kann die
+Firmware Makros sehr wohl per normaler USB-Verbindung schreiben
+(`USB_CMD_MACRO_BEGIN/DATA/COMMIT` in `CMainController.cpp` sind
+implementiert) — kein SWD/JTAG noetig. Der VersaPad-Skill
+(`~/.claude/skills/versapad/SKILL.md`) behauptet noch das Gegenteil und
+sollte bei Gelegenheit korrigiert werden.
+
+## Start
+
+```
+py server.py            # Browser, http://127.0.0.1:8765
+pyw desktop_viewer.py    # natives Fenster, kein Konsolenfenster
+```
+Oder `run_browser.bat` / `run_desktop.bat` per Doppelklick, oder die
+Desktop-Verknuepfungen "VersaPad Viewer (Browser)" / "VersaPad Viewer
+(Fenster)".
+
+**Wichtig:** `pyw`/`py` benutzen, nicht bare `pythonw`/`python` — auf hal9001
+liegt in PATH zuerst eine Hermes-Agent-venv (`...\hermes\hermes-agent\venv\
+Scripts\pythonw.exe`) ohne pyserial. `pyw`/`py` (Python Launcher) lösen
+zuverlässig zur echten Python313-Installation auf.
+
+## Dateien/Pfade (hardcoded, hal9001-spezifisch)
+
+- Einzel-JSONs (Read-only-Modus): `~\OneDrive\Desktop\versapad_config{1,2,3}.json`
+  — Profil 0 Windows / 1 Fusion 360 / 2 BricsCAD, siehe `versapad_data.CONFIG_PATHS`.
+- Kombinierte Datei (Programmiermodus-Export): `~\OneDrive\Desktop\
+versapad_config_all.json` (Default, siehe `versapad_combined.DEFAULT_PATH`).
+
+## Offene Punkte
+
+- Kein automatischer Windows-Start/Tray-Icon — bewusst einfach gehalten,
+  bei Bedarf nachrüstbar.
+- Live-Sync und VersaGUI (bzw. Programmiermodus) können den COM-Port nicht
+  gleichzeitig halten (exklusiver Zugriff) — zeigt dann "Port belegt", kein
+  Crash. VersaGUI läuft als Tray-App dauerhaft im Hintergrund weiter, auch
+  wenn nur das Konfigurationsfenster geschlossen wird — für Programmiermodus/
+  Live-Sync muss es über das Tray-Icon → "Beenden" wirklich beendet werden.
+  Live-Sync wird beim Aktivieren des Programmiermodus automatisch ausgeschaltet.
+  Innerhalb des Programmiermodus selbst laufen "Vom Board laden"/"Zum Board
+  übertragen" synchron im UI-Thread (kurzzeitiges Einfrieren möglich, v.a.
+  bei Timeout) — bislang nicht als Hintergrund-Thread ausgelagert.
+  Der Browser-Server (`server.py`) hat keinen Programmiermodus.
+- HID-Tasten-Auswahl im Programmiermodus ist ein Dropdown, kein
+  Tastendruck-Capture (bewusst, um WinAPI-Hooks/AV-Fehlalarme zu vermeiden).
+- Macro-Editor erlaubt nur Strg/Shift/Alt pro Schritt (kein Win), passend
+  zum Original-`ActionDialog.cs`-Verhalten fuer Makro-Steps.