Update firmware documentation and agent guidance

2026-07-24 09:27:07 +02:00
parent ac3b2aa90f
commit 50dbf8fbee
26 changed files with 592 additions and 196 deletions
@@ -0,0 +1,95 @@
+# Entwicklung und Einstieg
+
+Diese Seite ist der praktische Einstieg für neue Entwickler. Für einen
+LLM-basierten Coding-Agent zusätzlich die Anweisungen in
+[`../AGENTS.md`](../AGENTS.md) bereitstellen.
+
+## Voraussetzungen
+
+- PlatformIO Core oder PlatformIO IDE
+- USB-Kabel für Laufzeittests
+- Atmel-ICE beziehungsweise kompatibler CMSIS-DAP-Adapter für den Upload
+- Zugriff auf die separat gepflegte Windows-GUI, wenn das CDC-Protokoll oder
+  persistente Formate geändert werden
+
+PlatformIO lädt den Arduino-SAMD-Core, OpenOCD und `Adafruit NeoPixel` über
+`platformio.ini`. Das aktive Standardziel ist `versapad_nobl` im Environment
+`versapad`.
+
+## Build und Upload
+
+```bash
+pio run -e versapad
+pio run -e versapad --target upload
+```
+
+Der Upload nutzt `upload_openocd.py`, das das von PlatformIO installierte
+OpenOCD mit `interface/cmsis-dap.cfg` und `target/at91samdXX.cfg` startet.
+
+Das in `platformio.ini` nur als Beispiel enthaltene Environment
+`versapad_usb` ist auskommentiert und mit dem aktuellen NVM-/Linker-Layout
+nicht als unterstützt anzusehen.
+
+## Was beim Start passiert
+
+```text
+Arduino setup()
+  500 ms warten
+  WS2812 initialisieren
+  1 s rotes Startsignal
+  Makros aus NVM laden
+  Config laden und Buttons initialisieren
+  USB-HID/CDC, Matrix und Encoder initialisieren
+
+Arduino loop()
+  Matrix scannen
+  CDC-Pakete verarbeiten
+  Event-Queue leeren
+  Werksreset prüfen
+  LEDs rendern
+```
+
+Der Controller blockiert während Makros, Encoder-Taps, Start-/Reset-Feedback
+und NVM-Schreibvorgängen. Es gibt keinen Scheduler und keine Threads.
+
+## Einstieg nach Änderungstyp
+
+| Änderung | Zuerst lesen | Typische Dateien |
+|---|---|---|
+| Matrix/Key-Mapping | `01_matrix.md` | `hal/matrix.*`, `config/pins.h`, Variant |
+| Encoder | `02_encoder.md` | `hal/encoder.*`, `CMainController.cpp` |
+| Actions/HID | `03_action_engine.md` | `config/action.h`, Controller, `hal/usb_hid.*` |
+| Makros | `04_macro_system.md` | `config/macro_config.*`, Controller |
+| LEDs | `05_led_system.md` | `CButton.*`, `hal/ws2812.*` |
+| Persistente Config | `06_nvm_config.md` | `config/nvm_config.*`, Linker-Skripte |
+| Host-Protokoll | `07_serial_protocol.md` | `hal/usb_serial.*`, Controller |
+
+## Verifikation
+
+Es gibt derzeit keine automatisierten Tests. Der minimale lokale Check ist:
+
+```bash
+pio run -e versapad
+git diff --check
+```
+
+Je nach Änderung folgen Hardwaretests:
+
+- Matrix: jede Taste einzeln, Mehrfachtasten und beide Reset-Tasten
+- Encoder: beide Richtungen und schneller Richtungswechsel
+- HID: Down/Up sowie Modifier und Consumer Usage
+- CDC: Ping, vollständiger Config-/Makro-Transfer und Readback
+- NVM: Power-Cycle, ungültige CRC und Werksreset
+- LEDs: alle Animationen, Helligkeit und temporäre Overrides
+
+Die GUI ist ein externer Vertrag. Änderungen an `SDeviceConfig`,
+`SMacroTable`, Action-Werten oder USB-IDs sind erst vollständig verifiziert,
+wenn Firmware und GUI dieselben Bytes senden und interpretieren.
+
+## Dokumentation mitpflegen
+
+Bei jedem Change die betroffene Fachdokumentation aktualisieren. Zahlen wie
+Structgrößen, Offsets, Chunk-Anzahlen und Flashgrenzen immer aus dem neuen Code
+neu ableiten. Offene oder absichtlich nicht behobene Punkte gehören nach
+[`09_known_limitations.md`](09_known_limitations.md).
+