superx-goes-arch/README.md

SuperX-goes-Arch

Arbeitsrepo für Linux-/Arch-Support auf dem OneXPlayer Super X (Ryzen AI Max+ 395, Radeon 8060S, 128GB).

Betriebssystem: Arch Linux · Compositor: COSMIC Desktop (System76)

---

Übersicht

Bereich	Status	Beschreibung
Frostbay BLE (Kühlung)	✅ Produktiv	Fan/Pumpe via BlueZ/D-Bus steuern
Frostbay RGB	⚠️ Funktional	BLE-Writes funktionieren, aber LED-Strips physisch nicht angeschlossen
superx-ctrl.py	✅ Produktiv	Zentrale CLI-Steuerung (Frostbay + Tablet RGB + EC Turbo)
COSMIC Applet	✅ Produktiv	Panel-Applet für Cooling/RGB-Steuerung
DMS SuperXCtrl Widget	✅ Produktiv	GUI-Widget für Cooling/RGB-Steuerung im DMS-Panel (Hyprland)
Turbo-Daemon	✅ Produktiv	Key-Combo-Listener für Turbo/Mode/KB-Tasten
HHD Patch	✅ Produktiv	Turbo-Bypass für Super X ohne oxp-platform
Tablet RGB (HIDRAW)	⚠️ Hardware fehlt	RGB-Steuerung des Tablet-Moduls via HIDRAW (1a86:1305 Interface 2) – Code fertig, aber Tablet-Modul noch nicht verbaut
Keyboard RGB	❌ Nicht steuerbar	Keyboard-RGB kann nicht angesteuert werden
EC Turbo	✅ Produktiv	Turbo-Status lesen/setzen via EC (/sys/kernel/debug/ec/ec0/io)
Razer Naga Swap	✅ Produktiv	Links/Rechts-Tastenvertauschung für Razer Naga Left Handed Edition
eGPU Tuning	✅ Installiert	RX 9060 XT Performance-Tuning (runpm=0, DPM high)
Mainboard RGB (WS2812B)	🔄 In Arbeit	Original-LEDs kommen – dann Reverse-Engineering am Mainboard-RGB2-Anschluss
WMI/EC-Kernel-Module	🔄 In Arbeit	Erste Module kompilieren, aber noch nicht funktional

---

Verzeichnisstruktur

