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:

README.md für Scope, Build und Einstieg
doc/INDEX.md für die thematische Navigation
doc/00_architecture.md für Datenfluss und Laufzeitmodell
doc/09_known_limitations.md für bewusst noch nicht gelöste Risiken
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:

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:

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?

4.3 KiB Raw Permalink Blame History