jappel/VersaMCU
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
59b3cb4dd1aec67be7c7ada8987ca507f174c316
VersaMCU/README.md
T

12 KiB
Raw Blame History

VersaMCU

Firmware für das VersaPad v2 Macro-Pad. Läuft auf einem ATSAMD21G17D (Cortex-M0+), entwickelt mit PlatformIO + Arduino-Framework.

Voraussetzungen

  • PlatformIO (CLI oder VS Code Extension)
  • Atmel-ICE Debugger/Programmer (SWD-Verbindung zur PCB)
  • OpenOCD – wird von PlatformIO automatisch installiert

Flashen

pio run --target upload

Der Upload läuft via OpenOCD über SWD. Kein Bootloader nötig – der Chip wird direkt programmiert.

Funktionsumfang (Anforderungskatalog)

1 Hardware-Plattform

# Anforderung Status
1.1 Ziel-MCU: ATSAMD21G17D (Cortex-M0+, 48 MHz, 128 KB Flash, 16 KB RAM) ✅
1.2 Framework: Arduino + PlatformIO, kein Bootloader (Direktflash via SWD/Atmel-ICE) ✅
1.3 USB-Enumeration ohne externen Quarz (-DCRYSTALLESS, DFLL48M nutzt USB-SOF als Referenz) ✅
1.4 Benutzerdefiniertes Board-Profil (versapad_nobl.json) mit korrekten Flash/RAM-Limits ✅

2 Tasten-Matrix

# Anforderung Status
2.1 5×5-Matrix-Scan (25 Keys, davon 20 MX-Buttons + 4 Encoder-SW + 1 NC) ✅
2.2 10 ms Software-Debounce pro Taste (Flanken-Erkennung) ✅
2.3 KEY_DOWN- und KEY_UP-Events werden in die Event-Queue geschrieben ✅
2.4 Matrix-Scan im Loop-Kontext (kein ISR, kein Heap) ✅

3 Encoder

# Anforderung Status
3.1 4 Quadratur-Encoder (A/B-Phasen per EIC-Interrupt) ✅
3.2 Richtungserkennung: CW / CCW via 2-Bit-Greycode-Auswertung ✅
3.3 Encoder-Events im ISR-Kontext direkt in Event-Queue (interrupt-sicher, kein Heap) ✅
3.4 Encoder-SW-Tasten über Matrix-Scan (gleicher Pfad wie MX-Buttons) ✅

4 Aktions-Engine

# Anforderung Status
4.1 ActionType NONE: kein HID-Event beim Drücken ✅
4.2 ActionType HID_KEY: USB-HID-Tastendruck (Keycode + Modifier-Byte) ✅
4.3 ActionType HID_CONSUMER: USB Consumer Control (Play/Pause, Lautstärke …) ✅
4.4 ActionType HOST_COMMAND: Event-ID an VersaGUI senden, App führt aus ✅
4.5 ActionType MACRO: Sequenz aus bis zu 4 HID-Key-Schritten aus NVM-Tabelle abspielen ✅
4.6 Jede Aktion ausführbar ohne laufende VersaGUI (lokal per HID/Makro) ✅

5 Makro-System

# Anforderung Status
5.1 32 Makro-Slots, je 4 Steps (Keycode + Modifier-Byte) = 256 Byte gesamt ✅
5.2 Steps mit keycode = 0 werden übersprungen (variable Makrolänge 1–4) ✅
5.3 Timing: 10 ms Key-Down-Dauer + 20 ms Pause zwischen Steps ✅
5.4 Makro-Tabelle in separater NVM-Row (Row 1, 0x1FF00, 256 Byte) ✅
5.5 Makro-Tabelle wird beim Start aus NVM geladen; gelöschter Flash (0xFF) → leere Tabelle ✅

6 LED-System (WS2812)

# Anforderung Status
6.1 20 WS2812-LEDs, serpentiner Verdrahtung; Adafruit-NeoPixel bit-bang Treiber ✅
6.2 2-Schicht-Modell pro Button: base (Idle) + override (temporär von GUI) ✅
6.3 STATIC: feste Farbe aus NVM ✅
6.4 BLINK: binäres An/Aus mit konfigurierbarer Halbperiode ✅
6.5 PULSE: lineares Helligkeitsdreieck (0→255→0), kein Float ✅
6.6 COLOR_CYCLE (Regenbogen): Hue-Sweep über 6 Segmente, ignoriert base/override ✅
6.7 COLOR_FADE: einmaliger RGB-Crossfade zu Zielfarbe ✅
6.8 Phasenversatz beim Start: Regenbogen-LEDs sind gleichmäßig über die Periode verteilt ✅
6.9 ws2812_show() nur bei dirty-Flag aufgerufen (~600 µs Blockzeit vermieden) ✅
6.10 Alle Animationen in Integer-Arithmetik (kein FPU auf M0+) ✅

7 Konfigurations-Speicherung (NVM)

