104 lines
4.3 KiB
Markdown
104 lines
4.3 KiB
Markdown
# Arbeitsanweisungen für Coding-Agents
|
|
|
|
Diese Datei gilt für das gesamte Repository. Sie ist zugleich der kompakte
|
|
Einstiegskontext für LLM-basierte Entwicklungswerkzeuge.
|
|
|
|
## Ziel und Plattform
|
|
|
|
VersaMCU ist die Firmware des VersaPad-v2-Makropads. Das aktive und unterstützte
|
|
PlatformIO-Ziel ist `env:versapad`:
|
|
|
|
- ATSAMD21G17D, Cortex-M0+, 48 MHz
|
|
- 128 KiB Flash, 16 KiB RAM
|
|
- Arduino-SAMD-Core über PlatformIO
|
|
- Upload per Atmel-ICE/CMSIS-DAP und OpenOCD, ohne Bootloader
|
|
- USB Composite Device: Keyboard-HID, Consumer-HID und CDC Serial
|
|
|
|
Das auskommentierte Bootloader-Ziel in `platformio.ini` ist kein verifiziertes
|
|
Produktionsziel.
|
|
|
|
## Vor dem Ändern lesen
|
|
|
|
In dieser Reihenfolge:
|
|
|
|
1. `README.md` für Scope, Build und Einstieg
|
|
2. `doc/INDEX.md` für die thematische Navigation
|
|
3. `doc/00_architecture.md` für Datenfluss und Laufzeitmodell
|
|
4. `doc/09_known_limitations.md` für bewusst noch nicht gelöste Risiken
|
|
5. die zum Task gehörende Fachdokumentation und anschließend den Quellcode
|
|
|
|
Bei Widersprüchen ist der kompilierte Code die Quelle für das aktuelle
|
|
Verhalten. Hardwarekonstanten stehen in `src/config/pins.h` und
|
|
`variants/versapad/`; binäre Formate stehen in den Structs unter `src/config/`
|
|
und in `src/hal/usb_serial.h`. Widersprüche zwischen Code und Dokumentation
|
|
müssen im selben Change behoben oder ausdrücklich als bekannte Einschränkung
|
|
festgehalten werden.
|
|
|
|
## Unverzichtbare Verträge
|
|
|
|
- `SAction`, `SDeviceProfile`, `SDeviceConfig`, `SMacroStep` und
|
|
`SMacroTable` sind persistente beziehungsweise hostseitige Binärverträge.
|
|
- Änderungen an Feldreihenfolge, Enum-Werten, Packing, Größen, Magic, Version,
|
|
CRC-Bereich oder Chunking benötigen gleichzeitig:
|
|
Firmware-Migration/Versionswechsel, Anpassung der externen GUI und
|
|
Aktualisierung von `doc/06_nvm_config.md` sowie
|
|
`doc/07_serial_protocol.md`.
|
|
- Die Windows-GUI liegt im benachbarten, eigenständigen Repository
|
|
`../VersaGUI`. Bei gemeinsamen Verträgen beide Repositories ändern, prüfen
|
|
und jeweils bedarfsgerecht committen. `DelphiGUI` wird nicht gepflegt.
|
|
- Die NVM-Adressen liegen am oberen Ende des 128-KiB-Flash. Vor Änderungen an
|
|
Linker-Skripten, Boardgrößen oder NVM-Layouts immer
|
|
`doc/09_known_limitations.md` lesen.
|
|
- Der Code läuft auf 16 KiB RAM. Keine unnötige dynamische Allokation, keine
|
|
großen Stackpuffer und keine Float-Arithmetik in Loop-/ISR-Pfaden einführen.
|
|
- ISR-Code muss kurz und nicht blockierend bleiben. Niemals USB, NVM,
|
|
WS2812-Ausgabe oder `delay()` aus einer ISR aufrufen.
|
|
- Das feste CDC-Protokoll besteht aus 8-Byte-Paketen. Blob-Transfers prüfen
|
|
Chunkzahl, eindeutige Indizes und Vollständigkeit; paketweises Framing und
|
|
eine Makro-CRC gibt es weiterhin nicht.
|
|
|
|
## Änderungsleitfaden
|
|
|
|
- Kleine, lokale Änderungen bevorzugen; HAL, Controller und persistente Config
|
|
nicht ohne Grund vermischen.
|
|
- Neue Hardwarezugriffe gehören unter `src/hal/`.
|
|
- Neue konfigurierbare Werte benötigen definierte Defaults und eine
|
|
Validierungsstrategie für Daten vom Host.
|
|
- Neue Action- oder Eventtypen müssen in Firmware, Protokolldoku und externer
|
|
GUI gemeinsam geplant werden.
|
|
- Bei Matrix- oder Encoderänderungen die ISR-/Queue-Interaktion prüfen.
|
|
- Bei LED-Animationen nur ganzzahlige Arithmetik verwenden und Randwerte wie
|
|
`period_ms <= 1` behandeln.
|
|
- Bestehende deutsch- und englischsprachige Kommentare dürfen vereinheitlicht
|
|
werden; Dateien als UTF-8 speichern.
|
|
- Keine generierten Inhalte aus `.pio/` committen.
|
|
|
|
## Verifikation
|
|
|
|
Mindestens:
|
|
|
|
```bash
|
|
pio run -e versapad
|
|
git diff --check
|
|
```
|
|
|
|
Für Hardware-, USB-, NVM- oder Timingänderungen zusätzlich einen passenden
|
|
Gerätetest beschreiben. Für die Firmware gibt es derzeit keine automatisierten
|
|
Unit- oder Integrationstests. Ein erfolgreicher Build beweist daher weder
|
|
elektrische Funktion noch GUI-Kompatibilität.
|
|
|
|
Bei Änderungen an Config-, Makro- oder CDC-Verträgen zusätzlich:
|
|
|
|
```bash
|
|
dotnet build ../VersaGUI/src/VersaGUI.csproj --no-restore
|
|
dotnet run --project ../VersaGUI/tests/VersaGUI.ContractTests/VersaGUI.ContractTests.csproj
|
|
```
|
|
|
|
Vor Abschluss prüfen:
|
|
|
|
- Stimmen README und betroffene `doc/*.md` noch?
|
|
- Wurden Binärgrößen und Offsets neu berechnet statt übernommen?
|
|
- Bleiben Firmware und NVM-Bereiche kollisionsfrei?
|
|
- Ist klar getrennt, was verifiziert, nur aus Code abgeleitet oder noch offen
|
|
ist?
|