# VersaGUI

Windows-Tray-App zur Konfiguration des VersaPad v2.
Geschrieben in C# mit WinForms.

Diese GUI und das benachbarte Repository `../VersaMCU` sind die gemeinsam
gepflegten Referenzen für Protokoll und Datenlayout. Andere GUI-Ports gehören
nicht zum aktuellen Scope.

## Voraussetzungen

- Windows 10/11
- .NET 7 SDK mit Windows-Desktop-Unterstützung
- geflashte `VersaMCU`-Firmware
- Board per USB als Composite Device (Keyboard-HID, Consumer-HID und CDC)
  verbunden

## Starten

```bash
dotnet run --project src/VersaGUI.csproj
```

## Was die App macht

- 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
- validiert Chunkzahl, eindeutige Indizes, Vollständigkeit, CRC und Feldwerte
- zeigt MX-Buttons und Encoder-Aktionen an
- bearbeitet alle drei Profile über die Profilauswahl
- schreibt Config und Makros getrennt, aber in einem UI-Vorgang auf das Board
- sendet einen Protokoll-Ping und zeigt die Antwort an

## Aktueller Datenstand

### DeviceConfig

- Magic `0x56503203`
- Version `3`
- `740` Byte
- 3 Profile
- globale Helligkeit
- per-LED-Helligkeit

Globale Helligkeit und Encoder-Sensitivität werden bytegenau erhalten, besitzen
aber derzeit keine eigenen Bedienelemente. Per-LED-Helligkeit kann über JSON
gesetzt werden.

### 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
```

## GUI-Funktionen

- HID-Key-Zuweisung inklusive Modifier
- Consumer-Keys
- Host-Command-IDs konfigurieren und empfangen; Desktop-Aktionen werden noch
  nicht ausgeführt
- Makros mit bis zu 8 Steps
- Profilwechsel als ActionType
- LED-Farbe, Animation und Periode pro MX-Button
- JSON Import/Export

## Projektstruktur

```text
VersaGUI/
|-- AGENTS.md
|-- doc/
|-- tests/VersaGUI.ContractTests/
`-- src/
    |-- Program.cs
    |-- TrayApp.cs
    |-- SerialManager.cs
    |-- ChunkTransferBuffer.cs
    |-- DeviceConfig.cs
    |-- ConfigForm.cs
    |-- ActionDialog.cs
    |-- ConfigJson.cs
    `-- Protocol.cs
```

## Build und Vertragsprüfungen

```bash
dotnet build src/VersaGUI.csproj --no-restore
dotnet run --project tests/VersaGUI.ContractTests/VersaGUI.ContractTests.csproj
```

## Grenzen / Status

- die App ist Windows-only
- Host-Command-Events enthalten Command-ID, Key-/Encoder-ID und Richtung; ein
  sicheres Mapping auf konkrete Desktop-Aktionen ist noch nicht implementiert
- der ActionDialog bietet aktuell vier der sieben vom Binärformat unterstützten
  LED-Animationen an
- ein vollständig ausbleibendes Dump-Ende besitzt noch keinen Empfangs-Timeout

Die vollständige Liste steht in
[`doc/07_known_limitations.md`](doc/07_known_limitations.md).

## Einstieg für Coding-LLMs

Repository-Anweisungen, gemeinsame Binärverträge und Verifikation stehen in
[`AGENTS.md`](AGENTS.md).

## Weiterführende Doku

- [Dokumentationsindex](doc/INDEX.md)
- [Datenlayout](doc/02_device_config.md)
- [Bekannte Einschränkungen](doc/07_known_limitations.md)
- [../VersaMCU/doc/07_serial_protocol.md](../VersaMCU/doc/07_serial_protocol.md)