superx-goes-arch/
├── README.md                    # Diese Datei
├── install.sh                   # Full-Setup-Script (udev, Services, Applet, Tools)
├── docs/
│   ├── frostbay-ble-protocol.md # BLE GATT Protokoll (vollständig dokumentiert)
│   ├── frostbay-onec1-initial-findings.md
│   ├── frostbay-onec1-protocol.md
│   ├── frostbay-protocol-notes.md
│   ├── internal-rgb-*.md        # Mainboard RGB Research
│   ├── egpu-setup.md            # eGPU Setup (RX 9060 XT)
│   ├── live-hid-inventory.md    # HID Device Inventory
│   ├── hidraw1-feature-probe.md
│   ├── research-summary.md
│   ├── sources.md
│   └── ...
├── tools/
│   ├── frostbay_ble.py          # Frostbay BLE GATT Reader/Controller
│   ├── superx-ctrl.py           # Zentrale CLI-Steuerung (v4)
│   ├── tablet-rgb.py            # Tablet RGB via HIDRAW (dynamische Device-Erkennung)
│   ├── razer-naga-swap.py       # Button-Swap-Daemon (evdev/uinput)
│   ├── ec-read.py               # EC Turbo Status Reader
│   ├── turbo-daemon.py          # Turbo/FN Key Combo Daemon
│   ├── turbo-monitor.py         # evdev Monitor für Turbo-Tasten
│   ├── turbo-hid.py             # HIDRAW Turbo-Listener
│   ├── turbo-all.py             # Multi-Source Turbo-Scanner (ACPI + evdev + HID)
│   ├── turbo-deep.py            # Deep Turbo-Scanner (CoolingSystem + HID + Keyboard)
│   ├── turbo-atkbd.py           # AT Keyboard Turbo-Listener
│   ├── turbo-scanner.py         # Alle evdev-Geräte scannen
│   ├── patch-hhd-superx.py      # HHD Patch: Turbo-Bypass für Super X
│   ├── superx_hid_*.py          # HID Reverse-Engineering Tools
│   ├── superx_rgb_*.py          # RGB Reverse-Engineering Tools
│   ├── superx_wmi_*.py/sh       # WMI/EC Tools
│   ├── superx-egpu-perf.sh      # eGPU Performance Tuning
│   ├── superx-game-wrapper.sh   # Game Wrapper mit GPU-Selection
│   ├── steam-egpu*              # Steam eGPU Integration
│   └── wmi/                     # WMI Kernel Module Source
├── udev/
│   ├── 99-superx-hid.rules      # HIDRAW-Zugriff für Super X Vendor HID (1a86:1305)
│   ├── 99-razer-naga-swap.rules # Startet Button-Swap beim Einstecken der Razer Naga
│   └── 99-egpu-superx.rules     # eGPU Performance beim Hotplug
├── configs/
│   ├── hyprland.conf            # Hyprland Konfiguration
│   ├── amdgpu-egpu.conf         # AMDGPU eGPU Tuning (runpm=0, sched_policy=1)
│   ├── razer-naga-swap.service  # systemd-Service für Button-Swap-Daemon
│   └── steam-egpu.desktop       # Steam Desktop Entry mit eGPU
├── cosmic-applet-superx/
│   ├── Cargo.toml               # Rust-Projekt
│   ├── src/
│   │   ├── main.rs              # Einstiegspunkt
│   │   ├── lib.rs               # Modul-Deklaration
│   │   ├── app.rs               # Applet-Logik (UI, Subprocess-Aufrufe)
│   │   └── config.rs            # APP_ID
│   ├── com.system76.CosmicAppletSuperX.desktop
│   └── install.sh               # Build + Install für COSMIC Applet
└── dms/
    └── plugins/
        └── SuperXCtrl/
            ├── plugin.json          # DMS Plugin-Metadaten
            ├── plugin_settings.json # Plugin-Settings (enabled)
            └── SuperXWidget.qml     # QML Widget (Cooling + RGB Tabs)

---

Installation

Komplett-Setup (empfohlen)

git clone ssh://git@git.nepharius.at:2222/nepharius/superx-goes-arch.git
cd superx-goes-arch
./install.sh

Das Script installiert:

• COSMIC Applet (build + systemd-User-Service)
• udev-Regeln (Super X HID, Razer Naga, eGPU)
• Razer Naga Button-Swap-Daemon
• eGPU Performance-Tuning (modprobe.d + perf-script)
• Symlinks für CLI-Tools in ~/.local/bin/
• DMS Widget (falls DMS installiert)

Einzel-Komponenten

Siehe Abschnitte unten.

---

COSMIC Applet

Ein Rust-Applet für den COSMIC Desktop-Panel. Steuert Frostbay Cooling, RGB und Tablet RGB.

Installation

cd cosmic-applet-superx
cargo build --release
install -Dm755 target/release/cosmic-applet-superx ~/.local/bin/
install -Dm644 com.system76.CosmicAppletSuperX.desktop ~/.local/share/applications/

Autostart (systemd user service)

cat > ~/.config/systemd/user/cosmic-applet-superx.service << 'EOF'
[Unit]
Description=Super X Control COSMIC Applet
After=graphical-session.target
PartOf=graphical-session.target

[Service]
Type=simple
ExecStart=%h/.local/bin/cosmic-applet-superx
Restart=on-failure
RestartSec=3

[Install]
WantedBy=graphical-session.target
EOF
systemctl --user daemon-reload
systemctl --user enable --now cosmic-applet-superx.service

Panel-Platzierung

