forked from jappel/VersaMCU
Julian Appel
d325297063
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>
101 lines
4.6 KiB
Markdown
101 lines
4.6 KiB
Markdown
# 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_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 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.
|