VersaGUI/doc/02_device_config.md

DeviceConfig und MacroTable

Datei:

• src/DeviceConfig.cs

Zweck

Die C#-Klassen spiegeln das aktuelle Firmware-Layout bytegenau. Sie muessen deshalb synchron zu VersaMCU/src/config/nvm_config.h und macro_config.h bleiben.

DeviceConfig

Globaler Stand

• Magic 0x56503203
• Version 3
• Groesse 740 Byte
• 3 Profile

Wichtige Felder

Feld	Bedeutung
ActiveProfileIndex	aktives Profil 0..2
GlobalBrightness	globale LED-Helligkeit
Profiles[3]	komplette Profil-Daten
EncSensitivity[4]	im Vertrag enthalten; Firmware nutzt den Wert derzeit nicht

Fuer die GUI gibt es zusaetzlich Komfortzugriffe auf das aktive Profil:

• MxActions[20]
• EncActions[4,3]
• LedBase[20]
• LedAnim[20]
• LedPeriod[20]

Layout

Offset 0    4B   magic
Offset 4    1B   version
Offset 5    2B   crc
Offset 7    1B   active_profile
Offset 8    1B   global_brightness
Offset 9    4B   enc_sensitivity[4]
Offset 13  19B   reserve
Offset 32       profile 0
Offset 268      profile 1
Offset 504      profile 2

Jedes Profil belegt 236 Byte:

20 x mx_actions
12 x enc_actions
20 x led_r
20 x led_g
20 x led_b
20 x led_brightness
20 x led_anim
20 x led_period_ms

Action-Daten

Typ	Datenbereich
None	Daten werden ignoriert
HidKey	Low-Byte Keycode 0x00..0x65, High-Byte Modifier
HidConsumer	Usage 0x0000..0x03FF
HostCommand	frei definierte Command-ID 0x0000..0xFFFF
Macro	Slot 0..31
ProfileSwitch	Profil 0..2; 0x00FF oder 0xFFFF bedeuten „nächstes Profil“

LED-Animationen im Binärformat

Wert	Enum
0	Static
1	Blink
2	Pulse
3	FadeIn
4	FadeOut
5	ColorCycle
6	ColorFade

DeviceConfig akzeptiert alle Werte 0..6. Der aktuelle ActionDialog bietet nur Static, Blink, Pulse und ColorCycle an.

CRC

CRC16-CCITT:

• Polynom 0x1021
• Init 0xFFFF
• Bereich 7..739

Die CRC muss exakt zur Firmware passen.

Defaults

Firmware-Defaults:

• alle Actions None
• GlobalBrightness = 255
• enc_sensitivity = 1
• Base-Farbe R=80, G=40, B=0
• Animation ColorCycle
• Periode 4000 ms

Sichtbarer Effekt auf dem Board:

• alle MX-LEDs laufen im Regenbogenmodus

MacroTable

Stand

• 32 Slots
• 8 Steps pro Slot
• 512 Byte gesamt

Slot-Konvention

Slots	Bedeutung
0..19	MX-Buttons
20..31	Encoder-Aktionen

Serialisierung

Ein Step besteht aus:

• keycode
• modifier

keycode == 0 beendet die Ausführung des Slots. Belegte Steps nach der ersten Lücke werden daher zwar serialisiert, von der Firmware aber nicht ausgeführt.

Es gibt kein Magic und keine CRC fuer die Makrotabelle. Beim Transfer prüft die GUI trotzdem exakte Größe und alle HID-Keycodes; die Firmware prüft zusätzlich die vollständige Chunkmenge.

Validierung

ToBytes() verweigert ungültige Objektzustände. FromBytes() verändert das bestehende Objekt erst, nachdem Größe, Magic, Version, CRC, aktives Profil, Action-Werte, LED-Enums und die Mindestperiode von 2 ms für Pulse geprüft wurden. Für die Makrotabelle gelten exakte 512 Byte und Keycodes bis 0x65.

Wichtig fuer Aenderungen

Wenn sich Firmware-Layout, Magic, Version, Profilzahl oder Makrogroesse aendern, muessen mindestens diese Stellen zusammen angepasst werden:

• VersaMCU
• VersaGUI

Beide sind eigenständige Git-Repositories und werden getrennt gebaut und committed. Andere GUI-Ports gehören nicht zum gepflegten Scope.