VersaMCU/doc/03_action_engine.md

Aktions-Engine

Dateien:

• config/action.h
• CMainController.h/.cpp
• CButton.h/.cpp

SAction

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	aktuell nicht ausgewertet
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_EVT_KEY_DOWN (0x81) mit key_id senden
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	keine Ausgabe; USB_EVT_KEY_UP ist nur definiert
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:

down -> delay(10 ms) -> up

• Makros laufen komplett synchron in der Firmware.

Das Hold-Modell verwaltet keine Menge gleichzeitig gedrückter Tasten. Ein neuer Keyboard-Down ersetzt den vorherigen Report und jeder Keyboard-Up leert den gesamten Report. Consumer-HID hat dieselbe Einschränkung mit genau einem Usage-Wert.

Host-Commands

Der aktuelle Code sendet für jede HOST_COMMAND-Action nur:

Byte 0 = USB_EVT_KEY_DOWN (0x81)
Byte 1 = Matrix-Key-ID oder Encoder-ID

SAction.data wird dabei nicht übertragen. Auch Encoder-Actions verwenden aktuell 0x81; die definierten Events ENC_CW (0x83) und ENC_CCW (0x84) werden nicht emittiert. Ein Release erzeugt kein KEY_UP-Paket. Das ist aktuelles Verhalten und als Einschränkung in 09_known_limitations.md festgehalten.

Makro-Ausfuehrung

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

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