Skip to content

asus_ryuo: add coolant temp, LED control, and OLED display upload#880

Open
bl4dee wants to merge 1 commit into
liquidctl:mainfrom
bl4dee:add-ryuo-sensors-led-oled
Open

asus_ryuo: add coolant temp, LED control, and OLED display upload#880
bl4dee wants to merge 1 commit into
liquidctl:mainfrom
bl4dee:add-ryuo-sensors-led-oled

Conversation

@bl4dee
Copy link
Copy Markdown

@bl4dee bl4dee commented Mar 27, 2026

Summary

Extends the ASUS Ryuo I 240 driver with three new capabilities:

  • Coolant temperatureget_status() reads sensor register 0x6A and reports liquid temperature in °C
  • LED controlset_color() supports 6 modes: off, static, breathing, flash, spectrum, rainbow (commands 0x3B/0x3F)
  • OLED display uploadset_screen() uploads images/GIFs to the 160×128 OLED on the pump head via a 9-step chunked HID transfer protocol

OLED upload protocol

Reverse-engineered from ASUS LiveDash v1.05.03 (AuraIC.dll, WriteFileToFW() function):

  1. Init transfer (0x51 0xA0)
  2. Set file slot (0x6B)
  3. Stop animation (0x6C 0x01, 0x6C 0x03)
  4. Prepare transfer (0x6C 0x04)
  5. Send GIF in 62-byte chunks (0x6E) with 20ms delays (hardware SPI flash speed limit)
  6. Signal complete (0x6C 0x05)
  7. Finalize (0x6C 0xFF)
  8. Commit (0x51 0x10 0x01 N)
  9. Start playback (0x6E 0x00)

Warning: Register 0x5C must never be written after upload — it causes the OLED to go permanently black until a full power cycle. Discovered the hard way.

Usage examples

# Coolant temperature
liquidctl status

# LED control
liquidctl set led color static ff0000
liquidctl set led color breathing 0000ff
liquidctl set led color spectrum

# OLED display
liquidctl set lcd screen static photo.png
liquidctl set lcd screen gif animation.gif

Changes

File Change
liquidctl/driver/asus_ryuo.py Added get_status(), set_color(), set_screen(), _prepare_gif(), _upload_oled()
tests/test_asus_ryuo.py 16 tests (was 3) — sensors, LED modes, validation, full upload protocol verification
docs/asus-ryuo-guide.md User guide with examples for all new features
docs/developer/protocol/asus_ryuo.md Complete protocol spec including OLED upload sequence

Testing

  • 16/16 driver tests pass
  • 531/531 full suite passes (0 regressions)
  • Tested on real hardware (ASUS ROG Ryuo I 240, firmware AURO0-S452-0205)
  • Pillow is an optional dependency — only imported when set_screen() is called
  • Formatted with black --line-length 100

Notes

  • Pillow (pip install pillow) is required only for OLED uploads, imported at call time to avoid adding a hard dependency
  • I can provide USB pcap captures if needed — happy to submit a companion PR to liquidctl/collected-device-data
  • Built and tested on NixOS Linux

@bl4dee bl4dee force-pushed the add-ryuo-sensors-led-oled branch from dffa1b4 to e7f33a7 Compare March 27, 2026 00:32
Extend the ASUS Ryuo I 240 driver with:

- get_status(): read coolant temperature from sensor register 0x6A
- set_color(): LED control with 6 modes (off, static, breathing,
  flash, spectrum, rainbow) via commands 0x3B/0x3F
- set_screen(): OLED display upload using the 9-step chunked transfer
  protocol reverse-engineered from LiveDash v1.05.03 (AuraIC.dll)

The OLED upload sends GIF data in 62-byte HID chunks with 20ms delays
(hardware SPI flash speed limit). Images are auto-resized to 160x128
using Pillow (optional dependency, imported at call time).

WARNING: Register 0x5C must never be written after upload — it causes
the OLED to go permanently black until a full power cycle.

Tested on hardware. All 16 tests pass, 531 full suite pass.
@bl4dee bl4dee force-pushed the add-ryuo-sensors-led-oled branch from e7f33a7 to 600a581 Compare March 27, 2026 00:47
@rebasecase
Copy link
Copy Markdown

rebasecase commented Apr 15, 2026

There is a hid for direct frame buffer write. No point using their garbage implementation of writing to spi

also I don’t expect this to be merged. both this and openrgb maintainers seem very upset about inorganic code… the matter that you can point a binaryninja/ida/ghidra harness at the binaries and it reverses it in an hour, seems to hurt their ego

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants