Added mcu recommendation and merged project-context content from earlier

Added doc
2026-03-30 19:53:34 +02:00 · 2026-03-30 19:52:37 +02:00
10 changed files with 782 additions and 9 deletions
--- a/README.md
+++ b/README.md
@ -3,6 +3,44 @@
 Firmware für das VersaPad v2 Macro-Pad.
 Läuft auf einem **ATSAMD21G17D** (Cortex-M0+), entwickelt mit PlatformIO + Arduino-Framework.

+## Hardware
+
+| Eigenschaft | Detail |
+|---|---|
+| MCU | ATSAMD21**G17D** (Cortex-M0+, 128 KB Flash, 16 KB RAM) |
+| Taktfrequenz | 48 MHz (DFLL, intern – kein externer 32 kHz-Quarz) |
+| Framework | Arduino SAMD Core 1.8.14, PlatformIO |
+| Programmer | Atmel-ICE via SWD (kein Bootloader) |
+
+### Button-Matrix
+
+- **5×5-Matrix** (COL_0–4 × ROW_0–4) = 25 logische Keys
+- **20 Cherry MX Switches** (COL_1–4 × ROW_0–4), je eine WS2812-LED
+- **4 Encoder-SW-Buttons** (COL_0 × ROW_0–3), keine LEDs
+- COL_0 × ROW_4 = nicht belegt
+- **Dioden**: D4148 je Taste, Anode an Switch, Kathode an ROW → Ghost-Key-freies Scannen
+- **Scan-Richtung**: ROW wird OUTPUT LOW getrieben, COL-Leitungen haben 10 kΩ-Pullup nach 3V3 (werden gelesen)
+
+### Rotary Encoder
+
+- 4× Encoder (ENC0 = USB-nah, ENC3 = USB-fern)
+- Alle A/B-Leitungen auf EIC (PA16–PA23), Quadratur-Dekodierung via ISR + 4-State-Lookup
+- Jeder Encoder hat drei Aktionen: **CW**, **CCW**, **SW** (alle aus NVM konfigurierbar)
+
+### LEDs (WS2812)
+
+- 20× WS2812B, serpentinen-verdrahtet (Reihe 0: L→R, Reihe 1: R→L, …)
+- Datenleitung: **PB22 (D18)**, bit-bang via Adafruit NeoPixel Library
+- **LED_INDEX-Formel**: `row * 4 + ((row & 1) ? (4 - col) : (col - 1))`
+- **Pegelproblematik**: WS2812 sind 5V-Devices (HIGH-Schwelle ~3,5 V), SAMD21 liefert 3,3 V ohne Level-Shifter. LED 0 empfängt einen marginal gültigen Pegel; ab LED 1 regeneriert jede LED intern auf 5 V → alle weiteren problemlos. Fix nächste PCB-Revision: Level-Shifter oder Diode in der VDD-Leitung.
+
+### Fader (ADC)
+
+- 3× Linearpotentiometer: PA02 (A0), PA03 (A1, auch VREFA), PB08 (A2)
+- Noch nicht implementiert (siehe Roadmap)
+
+---
+
 ## Voraussetzungen

 - [PlatformIO](https://platformio.org/) (CLI oder VS Code Extension)
@ -151,6 +189,51 @@ VersaMCU/

 ## Architektur

+### Schichten
+
+```
+┌────────────────────────────────────────────────┐
+│  main.cpp                                      │
+│  CMainController (setup / work)                │
+├────────────────────────────────────────────────┤
+│  Modell                                        │
+│  CButton (LED 2-Layer, Action, dirty-Flag)     │
+│  CEventQueue (Ring-Buffer FIFO, 16 Slots)      │
+├────────────────────────────────────────────────┤
+│  HAL                                           │
+│  hal/matrix    – 5×5-Scan, 10 ms Debounce     │
+│  hal/encoder   – Quadratur via EIC-ISR         │
+│  hal/ws2812    – Adafruit NeoPixel bit-bang    │
+│  hal/usb_hid   – HID Keyboard + Consumer       │
+│  hal/usb_serial– CDC Serial bidirektional      │
+├────────────────────────────────────────────────┤
+│  Config                                        │
+│  config/pins.h       – Pin-Mapping             │
+│  config/action.h     – ActionType + SAction    │
+│  config/nvm_config   – Flash R/W, CRC16        │
+└────────────────────────────────────────────────┘
+```
+
+### Datenfluss
+
+```
+HAL (matrix_scan, Encoder-ISR)
+  └─► matrix_cb / encoder_cb
+        └─► CEventQueue.push()
+              └─► CMainController.processEvents()
+                    ├─► CButton.on_press() / on_release()
+                    ├─► execute_action()  →  usb_hid_send_key / send_consumer
+                    └─► usb_serial_send() (nur bei HOST_COMMAND)
+
+SerialUSB (PC → Board, 8-Byte-Pakete)
+  └─► CMainController.poll_vendor()
+        └─► CButton.set_override() / set_base() / clear_override()
+
+CMainController.updateLEDs()
+  └─► CButton.render_led()  →  ws2812_set()
+        └─► ws2812_show() (nur wenn dirty)
+```
+
 ### Loop-Ablauf

 ```
@ -172,16 +255,37 @@ Aktive Farbe = `override` wenn aktiv, sonst `base`. `clear_override()` kehrt sof

 ### LED-Animationen

-| Animation | Verhalten |
-|---|---|
-| `STATIC` | Feste Farbe |
-| `BLINK` | Binäres An/Aus |
-| `PULSE` | Lineares Dreieck 0→255→0 |
-| `FADE_IN / FADE_OUT` | Einmaliges Ein-/Ausblenden |
-| `COLOR_CYCLE` | Hue-Sweep (Regenbogen), ignoriert base/override |
-| `COLOR_FADE` | Crossfade zu Zielfarbe |
+Animationen modulieren die Helligkeit oder Farbe der aktiven Schicht (base oder override). Alle Berechnungen in **Integer-Arithmetik** (Cortex-M0+ hat keine FPU).

-Alle Berechnungen in Integer-Arithmetik (kein FPU auf Cortex-M0+).
+| Animation | Typ | Verhalten | `period_ms`-Semantik |
+|---|---|---|---|
+| `STATIC` | – | Feste Helligkeit (Standardzustand) | – |
+| `BLINK` | Helligkeit | Binäres An/Aus, endlos | Halbperiode (An = Aus) |
+| `PULSE` | Helligkeit | Lineares Dreieck 0→255→0, endlos | Vollperiode |
+| `FADE_IN` | Helligkeit | Einmalig: schwarz → voll, dann STATIC | Dauer |
+| `FADE_OUT` | Helligkeit | Einmalig: voll → schwarz, dann STATIC + base=schwarz | Dauer |
+| `COLOR_CYCLE` | Farbe | Hue-Sweep Regenbogen, endlos, ignoriert base/override | Eine volle Runde |
+| `COLOR_FADE` | Farbe | Einmalig: Crossfade akt. Farbe → Zielfarbe, dann STATIC + base=Ziel | Dauer |
+
+**API:**
+
+```cpp
+set_anim(LEDAnim, period_ms, phase_offset_ms = 0)
+// Für alle Typen außer COLOR_FADE.
+// phase_offset_ms verschiebt den Startpunkt in die Vergangenheit →
+// mehrere LEDs versetzt starten (z. B. Regenbogen-Welle).
+
+set_color_fade(RGB to, period_ms)
+// Startet COLOR_FADE von aktueller Farbe zu `to`.
+
+clear_anim()
+// Sofort zurück zu STATIC (volle Helligkeit).
+
+render_led()
+// Gibt true zurück solange dirty oder Animation läuft → ws2812_show() nötig.
+```
+
+**Idle-Zustand:** Alle 20 MX-LEDs laufen mit `COLOR_CYCLE` (4 s/Runde, 40 % Helligkeit). Der Phasenversatz ist gleichmäßig über alle 20 LEDs verteilt, sodass immer ein vollständiger Regenbogen auf dem Pad liegt.

 **Warum Bit-Bang statt DMA?**

@ -271,3 +375,105 @@ Via Linkerscript reserviert. Bei ungültigem Magic/Version/CRC werden Defaults g
 | `ws2812_show()` blockiert ~600 µs | Dirty-Flag-Pattern: nur aufrufen wenn nötig, nie aus ISR |
 | SAction muss `__attribute__((packed))` haben | Ohne packed: 4B statt 3B → CRC-Mismatch beim Config-Laden |
 | Windows HID-Descriptor-Cache | Bei PID-Änderung Board neu einstecken |
+| `SERCOM5 CTRLB.RXEN` Sync-Bug | `while(SYNCBUSY.bit.CTRLB)` hängt vor ENABLE → nur relevant bei manueller SERCOM5-Konfiguration; nicht im Normalbetrieb |
+| `PluggableUSBModule` nicht nutzbar | `USB_SendControl` / `USB_RecvControl` nicht verlinkt in dieser Core-Version → CDC Serial statt Vendor HID für PC-Kommunikation verwenden |
+| HID-Descriptor vor USB-Enumeration registrieren | Registrierung via globalem Konstruktor (läuft vor `main()`), nicht in `setup()` |
+
+---
+
+## Next-Generation Hardware – MCU-Empfehlung
+
+### Warum der SAMD21G17D an seine Grenzen stößt
+
+| Einschränkung | Auswirkung auf geplante Features |
+|---|---|
+| **128 KB Flash** | Mehrere Profile + lange Makros + OLED-Fonts füllen den Speicher vollständig |
+| **16 KB RAM** | OLED-Framebuffer (128×64 px = 1 KB) + Profil-Puffer + Makro-Tabellen + Stack = kaum Luft |
+| **Kein FPU** | LED-Animationen erfordern Integer-Arithmetik-Workarounds; aufwändigere Effekte unwirtschaftlich |
+| **Kein Ethernet-MAC** | Ethernet nur via langsamen SPI-Chip möglich |
+| **Kein USB High-Speed** | CDC bleibt auf 12 Mbit/s (Full Speed); für schnelle Konfigurationsübertragungen ausreichend, aber kein Spielraum |
+| **WS2812 bit-bang blockiert 600 µs** | Mit mehr LEDs oder höherer Auflösung kritisch; kein DMA ohne SERCOM-Umbau |
+
+---
+
+### Empfehlung: Microchip SAME54P20A
+
+**Primäre Empfehlung** – selber Hersteller, gleicher Toolchain-Stack, deutlich mehr Reserven.
+
+| Merkmal | SAMD21G17D (aktuell) | SAME54P20A (empfohlen) |
+|---|---|---|
+| Kern | Cortex-M0+, 48 MHz | Cortex-M4F, 120 MHz |
+| **FPU** | ✗ | ✓ (single-precision) |
+| **Flash** | 128 KB | **1 MB** |
+| **RAM** | 16 KB | **256 KB** |
+| **USB** | Full Speed (12 Mbit/s) | Full Speed + optionaler HS-PHY |
+| **Ethernet MAC** | ✗ | ✓ (IEEE 802.3, braucht ext. PHY) |
+| **DMA** | 12 Kanäle | 32 Kanäle |
+| SERCOM | 6 | 8 |
+| NVM (intern) | 128 KB | 1 MB (kein ext. Flash nötig) |
+| Preis (LCSC ca.) | ~2 € | ~8–10 € |
+
+**Warum SAME54?**
+- Direkter Upgrade-Pfad: Arduino-Framework, PlatformIO, gleiche HAL-Konzepte
+- Ethernet-MAC integriert → nur externer PHY nötig (z.B. **KSZ8081** oder **LAN8720A**, ~1–2 €)
+- 1 MB Flash reicht für viele Profile, lange Makros und OLED-Font-Tabellen ohne externen Flash
+- 256 KB RAM: OLED-Framebuffer, Profil-Puffer und komplexe Makro-Engines kein Problem
+- FPU: sauberere LED-Animationen, kein Integer-Workaround mehr nötig
+- DMA: WS2812 via SERCOM-SPI + DMA möglich → kein Bit-Bang, keine Interrupt-Sperre
+
+---
+
+### Alternative: Raspberry Pi RP2350
+
+Falls Ethernet nicht zwingend auf dem MCU selbst integriert sein muss (z.B. W5500 via SPI):
+
+| Merkmal | RP2350 |
+|---|---|
+| Kern | Dual Cortex-M33 oder RISC-V, 150 MHz |
+| FPU | ✓ |
+| RAM | **520 KB** SRAM |
+| Flash | Kein interner; ext. QSPI (typ. 2–16 MB) |
+| USB | Full Speed (Device + Host) |
+| Ethernet MAC | ✗ (W5500 via SPI, ~3 €) |
+| PIO | 3 × 4 PIO-Blöcke → WS2812 hardwareseitig ohne CPU |
+| Preis | ~1,50 € |
+
+**Vorteil:** PIO-Blöcke übernehmen WS2812-Timing hardwareseitig (kein bit-bang, kein DMA-Setup). Sehr viel RAM für komplexe Logik. Günstiger als SAME54.
+
+**Nachteil:** Kein integrierter Ethernet-MAC. W5500 übernimmt TCP/IP-Stack per SPI (ausreichend für einfaches HTTP/Telnet-Protokoll), ist aber kein vollwertiger Network-Stack.
+
+---
+
+### System-Architektur für PoE-Betrieb
+
+PoE erfordert unabhängig vom MCU zusätzliche Hardware:
+
+```
+RJ45-Buchse (mit integrierten Magnetics)
+  └─► PoE-PD-Controller  (z.B. TPS2372-4, AG9800)
+        ├─► DC/DC-Wandler  → 3.3V / 5V Versorgung des Boards
+        └─► Ethernet-Signal → MCU-Ethernet-MAC → ext. PHY (LAN8720A / KSZ8081)
+```
+
+Der PoE-PD-Controller ist zwingend: Er verhandelt mit dem PoE-Switch (IEEE 802.3af/at), isoliert galvanisch und liefert geregelte Spannung. Typische PoE-Leistungsklasse 0 (15,4 W) reicht für MCU + LEDs + Display mehrfach aus.
+
+**Empfohlene ICs:**
+
+| Funktion | IC | Preis ca. |
+|---|---|---|
+| PoE PD Controller | AG9800 oder TPS2372-4 | 1–3 € |
+| Ethernet PHY | LAN8720A oder KSZ8081 | 1–2 € |
+| QSPI-Flash (falls RP2350) | W25Q128 (16 MB) | ~0,80 € |
+| OLED Controller | SSD1306 (128×64, I2C/SPI) | im Modul enthalten |
+
+---
+
+### Empfehlung nach Szenario
+
+| Szenario | Empfehlung |
+|---|---|
+| Voller Feature-Umfang (Ethernet-MAC, PoE, Profile, OLED) | **SAME54P20A** + LAN8720A + PoE-PD |
+| Maximale RAM/Flash-Reserve, WS2812 ohne CPU-Last | **RP2350** + W5500 + PoE-PD |
+| Minimaler Footprint, kein Ethernet | **RP2040** (günstiger als RP2350, 264 KB RAM reicht für OLED + Profile) |
+
+Für VersaPad v3 mit allen genannten Features ist der **SAME54P20A** die solideste Wahl: gleicher Hersteller, etablierter Toolchain, integrierter Ethernet-MAC, und der Firmware-Code von v2 (HAL-Struktur, Event-Queue, CButton-Modell) ist weitgehend übertragbar.
--- a/doc/00_architecture.md
+++ b/doc/00_architecture.md
@ -0,0 +1,83 @@
+# VersaMCU – Architektur-Übersicht
+
+## Ziel-Hardware
+
+| Merkmal | Wert |
+|---|---|
+| MCU | ATSAMD21G17D (Cortex-M0+, 48 MHz) |
+| Flash | 128 KB (davon 512 B am Ende für NVM-Config reserviert) |
+| RAM | 16 KB |
+| FPU | Keine – alle Berechnungen in Integer-Arithmetik |
+| USB | Native USB, DFLL48M via USB-SOF-Kalibrierung (`-DCRYSTALLESS`) |
+| Framework | Arduino + PlatformIO, kein Bootloader (Direktflash via SWD/Atmel-ICE) |
+
+## Loop-Ablauf
+
+```
+setup()
+  ├── macro_config_load()   – Makro-Tabelle aus NVM in RAM laden
+  ├── init_buttons()        – CButton-Objekte aus NVM initialisieren
+  ├── usb_hid_init()        – HID-Descriptor (No-Op, läuft via global ctor)
+  ├── usb_serial_init()     – CDC Serial öffnen
+  ├── matrix_init(cb)       – 5×5-Matrix + Debounce-Zustand
+  └── encoder_init(cb)      – EIC-Interrupts für 4 Encoder
+
+loop()  [~20 ms Iteration]
+  ├── matrix_scan()         – Debounce-Zustand prüfen → Events in Queue
+  ├── poll_vendor()         – CDC-Pakete vom PC verarbeiten (LED-Cmds, Config, Makros)
+  ├── processEvents()       – Queue leeren: Aktionen ausführen, HOST_COMMAND melden
+  └── updateLEDs()          – Dirty-CButtons → WS2812-Buffer → show() (nur wenn dirty)
+```
+
+Encoder-ISRs laufen asynchron (CHANGE-Interrupt auf A und B) und schreiben direkt in die Event-Queue. Die Queue ist interrupt-sicher (keine Locks nötig auf Single-Core-M0+).
+
+## Datenfluss
+
+```
+HAL-Callbacks (matrix_cb, encoder_cb)
+  └─► CEventQueue (16 Slots, Ring-Buffer, kein Heap)
+        └─► processEvents()
+              ├─► CButton.on_press() / on_release()   [Hooks, aktuell leer]
+              ├─► execute_action()  →  USB HID / Makro-Ablauf
+              └─► usb_serial_send() →  HOST_COMMAND-Events an PC
+
+SerialUSB (CDC, PC → Board)
+  └─► poll_vendor()
+        ├─► CButton.set_override() / clear_override() / set_base()
+        └─► Config/Makro-Transfer (chunked, 6 B/Paket)
+```
+
+## Komponenten-Übersicht
+
+| Datei | Verantwortung |
+|---|---|
+| `main.cpp` | `setup()` / `loop()` – ruft nur CMainController auf |
+| `CMainController` | Zentraler Orchestrator, hält alle CButton-Instanzen |
+| `CButton` | LED-Layering, Animations-Engine, Action-Referenz |
+| `CEventQueue` | ISR-sicherer Ring-Buffer, 16 Events |
+| `hal/matrix` | 5×5-Matrix-Scan, 10 ms Debounce |
+| `hal/encoder` | Quadratur-Dekodierung via EIC-ISR |
+| `hal/ws2812` | Thin Wrapper um Adafruit NeoPixel (bit-bang) |
+| `hal/usb_hid` | HID Keyboard + Consumer Control |
+| `hal/usb_serial` | CDC bidirektional, 8-Byte-Pakete, Ring-Buffer |
+| `config/nvm_config` | SDeviceConfig: laden, speichern, CRC16, Defaults |
+| `config/macro_config` | SMacroTable: laden, speichern (NVM Row 1) |
+| `config/action` | SAction-Struct + ActionType-Enum |
+
+## Key-ID-Schema
+
+```
+key_id 0–3   : Encoder-SW-Buttons (COL_0 × ROW_0–3), kein LED
+key_id 4     : nicht belegt (COL_0 × ROW_4)
+key_id 5–24  : MX-Buttons (COL_1–4 × ROW_0–4), je ein WS2812-LED
+```
+
+LED-Index folgt serpentiner Verdrahtung: `LED_INDEX(col, row)`.
+
+## Invarianten / Constraints
+
+- **Kein Heap**: kein `new`/`malloc` – alle Objekte statisch oder als Felder in CMainController.
+- **Kein Float**: Cortex-M0+ hat keine FPU; Float würde per Software emuliert (~10–20× langsamer).
+- **Packed Structs**: `SAction` und `SDeviceConfig` sind `__attribute__((packed))` damit die Byte-Größen mit der C#-Serialisierung in VersaGUI übereinstimmen.
+- **Aligned NVM-Writes**: `nvm_write_page` castet Pointer zu `uint32_t*`; Puffer müssen vor dem Aufruf in `__attribute__((aligned(4)))`-Variablen kopiert werden (sonst HardFault auf M0+).
+- **DTR-Check**: `usb_serial_send()` prüft ob SerialUSB aktiv ist, bevor Bytes gesendet werden.
--- a/doc/01_matrix.md
+++ b/doc/01_matrix.md
@ -0,0 +1,45 @@
+# Tasten-Matrix
+
+**Dateien:** `hal/matrix.h`, `hal/matrix.cpp`, `config/pins.h`
+
+## Hardware
+
+5×5-Matrix mit externer 10-kΩ-Pullup-Beschaltung auf den COL-Leitungen (immer HIGH im Ruhezustand). Dioden zwischen Schalter-DO und ROW-Leitung (Anode = Schalter, Kathode = ROW) verhindern Geistertasten bei Mehrfachdrücken.
+
+Scan-Prinzip: ROW LOW treiben → gedrückter Schalter zieht zugehörige COL durch Diode auf LOW.
+
+## Scan-Logik
+
+```
+für jede ROW r:
+    ROW r → OUTPUT LOW
+    warte 10 µs  (Einschwingen)
+    für jede COL c:
+        raw = (digitalRead(COL[c]) == LOW)
+        Debounce prüfen
+    ROW r → INPUT (hochohmig, Pullup-Freigabe)
+```
+
+ROW-Pins wechseln zwischen OUTPUT-LOW (während Scan) und INPUT (hochohmig) – kein dauerhaftes LOW.
+
+## Debounce
+
+- **10 ms**, Software-seitig pro Taste
+- Flanken-Erkennung: Zustandsänderung (raw) wird mit Timestamp notiert
+- Erst nach 10 ms stabiler neuer Zustand wird `s_debounced` aktualisiert und der Callback aufgerufen
+- Callback: `matrix_cb(key_id, pressed)` → `CEventQueue::push(KEY_DOWN / KEY_UP)`
+
+## Key-ID-Berechnung
+
+```cpp
+key_id = col * MATRIX_ROWS + row
+// col 0–4, row 0–4
+// key_id 0–4: Encoder-SW (COL_0)
+// key_id 5–24: MX-Buttons (COL_1–4)
+```
+
+## Kontext
+
+- Läuft im Loop-Kontext (kein ISR)
+- Encoder-SW-Tasten gehen durch denselben Matrix-Pfad (COL_0)
+- `matrix_scan()` wird einmal pro `loop()` aufgerufen
--- a/doc/02_encoder.md
+++ b/doc/02_encoder.md
@ -0,0 +1,44 @@
+# Quadratur-Encoder
+
+**Dateien:** `hal/encoder.h`, `hal/encoder.cpp`, `config/pins.h`
+
+## Hardware
+
+4 mechanische Quadratur-Encoder mit je 2 Phasen-Pins (A, B). Pins sind INPUT_PULLUP.
+Encoder-SW-Tasten laufen **nicht** durch diesen HAL, sondern durch den Matrix-Scan (COL_0).
+
+## Dekodierung
+
+4-State-Lookup-Table über `(prev_state << 2) | cur_state`:
+
+```
+Zustand = (A << 1) | B  →  4 Bits: 00 / 01 / 10 / 11
+LUT[prev<<2 | cur] → +1 (CW), -1 (CCW), 0 (ungültig/Prellen)
+```
+
+Mechanische Encoder erzeugen 4 Flanken pro Raste → Akkumulator zählt Halbschritte.
+Ein Event wird erst gefeuert wenn `|accum| >= 4` (= ein vollständiger Klick).
+
+## ISR-Aufbau
+
+8 ISR-Wrapper (je einer pro Pin, da `attachInterrupt` keinen Parameter unterstützt):
+
+```cpp
+static void isr_enc0_a() { handle_encoder(0); }
+static void isr_enc0_b() { handle_encoder(0); }
+// ... analog für Encoder 1–3
+```
+
+`attachInterrupt(..., CHANGE)` auf beiden Pins jedes Encoders.
+
+`handle_encoder()` → `encoder_cb(enc_id, direction)` → `CEventQueue::push(ENC_CW / ENC_CCW)`
+
+## ISR-Sicherheit
+
+- `s_state[]` und `s_accum[]` sind `volatile`
+- `CEventQueue::push()` ist ISR-sicher (atomare Index-Inkremente auf Single-Core-M0+, kein Heap)
+- Der Callback-Pointer `s_cb` wird einmalig in `setup()` gesetzt, bevor Interrupts aktiviert werden
+
+## Initialisierung
+
+Initialer Zustand von A/B wird beim `encoder_init()` gelesen damit der erste Interrupt korrekt ausgewertet wird (kein "Phantom-Step" beim Einschalten).
--- a/doc/03_action_engine.md
+++ b/doc/03_action_engine.md
@ -0,0 +1,70 @@
+# Aktions-Engine
+
+**Dateien:** `config/action.h`, `CMainController.cpp` (`processEvents`, `execute_action`)
+
+## SAction-Struct
+
+```cpp
+struct __attribute__((packed)) SAction {
+    ActionType type;   // 1 Byte
+    uint16_t   data;   // 2 Bytes (Keycode, Consumer-Code, Command-ID oder Slot-Index)
+};
+// Gesamt: 3 Bytes (packed! ohne packed wären es 4 durch Alignment)
+```
+
+`packed` ist zwingend damit `sizeof(SDeviceConfig) == 223` mit der C#-Serialisierung in VersaGUI übereinstimmt.
+
+## ActionType
+
+| Typ | Bedeutung | data-Inhalt |
+|---|---|---|
+| `NONE` | Keine Aktion | — |
+| `HID_KEY` | Tastendruck via USB HID Keyboard | Low-Byte = HID Keycode, High-Byte = Modifier |
+| `HID_CONSUMER` | Consumer Control (Volume, Media, …) | Consumer Usage ID |
+| `HOST_COMMAND` | Event an VersaGUI senden, App führt aus | Command-ID (frei definiert) |
+| `MACRO` | Makro-Sequenz aus NVM-Tabelle | Slot-Index 0–31 |
+
+## Ausführung (execute_action)
+
+**HID_KEY:**
+```
+usb_hid_send_key(keycode, modifier)
+delay(10 ms)
+usb_hid_release_key()
+```
+→ Tap-Only-Modell. Kein Hold-Support. KEY_UP löst kein HID-Release aus.
+
+**HID_CONSUMER:**
+```
+usb_hid_send_consumer(usage_id)
+usb_hid_release_consumer()
+```
+→ Kein Delay nötig (Consumer-Keys sind Edge-getriggert).
+
+**HOST_COMMAND:**
+`execute_action()` macht nichts. `processEvents()` sendet zusätzlich `USB_EVT_KEY_DOWN` via CDC Serial an VersaGUI. Die App entscheidet was passiert (URL öffnen, Programm starten, …).
+
+**MACRO:**
+```
+für jeden Step [0–3] im Slot:
+    if keycode == 0: abbrechen
+    usb_hid_send_key(keycode, modifier)
+    delay(10 ms)
+    usb_hid_release_key()
+    delay(20 ms)   // Pause damit der Host den Step verarbeiten kann
+```
+
+## Event-Verarbeitung
+
+Events werden in `processEvents()` aus `CEventQueue` konsumiert (FIFO):
+
+- `KEY_DOWN` → `CButton.on_press()` (aktuell leer, Erweiterungspunkt) + `execute_action()`
+- `KEY_UP`   → `CButton.on_release()` (aktuell leer)
+- `ENC_CW/CCW` → `execute_action(m_enc_cw/ccw[enc_id])`
+
+Encoder CW/CCW-Aktionen sind in `CMainController` direkt als `SAction`-Arrays gehalten (kein CButton-Objekt, da Encoder keine LED haben).
+
+## Bekannte Einschränkungen
+
+- **Kein Hold**: `execute_action` bei KEY_DOWN sendet sofort Key-Down + Key-Up. Halten der Taste löst keine Wiederholung aus.
+- **HOST_COMMAND KEY_UP**: Board sendet derzeit kein `USB_EVT_KEY_UP` für KEY_UP-Events (nur KEY_DOWN wird gemeldet).
--- a/doc/04_macro_system.md
+++ b/doc/04_macro_system.md
@ -0,0 +1,59 @@
+# Makro-System
+
+**Dateien:** `config/macro_config.h`, `config/macro_config.cpp`, `CMainController.cpp`
+
+## Datenstruktur
+
+```cpp
+struct __attribute__((packed)) SMacroStep {
+    uint8_t keycode;    // HID Keyboard Usage (0x00 = leer → Step überspringen)
+    uint8_t modifier;   // HID Modifier: Ctrl=0x01, Shift=0x02, Alt=0x04, GUI=0x08
+};
+
+struct __attribute__((packed)) SMacroTable {
+    SMacroStep steps[32][4];   // 32 Slots × 4 Steps × 2 Byte = 256 Byte
+};
+```
+
+Beide Structs sind `packed` (kein Padding). `sizeof(SMacroTable) == 256 == eine NVM-Row`.
+
+## NVM-Speicherort
+
+- **Row 1**: Adresse `0x1FF00`, 256 Byte
+- Vom Linkerscript reserviert (nicht überschreibbar durch Code)
+- Gelöschter Flash (`0xFF`-Bytes) → `macro_config_load()` gibt false zurück → leere Tabelle (alle Keycodes 0)
+
+## Slot-Zuweisung (Konvention, Board speichert blind)
+
+| Slots | Verwendung |
+|---|---|
+| 0–19 | MX-Button `mx_idx` (entspricht key_id − 5) |
+| 20–31 | Encoder-Aktionen (`enc * 3 + act_idx`, 0=SW / 1=CW / 2=CCW) |
+
+## Laden und Speichern
+
+**Laden** (`macro_config_load`):
+- `memcpy` direkt aus Flash-Adresse in RAM-Struct
+- Kein Magic/CRC (leere Tabelle bei 0xFF ist akzeptabler Zustand)
+
+**Speichern** (`macro_config_save`):
+- SMacroTable in `uint8_t aligned_buf[256] __attribute__((aligned(4)))` kopieren (Pflicht!)
+- `NVMCTRL->CTRLB.bit.MANW = 1` (manueller Schreib-Modus)
+- Row 1 löschen (`nvm_erase_row`)
+- 4 Pages à 64 Byte schreiben (`nvm_write_page`)
+
+> **Warum aligned_buf?** `nvm_write_page` castet den Pointer zu `volatile uint32_t*`. Wenn `&tbl` nicht 4-Byte-aligned ist (möglich bei packed struct), entsteht ein HardFault auf Cortex-M0+ (kein unaligned 32-Bit-Zugriff auf Peripherie-Adressen).
+
+## Ausführung (in execute_action, ActionType::MACRO)
+
+```
+slot = action.data  (0–31)
+für Step 0–3:
+    if step.keycode == 0: abbrechen
+    HID Key-Down (keycode, modifier)
+    delay(10 ms)
+    HID Key-Up
+    delay(20 ms)
+```
+
+Die Makro-Tabelle liegt nach `setup()` im RAM (`m_macros` in CMainController). Kein NVM-Zugriff während der Ausführung.
--- a/doc/05_led_system.md
+++ b/doc/05_led_system.md
@ -0,0 +1,88 @@
+# LED-System (WS2812)
+
+**Dateien:** `hal/ws2812.h`, `hal/ws2812.cpp`, `CButton.h`, `CButton.cpp`
+
+## Hardware-Treiber (ws2812 HAL)
+
+Dünner Wrapper um **Adafruit NeoPixel** (bit-bang, kein DMA, kein SERCOM).
+
+| Funktion | Bedeutung |
+|---|---|
+| `ws2812_init()` | `begin()` + `clear()` + `show()` |
+| `ws2812_set(idx, r, g, b)` | `setPixelColor()` – schreibt in RAM-Puffer |
+| `ws2812_fill(r, g, b)` | Alle LEDs gleiche Farbe |
+| `ws2812_show()` | Bit-Bang-Übertragung (~600 µs, Interrupts gesperrt) |
+| `ws2812_clear()` | `clear()` + `show()` |
+
+`ws2812_show()` wird in `CMainController::updateLEDs()` **nur** aufgerufen wenn mindestens ein Button dirty war – 600 µs Blockzeit werden so vermieden wenn keine Änderung nötig ist.
+
+**Warum kein DMA?** DMA + SERCOM-SPI würde ~1,5 KB extra RAM (1440 Byte Kodier-Puffer) und erhebliche Implementierungskomplexität erfordern. Bei 20 LEDs und ~20 ms Loop-Rate sind 600 µs gesperrte Interrupts (= 3 % der Loop-Zeit) unkritisch.
+
+## 2-Schicht-Modell (CButton)
+
+Jeder MX-Button hat zwei LED-Schichten:
+
+```
+override (aktiv wenn set_override() aufgerufen)  ← temporär (GUI-Benachrichtigungen)
+base     (Idle-Farbe aus NVM)                    ← dauerhaft
+```
+
+Aktive Farbe = `override` wenn aktiv, sonst `base`. `clear_override()` kehrt sofort zu `base` zurück, ohne base zu verändern.
+
+## Animationen
+
+| Animation | Typ | Verhalten | Endbedingung |
+|---|---|---|---|
+| `STATIC` | — | Feste Farbe | — |
+| `BLINK` | Helligkeit | An/Aus, `period_ms` = Halbperiode | endlos |
+| `PULSE` | Helligkeit | Lineares Dreieck 0→255→0 | endlos |
+| `FADE_IN` | Helligkeit | Einmalig schwarz → voll | → STATIC (voll) |
+| `FADE_OUT` | Helligkeit | Einmalig voll → schwarz | → STATIC (base=schwarz) |
+| `COLOR_CYCLE` | Farbe | Hue-Sweep, ignoriert base/override | endlos |
+| `COLOR_FADE` | Farbe | Crossfade from→to | → STATIC (base=to) |
+
+**Helligkeits-Animationen** (`compute_scale`): Multiplizieren die aktive Farbe mit einem Skalierungsfaktor 0–255. Formel: `(channel * scale) / 255`.
+
+**Farb-Animationen** (`compute_rgb`): Berechnen RGB direkt; base/override werden nicht verändert (außer bei Abschluss).
+
+### COLOR_CYCLE – Hue-Arithmetik (kein Float)
+
+Hue 0–255 aufgeteilt in 6 Segmente à 43 Einheiten. Innerhalb jedes Segments steigt/fällt ein Kanal linear:
+
+```
+Seg 0: R=255, G steigt     (Rot → Gelb)
+Seg 1: R fällt, G=255      (Gelb → Grün)
+Seg 2: G=255, B steigt     (Grün → Cyan)
+Seg 3: G fällt, B=255      (Cyan → Blau)
+Seg 4: B=255, R steigt     (Blau → Magenta)
+Seg 5: R=255, B fällt      (Magenta → Rot)
+```
+
+Ausgabe wird auf 40 % Helligkeit skaliert (Faktor 102/255) damit die LEDs nicht blenden.
+
+`Adafruit_NeoPixel::ColorHSV()` ist nicht nutzbar: verwendet intern float (kein FPU auf M0+).
+
+### Phasenversatz (Regenbogen-Wellen)
+
+`set_anim(COLOR_CYCLE, period, phase_offset_ms)`: `m_anim_start_ms = millis() - phase_offset_ms`. Die 20 MX-Buttons werden in `init_buttons()` gleichmäßig phasenverschoben initialisiert:
+
+```cpp
+uint16_t phase = (mx_idx * period) / 20;
+```
+
+## Render-Pipeline
+
+```
+CMainController::updateLEDs()
+  für jeden CButton:
+    CButton::render_led()
+      if !dirty && !is_animating(): return false
+      rgb = compute_rgb()
+      ws2812_set(led_index, rgb.r, rgb.g, rgb.b)
+      dirty = false
+      return true
+  if any returned true:
+    ws2812_show()
+```
+
+`dirty` wird gesetzt bei: `init()`, `set_base()`, `set_override()`, `clear_override()`, `set_anim()`, `clear_anim()`, Animations-Abschluss.
--- a/doc/06_nvm_config.md
+++ b/doc/06_nvm_config.md
@ -0,0 +1,68 @@
+# NVM-Konfiguration
+
+**Dateien:** `config/nvm_config.h`, `config/nvm_config.cpp`
+
+## Flash-Layout
+
+| Row | Adresse | Größe | Inhalt |
+|---|---|---|---|
+| Row 0 | `0x1FE00` | 256 B | SDeviceConfig (223 B genutzt, 33 B Padding) |
+| Row 1 | `0x1FF00` | 256 B | SMacroTable (256 B, komplett genutzt) |
+
+Beide Rows sind im Linkerscript vom Code-Bereich ausgeschlossen.
+
+## SDeviceConfig – Byte-Layout (223 Byte, packed)
+
+| Offset | Größe | Feld |
+|---|---|---|
+| 0 | 4 | `magic` = `0x56503202` ('VP2\x02') |
+| 4 | 1 | `version` = 2 |
+| 5 | 2 | `crc` – CRC16-CCITT über Bytes 7–222 |
+| 7 | 60 | `mx_actions[20]` – 20 × 3 B SAction |
+| 67 | 36 | `enc_actions[4][3]` – 12 × 3 B SAction |
+| 103 | 20 | `led_r[20]` |
+| 123 | 20 | `led_g[20]` |
+| 143 | 20 | `led_b[20]` |
+| 163 | 20 | `led_anim[20]` – LEDAnim-Typ als uint8_t |
+| 183 | 40 | `led_period_ms[20]` – uint16_t, little-endian |
+| **223** | — | Ende des genutzten Bereichs |
+
+`__attribute__((packed))` ist zwingend. Ohne packed wäre SAction 4 B statt 3 B (Alignment-Padding), was `sizeof(SDeviceConfig)` um 32 B vergrößert und die C#-Deserialisierung in VersaGUI zerstört.
+
+## CRC16-CCITT
+
+- Polynom: `0x1021`, Init: `0xFFFF`
+- Berechnet über Bytes 7–222 (ab `mx_actions`, nach dem `crc`-Feld selbst)
+- Sichert Datenintegrität nach NVM-Schreiben und bei Versionswechsel
+
+## Lese-Logik
+
+```
+memcpy aus Flash-Adresse 0x1FE00
+if magic != 0x56503202: Defaults laden, return false
+if version != 2:        Defaults laden, return false
+if crc != crc(cfg):     Defaults laden, return false
+return true
+```
+
+Kein Absturz bei ungültiger Config – Defaults greifen immer.
+
+## Defaults
+
+- Alle Aktionen: `NONE`
+- LEDs: warm-weiß (R=80, G=40, B=0)
+- Animation: `COLOR_CYCLE` (Typ 5), Period 4000 ms
+
+## Schreib-Logik (NVM-Mechanik)
+
+SAMD21 NVM: Row = 256 B = 4 Pages à 64 B. Schreiben erfordert:
+1. `NVMCTRL->CTRLB.bit.MANW = 1` (manueller Schreib-Modus, kein Auto-Write)
+2. Row löschen (`NVMCTRL_CTRLA_CMD_ER`)
+3. Page-Buffer löschen (`NVMCTRL_CTRLA_CMD_PBC`)
+4. 64 B als `uint32_t*` in Page-Buffer schreiben
+5. Page programmieren (`NVMCTRL_CTRLA_CMD_WP`)
+6. Schritte 3–5 viermal (für alle 4 Pages)
+
+> `NVMCTRL->ADDR.reg = addr / 2` – NVMCTRL erwartet Wort-Adresse (16-Bit-Worte), nicht Byte-Adresse.
+
+> **Aligned-Buffer-Pflicht**: `nvm_write_page` castet `data` zu `const uint32_t*`. Der Puffer muss `__attribute__((aligned(4)))` sein. Packed Structs sind nicht garantiert aligned → immer via lokalen `uint8_t buf[256] __attribute__((aligned(4)))` + `memcpy` übergeben.
--- a/doc/07_serial_protocol.md
+++ b/doc/07_serial_protocol.md
@ -0,0 +1,86 @@
+# Serial-Protokoll (CDC USB)
+
+**Dateien:** `hal/usb_serial.h`, `hal/usb_serial.cpp`
+
+## Grundprinzip
+
+Board erscheint unter Windows als CDC Serial-Port (kein Treiber nötig). Alle Pakete haben feste Größe von **8 Byte** – kein Längen-Header, kein Framing, kein Escape.
+
+```
+Byte 0: Command / Event-ID
+Byte 1: key_id (Button 0–24 oder Encoder 0–3) / Chunk-Index / Chunk-Count
+Byte 2: r / Daten-Byte A
+Byte 3: g / Daten-Byte B
+Byte 4: b
+Byte 5–7: reserviert (0x00)
+```
+
+## Richtungen
+
+| Richtung | ID-Bereich | Verarbeitung |
+|---|---|---|
+| PC → Board (Commands) | 0x01–0x7F | `poll_vendor()` in CMainController |
+| Board → PC (Events) | 0x81–0xFF | `usb_serial_send()` in processEvents |
+
+## Command-Referenz (PC → Board)
+
+| ID | Name | Bedeutung |
+|---|---|---|
+| `0x01` | SET_LED_OVERRIDE | key_id, r, g, b – temporäre Override-Farbe setzen |
+| `0x02` | CLEAR_LED_OVERRIDE | key_id – Override löschen, zurück zu base |
+| `0x03` | SET_LED_BASE | key_id, r, g, b – base-Farbe dauerhaft ändern (kein NVM) |
+| `0x05` | PING | Board antwortet sofort mit PONG (0x85) |
+| `0x10` | CONFIG_BEGIN | Byte[1] = Chunk-Anzahl – neuen Config-Empfang starten |
+| `0x11` | CONFIG_DATA | Byte[1] = Chunk-Index, Byte[2–7] = 6 B Nutzdaten |
+| `0x12` | CONFIG_COMMIT | CRC prüfen → NVM schreiben → Buttons neu laden → ACK/NACK |
+| `0x13` | CONFIG_READ | Board sendet aktuelle NVM-Config zurück (BEGIN/DATA/END) |
+| `0x20` | MACRO_BEGIN | Byte[1] = Chunk-Anzahl – neuen Makro-Empfang starten |
+| `0x21` | MACRO_DATA | Byte[1] = Chunk-Index, Byte[2–7] = 6 B Nutzdaten |
+| `0x22` | MACRO_COMMIT | NVM schreiben + MACRO_ACK zurück |
+| `0x23` | MACRO_READ | Board sendet aktuelle Makro-Tabelle zurück |
+
+## Event-Referenz (Board → PC)
+
+| ID | Name | Bedeutung |
+|---|---|---|
+| `0x81` | KEY_DOWN | key_id – HOST_COMMAND-Button gedrückt |
+| `0x82` | KEY_UP | key_id – (derzeit nicht gesendet) |
+| `0x83` | ENC_CW | enc_id – Encoder-Schritt CW (HOST_COMMAND) |
+| `0x84` | ENC_CCW | enc_id – Encoder-Schritt CCW (HOST_COMMAND) |
+| `0x85` | PONG | Antwort auf PING |
+| `0x90` | CONFIG_ACK | Config erfolgreich in NVM geschrieben |
+| `0x91` | CONFIG_NACK | Config CRC/Magic ungültig – nicht geschrieben |
+| `0x92` | CONFIG_BEGIN | Byte[1] = Chunk-Anzahl (Config-Dump) |
+| `0x93` | CONFIG_DATA | Byte[1] = Index, Byte[2–7] = 6 B (Config-Dump) |
+| `0x94` | CONFIG_END | Config-Dump abgeschlossen |
+| `0x95` | MACRO_ACK | Makro-Tabelle erfolgreich gespeichert |
+| `0x96` | MACRO_BEGIN | Byte[1] = Chunk-Anzahl (Makro-Dump) |
+| `0x97` | MACRO_DATA | Byte[1] = Index, Byte[2–7] = 6 B (Makro-Dump) |
+| `0x98` | MACRO_END | Makro-Dump abgeschlossen |
+
+## Chunked Transfer
+
+Config (223 B) und Makro-Tabelle (256 B) werden in 6-Byte-Chunks übertragen:
+
+```
+Config:  ceil(223 / 6) = 38 Chunks
+Makros:  ceil(256 / 6) = 43 Chunks (letzter Chunk hat 4 Nutzbytes)
+```
+
+Ablauf (PC → Board):
+```
+BEGIN (chunk_count)
+DATA chunk_0  (Bytes 0–5)
+DATA chunk_1  (Bytes 6–11)
+...
+COMMIT
+```
+
+COMMIT bei Config: Board prüft Magic + Version + CRC. Bei Fehler → NACK, kein NVM-Schreiben.
+COMMIT bei Makro: Kein CRC, Board schreibt blind → MACRO_ACK.
+
+## Implementierungsdetails
+
+- **Ring-Buffer**: 256 Byte Eingangspuffer (= 32 vollständige Pakete) in `usb_serial.cpp`
+- **DTR-Check**: `usb_serial_send()` sendet nur wenn `SerialUSB` aktiv ist (verhindert stilles Verwerfen wenn VersaGUI nicht verbunden)
+- **SAMD21 CDC**: Nach SWD-Flash braucht Windows eine physische USB-Reinitialisierung (Kabel abziehen/stecken) damit der CDC-Port neu enumeriert
--- a/doc/INDEX.md
+++ b/doc/INDEX.md
@ -0,0 +1,24 @@
+# VersaMCU – Dokumentations-Index
+
+Jede Datei deckt eine Firmware-Komponente ab. Für Claude: die relevante(n) Dateien zu Beginn einer Aufgabe lesen statt die gesamten Quelldateien zu scannen.
+
+| Datei | Inhalt |
+|---|---|
+| [00_architecture.md](00_architecture.md) | Loop-Ablauf, Datenfluss, Key-ID-Schema, globale Invarianten (kein Heap, kein Float, packed Structs, aligned NVM) |
+| [01_matrix.md](01_matrix.md) | 5×5-Scan, Debounce, Key-ID-Berechnung |
+| [02_encoder.md](02_encoder.md) | Quadratur-Dekodierung, LUT, ISR-Aufbau, Halbschritt-Akkumulator |
+| [03_action_engine.md](03_action_engine.md) | SAction-Struct, ActionType, execute_action, Tap-Only-Modell, HOST_COMMAND-Pfad |
+| [04_macro_system.md](04_macro_system.md) | SMacroTable, NVM Row 1, Slot-Konvention, aligned-Buffer-Pflicht |
+| [05_led_system.md](05_led_system.md) | 2-Schicht-Modell, alle Animationen, Hue-Arithmetik (kein Float), Render-Pipeline, Bit-Bang vs. DMA |
+| [06_nvm_config.md](06_nvm_config.md) | Flash-Layout, SDeviceConfig-Byte-Map, CRC16-CCITT, Schreib-Mechanik, Defaults |
+| [07_serial_protocol.md](07_serial_protocol.md) | 8-Byte-Pakete, alle Command/Event-IDs, Chunked Transfer, Ring-Buffer |
+
+## Schnell-Referenz: Was steht wo?
+
+- **Warum packed?** → [03_action_engine.md](03_action_engine.md), [06_nvm_config.md](06_nvm_config.md)
+- **Warum kein Float?** → [05_led_system.md](05_led_system.md), [00_architecture.md](00_architecture.md)
+- **Warum Bit-Bang statt DMA?** → [05_led_system.md](05_led_system.md)
+- **Aligned-Buffer bei NVM-Write?** → [04_macro_system.md](04_macro_system.md), [06_nvm_config.md](06_nvm_config.md)
+- **Warum on_press/on_release leer?** → [03_action_engine.md](03_action_engine.md)
+- **Kein Hold-Support?** → [03_action_engine.md](03_action_engine.md)
+- **USB nach SWD-Flash nicht erkannt?** → [07_serial_protocol.md](07_serial_protocol.md)
Author	SHA1	Message	Date
Julian Appel	d6ed7cb81f	Added mcu recommendation and merged project-context content from earlier	2026-03-30 19:53:34 +02:00
Julian Appel	9079fefad8	Added doc	2026-03-30 19:52:37 +02:00