# 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
- das benachbarte Repository `../VersaGUI`, 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

Für die Firmware gibt es 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 separates Git-Repository im selben Workspace. Änderungen an
`SDeviceConfig`, `SMacroTable`, Action-Werten oder USB-IDs sind erst
vollständig verifiziert, wenn Firmware und `../VersaGUI` dieselben Bytes
senden und interpretieren. `DelphiGUI` gehört nicht zum gepflegten Scope.
Die automatisierten GUI-Vertragstests liegen unter
`../VersaGUI/tests/VersaGUI.ContractTests/`.

## 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).