jappel/VersaMCU
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Update firmware documentation and agent guidance

Browse Source
This commit is contained in:
Julian Appel
2026-07-24 09:27:07 +02:00
parent ac3b2aa90f
commit 50dbf8fbee
26 changed files with 592 additions and 196 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+109 -118
View File
@@ -1,33 +1,59 @@
# VersaMCU
Firmware fuer das VersaPad v2 Macro-Pad.
Laeuft auf einem ATSAMD21G17D mit PlatformIO und Arduino-Framework.
Firmware für das VersaPad-v2-Makropad. Das Projekt läuft auf einem
ATSAMD21G17D mit PlatformIO und dem Arduino-SAMD-Framework.
## Aktueller Funktionsumfang
| Bereich | Stand |
|---|---|
| Eingaben | 20 MX-Tasten, 4 Encoder-Taster und 4 Quadratur-Encoder |
| USB | Keyboard-HID, Consumer-HID und CDC Serial |
| Aktionen | HID-Key, Consumer-Key, Host-Event, Makro, Profilwechsel |
| Makros | 32 Slots mit je bis zu 8 HID-Schritten |
| Profile | 3 Profile in Config v3 |
| LEDs | 20 WS2812B mit Base-/Override-Farbe und 7 Animationsmodi |
| Persistenz | Config und Makros im internen Flash |
| Recovery | Werksreset über zwei Tasten |
Die drei Fader-Pins sind im Board-Variant definiert, werden von der aktuellen
Firmware aber noch nicht eingelesen.
## Hardware
| Eigenschaft | Detail |
|---|---|
| MCU | ATSAMD21G17D, Cortex-M0+, 48 MHz |
| Flash / RAM | 128 KB / 16 KB |
| USB | Composite: HID Keyboard + Consumer + CDC Serial |
| Matrix | 5x5 logisch, davon 20 MX-Buttons + 4 Encoder-SW + 1 unbelegt |
| Encoder | 4x Rotary Encoder mit Quadratur via EIC-Interrupt |
| LEDs | 20x WS2812B an `PB22` |
| Programmer | Atmel-ICE via SWD, kein Bootloader |
| Flash / RAM | 128 KiB / 16 KiB |
| Matrix | logisch 5×5: 20 MX, 4 Encoder-SW, 1 unbelegt |
| Encoder | 4× Quadratur über EIC-Interrupts |
| LEDs | 20× WS2812B an `PB22` |
| USB | Native USB als HID + CDC Composite Device |
| Programmer | Atmel-ICE/CMSIS-DAP über SWD, standardmäßig ohne Bootloader |
## Build und Flash
## Schnellstart
Voraussetzungen sind PlatformIO Core oder die PlatformIO IDE sowie für den
Upload ein angeschlossener Atmel-ICE beziehungsweise kompatibler
CMSIS-DAP-Adapter.
```bash
pio run
pio run --target upload
pio run -e versapad
pio run -e versapad --target upload
```
Der Upload laeuft per OpenOCD ueber SWD.
Das Standard-Environment `versapad` baut für `boards/versapad_nobl.json`. Der
Upload wird durch `upload_openocd.py` über das von PlatformIO installierte
OpenOCD ausgeführt.
Das in `platformio.ini` auskommentierte Bootloader-Environment ist derzeit
nicht als Produktionsziel unterstützt. Details stehen unter
[bekannte Einschränkungen](doc/09_known_limitations.md).
## Laufzeitmodell
`main.cpp` startet genau einen `CMainController`.
Die Hauptschleife in `work()` ist:
`main.cpp` besitzt genau einen `CMainController`. Nach einem roten Startsignal
initialisiert er NVM, USB, Matrix und Encoder. Die Hauptschleife ist:
```text
matrix_scan()
@@ -37,133 +63,98 @@ check_factory_reset()
updateLEDs()
```
Dabei gilt:
- Matrix und Encoder legen `SEvent`s in eine feste Queue.
- Der Controller setzt Events in HID-Aktionen, Makros, Host-Events oder
Profilwechsel um.
- `poll_vendor()` verarbeitet feste 8-Byte-Pakete über CDC.
- LEDs werden nur neu übertragen, wenn ein Zustand dirty ist oder eine
Animation läuft.
- Makros, Encoder-Taps, NVM-Zugriffe und visuelles Reset-Feedback blockieren
den Loop kurzzeitig; es gibt keinen Scheduler.
- Matrix und Encoder erzeugen `SEvent`s.
- `processEvents()` fuehrt daraus HID, Makros, Host-Commands oder Profilwechsel aus.
- `poll_vendor()` verarbeitet das 8-Byte-CDC-Protokoll mit Config- und Makro-Transfers.
- `updateLEDs()` rendert nur dann zu den WS2812, wenn sich etwas geaendert hat.
## Wichtige Datenverträge
## Action-System
### Config v3
Unterstuetzte `ActionType`s:
| Typ | Verhalten |
|---|---|
| `NONE` | keine Aktion |
| `HID_KEY` | Keyboard-Hold ueber USB HID |
| `HID_CONSUMER` | Media/Consumer-Hold ueber USB HID |
| `HOST_COMMAND` | Event an die GUI per CDC Serial |
| `MACRO` | Firmware spielt Makro-Slot komplett ab |
| `PROFILE_SWITCH` | aktives Profil in NVM wechseln |
Wichtige Semantik:
- normale Keys und Consumer folgen dem Hold-Modell
- Encoder `CW` / `CCW` sind immer Tap-Events
- Makros laufen komplett in der Firmware, ohne laufende App
## LED-System
Jeder MX-Button hat:
- eine Base-Farbe
- optional eine temporaere Override-Farbe
- eine Animation
Aktuelle Animationsmodi:
- `STATIC`
- `BLINK`
- `PULSE`
- `FADE_IN`
- `FADE_OUT`
- `COLOR_CYCLE`
- `COLOR_FADE`
Die GUI nutzt derzeit vor allem `STATIC`, `BLINK`, `PULSE` und `COLOR_CYCLE`.
## Aktuelles NVM-Layout
### DeviceConfig
- Version: `3`
- Magic: `0x56503203`
- Groesse: `740` Byte
- CRC16-CCITT ueber Bytes `7..739`
- Magic `0x56503203`
- `SDeviceConfig`: 740 Byte
- CRC16-CCITT über Bytes `7..739`
- 3 Profile
- globale Helligkeit
- per-LED-Helligkeit
- globale und LED-spezifische Helligkeit
- 124 Chunks mit je 6 Nutzbytes beim CDC-Transfer
### MacroTable
### Makros
- 32 Slots
- 8 Steps pro Slot
- 512 Byte gesamt
- `SMacroTable`: 512 Byte
- 32 Slots × 8 Schritte × 2 Byte
- 86 Chunks mit je 6 Nutzbytes beim CDC-Transfer
### Flash-Bereich
### Flashzugriffe
| Bereich | Adresse | Groesse |
| Bereich | Adresse | Größe |
|---|---|---|
| Makros | `0x1FB00-0x1FCFF` | 512 B |
| Config | `0x1FD00-0x1FFFF` | 768 B, davon 740 B genutzt |
| Makros | `0x1FB00..0x1FCFF` | 512 B |
| Config | `0x1FD00..0x1FFFF` | 768 B, davon 740 B genutzt |
Config und Makros liegen in getrennten reservierten NVM-Bereichen.
Beim Serial-Dump der Config werden 124 Chunks zu je 6 Nutzbytes uebertragen. Implementierungen muessen den daraus berechneten Byte-Offset mindestens 16 Bit breit halten, weil Profil 2 und 3 hinter Byte 255 liegen.
Wichtig: Das aktive Linker-Skript reserviert aktuell nur die letzten 512 Byte
explizit. Das derzeit kleine Firmware-Image überschneidet sich nicht mit den
NVM-Daten, zukünftiges Wachstum ist aber nicht vollständig abgesichert. Siehe
[bekannte Einschränkungen](doc/09_known_limitations.md).
## Werksreset
Die Firmware hat einen eingebauten Recovery-Pfad:
Unteren linken und unteren rechten MX-Button gleichzeitig fünf Sekunden
halten:
- unteren linken und unteren rechten MX-Button gleichzeitig 5 Sekunden halten
- waehrend des Holds leuchten diese beiden Tasten rot
- ihre normalen HID-Aktionen werden waehrenddessen unterdrueckt
- bei Erfolg blinken alle LEDs kurz rot
- danach werden Config und Makros auf Werkseinstellungen zurueckgesetzt und neu geladen
- die Tasten werden während des Haltens rot markiert,
- ihre normalen Aktionen werden unterdrückt,
- bei Erfolg blinken alle LEDs kurz rot,
- Config und Makrotabelle werden auf Defaults zurückgesetzt.
Reset-Inhalt:
- alle Aktionen `NONE`
- alle Makro-Slots leer
- Base-LEDs auf Defaultwerte
- sichtbarer Idle-Zustand wieder Regenbogen
Wichtig:
- ein SWD-Reflash loescht diese NVM-Daten nicht automatisch
- der Werksreset ist der vorgesehene Weg, um eine kaputte Konfiguration zu bereinigen
Ein normaler SWD-Reflash löscht diese NVM-Daten nicht automatisch.
## Projektstruktur
```text
VersaMCU/
|-- AGENTS.md # Kontext und Richtlinien für Coding-LLMs
|-- README.md
|-- platformio.ini
|-- boards/
|-- variants/versapad/
|-- boards/ # PlatformIO-Boarddefinitionen
|-- variants/versapad/ # Pinmapping und Linker-Skripte
|-- doc/ # Architektur- und Protokolldokumentation
`-- src/
|-- main.cpp
|-- CMainController.h/.cpp
|-- CButton.h/.cpp
|-- CEventQueue.h/.cpp
|-- SEvent.h
|-- config/
| |-- action.h
| |-- macro_config.h/.cpp
| `-- nvm_config.h/.cpp
`-- hal/
|-- encoder.h/.cpp
|-- matrix.h/.cpp
|-- usb_hid.h/.cpp
|-- usb_serial.h/.cpp
`-- ws2812.h/.cpp
|-- CMainController.* # Orchestrierung
|-- CButton.* # Actions und LED-Zustand
|-- CEventQueue.* # feste Event-Queue
|-- config/ # Binärformate, NVM und Pins
`-- hal/ # Matrix, Encoder, HID, CDC, WS2812
```
## Weiterfuehrende Doku
## Einstieg für Entwickler und LLMs
- [doc/INDEX.md](doc/INDEX.md)
- [doc/00_architecture.md](doc/00_architecture.md)
- [doc/03_action_engine.md](doc/03_action_engine.md)
- [doc/04_macro_system.md](doc/04_macro_system.md)
- [doc/06_nvm_config.md](doc/06_nvm_config.md)
- [doc/07_serial_protocol.md](doc/07_serial_protocol.md)
Für einen neuen Kollegen:
1. [Entwicklung und Einstieg](doc/08_development.md)
2. [Architektur](doc/00_architecture.md)
3. die zum Task passende Fachdokumentation im [Dokumentationsindex](doc/INDEX.md)
4. [bekannte Einschränkungen](doc/09_known_limitations.md)
Für einen Coding-Agent zusätzlich [`AGENTS.md`](AGENTS.md) als
Repository-Anweisung mitgeben. Die Datei enthält Quellenhierarchie,
Binärverträge, Änderungsregeln und die minimale Verifikation.
## Dokumentation
- [Dokumentationsindex](doc/INDEX.md)
- [Architektur](doc/00_architecture.md)
- [Matrix](doc/01_matrix.md)
- [Encoder](doc/02_encoder.md)
- [Action-Engine](doc/03_action_engine.md)
- [Makros](doc/04_macro_system.md)
- [LED-System](doc/05_led_system.md)
- [NVM-Config](doc/06_nvm_config.md)
- [CDC-Protokoll](doc/07_serial_protocol.md)
- [Entwicklung und Einstieg](doc/08_development.md)
- [Bekannte Einschränkungen](doc/09_known_limitations.md)