RGB Linux Controller

Robust, manufacturer-independent RGB lighting control for Linux — no Windows required.

RGB Linux Controller is a thin, well-tested layer on top of the OpenRGB project. It detects your RGB hardware, addresses each device by category instead of a fragile hard-coded index, and applies colors and effects from a single command — either through the OpenRGB SDK server (preferred) or by falling back to the openrgb binary.

Originally built to tame Corsair RGB memory, AIGO fans and Gigabyte motherboards on Linux Mint, it now works with any OpenRGB-compatible device.

---

Features

• SDK-first, CLI-fallback — talks to openrgb --server via the official openrgb-python SDK, and transparently falls back to the openrgb binary when no server is running.
• Category-based targeting — apply a color to all devices or only to memory, motherboard, cooler, gpu, keyboard or mouse. No more guessing device numbers.
• Named & hex colors — red, blue, purple, … or any #RRGGBB code, validated before anything touches the hardware.
• Effects — Static, Breathing, Rainbow Wave, Color Pulse, Color Shift (whatever your device exposes).
• Actually tested — a real unit-test suite (pytest) covers color parsing, device detection, orchestration and the CLI, with hardware fully mocked.
• One-command installer — resolves the ACPI SMBus conflict, installs OpenRGB, sets udev permissions and registers a rgb-controller command.

Supported Hardware

Tested by the maintainer

• Memory: Corsair Vengeance RGB Pro DDR4 (I²C 0x5A / 0x5B)
• Fans: AIGO RGB fans (via the motherboard controller)
• Motherboards: Gigabyte B550M AORUS ELITE

Should work (community / OpenRGB-compatible)

Any device supported by OpenRGB — most Corsair, ASUS Aura, MSI Mystic Light and Gigabyte RGB gear. See docs/HARDWARE_GUIDE.md. Got hardware not listed? Open a hardware report.

How AIGO fans work here: AIGO fans (AR12, DR12, Aurora, …) have no software controller of their own. They plug into a small hub whose output is a standard 5V 3-pin ARGB (WS2812x) cable that goes to your motherboard's ARGB header. So OpenRGB controls them through the motherboard RGB chip (ITE/Nuvoton) — they appear as the motherboard controller, not as an "AIGO" device. To light them correctly in Direct mode, set the LED count with rgb-controller --leds N --kind motherboard.

Installation

Quick install (Ubuntu / Mint / Pop!_OS)

git clone https://github.com/philling-dev/rgb-linux-controller.git
cd rgb-linux-controller
sudo ./install.sh
sudo reboot   # required once, so the ACPI/GRUB change takes effect

The installer:

• installs OpenRGB, i2c-tools, liquidctl and the Python package
• adds acpi_enforce_resources=lax to GRUB (backs up your config first)
• writes udev rules so RGB devices are reachable without root where possible
• enables an openrgb --server systemd service and installs the rgb-controller command

Note: a reboot is required once after the first install so the kernel picks up the ACPI parameter needed to detect RGB memory.

Developer / manual install

git clone https://github.com/philling-dev/rgb-linux-controller.git
cd rgb-linux-controller
pip install -e ".[dev]"        # installs the package + test tooling
openrgb --server &             # start the SDK server (or use the systemd unit)
python -m rgb_controller.cli --list

Usage

# List every detected device, grouped by category
rgb-controller --list

# Set everything to a color
rgb-controller blue
rgb-controller "#FF6600"

# Effects
rgb-controller red --mode Breathing
rgb-controller cyan --mode "Rainbow Wave"

# Target only one category of device
rgb-controller purple --kind memory
rgb-controller off --kind motherboard

# Force the binary fallback (skip the SDK server)
rgb-controller green --no-sdk

Run rgb-controller --help for the full list. Exit codes: 0 success, 1 no/failed devices, 2 invalid color.

Available colors

red, green, blue, white, purple, yellow, cyan, orange, pink, off — or any hex code such as #FF0000.

Available modes

Static, Breathing, Rainbow Wave, Color Pulse, Color Shift (subject to what each device supports).

Project structure

rgb-linux-controller/
├── install.sh                 # One-command installer
├── pyproject.toml             # Package + test configuration
├── src/rgb_controller/
│   ├── cli.py                 # Command-line entry point (rgb-controller)
│   ├── controller.py          # High-level orchestration
│   ├── backends.py            # SDK + CLI backends, device detection
│   ├── colors.py              # Color parsing (named + hex)
│   └── errors.py              # Typed exceptions
├── tests/                     # pytest suite (hardware fully mocked)
├── scripts/detect_rgb_hardware.sh
├── examples/quick_start.sh
└── docs/
    ├── INSTALLATION.md
    └── HARDWARE_GUIDE.md

Troubleshooting

No devices detected

grep acpi_enforce_resources=lax /proc/cmdline   # empty? you still need to reboot
sudo openrgb --list-devices                     # does OpenRGB itself see them?

SDK server not reachable — the controller falls back to the binary automatically, but to use the faster SDK path make sure the server is running:

systemctl status openrgb-server   # if you used the installer
openrgb --server &                # or start it manually

Memory RGB missing — this is almost always the ACPI SMBus conflict. Confirm the GRUB parameter is active (/proc/cmdline above) and reboot once.

More in docs/INSTALLATION.md.

Running the tests

pip install -e ".[dev]"
pytest

The suite mocks all hardware, so it runs anywhere — no OpenRGB server or RGB devices required.

Contributing

Contributions are welcome — see CONTRIBUTING.md. Adding a new device usually just means confirming OpenRGB detects it and, if needed, extending classify_device() in src/rgb_controller/backends.py (with a test).

Changelog

v2.1.0

• Categorize devices by the OpenRGB device type (SDK), not name guessing — fixes memory/GPU/cooler detection for G.Skill, Kingston, MSI, ASUS and more.
• Validate the requested mode against each device and report the available modes instead of failing opaquely.
• Warn when a mode ignores the color (e.g. Rainbow) instead of falsely reporting success.
• New --leds N [--zone Z] to resize ARGB zones so fans wired through a motherboard header (e.g. AIGO) light with the correct LED count.
• Abort cleanly when the OpenRGB server drops mid-operation; close the SDK connection; normalize CLI timeouts.
• Harden install.sh: run the OpenRGB server as a non-root user, group-scoped udev rules (not world-writable), a dedicated virtualenv, a robust GRUB drop-in, and automatic I2C module loading (AMD/Intel).

v2.0.0

• Rewrote the controller around the OpenRGB SDK with a CLI fallback.
• Device targeting by category instead of hard-coded indexes.
• Added a full pytest suite (colors, backends, controller, CLI).
• Proper Python package + rgb-controller console script via pyproject.toml.
• Documentation rewritten to match the actual codebase.

v1.0.0

• Initial release: Corsair Vengeance RGB Pro, AIGO fans, Gigabyte B550M AORUS ELITE, automatic ACPI conflict resolution and one-click installer.

License

MIT — see LICENSE.

Acknowledgments

• OpenRGB — the foundation this project builds on.
• openrgb-python — the SDK client.
• The Linux RGB community for hardware testing and feedback.