160 lines
5.0 KiB
Markdown
160 lines
5.0 KiB
Markdown
# VersaMCU
|
||
|
||
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 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 |
|
||
|
||
## 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 -e versapad
|
||
pio run -e versapad --target upload
|
||
```
|
||
|
||
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` besitzt genau einen `CMainController`. Nach einem roten Startsignal
|
||
initialisiert er NVM, USB, Matrix und Encoder. Die Hauptschleife ist:
|
||
|
||
```text
|
||
matrix_scan()
|
||
poll_vendor()
|
||
processEvents()
|
||
check_factory_reset()
|
||
updateLEDs()
|
||
```
|
||
|
||
- 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.
|
||
|
||
## Wichtige Datenverträge
|
||
|
||
### Config v3
|
||
|
||
- Magic `0x56503203`
|
||
- `SDeviceConfig`: 740 Byte
|
||
- CRC16-CCITT über Bytes `7..739`
|
||
- 3 Profile
|
||
- globale und LED-spezifische Helligkeit
|
||
- 124 Chunks mit je 6 Nutzbytes beim CDC-Transfer
|
||
|
||
### Makros
|
||
|
||
- `SMacroTable`: 512 Byte
|
||
- 32 Slots × 8 Schritte × 2 Byte
|
||
- 86 Chunks mit je 6 Nutzbytes beim CDC-Transfer
|
||
|
||
### Flashzugriffe
|
||
|
||
| Bereich | Adresse | Größe |
|
||
|---|---|---|
|
||
| Makros | `0x1FB00..0x1FCFF` | 512 B |
|
||
| Config | `0x1FD00..0x1FFFF` | 768 B, davon 740 B genutzt |
|
||
|
||
Das aktive Linker-Skript und `boards/versapad_nobl.json` begrenzen das
|
||
Firmware-Image auf `0x00000..0x1FAFF`. Damit sind alle fünf NVM-Rows gegen
|
||
Firmwarewachstum geschützt.
|
||
|
||
## Werksreset
|
||
|
||
Unteren linken und unteren rechten MX-Button gleichzeitig fünf Sekunden
|
||
halten:
|
||
|
||
- 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.
|
||
|
||
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/ # PlatformIO-Boarddefinitionen
|
||
|-- variants/versapad/ # Pinmapping und Linker-Skripte
|
||
|-- doc/ # Architektur- und Protokolldokumentation
|
||
`-- src/
|
||
|-- main.cpp
|
||
|-- CMainController.* # Orchestrierung
|
||
|-- CButton.* # Actions und LED-Zustand
|
||
|-- CEventQueue.* # feste Event-Queue
|
||
|-- config/ # Binärformate, NVM und Pins
|
||
`-- hal/ # Matrix, Encoder, HID, CDC, WS2812
|
||
```
|
||
|
||
## Einstieg für Entwickler und LLMs
|
||
|
||
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)
|