Repository avatar
Other Tools
v0.1.0
active

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

CapabilitySupportedNotes / Limits
4-vendor discovery (probe, profiles)YesXREAL (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)YesPre-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)YesAccepts 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)Yes60|90|120 Hz (validated per model) and 0..100 panel brightness.
1000Hz IMU & wear sensor (imu, wear)YesFixed 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)YesConsumes 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 testingNoZero 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

  1. Non-TTY Guard: Mutating mode commands without --yes (and without --dry-run) fail closed with exit 2 before writing snapshots or hardware registers.
  2. Symlink Guard: Snapshot and license cache writes check lstat() (S_ISLNK) and refuse symlink targets with exit 4.
  3. 15-Second Auto-Revert: mode snapshots prior state atomically, verifies readback, and runs a non-restarting sigaction(sa_flags=0) + poll() watchdog that reverts to 2d on timeout (exit 1) or SIGINT/SIGTERM (exit 130).
  4. Permissions: macOS Input Monitoring denial (IOHIDCheckAccess) and Linux /dev/hidraw* EACCES/EPERM exit 4 with OS remediation hints; absent hardware exits 3.

Exit Codes & CLI Reference

Run xrctl --help for human usage or xrctl --describe for the full JSON capability manifest:

  • 0: Success
  • 1: Runtime, wire-CRC, or confirmation-timeout rollback failure
  • 2: Invalid usage, non-TTY confirm required, unsupported refresh rate, or upstream --from-json failure
  • 3: Hardware or model capability unavailable (e.g., tint on non-electrochromic glasses)
  • 4: OS HID permission denied or symlink guard triggered
  • 5: Pro license required or invalid (xrctl license activate --key <KEY>)
  • 130: SIGINT/SIGTERM received and display mode reverted to 2d

License & Security

MCPB
https://github.com/raydeoliveira/xrctl/releases/download/v0.1.0/xrctl-0.1.0-macos-arm64.mcpb
Install Command
# mcpb: https://github.com/raydeoliveira/xrctl/releases/download/v0.1.0/xrctl-0.1.0-macos-arm64.mcpb