Synced RGB on a Steam Machine: Razer keyboard, mouse and the front light bar, with Flatpak OpenRGB
This guide runs one animated effect across a Razer keyboard, a Razer mouse and the Steam Machine's own front light bar, in both Desktop Mode and Game Mode, starting automatically at boot. It keeps:
- the Flatpak OpenRGB from Flathub (no AppImage),
- a read-only SteamOS root (no
steamos-readonly disable, no pacman, no custom udev rules), - everything in your home directory and user systemd units.
My hardware is a Razer Ornata Chroma keyboard and a Razer DeathAdder V2 mouse, with OpenRGB's Effects plugin running Spectrum Cycling. The light bar part isn't Razer-specific; any device OpenRGB supports works the same way.
- Part 1 gets the keyboard and mouse running an effect. That part is easy.
- Part 2 brings in the light bar. OpenRGB detects it, but out of the box it never lights up.
Part 1: Razer keyboard and mouse
1.1 Install OpenRGB and the Effects plugin from Flathub
flatpak install --user flathub org.openrgb.OpenRGB org.openrgb.OpenRGB.Plugin.Effects
The Effects plugin is a separate Flatpak extension; without it there's no Effects tab. (I used OpenRGB 1.1 and Effects plugin 1.1.)
1.2 You don't need OpenRazer, Polychromatic, or udev rules
This is where I wasted the most time, so here's what turned out to matter:
-
OpenRGB drives Razer devices itself, directly over
/dev/hidraw*. In OpenRGB the devices show up with a location likeHID: /dev/hidraw13. OpenRazer (a kernel module and daemon) and Polychromatic (its GUI) are a separate stack and aren't needed. On a read-only SteamOS root you can't easily install OpenRazer's kernel module anyway. -
SteamOS already gives the logged-in user access to these hidraw devices. They're tagged
uaccess, which gives the logged-in user a read/write ACL on them. Check yours:for h in /dev/hidraw*; do id=$(udevadm info "$h" | grep -oE '0003:1532:[0-9A-F]{4}' | head -1) # 1532 = Razer [ -n "$id" ] && echo "$h $id $(getfacl -p "$h" 2>/dev/null | grep '^user:[a-z]')" doneYou want
user:deck:rw-on each Razer node. -
The Flatpak can already reach them: OpenRGB's Flathub manifest grants
devices=all. Check withflatpak info --show-permissions org.openrgb.OpenRGB. -
Check any udev rules you download. I had "installed" OpenRGB's
60-openrgb.rulesinto/etc/udev/rules.d/, and the file turned out to be a saved 404 HTML page.udevadm testshowsInvalid key/value pair, ignoringfor every line. Everything worked anyway, because the rules weren't needed. Runheadon rule files before trusting them.
If your Razer nodes don't show a user:deck ACL (other hardware or SteamOS
versions), then install the real 60-openrgb.rules from the OpenRGB project.
1.3 Create the effect
- Start OpenRGB. The keyboard, the mouse and "Valve Steam Machine" should all be listed.
- In the Effects tab, add an effect (I used Spectrum Cycling) and tick the devices you want, including the Valve Steam Machine for Part 2.
- Start it. The keyboard and mouse should animate together.
Keep the effect settings open; Part 2 step 1 saves them to a profile so they come back at boot.
Part 2: the Steam Machine light bar
Why it doesn't work out of the box
The light bar is driven by the leds-valve kernel module through sysfs, one LED class
device per LED:
/sys/class/leds/valve-leds[0] … /sys/class/leds/valve-leds[16]
Note the square brackets in the names: always quote these paths in the shell.
Each LED has a multi_intensity file that takes "R G B", plus brightness. SteamOS's
own /usr/lib/udev/rules.d/70-steam-jupiter-leds.rules makes the deck user the
owner of these files, so this works from a normal terminal with no sudo and no extra
rule:
echo "255 0 0" > '/sys/class/leds/valve-leds[0]/multi_intensity' # LED 0 turns red
Flatpak, however, mounts /sys read-only inside the sandbox, and no permission
override changes that. OpenRGB can see the device but its writes fail with
"Read-only file system".
The approach: a tiny host-side bridge
- Flatpak OpenRGB keeps running your effect, with the Steam Machine included, and
exposes its SDK server on
127.0.0.1:6742. - A small Python script on the host polls the Steam Machine device's colours over the SDK (every 50 ms) and writes them to sysfs.
The basic idea is simple. Most of the work was in the gotchas, so read that section even if you just copy the files.
Gotchas for the light bar (the useful part)
systemctl --user restartdoesn't restart a Flatpak app.flatpak runmoves the app into its ownapp-flatpak-…scope, so stopping the service only kills thebwrapwrapper. You end up with two OpenRGB instances. Fix:ExecStop=/usr/bin/flatpak kill org.openrgb.OpenRGB.- Two OpenRGB instances make effects fight. Opening OpenRGB from the app menu while the service copy is running starts a second instance. Both run the effect at different phases, the peripherals flicker between them, and the light bar (mirroring only one of them) looks "too fast" and out of sync. Fix: only ever use the tray icon, and override the menu launcher so it can't start a duplicate (below).
- openrgb-python 0.3.8 crashes on connect when the Effects plugin is loaded. With
SDK protocol ≥ 4 it queries plugins and dies with
StopIterationin_callbackon the Effects plugin's packets. Fix: connect withprotocol_version=3, which still provides full device and colour data. - Effects don't autostart unless their profile is loaded. In current OpenRGB the Effects plugin stores effects (including their AutoStart flag) inside a regular OpenRGB profile. That flag only fires when the profile is loaded, and "load profile on open" is off by default.
- Game Mode has no desktop for OpenRGB's Qt window. At boot in Game Mode, OpenRGB
aborts with
qt.qpa.xcb: could not connect to displayand loops on restart until you switch to Desktop Mode. Fix: run it windowless (QT_QPA_PLATFORM=offscreen) whengamescope-session.serviceis active. Effects, profiles and the SDK server all still work without a window. - Watch your unit ordering. I first had the bridge
After=openrgb.servicewith OpenRGBAfter=graphical-session.target, while the bridge wasWantedBy=default.target. In Game Mode that creates an ordering cycle throughgamescope-session.service, and systemd resolves it by droppinggraphical-session-pre.target. Fix: the bridge doesn't depend on OpenRGB at all; it just retries the connection. - The rollback trap:
brightness_startupholds a hex string (e.g.0x38) thatbrightnessrefuses. Restore onlymulti_intensity(or reboot).
Setup
1. Save the effect so it starts at boot
- Make sure the effect from Part 1 has the Valve Steam Machine ticked along with your other devices.
- Enable the effect's autostart, and save it to an OpenRGB profile (mine is called
razer). - Turn on loading that profile when OpenRGB opens: the "load profile on open" option in
OpenRGB's settings. With OpenRGB fully quit, you can instead set
"open_profile": {"enabled": true, "name": "<your profile>"}underProfileManagerin~/.var/app/org.openrgb.OpenRGB/config/OpenRGB/OpenRGB.json.
2. Install the Python client in a venv
python3 -m venv ~/.local/share/steambar
~/.local/share/steambar/bin/pip install openrgb-python==0.3.8
(Pinned because the protocol_version=3 workaround was tested against 0.3.8.)
3. The bridge: ~/.local/bin/steambar.py
#!/home/deck/.local/share/steambar/bin/python
"""Mirror the OpenRGB "Steam Machine" device colours onto the leds-valve sysfs light bar.
Flatpak OpenRGB can't write /sys (read-only inside the sandbox), so this host-side
bridge polls OpenRGB's SDK server and writes the colours itself.
"""
import glob
import os
import re
import sys
import time
from openrgb import OpenRGBClient
HOST, PORT = "127.0.0.1", 6742
DEVICE_MATCH = "Steam Machine"
INTERVAL = 0.05 # seconds between polls
RETRY = 3 # seconds between connection attempts
REVERSE = False # set True if the animation runs the wrong way
# openrgb-python 0.3.8 crashes on the Effects plugin's packets when protocol >= 4
# (plugin queries); protocol 3 still provides full device/colour data.
PROTOCOL = 3
def log(msg):
print(msg, file=sys.stderr, flush=True)
def led_dirs():
dirs = glob.glob("/sys/class/leds/valve-leds[[]*[]]")
dirs.sort(key=lambda d: int(re.search(r"\[(\d+)\]$", d).group(1)))
return dirs[::-1] if REVERSE else dirs
def write(path, value):
with open(path, "w") as f:
f.write(value)
def connect():
while True:
try:
client = OpenRGBClient(HOST, PORT, name="steambar", protocol_version=PROTOCOL)
dev = next((d for d in client.devices if DEVICE_MATCH in d.name), None)
if dev is not None:
log(f"connected; mirroring '{dev.name}' (id {dev.id}, {len(dev.colors)} LEDs)")
return client, dev
log(f"no device matching '{DEVICE_MATCH}' yet; retrying")
client.disconnect()
except Exception as e:
log(f"OpenRGB SDK not reachable ({e!r}); retrying in {RETRY}s")
time.sleep(RETRY)
def main():
dirs = led_dirs()
if not dirs:
sys.exit("no /sys/class/leds/valve-leds[N] found")
for d in dirs:
with open(os.path.join(d, "max_brightness")) as f:
write(os.path.join(d, "brightness"), f.read().strip())
files = [os.path.join(d, "multi_intensity") for d in dirs]
log(f"{len(files)} sysfs LEDs")
last = [None] * len(files)
while True:
client, dev = connect()
try:
while True:
client.comms.requestDeviceData(dev.id)
for i, (path, c) in enumerate(zip(files, dev.colors)):
rgb = f"{c.red} {c.green} {c.blue}"
if rgb != last[i]:
write(path, rgb)
last[i] = rgb
time.sleep(INTERVAL)
except OSError as e:
if getattr(e, "filename", None):
raise # sysfs write error: let systemd restart us
log(f"lost connection ({e!r}); reconnecting")
except Exception as e:
log(f"lost connection ({e!r}); reconnecting")
try:
client.disconnect()
except Exception:
pass
time.sleep(RETRY)
if __name__ == "__main__":
try:
main()
except KeyboardInterrupt:
pass
chmod +x ~/.local/bin/steambar.py
client.comms.requestDeviceData(id) re-reads just the one device synchronously, which
is much cheaper than client.update() (all devices plus profiles).
4. OpenRGB start script: ~/.local/bin/openrgb-service.sh
#!/bin/sh
# Start Flatpak OpenRGB for openrgb.service.
# Game Mode (gamescope) has no desktop/tray for OpenRGB's Qt window, so run it
# windowless there; effects, profiles and the SDK server still work.
if systemctl --user -q is-active gamescope-session.service; then
exec /usr/bin/flatpak run --env=QT_QPA_PLATFORM=offscreen --env=DISPLAY= --env=WAYLAND_DISPLAY= \
org.openrgb.OpenRGB --startminimized --server
fi
exec /usr/bin/flatpak run org.openrgb.OpenRGB --startminimized --server
chmod +x ~/.local/bin/openrgb-service.sh
5. Systemd user units
~/.config/systemd/user/openrgb.service:
[Unit]
Description=OpenRGB (Flatpak) with SDK server
After=graphical-session.target
PartOf=graphical-session.target
StartLimitIntervalSec=0
[Service]
Type=simple
ExecStartPre=/bin/sleep 5
ExecStart=%h/.local/bin/openrgb-service.sh
ExecStop=/usr/bin/flatpak kill org.openrgb.OpenRGB
Restart=on-failure
RestartSec=5
[Install]
WantedBy=graphical-session.target
PartOf= + WantedBy=graphical-session.target means switching between Game Mode and
Desktop Mode restarts OpenRGB in the right form: windowless in Game Mode, with its
tray icon in Desktop Mode.
~/.config/systemd/user/steambar.service:
[Unit]
Description=Mirror OpenRGB Steam Machine colours to the leds-valve light bar
StartLimitIntervalSec=0
[Service]
ExecStart=%h/.local/share/steambar/bin/python %h/.local/bin/steambar.py
Restart=always
RestartSec=3
[Install]
WantedBy=default.target
Note: no After=/Wants=openrgb.service here (see gotcha 6).
systemctl --user daemon-reload
systemctl --user enable --now openrgb.service steambar.service
6. Stop the app menu from starting a second copy
~/.local/bin/openrgb-launch.sh:
#!/bin/sh
# Menu launcher for Flatpak OpenRGB: never start a second copy (it would fight the
# service copy over the devices). Use the tray icon to open the running one.
if flatpak ps --columns=application | grep -qx org.openrgb.OpenRGB; then
notify-send -a OpenRGB -i org.openrgb.OpenRGB "OpenRGB is already running" "Open it from its tray icon."
else
systemctl --user start openrgb.service
notify-send -a OpenRGB -i org.openrgb.OpenRGB "OpenRGB started" "It is in the tray; click its icon to open it."
fi
Then override the menu entry (user entries take precedence over Flatpak's exported one):
chmod +x ~/.local/bin/openrgb-launch.sh
mkdir -p ~/.local/share/applications
sed -E "s|^Exec=.*|Exec=$HOME/.local/bin/openrgb-launch.sh|" \
~/.local/share/flatpak/exports/share/applications/org.openrgb.OpenRGB.desktop \
> ~/.local/share/applications/org.openrgb.OpenRGB.desktop
If OpenRGB is installed system-wide rather than per-user, the source .desktop file is
under /var/lib/flatpak/exports/share/applications/ instead.
Checking it works
systemctl --user status openrgb.service steambar.service
flatpak ps | grep -c openrgb # must be 1
cat '/sys/class/leds/valve-leds[0]/multi_intensity' # should change over time
journalctl --user -u openrgb.service -u steambar.service -b
Rollback
systemctl --user disable --now steambar.service openrgb.service
rm ~/.local/share/applications/org.openrgb.OpenRGB.desktop
for d in /sys/class/leds/valve-leds\[*\]; do
cat "$d/multi_intensity_startup" > "$d/multi_intensity"
done
(Or just reboot after disabling the services.)
Limitations
- Polling at 50 ms adds up to one frame of lag; with smooth effects it's invisible.
- In Game Mode OpenRGB has no UI, so change effects in Desktop Mode and save them to the profile.
- Tested on SteamOS with OpenRGB (Flathub) and the OpenRGB Effects plugin 1.1, and openrgb-python 0.3.8. Newer versions may fix gotchas 3 and 5 or move things around.