onexplayer-superxcontrol/README.md

onexplayer-superxcontrol

Linux control stack for OneXPlayer Super X with:

• DKMS kernel module
• fan control service
• GNOME Shell extension
• RGB control
• TDP control
• battery charge-limit backend

If you are searching for OneXPlayer Super X Linux fan control, OneXPlayer Super X RGB control, OneXPlayer Super X TDP control, or a GNOME extension for OneXPlayer Super X, this repository is intended for that use case.

WARNING

THIS SOFTWARE CAN CHANGE LOW-LEVEL HARDWARE BEHAVIOR. IT MAY CAUSE SYSTEM INSTABILITY, OVERHEATING, DATA LOSS, OR PERMANENT HARDWARE DAMAGE.

YOU USE THIS PROJECT ENTIRELY AT YOUR OWN RISK. I ACCEPT NO RESPONSIBILITY OR LIABILITY FOR ANY DAMAGE, FAILURE, OR LOSS CAUSED BY ITS USE, MISUSE, OR MODIFICATION.

ANYTHING ABOVE 75W TDP IS STRICTLY AT YOUR OWN RISK AND SHOULD ONLY BE USED WITH ADEQUATE THERMAL HEADROOM AND, IN PRACTICE, A WATER COOLER.

Public repository scope:

• DKMS kernel module for the oxp-sensors platform driver
• fan-control daemon and profile manager
• GNOME Shell extension
• client helpers for RGB, TDP, and battery controls used by the extension

Local reverse-engineering artifacts and dumps are kept under local/ and are excluded from Git.

Features

• oxp-sensors DKMS module for fan and EC-backed controls
• systemd fan-control daemon with switchable profiles
• GNOME Shell top-bar plugin for daily use
• RGB preset and color control helpers
• TDP presets through ryzenadj
• battery status and charge-limit backend used by the plugin

Compatibility

This repository is focused on OneXPlayer Super X.

Other OneXPlayer, AOKZOE, AYANEO, mini, or older board variants are not the target of this public tree.

Upstream Base

This project is based on the original oxp-sensors work:

• https://gitlab.com/Samsagax/oxp-sensors

Included Components

• oxp-sensors.c: kernel driver
• oxp-fan-control.py: fan-control daemon
• oxp-fan-profile.py: profile CLI used by the daemon and the plugin
• gnome-extension/: GNOME Shell top-bar plugin
• oxp-rgb, oxp-rgb-hid.py: RGB control helpers
• oxp-tdp: TDP helper based on ryzenadj
• oxp-battery-probe.py, oxp-battery-ec-probe.c: battery status / charge-limit backend for the plugin

Build DKMS Module

To build the kernel module for the running kernel:

make

To install through DKMS:

make dkms

Install On Linux

Install the running-kernel module, client tools, fan-control service, and GNOME extension:

./install.sh

Uninstall

Remove the installed userland components with:

./uninstall.sh

Full removal including /etc/oxp-fan-control.conf and user plugin state:

./uninstall.sh --purge

Fan Control Profiles

The fan daemon uses /etc/oxp-fan-control.conf and supports named profiles. Stock profiles are:

• silent
• balanced
• watercool
• aggressive

Useful commands:

/usr/local/bin/oxp-fan-profile list
/usr/local/bin/oxp-fan-profile current
sudo /usr/local/bin/oxp-fan-profile set balanced

GNOME Shell Extension

The GNOME Shell extension adds a top-bar menu for:

• fan profile switching
• RGB presets and custom color
• TDP presets
• battery charge-limit / bypass controls when the backend is available

Enable it after install:

gnome-extensions enable oxp-fan-profiles@ps1x

RGB And TDP Commands

Examples:

/usr/local/bin/oxp-rgb rainbow
/usr/local/bin/oxp-rgb red
sudo /usr/local/bin/oxp-tdp 15
sudo /usr/local/bin/oxp-tdp 20

Frost Bay Read-Only Diagnostics

Experimental Frost Bay reverse-engineering helpers live in tools/. They are read-only and intended for diagnosis before any control path is attempted.

Build the WMI EC read probe for the running kernel:

make -C /lib/modules/$(uname -r)/build M=$PWD/tools modules

Capture a labeled read-only EC snapshot. This loads the probe, captures its dmesg output, and unloads it again:

tools/oxp-wmi-ec-dump.sh frostbay-on

Summarize one or more captured dumps:

tools/oxp-wmi-dump-summary.py /tmp/oxp-wmi-ec-read-*.txt

Print a concise status from the newest /tmp dump or from an explicit dump:

tools/oxp-frostbay-status.py
tools/oxp-frostbay-status.py /tmp/oxp-wmi-ec-read-frostbay-on-YYYYmmdd-HHMMSS.txt

For native Linux BLE validation, run the guarded Frost Bay preflight script. This requires a real BlueZ Bluetooth session and will not work from WSL:

tools/frostbay-native-test.sh

Current Frost Bay observations:

• 0xfd/0xfe = 04/05 correlates with Frost Bay / high-capability power state.
• 0xfd/0xfe = 01/01 correlates with battery/direct-normal power state.
• 0x30..0x33 expose firmware-visible power-profile bytes, e.g. 04 50 64 55 for an 80/100/85 W class and 01 37 46 3c for a 55/70/60 W class.
• Do not write EC/WMI/DPTC values until the protocol is understood.

License

This repository is distributed under GPL-2.0-or-later. See LICENSE.