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. Das auskommentierte USB-Bootloader-Environment verwendet dagegen weiterhin eine historische Board-/Linker-Konfiguration und ist nicht als Produktionsziel verifiziert.

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.