
xrctl
io.github.raydeoliveira/xrctl
4-vendor AR glasses CLI & MCP server for 2D/3D SBS rollback, tint, 120Hz, and 1000Hz IMU.
Documentation
xrctl
Clean-room C17 CLI and stdio MCP server for XREAL, VITURE, Rokid, and RayNeo AR glasses on macOS and Linux/SteamOS over USB-HID and XREAL One link-local TCP (169.254.2.1:52999).
xrctl compiles to a 145,360-byte (~142 KB) stripped Mach-O arm64 binary with 4.5 ms average --version cold start and zero third-party runtime dependencies.
What It Does / What It Does Not Do
| Capability | Supported | Notes / Limits |
|---|---|---|
4-vendor discovery (probe, profiles) | Yes | XREAL (0x3318), VITURE (0x35ca), Rokid (0x04d2), RayNeo (0x1bbb/0x3941) via IOKit HID (macOS), hidraw (Linux), and XREAL One TCP (169.254.2.1:52999). |
2D / 3D SBS switching (mode, restore) | Yes | Pre-change lstat-guarded atomic snapshot, --dry-run, non-TTY --yes fail-closed guard (exit 2), and 15-second sigaction (sa_flags=0) auto-revert to 2d. |
Electrochromic lens tint (tint) | Yes | Accepts 0..3, 4..100, 0%..100%, or clear|mid|dark|opaque; fails closed (exit 3) on models without electrochromic lenses. |
Refresh rate & brightness (refresh, brightness) | Yes | 60|90|120 Hz (validated per model) and 0..100 panel brightness. |
1000Hz IMU & wear sensor (imu, wear) | Yes | Fixed 1024-slot O(1) circular ring buffer + Mahony 6DoF/9DoF quaternion fusion (--count, --duration-ms, --stream JSONL); IR/IMU wear status. |
UNIX composability & MCP (--from-json -, mcp) | Yes | Consumes display_identity, solved_mode, and target_surface envelopes; built-in JSON-RPC 2.0 mcp server (protocolVersion: "2024-11-05"). |
| Kernel extensions / physical device lab testing | No | Zero kexts or vendor SDKs. On hosts without physical glasses attached, wire codecs, state transitions, loopback TCP/HTTP, and SIGINT rollback are verified against deterministic binary fixtures and loopback servers; live USB-HID (IOKit/hidraw) and physical XREAL TCP firmware exchanges have not been tested against attached hardware. |
Install & Uninstall
Build From Source (macOS arm64 & Linux)
cd projects/xrctl
make test # ASan + UBSan C & E2E test suite
Homebrew
brew install raydeoliveira/tap/xrctl
brew uninstall xrctl
Quick Start (Human & --json Agent Usage)
Probe attached devices or run against deterministic hardware-free fixtures:
xrctl --version --json
# {"schema_version":1,"ok":true,"data":{"name":"xrctl","version":"0.1.0","edition":"commercial","arch":"arm64","platform":"macos-arm64"},"error":null}
xrctl probe --fixture xreal-air --json
# {"schema_version":1,"ok":true,"data":{"count":1,"first_vendor":"xreal","first_model":"XREAL Air 2 Pro","display_identity":{"vendor_id_hex":"3318","product_id_hex":"0424","manufacturer_code":"NRL","monitor_name":"XREAL Air 2 Pro","quirk_id":"xreal-air"},"devices":[{"vendor":"xreal","model":"XREAL Air 2 Pro","vendor_id_hex":"3318","product_id_hex":"0424","transport":"usb-hid","imu_hz":1000}]},"error":null}
xrctl profiles --vendor viture --json
# {"schema_version":1,"ok":true,"data":{"profiles":[{"vendor":"viture","vendor_id_hex":"0x35ca","known_pids":"0x1011 (One), 0x1015 (One Lite), 0x1019 (Pro)","transports":"usb-hid (0xFF 0xFE CRC16-CCITT)","modes":"2d, 3d-sbs, 3d-half-sbs","refresh_rates":"60, 90, 120","has_tint":true,"imu_hz":1000,"has_wear_sensor":true}]},"error":null}
Pipe upstream EDID patch / link-budget output into xrctl (ok:false or fits:false fails closed with exit 2):
edidsmith edid patch --fixture xreal-ar-glasses --preset full-sbs-1080p-120 --dry-run --json \
| xrctl mode 3d-sbs --fixture xreal-air --from-json - --confirm-timeout 15 --dry-run --json
Safety & Rollback
- Non-TTY Guard: Mutating
modecommands without--yes(and without--dry-run) fail closed with exit2before writing snapshots or hardware registers. - Symlink Guard: Snapshot and license cache writes check
lstat()(S_ISLNK) and refuse symlink targets with exit4. - 15-Second Auto-Revert:
modesnapshots prior state atomically, verifies readback, and runs a non-restartingsigaction(sa_flags=0)+poll()watchdog that reverts to2don timeout (exit 1) orSIGINT/SIGTERM(exit 130). - Permissions: macOS Input Monitoring denial (
IOHIDCheckAccess) and Linux/dev/hidraw*EACCES/EPERMexit4with OS remediation hints; absent hardware exits3.
Exit Codes & CLI Reference
Run xrctl --help for human usage or xrctl --describe for the full JSON capability manifest:
0: Success1: Runtime, wire-CRC, or confirmation-timeout rollback failure2: Invalid usage, non-TTY confirm required, unsupported refresh rate, or upstream--from-jsonfailure3: Hardware or model capability unavailable (e.g.,tinton non-electrochromic glasses)4: OS HID permission denied or symlink guard triggered5: Pro license required or invalid (xrctl license activate --key <KEY>)130:SIGINT/SIGTERMreceived and display mode reverted to2d
License & Security
- Security policy: SECURITY.md
https://github.com/raydeoliveira/xrctl/releases/download/v0.1.0/xrctl-0.1.0-macos-arm64.mcpb# mcpb: https://github.com/raydeoliveira/xrctl/releases/download/v0.1.0/xrctl-0.1.0-macos-arm64.mcpbRelated Servers
io.github.raydeoliveira/depthpipe
Live 2D-to-3D stereo depth pipeline, Metal DIBR weaver, and MV-HEVC Spatial Video tool.
io.github.raydeoliveira/edidsmith
EDID 1.4/CTA-861/DisplayID 2.1 parser, CVT-RB2 link-budget solver, and safe EDID patcher.
io.github.raydeoliveira/glassweave
Eye-tracked glasses-free 3D display CLI & MCP server with DDC/CI switching and shaders.