# 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).