Atemlire

Synced RGB on a Steam Machine: Razer keyboard, mouse and the front light bar, with Flatpak OpenRGB

Steam-machine · Steamos · Openrgb · Razer · Rgb · Flatpak · Systemd · Linux-gaming

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 like HID: /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]')"
    done
    

    You want user:deck:rw- on each Razer node.

  • The Flatpak can already reach them: OpenRGB's Flathub manifest grants devices=all. Check with flatpak info --show-permissions org.openrgb.OpenRGB.

  • Check any udev rules you download. I had "installed" OpenRGB's 60-openrgb.rules into /etc/udev/rules.d/, and the file turned out to be a saved 404 HTML page. udevadm test shows Invalid key/value pair, ignoring for every line. Everything worked anyway, because the rules weren't needed. Run head on 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

  1. Start OpenRGB. The keyboard, the mouse and "Valve Steam Machine" should all be listed.
  2. 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.
  3. 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

  1. Flatpak OpenRGB keeps running your effect, with the Steam Machine included, and exposes its SDK server on 127.0.0.1:6742.
  2. 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)

  1. systemctl --user restart doesn't restart a Flatpak app. flatpak run moves the app into its own app-flatpak-…scope, so stopping the service only kills the bwrap wrapper. You end up with two OpenRGB instances. Fix: ExecStop=/usr/bin/flatpak kill org.openrgb.OpenRGB.
  2. 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).
  3. openrgb-python 0.3.8 crashes on connect when the Effects plugin is loaded. With SDK protocol ≥ 4 it queries plugins and dies with StopIteration in _callback on the Effects plugin's packets. Fix: connect with protocol_version=3, which still provides full device and colour data.
  4. 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.
  5. 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 display and loops on restart until you switch to Desktop Mode. Fix: run it windowless (QT_QPA_PLATFORM=offscreen) when gamescope-session.service is active. Effects, profiles and the SDK server all still work without a window.
  6. Watch your unit ordering. I first had the bridge After=openrgb.service with OpenRGB After=graphical-session.target, while the bridge was WantedBy=default.target. In Game Mode that creates an ordering cycle through gamescope-session.service, and systemd resolves it by dropping graphical-session-pre.target. Fix: the bridge doesn't depend on OpenRGB at all; it just retries the connection.
  7. The rollback trap: brightness_startup holds a hex string (e.g. 0x38) that brightness refuses. Restore only multi_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>"} under ProfileManager in ~/.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.