Das Applet erscheint in COSMIC Settings → Desktop → Panel → Applets → Add. Oder direkt via Config: in ~/.config/cosmic/com.system76.CosmicPanel.Panel/v1/plugins_wings den Eintrag "com.system76.CosmicAppletSuperX" hinzufügen.

Features

• Cooling Modes: Off, Silent, Gentle, Strong, Extreme, Smart
• Custom Fan/Pump: Slider 0-100%
• Frostbay RGB: 10 Presets + On/Off
• Tablet RGB: On/Off, Rainbow, Aurora
• Status-Anzeige im Popup

---

Frostbay BLE (Kühlung)

Die Frostbay ONEC1 Wasserkühlung kommuniziert via BLE GATT (nicht HID!).

Verbindung

Eigenschaft	Wert
Gerätename	CoolingSystem_ONEC1
BT-Adresse	variabel (z.B. C8:17:17:F5:C8:62)
Service	0000ffe0-0000-1000-8000-00805f9b34fb
Char (R/W)	0000ffe1-0000-1000-8000-00805f9b34fb (64 Byte Blocks)

Nutzung

# Status abfragen
python3 tools/frostbay_ble.py status

# Modus setzen
python3 tools/frostbay_ble.py mode silent
python3 tools/frostbay_ble.py mode custom --fan 25 --pump 25

# Ausschalten
python3 tools/frostbay_ble.py off

# Raw-Dump
python3 tools/frostbay_ble.py raw

Wichtig: D-Bus (BlueZ) muss für den User zugänglich sein. Standardmässig via TAG+="uaccess" in der udev-Regel. Kein sudo nötig.

Details: docs/frostbay-ble-protocol.md

---

superx-ctrl.py (Zentrale Steuerung)

tools/superx-ctrl.py ist die zentrale CLI-Schnittstelle, die alle Subsysteme zusammenfasst.

Nutzung

# Status (Frostbay + verfügbare Modi)
superx-ctrl.py status

# Frostbay Cooling Mode
superx-ctrl.py mode off|silent|gentle|strong|extreme|smart

# Custom Fan/Pump
superx-ctrl.py custom 30 30

# Frostbay RGB Preset (1-10)
superx-ctrl.py rgb-preset 9

# Frostbay RGB Helligkeit
superx-ctrl.py rgb-brightness <switch> <speed> <brightness>
superx-ctrl.py rgb-on
superx-ctrl.py rgb-off

# Tablet RGB (HIDRAW)
superx-ctrl.py tablet on|off|rainbow|aurora
superx-ctrl.py tablet <r> <g> <b>   # Static Color

# EC Turbo
superx-ctrl.py ec-status
superx-ctrl.py ec-turbo-on
superx-ctrl.py ec-turbo-off

Architektur

superx-ctrl.py
├── Frostbay BLE (D-Bus/BlueZ) → tools/frostbay_ble.py
│   ├── Cooling Modes (off/silent/gentle/strong/extreme/smart/custom)
│   ├── RGB Presets (1-10) via 2-Step BLE Write
│   └── RGB Brightness/Switch/Speed
├── Tablet RGB (HIDRAW) → tools/tablet-rgb.py
│   ├── Static Color (R G B)
│   ├── Presets (rainbow, aurora)
│   └── On/Off
└── EC Turbo (debugfs) → tools/ec-read.py
    ├── Turbo Status lesen
    └── Turbo setzen (0x30 = 0x06/0x00)

---

Razer Naga Left Handed – Button Swap

tools/razer-naga-swap.py ist ein Daemon, der die linke und rechte Maustaste der Razer Naga Left Handed Edition vertauscht.

Funktionsweise

• Nutzt evdev + uinput (Kernel-Level)
• Grabbed die originale Maus, erzeugt einen virtuellen Device mit getauschten Tasten
• Funktioniert systemweit: COSMIC, Greeter, XWayland, Spiele
• Nur die Razer Naga (1532:008d) wird beeinflusst – Touchpad und andere Mäuse bleiben normal

Installation

