Julian Appel 33d9e85992 Fold bootloader documentation into the main doc/ index

Adds doc/10_usb_bootloader.md as the primary reference for the UF2
bootloader (memory layout, key-based boot entry, build/flash steps,
hardware test findings, known limitations), following the existing
numbered-doc convention. Updates doc/INDEX.md, doc/09_known_limitations.md
(bootloader is no longer "not supported", just scoped), and
doc/08_development.md accordingly.

Removes bootloader/TESTING.md (its findings now live in
doc/10_usb_bootloader.md) and trims bootloader/README.md down to what
belongs with that subproject specifically: upstream attribution/license
and local build/flash commands, plus the OpenOCD manual-flashing
warning since that's implementation-specific detail that would clutter
the higher-level doc.

Updates the top-level README.md (feature table, hardware table,
quickstart, project tree, doc links) to reflect USB flashing as a
supported path alongside SWD.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-08-05 22:49:56 +02:00

4.4 KiB

Raw Blame History

Bekannte Einschränkungen und Risiken

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

USB-Bootloader hat einen eingeschränkten Gültigkeitsbereich

Der UF2-Bootloader (bootloader/, App-Environment env:versapad_usb, Details in 10_usb_bootloader.md) ist auf echter Hardware verifiziert und ergänzt den SWD-Weg, ersetzt ihn aber nicht: der Bootloader selbst muss weiterhin einmalig per Atmel-ICE/SWD geflasht werden.

Verbleibende Einschränkungen:

uf2conv.py/upload_uf2.py (Repo-Root) suchen das VERSABOOT-Laufwerk nur über die Windows-API, keine macOS/Linux-Unterstützung.
Die Bootloader-USB-PID (0x0043) ist kollisionsfrei verifiziert, aber kein offiziell registrierter Wert unter Adafruits VID 0x239A.
Kein Software-Trigger, um aus der laufenden App heraus in den Bootloader-Modus zu wechseln — nur der physische Weg (Kabel ziehen, Taste halten, wieder einstecken).
Bootloader-Flash-Auslastung ~90 % (7364 von 8192 Byte), wenig Puffer für Änderungen am Bootloader selbst.

Sowohl boards/versapad_nobl.json (SWD-Ziel) als auch boards/versapad.json (USB-Bootloader-Ziel) benennen die MCU als samd21g17d, setzen 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 (versapad_nobl) beziehungsweise 121.600 Byte (versapad, abzüglich 8 KiB Bootloader) 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.

4.4 KiB Raw Blame History