139 lines
3.3 KiB
Markdown
139 lines
3.3 KiB
Markdown
# 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)
|