Add OpenRGB SDK startup readiness service #60

Merged

JackFrostbyte merged 1 commit from fix/issue-51-openrgb-startup-device-rescan into develop

2026-05-15 19:49:56 -04:00

JackFrostbyte commented

2026-05-15 19:48:29 -04:00

Owner

Summary

Fixes #51.

This PR replaces the dependency on the generated OpenRGB XDG autostart unit with a repo-owned OpenRGB SDK user service.

The goal is to make OpenRGB start only after the NVIDIA I2C adapter needed for GPU RGB discovery is visible, reducing the chance that OpenRGB scans too early and exposes only the motherboard.

Changes

Added scripts/wait_for_openrgb_i2c.py
- waits for matching I2C adapter names under /sys/class/i2c-dev
- defaults to matching NVIDIA i2c adapter
- exits cleanly with 0 when found, 1 on timeout, and 2 for invalid arguments
Added systemd/user/openrgb-sdk.service
- runs the I2C readiness helper as ExecStartPre
- starts OpenRGB SDK server with:
  - /usr/bin/openrgb --server --server-host 127.0.0.1 --server-port 6742
Updated systemd/user/rgb-aura.service
- now depends on openrgb-sdk.service
- no longer depends on generated app-OpenRGB@autostart.service
Updated docs/systemd-user-service.md
- documents the new two-service setup
- documents disabling OpenRGB GUI/XDG autostart
- documents the NVIDIA I2C startup race
- documents the OpenRGB SDK rescan finding without relying on raw packet use
Added tests for the I2C readiness helper.

Safety notes

This does not weaken RGB Aura device mapping safety.

RGB Aura still validates the OpenRGB device mapping before writing any RGB data. Missing required devices remain a hard failure.

This PR intentionally does not hardcode the OpenRGB SDK rescan packet. The investigation confirmed that NET_PACKET_ID_REQUEST_RESCAN_DEVICES = 140 exists upstream, but the currently used openrgb-python 0.3.6 dependency does not expose it in its public API.

Validation

Validated locally:

ruff check scripts/wait_for_openrgb_i2c.py tests/test_wait_for_openrgb_i2c.py
python -m pytest tests/test_wait_for_openrgb_i2c.py
systemd-analyze --user verify systemd/user/openrgb-sdk.service systemd/user/rgb-aura.service
local user-service startup test:
- openrgb-sdk.service starts successfully
- ExecStartPre finds NVIDIA I2C adapters
- OpenRGB listens on 127.0.0.1:6742
- rgb-aura.service starts successfully afterward

## Summary Fixes #51. This PR replaces the dependency on the generated OpenRGB XDG autostart unit with a repo-owned OpenRGB SDK user service. The goal is to make OpenRGB start only after the NVIDIA I2C adapter needed for GPU RGB discovery is visible, reducing the chance that OpenRGB scans too early and exposes only the motherboard. ## Changes * Added `scripts/wait_for_openrgb_i2c.py` * waits for matching I2C adapter names under `/sys/class/i2c-dev` * defaults to matching `NVIDIA i2c adapter` * exits cleanly with `0` when found, `1` on timeout, and `2` for invalid arguments * Added `systemd/user/openrgb-sdk.service` * runs the I2C readiness helper as `ExecStartPre` * starts OpenRGB SDK server with: * `/usr/bin/openrgb --server --server-host 127.0.0.1 --server-port 6742` * Updated `systemd/user/rgb-aura.service` * now depends on `openrgb-sdk.service` * no longer depends on generated `app-OpenRGB@autostart.service` * Updated `docs/systemd-user-service.md` * documents the new two-service setup * documents disabling OpenRGB GUI/XDG autostart * documents the NVIDIA I2C startup race * documents the OpenRGB SDK rescan finding without relying on raw packet use * Added tests for the I2C readiness helper. ## Safety notes This does not weaken RGB Aura device mapping safety. RGB Aura still validates the OpenRGB device mapping before writing any RGB data. Missing required devices remain a hard failure. This PR intentionally does not hardcode the OpenRGB SDK rescan packet. The investigation confirmed that `NET_PACKET_ID_REQUEST_RESCAN_DEVICES = 140` exists upstream, but the currently used `openrgb-python 0.3.6` dependency does not expose it in its public API. ## Validation Validated locally: * `ruff check scripts/wait_for_openrgb_i2c.py tests/test_wait_for_openrgb_i2c.py` * `python -m pytest tests/test_wait_for_openrgb_i2c.py` * `systemd-analyze --user verify systemd/user/openrgb-sdk.service systemd/user/rgb-aura.service` * local user-service startup test: * `openrgb-sdk.service` starts successfully * `ExecStartPre` finds NVIDIA I2C adapters * OpenRGB listens on `127.0.0.1:6742` * `rgb-aura.service` starts successfully afterward

JackFrostbyte added 1 commit

2026-05-15 19:48:29 -04:00