# Anforderung Status
7.1 Config-Layout Version 2, 223 Byte packed, mit Magic 0x56503202 + CRC16-CCITT ✅
7.2 Config gespeichert in NVM Row 0 (0x1FE00, 256 Byte, via Linkerscript reserviert) ✅
7.3 Makro-Tabelle in NVM Row 1 (0x1FF00, 256 Byte) ✅
7.4 NVM-Schreiben: Row löschen + 4 Pages à 64 Byte manuell schreiben (MANW=1) ✅
7.5 Bei ungültigem Magic / falscher Version / CRC-Fehler → Defaults laden (kein Crash) ✅
7.6 Defaults: alle Aktionen NONE, LEDs warm-weiß, Animation Regenbogen 4 s ✅

8 Serial-Kommunikation mit VersaGUI

# Anforderung Status
8.1 CDC Serial (USB), kein Treiber nötig; 8-Byte-Festlängen-Pakete ✅
8.2 Ring-Buffer (256 Byte = 32 Pakete) für eingehende Bytes; kein Datenverlust bei Burst ✅
8.3 Ping / Pong (0x05 / 0x85) zur Verbindungsdiagnose ✅
8.4 Config-Transfer PC→Board: BEGIN(0x10) → 38×DATA(0x11) → COMMIT(0x12) → ACK/NACK ✅
8.5 Config-Dump Board→PC: auf READ(0x13) → BEGIN(0x92) → 38×DATA(0x93) → END(0x94) ✅
8.6 Makro-Transfer PC→Board: BEGIN(0x20) → 43×DATA(0x21) → COMMIT(0x22) → ACK(0x95) ✅
8.7 Makro-Dump Board→PC: auf READ(0x23) → BEGIN(0x96) → 43×DATA(0x97) → END(0x98) ✅
8.8 Config-COMMIT validiert Magic + Version + CRC; bei Fehler NACK ohne NVM-Schreiben ✅
8.9 Alle Sende-Pakete nur wenn SerialUSB aktiv (DTR-Check verhindert stilles Verwerfen) ✅

9 Nicht implementiert / Roadmap

# Anforderung Status
9.1 Fader/Potentiometer: 3× ADC-Kanäle auf Board vorhanden, HAL nicht implementiert 🔲 TODO
9.2 HOST_COMMAND-Payload: Board sendet Command-ID, App-Seite führt aus (halbfertig) 🔲 TODO
9.3 FADE_IN / FADE_OUT per GUI konfigurierbar (Firmware vorhanden, kein GUI-Eintrag) 🔲 TODO

Projekt-Struktur

VersaMCU/
├── platformio.ini          – Build- und Upload-Konfiguration
├── upload_openocd.py       – Benutzerdefiniertes Upload-Script (OpenOCD)
├── boards/
│   ├── versapad.json       – Board-Definition mit Bootloader
│   └── versapad_nobl.json  – Board-Definition ohne Bootloader (aktiv)
├── variants/versapad/
│   ├── variant.h/.cpp      – Pin-Mapping für den SAMD21G17D
│   └── linker_scripts/     – Linkerscript (kein Bootloader, NVM-Reservierung)
└── src/
    ├── main.cpp                   – Arduino setup()/loop()
    ├── CMainController.h/.cpp     – Zentraler Orchestrator
    ├── CButton.h/.cpp             – Button-Modell: LED-Schichten, Action, Animationen
    ├── CEventQueue.h/.cpp         – Ring-Buffer FIFO (16 Slots, kein Heap)
    ├── SEvent.h                   – Event-Typen (KEY_DOWN/UP, ENC_CW/CCW)
    ├── config/
    │   ├── pins.h                 – Pin-Nummern (Arduino-Nummern aus variant.h)
    │   ├── action.h               – ActionType-Enum + SAction-Struct (packed)
    │   └── nvm_config.h/.cpp      – NVM-Config: Laden, Speichern, CRC16, Defaults
    └── hal/
        ├── matrix.h/.cpp          – 5×5-Matrix-Scan, 10 ms Debounce
        ├── encoder.h/.cpp         – Quadratur-Dekodierung via EIC-Interrupts
        ├── ws2812.h/.cpp          – WS2812-LED-Treiber (Adafruit NeoPixel, bit-bang)
        ├── usb_hid.h/.cpp         – HID Keyboard + Consumer Control
        └── usb_serial.h/.cpp      – CDC Serial bidirektional, 8-Byte-Pakete

Architektur

Loop-Ablauf

loop()
  ├── matrix_scan()    → matrix_cb()    → CEventQueue.push()
  │   (Encoder-ISRs laufen asynchron)  → CEventQueue.push()
  ├── poll_vendor()    → Serial-Pakete von VersaGUI verarbeiten
  ├── processEvents()  → Queue leeren, Aktionen ausführen
  └── updateLEDs()     → Dirty-CButtons → WS2812-Buffer → show()

