Added doc

2026-03-30 19:51:38 +02:00
parent 2eb43826ce
commit 0d6ab21733
8 changed files with 550 additions and 0 deletions
@@ -0,0 +1,104 @@
+# DeviceConfig & MacroTable
+
+**Datei:** `DeviceConfig.cs`
+
+## Überblick
+
+C#-Spiegel der Firmware-Structs. Muss byte-kompatibel mit `SDeviceConfig` (nvm_config.h) und `SMacroTable` (macro_config.h) sein.
+
+---
+
+## DeviceConfig
+
+### Felder
+
+| Feld | Typ | Inhalt |
+|---|---|---|
+| `MxActions[20]` | `DeviceAction[]` | Aktionen für MX-Buttons 0–19 |
+| `EncActions[4,3]` | `DeviceAction[,]` | Encoder [0–3][SW=0/CW=1/CCW=2] |
+| `LedBase[20]` | `Color[]` | RGB-Basis-LED-Farbe je Button |
+| `LedAnim[20]` | `LedAnimType[]` | Animation je Button |
+| `LedPeriod[20]` | `ushort[]` | Animationsperiode in ms |
+
+### Serialisierungs-Layout (ToBytes / FromBytes, 223 B)
+
+```
+Offset  0   4B   Magic 0x56503202 (little-endian)
+Offset  4   1B   Version = 2
+Offset  5   2B   CRC16-CCITT über Bytes 7–222 (little-endian)
+Offset  7  60B   MxActions[20]       je 3B: type(1) + data_lo(1) + data_hi(1)
+Offset 67  36B   EncActions[4][3]    je 3B
+Offset103  20B   LedBase[i].R
+Offset123  20B   LedBase[i].G
+Offset143  20B   LedBase[i].B
+Offset163  20B   LedAnim[i]          als byte
+Offset183  40B   LedPeriod[i]        als uint16 little-endian
+```
+
+### CRC16-CCITT
+
+Polynom `0x1021`, Init `0xFFFF`, über Bytes 7–222 (nach dem CRC-Feld selbst). Muss identisch mit Firmware-Implementierung sein. `DeviceConfig.Crc16()` ist statisch und direkt testbar.
+
+### Defaults (entspricht Firmware-Defaults)
+
+- Alle Aktionen: `None`
+- LEDs: warm-weiß (R=80, G=40, B=0)
+- Animation: `ColorCycle` (Regenbogen), Period 4000 ms
+
+---
+
+## DeviceAction
+
+```csharp
+public enum ActionType : byte { None=0, HidKey=1, HidConsumer=2, HostCommand=3, Macro=4 }
+
+public class DeviceAction {
+    public ActionType Type { get; set; }
+    public ushort     Data { get; set; }
+    // HidKey:      Low-Byte = HID Keycode, High-Byte = Modifier
+    // HidConsumer: Consumer Usage ID
+    // HostCommand: Command-ID
+    // Macro:       Slot-Index 0–31
+}
+```
+
+`DeviceAction.Display` gibt einen lesbaren String zurück (z.B. `"Strg+C"`, `"Play/Pause"`, `"Makro 3"`).
+
+---
+
+## MacroTable
+
+```csharp
+public class MacroTable {
+    public const int Slots    = 32;
+    public const int MaxSteps = 4;
+    public MacroStep[,] Steps { get; }  // [slot][step]
+}
+public class MacroStep {
+    public byte Keycode  { get; set; }  // 0 = leer
+    public byte Modifier { get; set; }
+}
+```
+
+### Slot-Konvention
+
+| Slots | Verwendung |
+|---|---|
+| 0–19 | MX-Button `mxIdx` (`MacroTable.SlotForMx(mxIdx)`) |
+| 20–31 | Encoder: `20 + enc * 3 + actIdx` (`MacroTable.SlotForEncoder(enc, actIdx)`) |
+
+### Serialisierung (256 B)
+
+32 Slots × 4 Steps × 2 B = 256 B. Keycode zuerst, dann Modifier. Kein Magic/CRC (Board akzeptiert jeden Inhalt).
+
+---
+
+## LedAnimType
+
+```csharp
+public enum LedAnimType : byte {
+    Static=0, Blink=1, Pulse=2, ColorCycle=5
+}
+```
+
+Werte entsprechen `LEDAnim` in der Firmware. `FADE_IN` (3) und `FADE_OUT` (4) existieren in der Firmware aber nicht in der GUI (nicht konfigurierbar, nur `COLOR_FADE` intern).