VersaMCU/doc/09_known_limitations.md

# Bekannte Einschränkungen und Risiken

Diese Liste beschreibt den aktuellen Implementierungsstand nach den
Robustheitskorrekturen. Sie ist keine Liste bereits umgesetzter Features.

## Bootloader-Ziel bleibt nicht unterstützt

Das aktive Ziel `versapad_nobl` reserviert den kompletten Bereich
`0x1FB00..0x1FFFF` für Makros und Config.

Ein USB-Bootloader-Pfad wird im Branch `feature/usb-bootloader` aufgebaut
(`bootloader/`, App-Environment `env:versapad_usb`). Der Bootloader selbst
(UF2, `bootloader/`) ist dort auf echter Hardware verifiziert — inklusive
eines gefundenen und behobenen Bugs beim Sprung in die App (fehlende
`__DSB()`/`__ISB()` vor dem `bx`, siehe `bootloader/README.md`,
"Hardwaretest"). `env:versapad_usb`s Linkerskript
(`variants/versapad/linker_scripts/gcc/flash_with_bootloader.ld`) reserviert
inzwischen denselben NVM-Bereich wie `flash_without_bootloader.ld`.

Trotzdem noch kein Produktionsziel: `env:versapad_usb` verwendet
`upload_protocol = sam-ba`, das klassische Arduino/Atmel-SAM-BA-Protokoll —
das spricht der UF2-Bootloader nicht. Die App-Firmware erzeugt außerdem noch
keine `.uf2`-Datei. Vor einem Merge nach `master` fehlen also noch die
`.uf2`-Erzeugung und ein Ende-zu-Ende-Test des tatsächlichen USB-Flashwegs
(Datei aufs `VERSABOOT`-Laufwerk kopieren).

Die aktive Boarddatei benennt die MCU als `samd21g17d`, setzt für den
Arduino-Core aber weiterhin das Kompatibilitätsmakro `__SAMD21G18A__`. Der
PlatformIO-Build meldet korrekt 128 KiB physischen Flash, 16 KiB RAM und
129.792 Byte nutzbaren Firmwarebereich. Vor device-spezifischen
Core-Änderungen sollte die historische Makro-Abweichung trotzdem geprüft
werden.

## Event-Queue hat eine feste Kapazität

Matrix- und Encoder-Producer verändern den Tail-Index nicht mehr gleichzeitig:
Der Matrixcallback maskiert Interrupts während seines Queue-Pushs.

Die Queue besitzt aber weiterhin nur 16 nutzbare Slots. Bei Überlauf wird ein
neues Event ohne Hostmeldung verworfen. Das kann vor allem während
blockierender Makro-, NVM- oder Feedbackpfade auftreten.

## Host-Command-Ausführung liegt in der Desktop-App

Die Firmware überträgt Command-ID, Key-/Encoder-ID und Eventrichtung
vollständig. VersaGUI validiert und empfängt diese Pakete, führt eine
Command-ID aber noch nicht als Prozess-, URL- oder frei konfigurierbare
Hostaktion aus. Eine spätere Implementierung benötigt ein explizites,
sicheres Mapping; beliebige Command-Strings sollten nicht direkt an eine Shell
weitergegeben werden.

## Grenzen des HID-Reports

Keyboard-Holds und Modifier werden referenzgezählt. Der USB-Descriptor kann
maximal sechs unterschiedliche Keyboard-Usages gleichzeitig darstellen.
Weitere Holds bleiben intern aktiv und rücken nach, sobald ein Report-Slot
frei wird.

Der Consumer-Descriptor enthält genau ein Usage. Mehrere Consumer-Holds werden
intern verwaltet, sichtbar ist jeweils das zuletzt gedrückte aktive Usage.

## CDC bleibt ein festes, ungeframtes Paketprotokoll

Config- und Makrotransfers prüfen jetzt Chunkzahl, eindeutige Indizes und
Vollständigkeit. Config besitzt zusätzlich CRC und Feldvalidierung.

Weiterhin gilt:

- Das Protokoll hat kein Byte-Framing. Ein verlorenes oder zusätzliches Byte
  verschiebt die 8-Byte-Paketgrenzen bis zum Reconnect.
- Einzelpakete besitzen keine Sequenznummer oder Prüfsumme.
- Die Makrotabelle besitzt im NVM keine persistente CRC; beim Transfer werden
  nur Vollständigkeit und HID-Keycode-Bereiche geprüft.

## Farbanimationen und Helligkeit

Globale und LED-spezifische Helligkeit werden beim Laden in die Base-Farbe
eingerechnet. `COLOR_CYCLE` berechnet RGB dagegen direkt mit festen 40 %
Helligkeit und ignoriert Base-Farbe sowie Override.

`COLOR_FADE` aus der Config wird als einmaliger Fade von Schwarz zur
gespeicherten Base-Farbe interpretiert.

## Reservierte beziehungsweise noch ungenutzte Hardware und Felder

- Die drei Fader-Pins sind im Variant und in `config/pins.h` definiert, werden
  absichtlich noch nicht von der Firmware eingelesen.
- `enc_sensitivity[4]` wird gespeichert und mit Default `1` befüllt,
  beeinflusst die Encoderdekodierung derzeit aber nicht.
- `SET_LED_BASE` verändert nur den RAM-Zustand und wird nicht in NVM
  persistiert.

## Zeitverhalten

Makros und Encoder-Taps verwenden blockierende `delay()`-Aufrufe. Startsignal,
Werksreset-Feedback und NVM-Operationen blockieren ebenfalls den Loop. Während
dessen werden Matrix und CDC nicht bearbeitet; Encoder-ISRs können weiter
Events erzeugen, bis die Queue voll ist.