CButton – LED-Schichten

Jeder MX-Button hat zwei LED-Schichten:

  • base: Konfigurierte Idle-Farbe (aus NVM)
  • override: Temporär von VersaGUI gesetzt (Benachrichtigungen etc.)

Aktive Farbe = override wenn aktiv, sonst base. clear_override() kehrt sofort zu base zurück.

LED-Animationen

Animation Verhalten
STATIC Feste Farbe
BLINK Binäres An/Aus
PULSE Lineares Dreieck 0→255→0
FADE_IN / FADE_OUT Einmaliges Ein-/Ausblenden
COLOR_CYCLE Hue-Sweep (Regenbogen), ignoriert base/override
COLOR_FADE Crossfade zu Zielfarbe

Alle Berechnungen in Integer-Arithmetik (kein FPU auf Cortex-M0+).

Idle-Zustand: Alle 20 MX-LEDs zeigen einen rotierenden Regenbogen (COLOR_CYCLE, 4 s/Runde, 40 % Helligkeit, gleichmäßig phasenverschoben).

Serial-Protokoll (8 Bytes, fixed)

Byte 0: Command/Event-ID
Byte 1: key_id (Button 0–24 oder Encoder 0–3)
Byte 2: r / Daten-Byte A
Byte 3: g / Daten-Byte B
Byte 4: b
Byte 5–7: reserviert (0x00)
ID Richtung Bedeutung
0x01 PC→Board LED-Override setzen
0x02 PC→Board LED-Override löschen
0x03 PC→Board LED-Base setzen
0x05 PC→Board Ping
0x10 PC→Board Config-Begin (Chunks-Anzahl)
0x11 PC→Board Config-Data (Chunk-Index + 6B Nutzdaten)
0x12 PC→Board Config-Commit (CRC prüfen + NVM schreiben)
0x13 PC→Board Config-Read (Board sendet NVM-Config zurück)
0x81 Board→PC KEY_DOWN
0x82 Board→PC KEY_UP
0x83 Board→PC ENC_CW
0x84 Board→PC ENC_CCW
0x85 Board→PC Pong
0x90 Board→PC Config-ACK
0x91 Board→PC Config-NACK
0x20 PC→Board Makro-Begin (Chunk-Anzahl = 43)
0x21 PC→Board Makro-Data (Chunk-Index + 6B Nutzdaten)
0x22 PC→Board Makro-Commit (in NVM schreiben)
0x23 PC→Board Makro-Read (Board sendet Tabelle zurück)
0x90 Board→PC Config-ACK
0x91 Board→PC Config-NACK (CRC/Magic/Version ungültig)
0x92 Board→PC Config-Begin (Dump-Start, Chunks-Anzahl)
0x93 Board→PC Config-Data (Chunk-Index + 6B)
0x94 Board→PC Config-End
0x95 Board→PC Makro-ACK
0x96 Board→PC Makro-Begin (Dump-Start)
0x97 Board→PC Makro-Data (Chunk-Index + 6B)
0x98 Board→PC Makro-End

NVM-Config-Layout (Version 2, 223 Bytes, packed)

Offset   0   4B  Magic   0x56503202
Offset   4   1B  Version 2
Offset   5   2B  CRC16-CCITT (über Bytes 7–222)
Offset   7  60B  mx_actions[20]     – je 3B: type(1B) + data(2B)
Offset  67  36B  enc_actions[4][3]  – je 3B
Offset 103  20B  led_r[20]
Offset 123  20B  led_g[20]
Offset 143  20B  led_b[20]
Offset 163  20B  led_anim[20]       – LEDAnim-Typ (uint8_t)
Offset 183  40B  led_period_ms[20]  – Animationsperiode in ms (uint16_t, LE)

NVM Row 0 (0x1FE00, 256 Byte): Config (223B genutzt, 33B Padding) NVM Row 1 (0x1FF00, 256 Byte): Makro-Tabelle (32 Slots × 4 Steps × 2B) Via Linkerscript reserviert. Bei ungültigem Magic/Version/CRC werden Defaults geladen.

Bekannte Fallstricke

Problem Lösung
Kaltstart hängt (XOSC32KRDY) -DCRYSTALLESS in build_flags pflicht
Adafruit NeoPixel ZeroDMA inkompatibel Standard bit-bang Library verwenden
WS2812 Pegel 3.3V statt 5V LED 0 marginal OK, ab LED 1 selbst-regenerierend. Fix nächste PCB-Rev: Level-Shifter
ws2812_show() blockiert ~600 µs Dirty-Flag-Pattern: nur aufrufen wenn nötig, nie aus ISR
SAction muss __attribute__((packed)) haben Ohne packed: 4B statt 3B → CRC-Mismatch beim Config-Laden
Windows HID-Descriptor-Cache Bei PID-Änderung Board neu einstecken
Reference in New Issue View Git Blame Copy Permalink