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.

Das in platformio.ini nur als Beispiel enthaltene Environment versapad_usb ist auskommentiert und mit dem aktuellen NVM-/Linker-Layout nicht als unterstützt anzusehen.

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

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.4 KiB Raw Permalink Blame History