# 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

```text
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:

```text
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.