sudo cp tools/razer-naga-swap.py /usr/local/bin/
sudo chmod +x /usr/local/bin/razer-naga-swap.py
sudo cp configs/razer-naga-swap.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now razer-naga-swap.service

udev-Hotplug

udev/99-razer-naga-swap.rules startet den Daemon automatisch beim Einstecken der Maus.

---

eGPU Performance Tuning

Für die RX 9060 XT (Navi 44) am USB4-Controller.

Kernel-Parameter

configs/amdgpu-egpu.conf → /etc/modprobe.d/amdgpu-egpu.conf:

options amdgpu ppfeaturemask=0xfff7bfff   # OverDrive / PowerPlay
options amdgpu gpu_recovery=1              # GPU Recovery statt Kernel Panic
options amdgpu runpm=0                     # Runtime-PM aus (eGPU bleibt wach)
options amdgpu dc=1                        # Display Core
options amdgpu sched_policy=1             # Priority-Scheduler (Gaming)
options amdgpu mes=1                       # Micro Engine Scheduler

Reboot erforderlich nach Änderung (amdgpu ist built-in).

Performance-Script

tools/superx-egpu-perf.sh setzt beim eGPU-Connect:

• power_dpm_force_performance_level → high
• power/control → on (Runtime-PM deaktiviert)
• PCIe ASPM → aus

udev-Hotplug

udev/99-egpu-superx.rules triggert das Performance-Script beim Erscheinen der RX 9060 XT.

Game Wrapper

tools/superx-game-wrapper.sh erkennt live ob die eGPU verbunden ist und setzt DRI_PRIME=1 + VK_ICD_FILENAMES nur dann.

In Steam → Properties → Launch Options:

/home/nepharius/SuperX-goes-Arch/tools/superx-game-wrapper.sh %command%

---

Tablet RGB (HIDRAW)

tools/tablet-rgb.py steuert die RGB-Beleuchtung des Tablet-Moduls via HIDRAW.

Wichtig: Die HIDRAW-Erkennung ist dynamisch – sie sucht automatisch nach dem Super X Vendor HID (1a86:1305, Interface 2). Funktioniert auch wenn sich der Device-Node nach Neustart ändert.

Nutzung

# An/Aus
python3 tools/tablet-rgb.py on
python3 tools/tablet-rgb.py off

# Presets
python3 tools/tablet-rgb.py rainbow
python3 tools/tablet-rgb.py aurora
python3 tools/tablet-rgb.py preset 0x09

# Static Color
python3 tools/tablet-rgb.py 255 0 0    # Rot
python3 tools/tablet-rgb.py 0 255 0    # Grün
python3 tools/tablet-rgb.py 0 0 255    # Blau

---

udev-Regeln

99-superx-hid.rules

KERNEL=="hidraw*", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="1305", MODE="0666", TAG+="uaccess"

Gibt Lese-/Schreibzugriff auf die Super X Vendor HID-Schnittstelle (0x1A86:0x1305).

99-razer-naga-swap.rules

ACTION=="add", SUBSYSTEM=="input", ATTRS{idVendor}=="1532", ATTRS{idProduct}=="008d", ENV{ID_INPUT_MOUSE}=="1", RUN+="/usr/local/bin/razer-naga-swap.py"

Startet den Button-Swap-Daemon beim Einstecken der Razer Naga.

99-egpu-superx.rules

Triggert superx-egpu-perf.sh beim (Dis-)Connect der RX 9060 XT.

Installation

