RayNeo Control v1.0.0

A Decky Loader plugin that controls RayNeo XR glasses from the Steam Deck over USB — no phone app required.

⚠️ RayNeo GT Max only

Developed and tested against the RayNeo GT Max (雷鸟 GT Max) and nothing else.

The protocol is shared across the family, so other RayNeo / FFalcon models may work — but nothing here has been verified on them, the capability gating has only been exercised against one unit's bitmap, and the brightness table is selected by device type. Treat any other model as untested.

If you try it on one, please open an issue with your tools/rayneo_cli.py caps output.

Install

1. Download RayNeo-Control.zip below
2. Decky → Settings → General → turn on 开发者模式 / Developer mode
3. Go to the new 开发者 / Developer tab → 第三方插件 / Third-Party Plugins → 浏览文件 / Browse next to 从 ZIP 压缩文件安装插件 / Install Plugin from ZIP File → pick the zip and confirm
4. Plug the glasses in over USB-C and press Connect

Decky hides the ZIP option behind developer mode, so step 2 is required.

No udev rules, no system packages. plugin.json declares "flags": ["root"] because the glasses' USB node is 0664 root:root and a plugin running as deck cannot open it.

What it does

Section	Controls
连接 Connection	Connect / disconnect, model + firmware readout
显示 Display	屏幕亮度 brightness, 显示模式 2D/3D, 屏幕尺寸 115 % / 100 % / 85 %, 场景模式 通用/电影/护眼/阅读, 动态画质 SDR / AI-HDR, 色彩增强
声音 Sound	音量 volume, 音效 标准/轻语/空间环绕, 导音鳍 Sound Tube

Every control is gated on the capability bitmap the glasses report, so unsupported options grey out rather than failing a write.

Notable in this release

• Both sliders write on every tick, matching the official app, and brightness commits once at the end of a drag. Median round trip measured at 11 ms, down from 515 ms in the first working version.
• The panel never assumes a change landed. Every silent command is confirmed against the status read-back, and a refusal moves the control back to where the hardware actually is rather than showing the requested value.
• It recovers on its own. Three unanswered polls release the handle and it keeps looking for the glasses, so replugging needs no button press — while a disconnect you asked for is left alone, not undone.
• Debug mode (one switch at the bottom of the panel) hides the diagnostic tools and silences the per-frame trace, the startup protocol tables and the timing notes. Errors and warnings are never silenced.

Known limitations

• Brightness tops out at 12 steps while the panel may reflect fewer. The glasses stop reporting brightness above the current display strategy mode's band even though the write is accepted — the same reason the official app's slider appears to fall back on its own. The mode is not on the wire, so the ceiling is fixed rather than learned.
• 阅读 (reading) mode refuses colour enhancement in hardware and reports success anyway; the toggle is greyed out there rather than trusting the read-back.
• 0x0D (brightness save) is sent but has never been observed to do anything on this hardware. It is kept because the official app sends it.
• Refresh rate is not exposed — the protocol supports 60/120 Hz and the device reports 120 Hz, but the official app offers no such setting on this model, so neither does the plugin.
• Changing 3D mode briefly blanks the glasses and shows a split screen. That is the device's normal behaviour.

How it was built

The official Android app (雷鸟 XR 眼镜 v2.1.2) was decompiled and the native library carrying all device traffic, libFFalconXRServer.so, was reverse-engineered to recover the USB framing and the full command set. Nothing from the app is redistributed; this is an independent implementation of the wire protocol.

The command table was recovered twice by two independent methods (raw disassembly and Ghidra's decompiler), which agree on all 33 opcodes. The write-up is in docs/PROTOCOL.md, and the engineering notes behind the behaviour above are in docs/NOTES.md.

Requirements

• Steam Deck with Decky Loader
• RayNeo GT Max glasses

---

MIT licensed. Not affiliated with or endorsed by RayNeo or FFalcon.