Julian Appel
33d9e85992
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>
99 lines
3.5 KiB
Markdown
99 lines
3.5 KiB
Markdown
# 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`](../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
|
|
|
|
```bash
|
|
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](10_usb_bootloader.md).
|
|
|
|
## Was beim Start passiert
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
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`](09_known_limitations.md).
|