Julian Appel d325297063 Add end-to-end USB flashing for the app firmware via UF2

Adds uf2conv.py (minimal, dependency-free .bin -> .uf2 converter
matching bootloader/inc/uf2format.h's block layout) and upload_uf2.py,
a PlatformIO upload hook for env:versapad_usb that finds the mounted
VERSABOOT volume and copies the converted firmware onto it.

env:versapad_usb previously used upload_protocol=sam-ba, the classic
Arduino/Atmel protocol -- the actual bootloader speaks UF2/mass
storage, not SAM-BA, so that upload path never worked. Switched to
upload_protocol=custom with the new hook, and cleaned the now-unused
SAM-BA-specific fields out of boards/versapad.json.

Verified end to end on real hardware: pio run -e versapad_usb
--target upload builds, converts, copies to the VERSABOOT drive, and
the bootloader jumps into the freshly written app on its own.

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

2026-08-05 21:35:19 +02:00

4.6 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.

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 komplette Weg ist dort auf echter Hardware verifiziert: Bootloader-Flash, USB-Enumeration, Tastencheck-Einstieg (kein physischer Reset-Taster auf diesem Board, siehe bootloader/README.md, "Hardware-Bootloader-Einstieg"), App-Firmware per .uf2 über env:versapad_usb --target upload schreiben, automatischer Rücksprung in die neue App. Details und ein gefundener/behobener Hard-Fault-Bug beim Sprung Bootloader→App (fehlende __DSB()/__ISB() vor dem bx) stehen in bootloader/README.md, "Hardwaretest". env:versapad_usbs Linkerskript (variants/versapad/linker_scripts/gcc/flash_with_bootloader.ld) reserviert inzwischen denselben NVM-Bereich wie flash_without_bootloader.ld.

Trotzdem noch kein Merge-fertiges Produktionsziel: Der .bin→.uf2-Weg (uf2conv.py, upload_uf2.py, Repo-Root) sucht das VERSABOOT-Laufwerk bisher nur über die Windows-API, keine macOS/Linux-Unterstützung. Die Bootloader-USB-PID (0x0043) ist zwar kollisionsfrei verifiziert, aber kein offiziell registrierter Wert unter Adafruits VID 0x239A.

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.

4.6 KiB Raw Blame History