Document hidraw1 protocol errors and Frostbay findings

2026-05-25 11:09:02 +02:00 · 2026-05-25 11:09:02 +02:00 · faded1fbe2
commit faded1fbe2
parent 215a9cb771
3 changed files with 237 additions and 0 deletions
--- a/docs/frostbay-onec1-initial-findings.md
+++ b/docs/frostbay-onec1-initial-findings.md
@ -0,0 +1,131 @@
+# Frostbay / CoolingSystem_ONEC1: erste Linux-Funde
+
+Stand: 2026-05-26
+
+## Kurzfazit
+
+Für Frostbay sieht es gerade ziemlich gut aus — nicht im Sinne von "fertiger Linux-Treiber existiert", sondern im Sinne von "wir haben endlich echtes Material statt Nebel".
+
+Wichtigste harte Funde:
+- lokales Paket: `/home/nepharius/Downloads/frostbay firmware.zip`
+- darin ein BLE-Debugger als HTML-Artefakt
+- darin klare BLE-GATT-UUIDs
+- darin ein C-Interface-Snippet mit Befehlslayout
+- außerdem Windows-Tools für BLE und HID-Firmware-Upgrade
+
+Das ist Gold.
+
+## Inhalt des ZIPs
+
+Im Archiv liegen u.a.:
+- `BLE-FW-TOOL.exe`
+- `BLEDebug.EXE`
+- `coolingsystem_debugger.html`
+- `CoolingSystem_ONEC1_V08.bin`
+- `HIDFirmwareUpgrad.exe`
+- `WCHBLEDLL.dll`
+- `接口.C`
+
+Pfad im ZIP:
+- `GA25水冷固件_V08/CoolingSystem_ONEC1-FW-TOOL-V1.8/`
+
+## Harte BLE-Funde
+
+Aus `coolingsystem_debugger.html`:
+- Service UUID: `0000ffe0-0000-1000-8000-00805f9b34fb`
+- Characteristic UUID: `0000ffe1-0000-1000-8000-00805f9b34fb`
+- Gerätebezug: `CoolingSystem_ONEC1`
+
+Das heißt sehr wahrscheinlich:
+- Frostbay/ONEC1 lässt sich über normales BLE-GATT ansprechen
+- Arch Linux + BlueZ + ggf. `bleak` sollten dafür absolut machbar sein
+- COSMIC ist hier fast egal; das läuft userspace/BLE-seitig
+
+## Harter Kommando-Fund
+
+Im HTML-Debugger steckt ein 64-Byte-Default-Command:
+
+```text
+C1 02 01 00 01 25 00 00
+64 00 00 00 00 00 00 00
+09 01 05 03 00 00 00 19
+14 1A 16 1B 18 1C 1A 1D
+1C 1E 1E 1F 23 20 28 23
+2D 00 00 00 00 00 00 00
+00 00 00 00 00 00 00 00
+00 00 00 00 00 00 00 00
+```
+
+Und im C-Snippet `接口.C` sieht man:
+- `write_buff[0] == 0xC1` als relevanten Kontrollpfad
+- `write_buff[1] == 0x02` für Write/Set-Operation
+- Byte 4 = Betriebsmodus
+- Byte 5 = Lüfter-PWM/Gear
+- Byte 8 = Pumpen-PWM/Gear
+- Byte 16 = RGB-Modus / Spezialwerte
+- Byte 17/18/19 = Schalter/Frequenz/Helligkeit oder bei Custom RGB R/G/B
+
+Sehr wichtige Spezialwerte:
+- `write_buff[16] == 0xFF` -> Custom-RGB-Farbe über Bytes 17/18/19
+- `write_buff[16] == 0xFE` scheint ebenfalls ein spezieller Farb-/Moduspfad zu sein
+- `write_buff[16] == 0xFD` -> RGB-Schalter/Frequenz/Helligkeit
+- `0 < write_buff[16] < 21` -> RGB-Effektmodus
+
+Außerdem sieht das C-Snippet nach drei RGB-Kanälen/Zonen aus:
+- `RGB1_mode`
+- `RGB2_mode`
+- `RGB3_mode`
+
+## Harte Upgrade-/Tool-Funde
+
+Aus den Windows-Artefakten:
+- `BLE-FW-TOOL.exe` und `WCHBLEDLL.dll` enthalten BLE-APIs wie:
+  - `BLEInit`
+  - `BLEEnumDevice`
+  - `BLEOpenDevice`
+  - `BLEGetAllServicesUUID`
+  - `BLEReadCharacteristic`
+  - `BLEWriteCharacteristic`
+- `HIDFirmwareUpgrad.exe` deutet zusätzlich auf einen HID-Firmware-Pfad hin
+
+Einordnung:
+- Laufzeit-/Steuerpfad sehr wahrscheinlich BLE
+- Firmware-/Recovery-/Upgrade-Pfad evtl. HID oder Mischbetrieb
+
+## Web-/Ökosystem-Einordnung
+
+Konservativ gesagt:
+- kein klar belegter fertiger Linux-Frostbay-Treiber gefunden
+- aber alles deutet darauf, dass Linux-Steuerung technisch gut machbar ist
+- sinnvoller Linux-Stack wäre:
+  - `bluetoothctl`
+  - `btmon`
+  - BlueZ GATT
+  - Python `bleak`
+
+## Was das für SuperX-goes-Arch bedeutet
+
+Das Repo sollte nicht nur auf internes RGB schielen.
+Es braucht eher ein modulares Control-Gerüst:
+- Backend `hidraw` für interne RGB-/Keyboard-Kandidaten
+- Backend `ble` für Frostbay / CoolingSystem_ONEC1
+- später evtl. `ec`/`mcu`/`platform` wenn nötig
+
+## Konkrete nächste Schritte
+
+1. ZIP-Artefakte sauber ins Repo extrahieren bzw. dokumentieren
+2. aus dem HTML-Debugger die Befehlslogik als Linux-Testskript nachbauen
+3. unter Arch per BlueZ nach `CoolingSystem_ONEC1` scannen
+4. Service `ffe0` / Characteristic `ffe1` live bestätigen
+5. vorsichtig nur Read/Status/harmlosen Default-Write testen
+
+## Vorläufige Arbeitsentscheidung
+
+Für die nächsten echten Fortschritte ist Frostbay gerade fast der bessere Hebel als blindes internes RGB-Raten.
+Warum:
+- wir haben echte UUIDs
+- wir haben echte Befehlsstruktur
+- wir haben echte Tool-Artefakte
+- Linux/BLE ist dafür gut machbar
+
+Kurz: Frostbay ist nicht mehr Nebel. Frostbay ist jetzt reverse-engineerbares Fleisch.
--- a/docs/hidraw1-feature-probe.md
+++ b/docs/hidraw1-feature-probe.md
@ -0,0 +1,100 @@
+# hidraw1 Feature-/Vendor-Probe: Super X
+
+Stand: 2026-05-26
+
+## Kurzfazit
+
+`/dev/hidraw1` ist echt spannend, aber gerade noch verriegelt.
+
+Live bestätigt:
+- Compound-Interface unter `hid-multitouch`
+- Report-Descriptor-Länge: 508 Byte
+- Vendor-Page `0xff00` ist eingebettet
+- relevante Report-IDs im Descriptor:
+  - `0x1c`: Vendor Output
+  - `0x1d`: Vendor Feature
+  - `0x1e`: Vendor Feature
+
+Trotz descriptor-korrekter Minimalproben:
+- `0x1c` Output -> `EPROTO`
+- `0x1d` Feature ioctl -> `EPROTO`
+- `0x1e` Feature ioctl -> `EPROTO`
+
+Das riecht nicht nach "falsche Länge bisschen daneben".
+Das riecht eher nach mindestens einem von diesen Dingen:
+- nötiger Init-/Unlock-Handshake fehlt
+- Report-ID ist zwar richtig, Payload aber semantisch ungültig
+- Host muss erst in einen bestimmten Betriebszustand wechseln
+- `hidraw1` ist Companion-/Control-Pfad, aber nicht der erste direkt steuerbare RGB-Pfad
+
+## Live-Infos
+
+`python tools/superx_hidraw_rgb.py --device /dev/hidraw1 info`
+
+Wesentliche Ausgabe:
+- HID-Name: `Juer Xin Keyboard K2445`
+- HID-ID: `0003:00001A86:00001305`
+- phys: `usb-0000:c6:00.0-5/input1`
+- driver: `hid-multitouch`
+- report descriptor len: `508`
+
+## Sichere Proben
+
+### Output-Report `0x1c`
+Command:
+
+```bash
+python tools/superx_hidraw_rgb.py \
+  --device /dev/hidraw1 \
+  write-hex '1c 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00' \
+  --length 33 --exact-length --read-reply-ms 250
+```
+
+Resultat:
+- `write failed: [Errno 71] Protocol error`
+
+### Feature-Report `0x1d`
+Command:
+
+```bash
+python tools/superx_hidraw_rgb.py \
+  --device /dev/hidraw1 \
+  feature-hex '1d 00' \
+  --length 2 --exact-length --read-reply-ms 250
+```
+
+Resultat:
+- `feature ioctl failed: [Errno 71] Protocol error`
+
+### Feature-Report `0x1e`
+Command:
+
+```bash
+python tools/superx_hidraw_rgb.py \
+  --device /dev/hidraw1 \
+  feature-hex '1e 00 00' \
+  --length 3 --exact-length --read-reply-ms 250
+```
+
+Resultat:
+- `feature ioctl failed: [Errno 71] Protocol error`
+
+## Einordnung
+
+Wichtig:
+- Das ist keine tote Schnittstelle.
+- Aber sie akzeptiert gerade keine naiven Null-/Ping-Proben.
+- Also bitte nicht 1000 Byte-Mutationen blind draufwerfen.
+
+Praktische Schlussfolgerung:
+1. `hidraw2` ist als direkter OXP-artiger RGB-OUT-Pfad aktuell schwach
+2. `hidraw1` ist als Vendor-/Control-Fläche real, aber handshake-bedürftig
+3. damit steigt die Priorität für OEM-Artefakte und Nicht-HID-Pfade
+
+## Konsequenz für die nächsten Schritte
+
+Die engste saubere Folge ist jetzt:
+1. lokale OEM-/Tool-Artefakte weiter ausschlachten
+2. Frostbay-/CoolingSystem_ONEC1-Paket auf UUIDs, Befehlsformate und eventuelle gemeinsame Helper-Muster prüfen
+3. danach Linux-Backend-Gerüst im Repo so bauen, dass BLE/HID/EC als Backends eingehängt werden können
+4. erst dann neue Live-Writes
--- a/tools/superx_hidraw_rgb.py
+++ b/tools/superx_hidraw_rgb.py
@ -158,6 +158,9 @@ def cmd_write_hex(args):
        print(f"written: {written}")
        if args.read_reply_ms > 0:
            wait_for_reply(fd, args.read_reply_ms)
+    except OSError as exc:
+        eprint(f"write failed: {exc}")
+        return 3
    finally:
        os.close(fd)
    return 0
@ -185,6 +188,9 @@ def cmd_feature_hex(args):
        print(f"ioctl_rc: {rc}")
        if args.read_reply_ms > 0:
            wait_for_reply(fd, args.read_reply_ms)
+    except OSError as exc:
+        eprint(f"feature ioctl failed: {exc}")
+        return 3
    finally:
        os.close(fd)
    return 0