Fully working Delphi GUI

2026-04-19 11:59:32 +02:00
parent 24fe162833
commit aa6b7a8ec9
3 changed files with 184 additions and 292 deletions
@@ -1,14 +1,18 @@
 # VersaGUI

-Windows-Tray-App zur Konfiguration und Steuerung des VersaPad v2.
-Geschrieben in **C# / .NET 7 / WinForms**.
+Windows-Tray-App zur Konfiguration des VersaPad v2.
+Geschrieben in C# mit WinForms.
+
+Hinweis:
+Diese GUI ist weiterhin die Referenzimplementierung fuer Protokoll und Datenlayout.
+Parallel existiert mit `VersaGUIDelphi` ein Delphi/VCL-Port unter dem Namen `VersaGUI Delphi`.

 ## Voraussetzungen

 - Windows 10/11
- [.NET 7 SDK](https://dotnet.microsoft.com/download/dotnet/7.0) (zum Bauen)
- VersaMCU-Firmware auf dem Board geflasht
- Board per USB verbunden (erscheint als CDC COM-Port, kein Treiber nötig)
+- .NET SDK
+- geflashte `VersaMCU`-Firmware
+- Board per USB als CDC-Device verbunden

 ## Starten

@@ -16,194 +20,86 @@ Geschrieben in **C# / .NET 7 / WinForms**.
 dotnet run
 ```

-Oder als Release-Build:
+## Was die App macht

-```bash
-dotnet publish -c Release -r win-x64 --self-contained
+- erkennt das Board automatisch per VID/PID
+- oeffnet den CDC-COM-Port mit aktivem DTR
+- liest beim Verbinden zuerst die Config und danach die Makros
+- zeigt MX-Buttons und Encoder-Aktionen an
+- schreibt Config und Makros getrennt, aber in einem UI-Vorgang auf das Board
+
+## Aktueller Datenstand
+
+### DeviceConfig
+
+- Magic `0x56503203`
+- Version `3`
+- `740` Byte
+- 3 Profile
+- globale Helligkeit
+- per-LED-Helligkeit
+
+### MacroTable
+
+- 32 Slots
+- 8 Steps pro Slot
+- `512` Byte
+
+## Uebertragungsformat
+
+Es wird dasselbe 8-Byte-Protokoll wie in der Firmware verwendet.
+
+Aktuelle Chunk-Zahlen:
+
+- Config: `124`
+- Makros: `86`
+
+Speicherablauf:
+
+```text
+CONFIG_BEGIN
+CONFIG_DATA x124
+CONFIG_COMMIT
+wait for ACK/NACK
+
+MACRO_BEGIN
+MACRO_DATA x86
+MACRO_COMMIT
+wait for ACK/NACK
 ```

-Die App erscheint als Icon in der Windows-Taskleiste (System Tray). Kein Hauptfenster.
+## GUI-Funktionen

-## Bedienung
+- HID-Key-Zuweisung inklusive Modifier
+- Consumer-Keys
+- Host-Commands
+- Makros mit bis zu 8 Steps
+- Profilwechsel als ActionType
+- LED-Farbe, Animation und Periode pro MX-Button
+- JSON Import/Export

-1. **Board verbinden** – App erkennt das Board automatisch per VID/PID (`0x239A / 0x0042`) via WMI
-2. **Rechtsklick** auf das Tray-Icon → **Konfiguration...**
-3. Taste/Encoder anklicken → Aktion auswählen:
-   - **HID Tastatur**: Großen Button klicken, dann gewünschte Taste drücken (Strg+C, F5, …)
-   - **HID Consumer**: Dropdown – Play/Pause, Lautstärke, etc.
-   - **Host Command**: Numerische Command-ID (zukünftig: URL/Programm)
-   - **LED-Farbe**: Farbpicker für die Idle-LED des Buttons
-4. **Auf Board speichern** – überträgt Config in den NVM des Boards
-5. Beim nächsten Verbinden wird die Config automatisch vom Board geladen
+## Projektstruktur

---
-
-## Funktionsumfang (Anforderungskatalog)
-
-### 1 Verbindung & Geräteerkennung
-
-| # | Anforderung | Status |
-|---|-------------|--------|
-| 1.1 | App läuft als **Windows Tray-Anwendung** ohne sichtbares Hauptfenster | ✅ |
-| 1.2 | Automatische Board-Erkennung per **WMI / VID+PID** (`0x239A / 0x0042`) | ✅ |
-| 1.3 | **Automatischer Reconnect** alle 3 s; 5 s Backoff nach Verbindungsverlust | ✅ |
-| 1.4 | Verbindungsstatus im Tray-Icon (Symbol + Tooltip) sichtbar | ✅ |
-| 1.5 | Beim Verbinden wird die gespeicherte Config **automatisch vom Board gelesen** | ✅ |
-| 1.6 | Beim Verbinden wird die **Makro-Tabelle automatisch vom Board gelesen** | ✅ |
-
-### 2 Tastenbelegung – HID Tastatur
-
-| # | Anforderung | Status |
-|---|-------------|--------|
-| 2.1 | Taste durch **Drücken erfassen** (kein manuelles HID-ID-Eingeben) | ✅ |
-| 2.2 | Modifier-Kombination: **Strg / Shift / Alt / Win** einzeln oder kombiniert | ✅ |
-| 2.3 | **Pfeiltasten, Enter, Escape, F1–F12, Numpad** erfassbar | ✅ |
-| 2.4 | **Layout-unabhängige Erfassung** via PS/2-Scan-Code → HID-Usage; Ö/Ä/Ü auf QWERTZ korrekt | ✅ |
-| 2.5 | Taste-Name wird laut **aktivem Windows-Layout** angezeigt (`GetKeyNameText`) | ✅ |
-| 2.6 | Board führt Tastendruck als **USB-HID-Tastatureingabe** aus (funktioniert ohne laufende App) | ✅ |
-| 2.7 | **Hold-Semantik**: Taste bleibt gedrückt solange physisch gehalten (OS initiiert Repeat nach ~500ms) | ✅ |
-
-### 3 Tastenbelegung – HID Consumer / Medientasten
-
-| # | Anforderung | Status |
-|---|-------------|--------|
-| 3.1 | Auswahl per **Dropdown** mit Klartext-Namen | ✅ |
-| 3.2 | Unterstützte Aktionen: Play/Pause, Nächster/Vorheriger Titel, Stop, Lauter/Leiser, Mute, Taschenrechner, Browser Zurück/Vor | ✅ |
-| 3.3 | **Hold-Semantik**: Media-Control bleibt aktiv solange Taste gehalten wird (z.B. Lautstärke-Wiederholung) | ✅ |
-
-### 4 Tastenbelegung – Makros
-
-| # | Anforderung | Status |
-|---|-------------|--------|
-| 4.1 | Bis zu **4 Schritte** pro Makro (je 1 Taste + Modifier) | ✅ |
-| 4.2 | Jeder Schritt per **Taste drücken** erfassen, inkl. Sondertasten | ✅ |
-| 4.3 | Leere Schritte werden übersprungen (kürzere Makros möglich) | ✅ |
-| 4.4 | **32 Makro-Slots** – je ein Slot pro MX-Button (0–19) und Encoder-Aktion (20–31) | ✅ |
-| 4.5 | Makro-Tabelle wird **separat** vom Board gelesen und geschrieben (NVM Row 1) | ✅ |
-| 4.6 | Board führt Makro-Schritte mit 10 ms Key-Down + 20 ms Pause **ohne laufende App** aus | ✅ |
-
-### 5 Encoder-Belegung
-
-| # | Anforderung | Status |
-|---|-------------|--------|
-| 5.1 | **4 Encoder**, je 3 Aktionen: SW (Drücken), CW (Rechts), CCW (Links) | ✅ |
-| 5.2 | Gleiche Aktionstypen wie Tasten (HID Key, Consumer, Makro, Host Command) | ✅ |
-| 5.3 | **Encoder-SW**: Hold-Semantik wie normale Tasten (Taste bleibt gedrückt) | ✅ |
-| 5.4 | **Encoder-CW/CCW**: Tap-Modell (diskrete Ereignisse, atomare down+delay+up Sequenzen, kein Hold möglich) | ✅ |
-
-### 6 LED-Konfiguration
-
-| # | Anforderung | Status |
-|---|-------------|--------|
-| 6.1 | **Basis-LED-Farbe** pro MX-Button via Farbpicker (RGB) | ✅ |
-| 6.2 | **Animationsmodus** pro Button wählbar: Statisch, Blinken, Pulsieren, Regenbogen | ✅ |
-| 6.3 | **Animations-Tempo**: Schnell (0,5 s) / Mittel (1 s) / Langsam (2 s) / Sehr langsam (4 s) | ✅ |
-| 6.4 | Regenbogen-Modus: Board berechnet Hue-Sweep lokal, gleichmäßige Phasenverteilung | ✅ |
-| 6.5 | LED-Config und Aktionstyp im **gleichen Dialog** bearbeitbar | ✅ |
-
-### 7 Konfiguration speichern & laden
-
-| # | Anforderung | Status |
-|---|-------------|--------|
-| 7.1 | Config und Makros werden gleichzeitig per **„Auf Board speichern"** übertragen | ✅ |
-| 7.2 | Board validiert Config mit **CRC16-CCITT + Magic + Version**; NACK bei Fehler | ✅ |
-| 7.3 | Config bleibt nach Stromverlust im **NVM** erhalten (kein Flash-Verschleiß bei nur Lesen) | ✅ |
-| 7.4 | **JSON-Export** der gesamten Config (Aktionen + LED) in Datei | ✅ |
-| 7.5 | **JSON-Import** mit Versionscheck; ungültige Dateien werden abgelehnt | ✅ |
-
-### 8 Verbindungsprotokoll
-
-| # | Anforderung | Status |
-|---|-------------|--------|
-| 8.1 | **8-Byte-Festlängen-Pakete** über CDC Serial (kein Treiber nötig) | ✅ |
-| 8.2 | **Ping/Pong** zur manuellen Verbindungsdiagnose im Konfigurations-Fenster | ✅ |
-| 8.3 | Config-Transfer: BEGIN → n×DATA(6 Byte) → COMMIT → ACK/NACK | ✅ |
-| 8.4 | Makro-Transfer: gleiche Struktur, 43 Chunks à 6 Byte (256 Byte Tabelle) | ✅ |
-| 8.5 | Debug-Logging aller RX-Pakete in `%TEMP%\versapad_rx.txt` | ✅ |
-
-### 9 Nicht implementiert / Roadmap
-
-| # | Anforderung | Status |
-|---|-------------|--------|
-| 9.1 | **Host Command**: URL/Programm öffnen wenn Board-Taste gedrückt | 🔲 TODO |
-| 9.2 | Eigenes **Tray-Icon** (aktuell: Windows-Standard-Icon) | 🔲 TODO |
-| 9.3 | **Fader/Potentiometer**-Unterstützung (3× ADC-Achsen auf Board vorhanden) | 🔲 TODO |
-| 9.4 | **Profile**: mehrere Tastenbelegungen speichern und wechseln | 🔲 TODO |
-
---
-
-## Projekt-Struktur
-
-```
+```text
 VersaGUI/
-├── VersaGUI.csproj      – .NET 7 WinForms Projekt
-├── Program.cs           – Einstiegspunkt, startet TrayApp
-├── TrayApp.cs           – ApplicationContext: Tray-Icon, Menü, Paket-Routing
-├── ConfigForm.cs        – Konfigurations-Fenster (4×5 Grid + Encoder-Panel)
-├── ActionDialog.cs      – Dialog: Taste erfassen / Consumer / Makro / LED-Animation
-├── DeviceConfig.cs      – C#-Spiegel von SDeviceConfig (223 B, Version 2) + MacroTable (256 B)
-├── ConfigJson.cs        – JSON-Export/Import der DeviceConfig
-├── Protocol.cs          – Protokoll-Konstanten (Commands + Events)
-└── SerialManager.cs     – COM-Port-Erkennung, Read-Loop, Config + Makros senden/empfangen
+`-- src/
+    |-- Program.cs
+    |-- TrayApp.cs
+    |-- SerialManager.cs
+    |-- DeviceConfig.cs
+    |-- ConfigForm.cs
+    |-- ActionDialog.cs
+    |-- ConfigJson.cs
+    `-- Protocol.cs
 ```

-## Architektur
+## Grenzen / Status

-```
-TrayApp
-  ├── SerialManager          – Hintergrund-Thread: COM-Port-Verbindung + Leseloop
-  │     ├── Connected-Event  → Config vom Board anfordern (CMD_CONFIG_READ)
-  │     └── PacketReceived   → TrayApp.OnPacket()
-  ├── DeviceConfig           – In-Memory-Modell der Board-Config
-  └── ConfigForm (optional)  – Öffnet sich auf Benutzeranfrage
-        └── ActionDialog     – Modaler Dialog pro Taste/Encoder
-```
+- Host-Commands sind protokollseitig vorhanden, aber appseitig noch nicht voll ausgebaut
+- die App ist Windows-only
+- fuer eine alternative GUI ist `VersaGUIDelphi` der aktuelle Delphi/VCL-Port

-### SerialManager
+## Weiterfuehrende Doku

- Erkennt das Board per **WMI** (`Win32_PnPEntity`, VID/PID-Filter) → COM-Port-Name
- Lese-Loop im Hintergrund-Thread: sammelt 8-Byte-Pakete, feuert `PacketReceived`-Event auf dem UI-Thread
- **Reconnect-Timer**: versucht alle 3 Sekunden neu zu verbinden; nach Disconnect 5 Sekunden Backoff
- Wichtig: `DtrEnable = true` muss **vor** `Open()` gesetzt werden – der SAMD21 prüft die DTR-Leitung in `if (!SerialUSB)` und verwirft sonst alle ausgehenden Pakete
-
-### DeviceConfig / Serialisierung
-
-`DeviceConfig.ToBytes()` erzeugt den exakt **223-Byte**-Puffer der `SDeviceConfig`-Struct (Version 2, little-endian, packed). `CRC16-CCITT` (Poly 0x1021, Init 0xFFFF) über Bytes 7–222 – identisch zur Firmware-Implementierung.
-
-`MacroTable.ToBytes()` erzeugt **256 Byte** (32 Slots × 4 Steps × 2 Byte).
-
-Config-Übertragung Board→PC (Lesen):
-```
-PC sendet:    CMD_CONFIG_READ  (0x13)
-Board sendet: EVT_CONFIG_BEGIN (Chunk-Anzahl = 38)
-              EVT_CONFIG_DATA  × 38 (je 6 Nutzbytes)
-              EVT_CONFIG_END
-```
-
-Config-Übertragung PC→Board (Schreiben):
-```
-PC sendet:    CMD_CONFIG_BEGIN (0x10, Chunk-Anzahl)
-              CMD_CONFIG_DATA  × 38
-              CMD_CONFIG_COMMIT (0x12)
-Board sendet: EVT_CONFIG_ACK (0x90) oder EVT_CONFIG_NACK (0x91)
-```
-
-Makro-Übertragung (analog, separate Kommandos 0x20–0x23):
-```
-PC sendet:    CMD_MACRO_BEGIN  (0x20, Chunk-Anzahl = 43)
-              CMD_MACRO_DATA   × 43
-              CMD_MACRO_COMMIT (0x22)
-Board sendet: EVT_MACRO_ACK   (0x95)
-```
-
-### Kommunikationsprotokoll
-
-Das vollständige Protokoll (alle Command- und Event-IDs, NVM-Layout, Paketformat) ist in [VersaMCU/README.md](../VersaMCU/README.md#serial-protokoll-8-bytes-fixed) dokumentiert.
-
-### Bekannte .NET-Eigenheiten
-
-| Problem | Lösung |
-|---|---|
-| `.NET 7 SerialPort.ReadByte()` wirft `IOException` statt `TimeoutException` auf Timeout | `catch (IOException)` → nur als Fehler behandeln wenn Port nicht mehr offen ist |
-| `DtrEnable = false` (Standard) → Board sendet nichts | `DtrEnable = true` im SerialPort-Konstruktor setzen, **vor** `Open()` |
-| DTR-Zustandswechsel nach `Open()` löst CDC-Disconnect auf dem Board aus | DTR vor `Open()` setzen → kein Zustandswechsel |
+- [doc/02_device_config.md](doc/02_device_config.md)
+- [../VersaMCU/doc/07_serial_protocol.md](../VersaMCU/doc/07_serial_protocol.md)