Added doc

2026-03-30 19:52:37 +02:00
parent 0b3c5f3217
commit 9079fefad8
9 changed files with 567 additions and 0 deletions
@@ -0,0 +1,70 @@
+# Aktions-Engine
+
+**Dateien:** `config/action.h`, `CMainController.cpp` (`processEvents`, `execute_action`)
+
+## SAction-Struct
+
+```cpp
+struct __attribute__((packed)) SAction {
+    ActionType type;   // 1 Byte
+    uint16_t   data;   // 2 Bytes (Keycode, Consumer-Code, Command-ID oder Slot-Index)
+};
+// Gesamt: 3 Bytes (packed! ohne packed wären es 4 durch Alignment)
+```
+
+`packed` ist zwingend damit `sizeof(SDeviceConfig) == 223` mit der C#-Serialisierung in VersaGUI übereinstimmt.
+
+## ActionType
+
+| Typ | Bedeutung | data-Inhalt |
+|---|---|---|
+| `NONE` | Keine Aktion | — |
+| `HID_KEY` | Tastendruck via USB HID Keyboard | Low-Byte = HID Keycode, High-Byte = Modifier |
+| `HID_CONSUMER` | Consumer Control (Volume, Media, …) | Consumer Usage ID |
+| `HOST_COMMAND` | Event an VersaGUI senden, App führt aus | Command-ID (frei definiert) |
+| `MACRO` | Makro-Sequenz aus NVM-Tabelle | Slot-Index 0–31 |
+
+## Ausführung (execute_action)
+
+**HID_KEY:**
+```
+usb_hid_send_key(keycode, modifier)
+delay(10 ms)
+usb_hid_release_key()
+```
+→ Tap-Only-Modell. Kein Hold-Support. KEY_UP löst kein HID-Release aus.
+
+**HID_CONSUMER:**
+```
+usb_hid_send_consumer(usage_id)
+usb_hid_release_consumer()
+```
+→ Kein Delay nötig (Consumer-Keys sind Edge-getriggert).
+
+**HOST_COMMAND:**
+`execute_action()` macht nichts. `processEvents()` sendet zusätzlich `USB_EVT_KEY_DOWN` via CDC Serial an VersaGUI. Die App entscheidet was passiert (URL öffnen, Programm starten, …).
+
+**MACRO:**
+```
+für jeden Step [0–3] im Slot:
+    if keycode == 0: abbrechen
+    usb_hid_send_key(keycode, modifier)
+    delay(10 ms)
+    usb_hid_release_key()
+    delay(20 ms)   // Pause damit der Host den Step verarbeiten kann
+```
+
+## Event-Verarbeitung
+
+Events werden in `processEvents()` aus `CEventQueue` konsumiert (FIFO):
+
+- `KEY_DOWN` → `CButton.on_press()` (aktuell leer, Erweiterungspunkt) + `execute_action()`
+- `KEY_UP`   → `CButton.on_release()` (aktuell leer)
+- `ENC_CW/CCW` → `execute_action(m_enc_cw/ccw[enc_id])`
+
+Encoder CW/CCW-Aktionen sind in `CMainController` direkt als `SAction`-Arrays gehalten (kein CButton-Objekt, da Encoder keine LED haben).
+
+## Bekannte Einschränkungen
+
+- **Kein Hold**: `execute_action` bei KEY_DOWN sendet sofort Key-Down + Key-Up. Halten der Taste löst keine Wiederholung aus.
+- **HOST_COMMAND KEY_UP**: Board sendet derzeit kein `USB_EVT_KEY_UP` für KEY_UP-Events (nur KEY_DOWN wird gemeldet).