# 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 SDK
- geflashte `VersaMCU`-Firmware
- Board per USB als CDC-Device 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
- 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
```

## GUI-Funktionen

- 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

## Projektstruktur

```text
VersaGUI/
|-- AGENTS.md
|-- doc/
|-- tests/VersaGUI.ContractTests/
`-- src/
    |-- Program.cs
    |-- TrayApp.cs
    |-- SerialManager.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

## Einstieg für Coding-LLMs

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

## Weiterfuehrende Doku

- [doc/02_device_config.md](doc/02_device_config.md)
- [../VersaMCU/doc/07_serial_protocol.md](../VersaMCU/doc/07_serial_protocol.md)