# Aktions-Engine

Dateien:

- `config/action.h`
- `CMainController.h/.cpp`
- `CButton.h/.cpp`

## `SAction`

```cpp
struct __attribute__((packed)) SAction {
    ActionType type;
    uint16_t   data;
};
```

Groesse: 3 Byte.
Das `packed` ist zwingend, weil Config v3 bytegenau zwischen Firmware und GUI uebereinstimmen muss.

## `ActionType`

| Typ | Bedeutung | `data` |
|---|---|---|
| `NONE` | keine Aktion | - |
| `HID_KEY` | Tastaturtaste ueber USB HID | low byte = keycode, high byte = modifier |
| `HID_CONSUMER` | Media/Consumer-HID | usage id |
| `HOST_COMMAND` | Event an die GUI | command id |
| `MACRO` | Makro aus `SMacroTable` | slot 0..31 |
| `PROFILE_SWITCH` | Profilwechsel | 0..2 oder `0xFF` fuer naechstes Profil |

## Verhalten bei `KEY_DOWN`

| Typ | Effekt |
|---|---|
| `HID_KEY` | `usb_hid_send_key()` |
| `HID_CONSUMER` | `usb_hid_send_consumer()` |
| `HOST_COMMAND` | `usb_serial_send(KEY_DOWN/ENC_*)` |
| `MACRO` | komplette Sequenz sofort abspielen |
| `PROFILE_SWITCH` | Config aus NVM laden, Profil aendern, CRC neu berechnen, speichern, Buttons neu initialisieren |
| `NONE` | nichts |

## Verhalten bei `KEY_UP`

| Typ | Effekt |
|---|---|
| `HID_KEY` | `usb_hid_release_key()` |
| `HID_CONSUMER` | `usb_hid_release_consumer()` |
| `HOST_COMMAND` | optionaler Up-Pfad, derzeit praktisch ohne Nutzlast |
| `MACRO` | nichts |
| `PROFILE_SWITCH` | nichts |
| `NONE` | nichts |

## Hold- und Tap-Modell

- MX-Buttons und Encoder-SW benutzen fuer HID und Consumer das Hold-Modell.
- Encoder `CW` und `CCW` sind immer diskrete Tap-Events:

```text
down -> delay(10 ms) -> up
```

- Makros laufen komplett synchron in der Firmware.

## Makro-Ausfuehrung

Bei `ActionType::MACRO` wird `action.data` als Slot interpretiert.
Die Firmware laeuft dann durch bis zu 8 Steps:

```text
step.keycode == 0  -> Ende
Key-Down
10 ms warten
Key-Up
20 ms warten
```

## Profilwechsel

`PROFILE_SWITCH` arbeitet direkt auf der gespeicherten Config:

1. Config aus NVM laden
2. `active_profile` aendern
3. CRC neu berechnen
4. wieder speichern
5. `init_buttons()`

Wichtig:
`active_profile` liegt im CRC-geschuetzten Bereich. Ohne neue CRC wuerde die Config beim naechsten Laden verworfen.

## Sonderfall Werksreset

Die Reset-Kombination uebersteuert das normale Action-System fuer genau zwei Tasten:

- `key_id 9`
- `key_id 24`

Sobald beide gleichzeitig gehalten werden:

- ihre normalen Actions werden nicht weiter ausgefuehrt
- eventuell bereits gestartete HID-Holds werden sofort freigegeben
- die LEDs der beiden Tasten leuchten rot
- nach 5 Sekunden wird `perform_factory_reset()` ausgefuehrt