sudo cp udev/*.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

---

EC Turbo

Der Embedded Controller des Super X speichert den Turbo-Status in EC-RAM.

Register

Offset	Grösse	Beschreibung
0x30	1 Byte	Turbo Status (0x00=off, 0x06=turbo)
0x31	1 Byte	Fan1 PWM
0x32	1 Byte	Fan2 PWM
0x33	1 Byte	Pump PWM

Nutzung

# Status lesen
sudo python3 tools/ec-read.py

# Watch-Mode (alle 500ms)
sudo python3 tools/ec-read.py watch

# Turbo setzen
sudo sh -c 'printf "\x06" | dd of=/sys/kernel/debug/ec/ec0/io bs=1 seek=$((0x30)) count=1 conv=notrunc 2>/dev/null'

---

HHD Patch (Turbo-Bypass)

tools/patch-hhd-superx.py patcht HHD, damit der Turbo-Button auf dem Super X funktioniert — auch ohne oxp-platform Kernel-Modul.

Was der Patch macht

Ersetzt in /usr/lib/python3.14/site-packages/hhd/device/oxp/__init__.py die Turbo-Erkennung:

• Vorher: Turbo nur aktiv wenn /sys/devices/platform/oxp-platform/tt_toggle existiert
• Nachher: Zusätzlich: Wenn Super X Vendor HID (0x1A86:0x1305) erkannt wird → Turbo aktivieren

Anwendung

# Nach HHD-Update erneut ausführen
sudo python3 tools/patch-hhd-superx.py

---

Turbo-Daemon

tools/turbo-daemon.py lauscht auf Key Combos und führt Aktionen aus.

Key Combos

Combo	Aktion
LEFTCTRL + LEFTALT + LEFTMETA	Turbo → Cooling Mode "smart"
LEFTMETA + D	Mode → RGB Preset 9 (Aurora)
LEFTMETA + O + RIGHTCTRL	KB → Cooling Mode "gentle"

Start

# Manuell
python3 tools/turbo-daemon.py

# Als systemd-user Service (empfohlen)
# → ~/.config/systemd/user/turbo-daemon.service

---

DMS SuperXCtrl Widget

Das DMS-Widget bietet eine GUI für Cooling- und RGB-Steuerung im DMS-Panel (für Hyprland/DankMaterialShell).

Installation

mkdir -p ~/.config/DankMaterialShell/plugins/SuperXCtrl/
cp dms/plugins/SuperXCtrl/* ~/.config/DankMaterialShell/plugins/SuperXCtrl/
# Plugin aktivieren (plugin_settings.json)
# → {"superXCtrl": {"enabled": true}}

Features

• Cooling Tab: 6 Modes (Off/Silent/Gentle/Strong/Extreme/Smart) + Custom Fan/Pump Slider
• RGB Tab: 10 Frostbay RGB Presets + On/Off + Tablet RGB (4 Presets + 6 Farben)
• Status-Pill in der DMS-Bar: zeigt an ob Cooling aktiv ist

---

Hardware

• OneXPlayer Super X (Ryzen AI Max+ 395, Radeon 8060S, 128GB RAM, 96GB VRAM)
• Frostbay ONEC1 Wasserkühlung (BLE GATT)
• eGPU: RX 9060 XT (Navi 44, 16GB) via ADTLINK UT4G an USB4
• Tablet-Modul mit RGB via HIDRAW (0x1A86:0x1305) – noch nicht verbaut
• Mainboard RGB über SYSTEK ZT5571VG-Platine (GA25-RGB_FPC_VA_5522) – Original-LEDs kommen
• Razer Naga Left Handed Edition (1532:008d) – mit Button-Swap-Daemon

---

Git Remote

git remote add origin ssh://git@git.nepharius.at:2222/nepharius/superx-goes-arch.git

---

Roadmap

1. ✅ Frostbay BLE unter Linux/BlueZ steuern
2. ✅ superx-ctrl.py als zentrale CLI
3. ✅ COSMIC Applet für Panel-Steuerung
4. ✅ DMS Widget für GUI-Steuerung
5. ✅ HHD Patch für Turbo-Button
6. ✅ Tablet RGB via HIDRAW
7. ✅ Razer Naga Button-Swap
8. ✅ eGPU Performance-Tuning
9. 🔄 Original-LEDs verbauen → Mainboard-RGB Reverse-Engineering
10. 🔄 WMI/EC-Kernel-Module für vollständige Systemsteuerung