VersaGUI-py/AGENTS.md

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).

MCP-Server (Config per KI-Tool-Aufruf statt Hand-JSON):

• versapad_mcp_server.py — registriert als User-Scope-MCP-Server "versapad" (claude mcp add -s user versapad -- <Python313> versapad_mcp_server.py, landet in ~/.claude.json). Tools: list_profiles/get_profile/ get_macro/get_board_status (lesen), set_button_key/_consumer/ _macro/_profile_switch/_none/_led, dieselben set_encoder_*, set_macro, rename_profile (mutieren nur In-Memory-State), save_local/ load_local (↔ versapad_config_all.json), load_from_board/ write_to_board (↔ echtes Board per Serial). Nutzt das MCP-SDK v2 (Paket mcp, Klasse mcp.server.mcpserver.MCPServer — nicht FastMCP aus mcp.server.fastmcp, das gibt's in dieser SDK-Version nicht mehr, wurde umbenannt). @mcp.tool()-dekorierte Funktionen bleiben direkt aufrufbar (kein .fn-Unterschied wie bei alten FastMCP-Versionen).

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.

Gepackte .exe (PyInstaller) — kein Terminal-Flash, kein Python-Setup nötig

build_and_deploy.ps1 kopiert den Quellcode zuerst nach %TEMP%, baut dort mit PyInstaller (--windowed --onedir --icon icon.ico), und kopiert das Ergebnis nach %LOCALAPPDATA%\VersaPadViewer\VersaPadViewer.exe. Desktop-Verknüpfung "VersaPad Viewer (Fenster)" zeigt dorthin (inkl. eigenem Icon, IconLocation zeigt auf die .exe selbst statt auf pythonw.exe).

--onedir, nicht --onefile — Single-File-PyInstaller-Bundles lösen öfter AV-Fehlalarme aus (sehen strukturell wie ein Packer aus); --onedir (Ordner mit .exe + _internal) ist unauffälliger. Trotzdem unsigniert, also grundsätzlich nie über Smart App Control/AV in Stein gemeißelt sicher.

Zwei Netzlaufwerk-Stolpersteine, deshalb baut UND deployt alles lokal:

1. Laufzeit: die gebaute .exe läuft NICHT vom Netzlaufwerk aus (Z:\Git\..., SMB-Share auf cj-ki) — Windows blockiert das Nachladen der _internal-DLLs von einem Netzwerkpfad, der Prozess startet dann einfach nie, ganz ohne Fehlermeldung/Crash-Log/AV-Benachrichtigung (sah zuerst wie ein AV-Block aus, war aber keiner — verifiziert indem dieselbe .exe 1:1 lokal kopiert sofort lief).
2. Buildzeit: PyInstaller scheitert beim Kopieren der Tcl/Tk-tzdata (viele tief verschachtelte, lang benannte Zeitzonen-Ordner) auf dem SMB-Share mit FileNotFoundError: [WinError 3] — Pfadlängen-Problem, kombiniert mit dem eh schon langen Projektpfad (Z:\Git\Versa Board\ versapad-viewer\dist\...).

Deshalb kopiert build_and_deploy.ps1 den Quellcode zuerst nach %TEMP% und baut NUR dort — Z: wird nur zum Lesen der .py-Dateien angefasst.

Bei erneutem Bauen: .\build_and_deploy.ps1 in PowerShell ausführen (lokal, nicht über die sandboxed Bash-Tool-Umgebung — die hat eine eigene Dateisystem-Sicht, die nicht zuverlässig mit dem echten Windows-Dateisystem übereinstimmt; siehe Sessionlog: ein cp -r über Bash landete an einem Ort, den PowerShell/der reale Explorer nicht sah. Kopieroperationen für Dinge, die der User/andere Prozesse sehen sollen, gehören in PowerShell, nicht in Bash).

Icon + Tray (kein Taskleisten-Eintrag beim Minimieren, wie VersaGUI)

• icon.png/icon.ico — generiert via Pillow (dunkles abgerundetes Quadrat, blauer Block, 2x2-Punktraster; flaches Design, keine Farbverläufe/ Anti-Aliasing-Details, siehe Speicher-Notiz zu Tkinter-Flat-Design). .ico fürs Fenster-/Taskleisten-/Exe-Icon, .png fürs Tray-Icon (pystray braucht ein PIL-Image, kein Multi-Res-.ico).
• resource_path() in desktop_viewer.py findet Assets sowohl im Quellordner als auch im PyInstaller-Bundle (sys._MEIPASS).
• Minimieren (<Unmap> mit state()=='iconic') ruft withdraw() statt normal zu minimieren → kein Taskleisten-Eintrag, nur noch Tray-Icon. Schließen (X) macht dasselbe (_hide_to_tray, nicht _quit) — echtes Beenden nur über "Beenden" im Tray-Rechtsklickmenü (mirrort VersaGUIs TrayApp-Menü: Öffnen/Beenden). Tray-Icon läuft über pystray.Icon. run_detached() in eigenem Thread — Klicks im Tray-Menü legen nur ein Ereignis in self._tray_queue, das der Main-Thread per after()-Polling abholt (dieselbe Queue-statt-Direktzugriff-Regel wie beim Serial-Thread, siehe oben — Tk-Aufrufe aus einem Fremdthread haben schon mal einen stillen Absturz verursacht).
• Neue Abhängigkeiten: pystray, pillow (zusätzlich zu pyserial).
• Info-Button (ⓘ oben rechts im Header) öffnet einen Dialog mit der MCP-Server-Doku (MCP_INFO_TEXT-Konstante) — rein informativ, keine Logik.

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.