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

3.5 KiB

Raw Blame History

Entwicklung und Einstieg

Diese Seite ist der praktische Einstieg für neue Entwickler. Für einen LLM-basierten Coding-Agent zusätzlich die Anweisungen in ../AGENTS.md bereitstellen.

Voraussetzungen

PlatformIO Core oder PlatformIO IDE
USB-Kabel für Laufzeittests
Atmel-ICE beziehungsweise kompatibler CMSIS-DAP-Adapter für den Upload
das benachbarte Repository ../VersaGUI, wenn das CDC-Protokoll oder persistente Formate geändert werden

PlatformIO lädt den Arduino-SAMD-Core, OpenOCD und Adafruit NeoPixel über platformio.ini. Das aktive Standardziel ist versapad_nobl im Environment versapad.

Build und Upload

pio run -e versapad
pio run -e versapad --target upload

Der Upload nutzt upload_openocd.py, das das von PlatformIO installierte OpenOCD mit interface/cmsis-dap.cfg und target/at91samdXX.cfg startet.

Für App-Updates über USB (nach einem einmaligen Bootloader-Flash) gibt es zusätzlich env:versapad_usb, siehe 10_usb_bootloader.md.

Was beim Start passiert

Arduino setup()
  500 ms warten
  WS2812 initialisieren
  1 s rotes Startsignal
  Makros aus NVM laden
  Config laden und Buttons initialisieren
  USB-HID/CDC, Matrix und Encoder initialisieren

Arduino loop()
  Matrix scannen
  CDC-Pakete verarbeiten
  Event-Queue leeren
  Werksreset prüfen
  LEDs rendern

Der Controller blockiert während Makros, Encoder-Taps, Start-/Reset-Feedback und NVM-Schreibvorgängen. Es gibt keinen Scheduler und keine Threads.

Einstieg nach Änderungstyp

Änderung	Zuerst lesen	Typische Dateien
Matrix/Key-Mapping	`01_matrix.md`	`hal/matrix.*`, `config/pins.h`, Variant
Encoder	`02_encoder.md`	`hal/encoder.*`, `CMainController.cpp`
Actions/HID	`03_action_engine.md`	`config/action.h`, Controller, `hal/usb_hid.*`
Makros	`04_macro_system.md`	`config/macro_config.*`, Controller
LEDs	`05_led_system.md`	`CButton.`, `hal/ws2812.`
Persistente Config	`06_nvm_config.md`	`config/nvm_config.*`, Linker-Skripte
Host-Protokoll	`07_serial_protocol.md`	`hal/usb_serial.*`, Controller
USB-Bootloader	`10_usb_bootloader.md`	`bootloader/`, `variants/versapad/linker_scripts/gcc/flash_with_bootloader.ld`, `boards/versapad.json`, `uf2conv.py`, `upload_uf2.py`

Verifikation

Für die Firmware gibt es derzeit keine automatisierten Tests. Der minimale lokale Check ist:

pio run -e versapad
git diff --check

Je nach Änderung folgen Hardwaretests:

Matrix: jede Taste einzeln, Mehrfachtasten und beide Reset-Tasten
Encoder: beide Richtungen und schneller Richtungswechsel
HID: Down/Up sowie Modifier und Consumer Usage
CDC: Ping, vollständiger Config-/Makro-Transfer und Readback
NVM: Power-Cycle, ungültige CRC und Werksreset
LEDs: alle Animationen, Helligkeit und temporäre Overrides

Die GUI ist ein separates Git-Repository im selben Workspace. Änderungen an SDeviceConfig, SMacroTable, Action-Werten oder USB-IDs sind erst vollständig verifiziert, wenn Firmware und ../VersaGUI dieselben Bytes senden und interpretieren. DelphiGUI gehört nicht zum gepflegten Scope. Die automatisierten GUI-Vertragstests liegen unter ../VersaGUI/tests/VersaGUI.ContractTests/.

Dokumentation mitpflegen

Bei jedem Change die betroffene Fachdokumentation aktualisieren. Zahlen wie Structgrößen, Offsets, Chunk-Anzahlen und Flashgrenzen immer aus dem neuen Code neu ableiten. Offene oder absichtlich nicht behobene Punkte gehören nach 09_known_limitations.md.

3.5 KiB Raw Blame History