VersaGUI-py/AGENTS.md

AGENTS.md

Project Goal

Eigenständiges Begleit-Tool für das VersaPad-Makropad (Grovy311-Kontext, nicht Teil der fremden jappel-Repos VersaGUI/VersaMCU). Zeigt die Steuermatrix (4×5-Button-Grid + 4 Encoder) an, synchronisiert sie live mit dem Board und kann sie komplett neu programmieren — inzwischen ein schlankes Python-Pendant zur offiziellen VersaGUI (C#/.NET), plus ein MCP-Server, der dieselbe Programmierung per KI-Tool-Aufruf ermöglicht. Nutzerorientierte Einführung: README.md.

Aktuell unterstützte Architektur

Read-only-Schicht (JSON, beide Frontends):

• versapad_data.py — Decoding für Anzeige: JSON laden, HID-Keycode/ Consumer-Usage/Modifier → lesbarer Text, Grid-Geometrie (index = spalte*5+reihe), hid_key_choices()/consumer_choices(). Seit 2026-08-28 zusätzlich tk_event_to_hid() (Tk-Tastendruck → HID-Keycode+Modifier, siehe Tastendruck-Erkennung unten) und macro_slot_choices()/macro_slot_from_choice() für die Slot-Auswahl. action_label()/annotate_profile() nehmen die Makrotabelle optional entgegen und zeigen dann statt „Makro (Slot 7)" die echte Tastenfolge. app_dir() liefert das Verzeichnis für die eigene Config (versapad_combined.DEFAULT_PATH) — bei der .exe der Installations- ordner, sonst der Projektordner, siehe Installierbarkeit-Notiz unten. CONFIG_PATHS bleibt bewusst auf dem OneDrive-Desktop hartkodiert (Lese- Interop mit einem JSON-Export der offiziellen VersaGUI, kein von diesem Tool geschriebenes Format, siehe dort).
• server.py — stdlib http.server, generiert HTML pro Request neu, Profil-Wechsel über ?profile=0|1|2, Auto-Reload alle 4s. Rein lesend, kein Programmiermodus (bewusst einfach gehalten).

Binär-/Serial-Schicht (Programmiermodus + MCP):

• versapad_protocol.py — pack/unpack für SDeviceConfig (740B, alle 3 Profile) und SMacroTable (512B, 32 Slots) + CRC16 (Poly 0x1021, Init 0xFFFF), 1:1 aus den Firmware-Structs. Gegen echtes Board validiert: read → unpack → pack ist byte-identisch zum Original, inkl. CRC.

• versapad_serial.py — VersaPadLink: liest/schreibt komplette Config + Makros per 8-Byte-Paket-Protokoll, Board-Identifikation per VID/PID 239A:0042. Schreiben ist sicher im Sinne von "kann NVM nicht zerlegen" — Firmware prüft Magic/CRC/Keycode-Bereich vor jedem Save, antwortet sonst nur mit NACK. read_active_profile() (für Live-Sync-Polling) nutzt seit 2026-08-07 CMD_READ_STATUS/EVT_STATUS (0x06/0x86, ein 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 (Root Cause + Fix in VersaMCU-Commit "Add lightweight READ_STATUS command..."). Braucht entsprechend neue Firmware auf dem Board — mit altem versapad-Firmwarestand liefert READ_STATUS schlicht Timeout, kein Absturz.

• versapad_combined.py — Ein-Datei-Format (alle 3 Profile + Makros + nur lokal gespeicherte Profilnamen), Default-Pfad versapad_data.app_dir()\versapad_config_all.json (neben der Installation, nicht mehr hartkodiert auf einer bestimmten Maschine). Passt zum Wire-Protokoll: CONFIG_BEGIN/COMMIT überträgt ohnehin immer den kompletten 740B-Block. load_or_fetch() legt bei fehlender Datei automatisch eine neue an — erst Versuch per Serial vom Board, sonst als leere default_combined() (kein Board noetig fuer die Erstbenutzung). read_profile_names() liest nur die Namen (kein Board-Zugriff, fuer Tab-Beschriftungen im Nur-Lese-Modus, siehe Installierbarkeit-Notiz).

• versapad_keylayout.py (seit 2026-08-29) — passive Abfragen ans aktive Windows-Tastaturlayout: hid_for_vk() (Virtual-Key → Scan-Code → HID über MapVirtualKeyW) und key_name() (Beschriftung über GetKeyNameTextW). Optional: auf Nicht-Windows/ohne ctypes bleibt AVAILABLE False und versapad_data faellt auf seine US-Naeherung zurueck. Zur Abgrenzung gegen die WinAPI-Verbote siehe Domaenenregeln.

UI:

• desktop_viewer.py — Tkinter, flaches Design, drei unabhängige Modi (Nur lesen / Live-Sync / Programmiermodus, siehe Kritische Domänenregeln), Tray-Icon statt Taskleisten-Minimierung, Info-Button mit MCP-Doku.
• action_dialog.py — Bearbeiten-Dialoge (ActionEditDialog, MacroStepsDialog) für den Programmiermodus. Gemeinsame Basis _ModalDialog (Positionierung über dem Elternfenster, Enter/Escape, Verteilung der Tastenevents) und _KeyCapture (Tastendruck-Erkennung).

MCP-Server:

• versapad_mcp_server.py — registriert als projektgebundener MCP-Server "versapad" über .mcp.json im Projektordner (Alternative: claude mcp add -s user versapad -- <python> versapad_mcp_server.py). Nutzt MCP-SDK v2 (Paket mcp, Klasse mcp.server.mcpserver.MCPServer — nicht FastMCP aus mcp.server.fastmcp, das existiert in dieser SDK-Version nicht mehr, wurde umbenannt). @mcp.tool()-dekorierte Funktionen bleiben direkt aufrufbar (kein .fn-Unterschied wie bei älteren FastMCP-Versionen). Tool-Liste: siehe README oder MCP_INFO_TEXT in desktop_viewer.py.
• Board-Serial-Tools schliessen den Link nach jedem Aufruf (get_board_status, load_from_board, write_to_board — finally: _link.close()). Grund: VersaPadLink schliesst nie von selbst, ein einzelner Aufruf hätte sonst den exklusiven COM-Port dauerhaft für den Rest des MCP-Serverprozesses blockiert und Live-Sync/VersaGUI/den nächsten Aufruf mit "busy" ausgesperrt (am 2026-08-14 live so aufgetreten, siehe unten).
• Bug beobachtet 2026-08-14: In diesem Agenten-Environment (Claude-Code- VSCode-Extension) können mehrere unabhängige versapad_mcp_server.py- Prozesse gleichzeitig laufen (bis zu 8 beobachtet, vermutlich durch wiederholte Tool-Ladevorgänge/Reconnects innerhalb einer Session) — jeder mit eigenem, nicht geteiltem In-Memory-State (_state["combined"]). Konkret beobachtet: set_button_*/set_macro + save_local() liefen korrekt auf einem Prozess, ein späterer write_to_board()-Aufruf landete aber auf einem anderen (frischen, leeren) Prozess und schrieb versehentlich eine leere Default-Config aufs Board, trotz {"ok": true}-Antwort. Fix: vor write_to_board() immer erst load_local() (liest die Datei frisch von der Platte, unabhängig davon welcher Prozess antwortet), und nach jedem Schreibvorgang mit load_from_board() + get_profile() gegenlesen statt dem ACK allein zu vertrauen — genau dieses Verify-Pattern hat den Fehler hier live aufgedeckt.

Vollständige Modulübersicht mit Zeilenreferenzen bei Bedarf direkt im Code nachschlagen. Menschenlesbare Referenzdoku (Architektur, Datenmodell, Protokoll) liegt in docs/, siehe „Dokumentation und Verifikation" unten.

Kritische Domänenregeln

• Geometrie: index = spalte*5 + reihe, Reihe 0 = oben, Reihe 4 = unten (Firmware-Reihenfolge). Nicht raten, nicht neu herleiten.
• Encoder 0 sw ist auf allen 3 Profilen der Profilwechsel — nicht ohne Rücksprache mit dem User ändern.
• Makros sind eine EINE globale 32-Slot-Tabelle, nicht pro Profil. Slot 0-19 = MX-Button-Index, Slot 20-31 = 20 + enc*3 + act_idx. Zwei Profile, die denselben Slot referenzieren, spielen dieselben Schritte ab.
• Ein Makro-Schritt mit keycode=0 beendet die Sequenz (Firmware-Konvention) — keine Lücken vor dem letzten belegten Schritt lassen.
• Makro-Schritte erlauben nur Strg/Shift/Alt als Modifier, kein Win (passend zum Original-ActionDialog.cs-Verhalten).
• Profilnamen leben NUR lokal in versapad_config_all.json (profile_names) — 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.
• Notizen (freier Text je Button/Encoder-Aktion, seit 2026-08-15) sind aus demselben Grund rein lokal: leben im "note"-Feld JEDER Action ({"type","data","note"}), nicht in einer separaten Struktur. to_binary/ pack_config ignorieren das Feld beim Schreiben (liest nur type/data), from_binary liefert frisch vom Board immer note="" (Board kennt keine Notizen) — versapad_combined.merge_notes(neu, alt) kopiert bestehende Notizen nach jedem load_from_board()/fetch_from_board() zurück, sonst gingen sie bei jedem Board-Refresh verloren. Action-Typ wechseln (set_button_key etc.) darf die Notiz NICHT loeschen (baut die neue Action ueber _replace_action()/dlg.action["note"] mit der alten Notiz), nur set_button_note()/set_encoder_note()/das Notiz-Feld im Programmiermodus-Dialog aendern sie gezielt.
• Der COM-Port ist exklusiv. Live-Sync und Programmiermodus schalten sich gegenseitig aus (ein VersaPadLink kann nicht von zwei Konsumenten gleichzeitig genutzt werden); VersaGUI läuft als Tray-App dauerhaft im Hintergrund weiter, auch wenn nur ihr Konfigurationsfenster geschlossen wird — für Parallelbetrieb mit diesem Tool muss sie über ihr eigenes Tray-Menü ("Beenden") wirklich beendet werden.
• Programmiermodus-Änderungen werden bei jeder Bearbeitung automatisch in versapad_config_all.json gespeichert (nicht erst bei explizitem "Datei speichern"). Der Nur-Lese-Modus bevorzugt dieselbe Datei, falls vorhanden, und fällt sonst auf die klassischen versapad_config{1,2,3}.json zurück — beide Ansichten müssen dieselbe Quelle zeigen, sonst wirkt eine Bearbeitung "verschwunden".
• Config-Pfad darf NIE im Installationsverzeichnis liegen (2026-08-15, Datenverlust-Bug): build_and_deploy.ps1 räumt sein Zielverzeichnis vor jedem Deploy komplett ab (Remove-Item $localDir -Recurse -Force). Nachdem app_dir() am selben Tag auf genau dieses Verzeichnis gezeigt hatte, hat jeder Rebuild die Nutzer-Config mitgelöscht; die App hat sie danach kommentarlos leer vom Board neu aufgebaut (load_or_fetch() → fetch_from_board()), wodurch alle Notizen weg waren. Besonders tückisch: Board-Bindings und LEDs sahen danach völlig normal aus, nur die rein lokalen Felder (Notizen, Profilnamen) fehlten -- der Schaden ist also unsichtbar, wenn man nur aufs Grid schaut. Fix: app_dir() liefert jetzt %APPDATA%\VersaPadViewer (Roaming), getrennt vom Installationsordner in %LOCALAPPDATA%; zusätzlich rettet build_and_deploy.ps1 vorgefundene versapad_config*.json aus dem Zielverzeichnis über den Deploy hinweg (für Altinstallationen). Regel für künftige Änderungen: Programm- und Datenverzeichnis nie zusammenlegen, egal wie praktisch "alles an einem Ort" klingt.
• Nur EIN Config-Pfad, unabhängig vom Startweg (2026-08-15): app_dir() hat bewusst KEINEN sys.frozen-Zweig mehr. Vorher sah die gebaute .exe eine andere Datei als der aus dem Quellcode gestartete MCP-Server, was zu zwei auseinanderlaufenden Configs führte (die .exe zeigte ein anderes Profil 0 als der MCP-Server meldete). Wer hier wieder nach Startweg unterscheidet, baut denselben Bug erneut ein.
• Installierbarkeit verbessert 2026-08-14: Drei Probleme beim Weitergeben an andere Leute behoben. (1) build_and_deploy.ps1 starb bei fehlenden Paketen (pyinstaller/pystray/pillow) kommentarlos, v.a. bei Doppelklick im Explorer, weil das Fenster sich sofort schließt. Fix: requirements.txt (alle Pakete an einer Stelle, README und Skript nutzen dieselbe Datei), Skript installiert sie selbst per pip install -r, läuft komplett in try/catch, prüft $LASTEXITCODE nach jedem nativen Aufruf, und pausiert am Ende (Erfolg wie Fehler) auf Tastendruck -- -NoPause für CI/Automation. (2) versapad_combined.DEFAULT_PATH war hartkodiert auf ~\OneDrive\Desktop einer bestimmten Maschine -- für andere Nutzer unbrauchbar. Fix: versapad_data.app_dir() (neue Funktion) liefert bei der gebauten .exe deren Installationsordner (sys.executable-Verzeichnis), sonst den Projektordner (__file__- Verzeichnis) -- DEFAULT_PATH hängt jetzt daran, landet also immer neben der laufenden Installation. Diese app_dir()-Variante ist seit 2026-08-15 überholt und war aktiv schädlich, siehe oben "Config-Pfad darf nie im Installationsverzeichnis liegen". versapad_data.CONFIG_PATHS (Lese-Interop mit der C#-VersaGUI) bleibt bewusst auf dem Desktop, siehe oben. (3) Fehlte die Config UND war kein Board erreichbar, blockierte das Tool mit einer Fehlermeldung statt zu starten. Fix: load_or_fetch() legt jetzt bei Board-Fehlschlag eine leere default_combined() an statt RuntimeError zu werfen -- Erstbenutzung ganz ohne vorhandene Config oder Board funktioniert jetzt. (4) Profilnamen waren zusätzlich hartkodiert in versapad_data.PROFILE_NAMES (Dict, jetzt entfernt, ersetzt durch NUM_PROFILES = 3) und liefen der JSON-profile_names parallel -- Programmiermodus zeigte umbenannte Profile, Lesemodus/Browser-Ansicht weiterhin die alten Namen. Fix: server.py und desktop_viewer.py lesen Namen jetzt immer aus der kombinierten JSON (combined["profile_names"] bzw. versapad_combined.read_profile_names()), eine einzige Quelle der Wahrheit für alle Frontends.
• Herkunft der drei Punkte oben + Tab-Umbenennen-Fix: ursprünglich per Cherry-Pick aus Julian Appels dev/jappel-Branch auf main übernommen (der sich zeitgleich mit dem eigenen COM-Port-Fix entwickelt hatte, kein Fork-Sync-Automatismus -- manuell gegengelesen). Auf main bewusst NICHT übernommen wurde damals der dist/VersaPadViewer-Build-Zielpfad (statt %LOCALAPPDATA%\VersaPadViewer) sowie .mcp.json und die docs/*.md- Referenzdateien. 2026-08-15: main wurde zurück in dev/jappel gemerged, damit landen beide Linien wieder in einem Branch -- inklusive .mcp.json, docs/*.md und dem %LOCALAPPDATA%-Zielpfad (der hat sich im Merge durchgesetzt, siehe Config-Pfad-Bullets oben). Der Notes-Feature- Teil dieser Historie ist der Grund, warum docs/data-model.md das "note"-Feld nachträglich braucht.
• Bug behoben 2026-08-08: server.py (vp.load_profile()) und desktop_viewer.py (_current_profile_view()) lasen im Nur-Lese-Modus hart von den Desktop-JSONs -- fehlten sie (z.B. User loescht sie), gab es eine ungefangene FileNotFoundError bzw. "Config-Datei fehlt"-Anzeige, obwohl das Board die Config laengst dauerhaft im NVM haelt. Fix: neue versapad_combined.fetch_from_board()/load_or_fetch() -- fehlt die Kombi-JSON, wird sie automatisch per Serial vom Board neu aufgebaut und als Cache gespeichert (self-healing), nur bei unerreichbarem Board (Port belegt/kein Board) bleibt der Fallback auf die alten Einzel-JSONs bzw. eine Klartext-Fehlermeldung. In desktop_viewer.py nur versucht, wenn Live-Sync aus ist (sonst haelt der Serial-Hintergrundthread den COM-Port -- zwei gleichzeitige Zugriffe auf denselben self.ser waeren eine Race Condition). Die Desktop-JSONs sind damit reiner Lesecache, kein Pflegeaufwand mehr fuers Board-Backup.
• Bug behoben 2026-08-07: _on_toggle_editing() initialisierte self.combined beim ersten Aktivieren des Programmiermodus mit vcomb.default_combined() — das seedet ALLE 3 Profile aus den alten Einzel-JSONs versapad_config{1,2,3}.json, nicht aus der aktuellen versapad_config_all.json oder vom Board. Ein Klick auf "Zum Board übertragen" hat dadurch beim Testen alle 3 Profile auf einen veralteten Stand zurückgesetzt, obwohl nur ein Profil-Tab sichtbar bearbeitet wurde — der Schaden an den anderen beiden Profilen blieb unbemerkt, bis explizit jedes Profil einzeln gegengelesen wurde. Fix: lädt jetzt zuerst vcomb.DEFAULT_PATH, fällt nur bei fehlender/kaputter Datei auf default_combined() zurück. Bei jedem "komisches Layout"-Report hier immer ALLE 3 Profile prüfen, nicht nur das gemeldete.
• WinAPI: was verboten bleibt und was nicht. Verboten sind Fenstermanipulation am eigenen Fenster (SetWindowLongW, ShowWindow) und globale Eingabehooks (SetWindowsHookEx) — genau diese Kombination hat laut Speicher-Notiz „keine Selbstversteck- Fenstertricks" in einem anderen Projekt Bitdefender-Fehlalarme ausgeloest. Erlaubt und seit 2026-08-29 in Benutzung sind passive Layout-Abfragen (MapVirtualKeyW, GetKeyNameTextW in versapad_keylayout.py): sie lesen nur die Tastaturbelegung, fassen weder Fenster noch Prozesse noch den Eingabestrom an; die offizielle VersaGUI (C#) benutzt GetKeyNameText() fuer denselben Zweck. Die Grenze verlaeuft also nicht bei „ctypes", sondern bei „greift ins System ein".
• Normales Fenster mit Titelleiste (seit 2026-08-29). Von 2026-08-15 bis dahin lief das Fenster randlos (overrideredirect(True)) — das kostet unter Windows zwingend den Taskleisten-Eintrag. Als der ausdruecklich gebraucht wurde, gab es nur drei Wege: Titelleiste zurueck, SetWindowLongW+WS_EX_APPWINDOW (siehe Verbot oben) oder ein unsichtbares Proxy-Fenster. Der User hat sich fuer die Titelleiste entschieden. Damit sind ersatzlos entfallen: ziehbare Kopfzeile (_start_move/_on_move), Groessen-Anfasser unten rechts (_start_resize/_on_resize, ersetzt durch self.minsize()), die eigenen ✕/—-Knoepfe und der <Unmap>-Handler, der Minimieren ins Tray umgeleitet hat. Wer das Fenster wieder randlos machen will, nimmt dem User den Taskleisten-Eintrag weg — nicht ohne Ruecksprache.
• Schliessen (✕) legt weiterhin ins Tray statt zu beenden (wie die offizielle VersaGUI, das Programm laeuft im Hintergrund weiter), Minimieren geht jetzt aber ganz normal in die Taskleiste. Escape minimiert ebenfalls, statt wie frueher ins Tray zu legen — mit Taskleisten-Eintrag waere „verschwindet spurlos" die unangenehmere Ueberraschung.
• Fensterhöhe muss zum Karteninhalt passen: seit die Karten eine Notizzeile haben (CARD_H 84 → 114) braucht das Fenster ~960px, sonst liegen Encoder-Bereich und Fußzeile unterhalb des Rands. Wer CARD_H ändert, muss geometry() mit anpassen.
• Dialogposition wird gegen das ELTERNFENSTER begrenzt, nie gegen winfo_screenwidth() (2026-08-29): Tk meldet dort nur den Hauptbildschirm. Die erste Fassung hat damit geklemmt — lag das Hauptfenster auf einem zweiten Monitor, zog genau diese Begrenzung den Dialog zurueck an den Rand des ersten. Passt der Dialog nicht ins Elternfenster (der Makro-Schritte-Dialog ist breiter als der Action-Dialog), wird er an dessen linker oberer Ecke ausgerichtet statt zentriert.
• Dialoge öffnen über dem Hauptfenster, nicht in der Bildschirmecke (2026-08-28): _ModalDialog baut sich withdraw()n auf, positioniert sich in run() per _center_on_parent() und wird erst dann deiconify()t. Ohne das legt Tk jeden Toplevel bei +0+0 an — bei 20 Tasten hintereinander wandert der Blick jedes Mal in die linke obere Ecke. Das withdraw() gehört zwingend dazu, sonst blitzt der Dialog dort auf, bevor er springt.
• Verschachtelte Dialoge geben den Grab zurück: MacroStepsDialog läuft im ActionEditDialog. _finish() ruft grab_release(), was den Grab des aufrufenden Dialogs mit wegnimmt — run() setzt ihn deshalb am Ende wieder, wenn der Parent ein _ModalDialog ist.
• Panel-Höhe im ActionEditDialog ist fix (grid_propagate(False)): sonst springt die Fenstergröße bei jedem Typwechsel (Keine/Taste/Makro/…) und OK/Abbrechen wandern unter dem Mauszeiger weg.
• Kopieren/Einfügen zwischen Tasten (Rechtsklickmenü bzw. Strg+C/Strg+V auf der Karte unter dem Mauszeiger) benutzt eine reine In-Memory-Ablage (self._clip), nicht die System-Zwischenablage — dort liegen Action-Dicts, kein Text. Immer copy.deepcopy(), sonst teilen sich zwei Tasten dasselbe Dict und eine spätere Bearbeitung ändert beide. „Leeren" behält die Notiz (gleiche Regel wie beim Typwechsel im Dialog, siehe Notizen-Bullet oben). Eine kopierte LED-Farbe auf einen Encoder einzufügen ist wirkungslos (Encoder haben keine eigene LED) — das ist Absicht, kein Fehler.
• Die Toolbar des Programmiermodus ist bei der Standardbreite (790px) fast voll — zusätzliche Hinweistexte dort kurz halten, sonst werden sie rechts abgeschnitten.
• Tastendruck-Erkennung (seit 2026-08-28, auf expliziten User-Wunsch): Tasten lassen sich im Bearbeiten-Dialog per „⌨ Taste drücken" erfassen, Makro-Schritte zusätzlich als Folge am Stück („⏺ Folge aufnehmen"). Umgesetzt ausschließlich über Tk-Fenster-Events (<KeyPress>/ <KeyRelease> auf dem Dialog-Toplevel, ausgewertet in versapad_data.tk_event_to_hid()) — weiterhin kein WinAPI-Hook (SetWindowsHookEx o.ä.), aus demselben AV-Fehlalarm-Grund wie bei den Fensterverstecktricks. Wer hier auf einen globalen Hook „aufrüstet", baut genau dieses Risiko ein. Konsequenzen, die so bleiben müssen:
  • Erkannt wird nur, was das fokussierte Fenster erreicht — Win+L, Strg+Alt+Entf und andere vom System abgefangene Kombinationen nicht.
  • Welche Taste gemeint ist, wird ueber die PHYSISCHE POSITION aufgeloest, nie ueber das erzeugte Zeichen (2026-08-29, nach Fehlermeldung aus der Praxis). HID-Keycodes sind Positionen: das Board sendet eine Position, erst Windows macht daraus ein Zeichen. Die erste Fassung ging ueber keysym/Zeichen und war auf deutschem Layout entsprechend kaputt — Y und Z landeten vertauscht auf dem Board, ÄÖÜ und #/+ waren gar nicht erfassbar. Reihenfolge jetzt: (1) benannte Tasten ueber den keysym, (2) Zeichentasten ueber versapad_keylayout.hid_for_vk(), (3) die alte Naeherung nur noch als Fallback ohne WinAPI. Nicht auf "Zeichen auswerten" zurueckbauen — das ist genau der Fehler, der hier behoben wurde.
  • Schritt (1) ist keine Bequemlichkeit, sondern noetig: MapVirtualKeyW liefert fuer die Pfeiltasten denselben Scan-Code wie fuer ihre Numpad-Zwillinge (gemessen: VK_LEFT und VK_NUMPAD4 beide 0x4B, das E0-Praefix von MAPVK_VK_TO_VSC_EX bleibt dort aus). Ueber den Scan-Code allein waeren Pfeiltasten nicht von Numpad-Tasten zu unterscheiden.
  • Das Dropdown bleibt daneben stehen (Korrekturmöglichkeit), es ersetzt die Erkennung nicht und wird von ihr nicht ersetzt.
  • Modifier werden doppelt ermittelt (selbst mitgeführte Press/Release-Bits plus event.state), weil ein KeyRelease bei Fokuswechsel verloren gehen kann.
  • _KeyCapture hängt an einem tk.Label, nicht an einem tk.Button: Buttons reagieren per Klassen-Binding selbst auf Leertaste/Enter und würden die laufende Aufnahme mit ihrem eigenen Klick beantworten.
  • Makro-Schritte filtern das Win-Bit weg (allow_win=False), passend zur Firmware-Regel oben.
• Tastenbeschriftungen kommen vom aktiven Layout (seit 2026-08-29). versapad_data.hid_key_name() fragt fuer Zeichentasten GetKeyNameTextW (deutsch: HID 0x1C → „Z", 0x34 → „ä"); fuer alles andere bleiben die gepflegten deutschen Namen aus _SPECIAL_KEYS („Enter", „Bild↑", „Num5") — die lesen sich besser als das, was Windows liefert („EINGABE", „4 (ZEHNERTASTATUR)"). Ohne Layout-Abfrage (Nicht-Windows) faellt alles auf die alte US-Naeherung zurueck. Konsequenzen, die man kennen muss:
  • Bestehende Belegungen aendern ihre Anzeige, nicht ihre Daten. Wer frueher im Dropdown „Z" gewaehlt hat, bekam 0x1D — das steht so in der Config und zeigt jetzt wahrheitsgemaess „Y", weil es auf dieser Tastatur ein Y tippt. Das ist keine Regression, sondern der sichtbar gewordene Altfehler.
  • Namen sind Schluessel (Dropdown, hid_key_code_for_name()) und muessen eindeutig bleiben. Es gibt echte Kollisionen: auf deutschem Layout heisst HID 0x31 schlicht „#" — den Namen trug bisher HID 0x32. Der Layoutname gewinnt, der verdraengte US-Name wird als „# (US-Layout)" gekennzeichnet statt verworfen, damit die Taste ansprechbar bleibt.
  • hid_key_code_for_name() akzeptiert weiterhin beide Schreibweisen, bei Kollision gewinnt das Layout. Fuer den MCP-Server heisst das: set_button_key(key="Z") trifft die Taste, die auf dieser Tastatur ein Z tippt (0x1C), nicht mehr die US-Position 0x1D.
  • Ein Layoutwechsel zur Laufzeit wird nicht bemerkt (Namen werden einmal ermittelt und behalten).
• Tk-Aufrufe (self.after(), Widget-Konfiguration) NIE direkt aus einem Fremdthread (Serial-Thread, pystray-Thread) — hat in einer früheren Version einen stillen Absturz verursacht. Threads legen Ergebnisse nur in eine queue.Queue, der Main-Thread holt sie per after()-Polling ab.
• .exe (PyInstaller) läuft NICHT vom Netzlaufwerk aus (Z:\Git\..., SMB-Share) — Windows blockiert das Nachladen der _internal-DLLs von einem Netzwerkpfad ohne jede Fehlermeldung. Bauen scheitert dort zusätzlich an Tcl/Tk-tzdata-Pfadlängen. build_and_deploy.ps1 kopiert den Quellcode deshalb zuerst nach %TEMP%, baut nur dort, deployt nach %LOCALAPPDATA%.
• --onedir, nicht --onefile beim PyInstaller-Build — Single-File-Bundles lösen öfter AV-Fehlalarme aus (sehen strukturell wie ein Packer aus).

Existing-Codebase-Regel

Es gibt bereits eine Codebasis mit validierter, gegen die echte Firmware getesteter Logik (Binärformat, CRC, Protokoll). Nicht blind neu raten oder umschreiben. Vor größeren Änderungen am Binärformat/Protokoll immer gegen die Firmware- und GUI-Quellen abgleichen, nicht aus dem Gedächtnis rekonstruieren:

• VersaGUI/src/ActionDialog.cs (HidKeyName, s_consumer, Modifier-Bits)
• VersaGUI/src/Protocol.cs (Paket-IDs, Chunk-Größen)
• 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 tatsächlich behandelt — Protocol.cs definiert mehr Konstanten als zwingend implementiert sind, immer hier gegenchecken)

Frühere falsche Annahme, die hier stand: Makros seien nur per SWD/JTAG schreibbar. Falsch — USB_CMD_MACRO_BEGIN/DATA/COMMIT in CMainController.cpp sind normal über USB implementiert. Korrigiert, auch im versapad-Skill (~/.claude/skills/versapad/SKILL.md).

Implementierungsdisziplin

In Phasen arbeiten, nicht mehrere unabhängige Features in einem Rutsch ohne Zwischenverifikation bauen. Vor jeder Änderung am Binärformat/Protokoll: gegen ein echtes Board testen (read → unpack → pack → Vergleich auf Byte-Identität), nicht nur gegen Beispieldaten. Vor jedem Schreibvorgang aufs Board: erst mit unveränderten Daten testen (Identity-Write), bevor echte Änderungen geschrieben werden.

Änderungen an der Config immer aus der Sicht prüfen, die die laufende App hat (2026-08-15 gelernt): Claudes Bash- und PowerShell-Werkzeuge sehen unter C:\Users\chris\AppData\... teilweise unterschiedliche Dateien — derselbe Pfad lieferte gleichzeitig 29826 Bytes (Bash/MCP-Server) und 28455 Bytes (PowerShell/.exe). Konkret heißt das: Config-Schreibvorgänge über den versapad-MCP-Server (save_local()) erreichen die installierte .exe nicht zuverlässig. Das hat eine Fehlersuche über viele Runden verschleppt, weil "Notizen sind in der Datei" (Bash) und "App zeigt keine Notizen" gleichzeitig stimmten. Vorgehen:

• Config-Dateien, die die installierte App lesen soll, über PowerShell schreiben/prüfen (Get-Item, dort ausgeführtes python), nicht über Bash.
• Bei "Änderung wirkt nicht"-Symptomen als Erstes Dateigröße/mtime aus beiden Sichten vergleichen, bevor Code-Ursachen gesucht werden.
• Z:\Git\... (SMB-Share) ist von diesem Effekt nicht betroffen — Quellcode und Build verhalten sich normal.

Verlässlich zum Ziel führt bei solchen Widersprüchen ein temporäres Diagnose-Modul, das im gebauten Bundle mitläuft und app_dir(), DEFAULT_PATH, os.stat() und den tatsächlich geladenen JSON-Inhalt in eine Datei schreibt — damit war die Ursache in einem Durchlauf sichtbar, nachdem Vermutungen mehrfach danebenlagen.

Naming

Code-Identifier englisch (Python-Konvention: pack_config, read_macros, ActionEditDialog). UI-Text, Kommentare und Docstrings deutsch (Projekt- und User-Konvention). Domänenbegriffe aus der Firmware direkt übernehmen, nicht neu erfinden: profile, action, led, slot, macro, encoder, chunk. Keine generischen Namen wie data/item/entry, wo eine Bedeutung existiert — Ausnahme: data als Feldname ist durch die Firmware selbst vorgegeben (SAction.data), dort beibehalten statt umzubenennen.

Deferred Work

• Board-seitiges Umschalten des aktiven Profils per Button in der GUI — explizit vom User abgelehnt ("lass uns weg"), Live-Sync bleibt read-only
• Profilnamen aufs Board schreiben — technisch unmöglich (kein Platz im Firmware-Struct), bleibt lokal
• Hintergrund-Thread für "Vom Board laden"/"Zum Board übertragen" — laufen aktuell synchron im UI-Thread (kurzzeitiges Einfrieren möglich)
• Vorgefertigte .exe im Repo/als Release-Asset — bewusst nicht committet (Build-Artefakt), Anleitung zum Selbstbauen steht in README.md

Nicht an diesen Punkten arbeiten, ohne dass der User es explizit anfragt.

Dokumentation und Verifikation

• README.md ist der Einstiegspunkt (Installation, Nutzung, Architektur- Überblick).
• AGENTS.md (diese Datei) ist die agentenseitige Quelle der Wahrheit für Domänenregeln, Architekturgrenzen und Bug-Historie — jede Session aktualisieren, die daran etwas ändert oder etwas Wichtiges lernt.
• docs/ (seit 2026-08-14, auf expliziten User-Wunsch) enthält die menschenlesbare Referenzdoku: architecture.md (Schichten, Prozess-/ Nebenläufigkeitsmodell, Config-Speicherort), data-model.md (JSON- Formate, binäres NVM-Layout, Geometrie, Enums), protocol.md (Serial-Wire-Protokoll). Bug-Historie/Domänenregeln bleiben bewusst nur in AGENTS.md, nicht dupliziert in docs/. Bei Änderungen am Binärformat/Protokoll/Datenmodell docs/data-model.md bzw. docs/protocol.md mitpflegen.

Prüfungen vor einem Commit an Binärformat/Protokoll:

python -m py_compile *.py

Für UI-Änderungen (Dialoge, Tastendruck-Erkennung, Kopieren/Einfügen) hat sich zusätzlich bewährt, ein Wegwerf-Skript im Scratchpad zu fahren, das die Dialoge ohne Board aufbaut, Tk-Events als kleine Fake-Event-Objekte (keysym/keycode/state) durchreicht und das Ergebnis-Dict prüft — die komplette Capture- und Copy/Paste-Logik ist so ohne Klicken verifizierbar. Wichtig dabei: versapad_combined.DEFAULT_PATH vorher auf eine Temp-Datei umbiegen, sonst schreibt _autosave_combined() in die echte Nutzer-Config. Für Screenshots gilt: Tk rechnet in logischen Pixeln, ImageGrab liefert physische — bei aktiver Windows-Skalierung (hier 125%) sonst ein zu kleiner Ausschnitt, der wie ein Layout-Fehler aussieht. Danach ein Live-Testskript gegen ein angeschlossenes Board laufen lassen (read → unpack → pack → Bytevergleich, siehe Existing-Codebase-Regel) — es gibt keine automatisierten Unit-Tests dafür, die Verifikation läuft manuell/interaktiv pro Session.

Committen: prägnante Commit-Message je abgeschlossenem, verifiziertem Arbeitspaket. Nach jedem Push: alle bekannten Remotes prüfen (origin auf GitHub, jappel auf git.jappel.io) — beide müssen synchron bleiben, siehe Speicher-Notiz "Multi-Remote-Repos synchron halten".

PR-Erstellung auf git.jappel.io per API/curl mit Access-Token wird vom Bash-Classifier geblockt (Auto-Mode, gilt auch für git credential fill), siehe Speicher-Notiz "Bash-Klassifikator blockt Credential/Auth-Schreibzugriffe". Branch pushen geht (nutzt den Git-eigenen Credential-Helper, kein Token im Klartext im Bash-Aufruf), den fertigen PR muss der User über den von Forgejo nach dem Push ausgegebenen Compare-Link selbst anlegen (oder Claude einen Token geben, der dann NICHT wiederverwendbar im Bash-Aufruf landen darf, sondern nur für den einen curl-Call — auch das kann der Classifier trotzdem blocken, dann bleibt nur der manuelle Link).