โ AllyDock (v1.2.1) - Autonomous Docking & System Optimization Suite for ASUS ROG Ally on Bazzite OS
Important
AllyDock v1.2.0 Autonomous Docking & Optimization Suite
AllyDock is a comprehensive, production-tested suite of automation scripts, udev rules, systemd system services, sleep/wake hooks, Handheld Daemon (hhd) state profiles, tuned Steam Input Desktop Layout configurations, and an intelligent display detector with 3-tier adaptive profiling (Handheld 45 FPS vs. 60Hz TV vs. AMD FreeSync/VRR Uncapped) engineered specifically for the ASUS ROG Ally (RC71L) running Bazzite OS.
The suite has been extensively battle-tested under real-world gaming conditions: it dynamically inspects connected displays via raw binary EDID and DRM sysfs interfaces, automatically selects optimal TDP and frame rate caps, resolves gamepad flapping loops, routes PipeWire audio seamlessly, and turns desktop joystick navigation into an ergonomic, responsive trackpad and turbo scroller.
Note
Personal Backup & Disclaimer
This repository is maintained for personal backup and automated deployment of the author's ASUS ROG Ally (RC71L) setup running Bazzite OS. The code is provided "AS-IS", without warranties or official support. You are warmly welcome to fork, modify, and adapt these scripts to suit your own handheld configurations.
allydock โข ally-dock โข asus-rog-ally โข rog-ally โข bazzite-os โข display-detection โข edid-parser โข amd-freesync โข vrr โข handheld-daemon โข hhd โข steam-input โข docked-mode โข tdp-switcher โข mangohud-fps โข pipewire-audio โข decky-loader โข ge-proton โข linux-gaming โข kde-plasma-6 โข handheld-pc โข gamepad-flapping-fix
| Component / Subsystem | Version / Configuration | Technical Notes |
|---|---|---|
| Hardware Platform | ASUS ROG Ally (RC71L.319) | AMD Ryzen Z1 Extreme, 16GB LPDDR5, 120Hz FreeSync Premium |
| Operating System | Bazzite 43 / 44 / 45 (Kinoite) | Linux Kernel 6.17.xโ6.18.x (fsync kernel) |
| Desktop Environment | KDE Plasma 6 (Wayland) | Gamescope Session in Game Mode, SDDM passwordless autologin |
| Display Detection | bin/ally-detect-display.py |
Pure Python 3: raw binary EDID parsing (CEA-861, DisplayID, AMD FreeSync OUI 0x00001a, HDMI Forum VRR OUI 0xc45dd8, VESA checksum) |
| Adaptive Profiler | bin/ally-docked-mode.sh |
3 Tiers: Handheld (45 FPS / 15W), TV 60Hz (60 FPS / 25W), AMD VRR (0 Uncapped / 30W Turbo) |
| Gamepad Daemon | InputPlumber / HHD | InputPlumber v0.83+ (Bazzite 45 default) / HHD v2.88+, flapping loop prevention |
| Decky Loader | v3.2.9 (plugin_loader.service) |
Fully verified with decky-lsfg-vk, CssLoader, Junk-Store, Bazzite Buddy |
| Proton Runner | GE-Proton11-7 |
Set environment variable: PROTON_FSR4_RDNA3_UPGRADE=1 |
| Audio Server (Sound) | PipeWire + WirePlumber | Calibrated speaker DSP filter + Valve HRTF 7.1 spatializer (sadie_d1.sofa) |
| Storage (NVMe SSD) | Samsung PM991a 1TB NVMe (SAMSUNG MZ9LQ1T0HBLB-00B00) |
Btrfs subvolumes subvol=root (/) and subvol=home (/var/home) |
-
Hardware Display Detector (
bin/ally-detect-display.py):- Written in pure Python 3 using standard library modules only (zero external runtime dependencies).
- Scans kernel DRM connector endpoints at
/sys/class/drm/card*-*/status(ignoring internaleDPand virtualWritebackconnectors). - Reads raw binary
ediddirectly from the connector sysfs node with strict validation:- VESA header signature verification:
00 FF FF FF FF FF FF 00. - Checksum validation across base and extension blocks (
sum(block) % 256 == 0).
- VESA header signature verification:
- Extracts the exact commercial monitor or TV model string from
0xFCdescriptor blocks (e.g., "LG OLED TV", "ASUS ROG XG27"). - Dynamically calculates maximum supported refresh rate (
max_hz) across Detailed Timing Descriptors (DTD), standard timing bytes, and the Range Limits descriptor (0xFD). - Deep-scans CTA-861 and DisplayID extension blocks for:
- AMD FreeSync (Vendor-Specific Data Block, IEEE OUI
0x00001a); - HDMI Forum VRR (HF-VSDB, IEEE OUI
0xc45dd8); - VESA Adaptive-Sync (DisplayID 2.0 block
0x22).
- AMD FreeSync (Vendor-Specific Data Block, IEEE OUI
- Verifies the kernel DRM
vrr_capableconnector property via sysfs anddrm_info. - Supports
--shellformatted output (for instantaneousevalingestion in bash scripts) and structured--jsonoutput.
-
3-Tier Adaptive Operating Profiles:
- ๐ฑ
handheld(Undocked / Handheld Mode):- TDP:
balanced(15โ20W) - CPU EPP:
balance_power - GPU DPM:
auto - Target FPS: 45 FPS (applied to
MangoHud.confandally-fps.statefor whisper-quiet fan operation, smooth 2:1 pulldown on the 120Hz native screen, and extended battery runtimes) - Audio: Calibrated
ROG Allyspeaker DSP equalizer profile - Controller: Internal controller enabled in standard mode (
mode=uinput)
- TDP:
- ๐บ
docked_tv_60(Standard Living Room TV or 60Hz Office Monitor):- TDP:
performance(25W) - CPU EPP:
balance_performance - GPU DPM:
auto - Target FPS: 60 FPS (fixed frame cap eliminating tearing, judder, and unnecessary thermal accumulation on fixed 60Hz displays)
- Audio: External HDMI audio sink (
alsa_output.pci-0000_09_00.1.hdmi-stereo) - Controller: Console Docked Mode (when an external controller is connected, the built-in controller hides into
mode=hidden, promoting the external pad to Player 1)
- TDP:
- โก
docked_amd_vrr(AMD FreeSync / 120Hz+ High-Refresh Gaming Monitor):- TDP:
performance(Turbo 30W) - CPU EPP:
performance - GPU DPM:
high(locks RDNA3 compute engines at maximum dynamic frequency ceiling) - Target FPS: 0 (Uncapped / No frame limiter)
- Audio: External HDMI audio sink
- Controller: Console Docked Mode
- TDP:
- ๐ฑ
-
Fail-Safe Architecture:
- If an external display is physically connected but the EDID is corrupted, missing, or fails checksum validation, AllyDock safely defaults to
docked_tv_60(60 FPS, 25W). - When an external display is disconnected, the system unconditionally reverts to
handheld(45 FPS, 15W).
- If an external display is physically connected but the EDID is corrupted, missing, or fails checksum validation, AllyDock safely defaults to
- The Problem: When placing the ROG Ally into a docking station and connecting it to a TV along with a wireless Bluetooth or USB gamepad (such as GuliKit KingKong, Xbox Wireless Controller, or DualSense), the handheld's internal controller remained registered as the primary gamepad (
/dev/input/js0/ Player 1). Games launched from couch distance assigned the external pad to "Player 2", rendering single-player couch gameplay impossible. Furthermore, if an external Bluetooth gamepad fell asleep during cutscenes, legacy scripts would re-enable the internal pad, causing the external gamepad to lose Player 1 upon waking up. - The AllyDock Solution:
ally-docked-mode.shcoordinates with udev and BlueZ to monitor external display and external controller attachment events:- TV Connected (Docked): The internal gamepad is unconditionally hidden via the HHD IPC API (
controllers.rog_ally.controller_mode.mode=hidden). This guarantees that external Bluetooth/USB gamepads have permanent, exclusive ownership of Player 1, even after repeated sleep/wake power cycles. - Bluetooth BlueZ Integration: Direct query via
bluetoothctl devices Connectedprevents race conditions during Bluetooth reconnections. - Handheld Mode (Undocked): Internal controller mode is immediately restored to its default state (
mode=uinput).
- TV Connected (Docked): The internal gamepad is unconditionally hidden via the HHD IPC API (
- The Problem: In Docked mode, when the external gamepad (e.g. GuliKit) powers down to save battery while watching a dialogue, reading, or paused in a single-player game (The Last Campfire, RPGs, etc.), and the built-in controller is hidden, the system input bus has 0 active gamepads. Steam's Big Picture / GamepadUI detects absolute inactivity and pops up the fullscreen screensaver (
Screensaver_uid2) after 300 seconds (5 minutes), obscuring the game and halting background subtitle/translation scanners. - The AllyDock Solution:
ally-keepalive.pydaemon managed automatically byally-keepalive.service:- Non-Gamepad Dummy Evdev Node: Creates a virtual dummy node via
/dev/uinput(EV_KEY: KEY_RESERVED). Because it carries NO joystick buttons or axes, it never registers as/dev/input/js*and strictly consumes ZERO gamepad slots, keeping Slot 1 100% reserved for external controllers. - Dual Activity Heartbeat: Every 90 seconds, emits a micro-sync on the evdev node and triggers
org.freedesktop.ScreenSaver.SimulateUserActivityvia user D-Bus. This keeps Steam's 300-second idle timer continuously refreshed without disturbing the running game. - Automatic Life-Cycle: Automatically started upon entering
docked_tv_60ordocked_amd_vrr, and stopped upon switching back tohandheld. Zero CPU overhead (<0.001%).
- Non-Gamepad Dummy Evdev Node: Creates a virtual dummy node via
- The Problem (Why controllers were disconnecting and cycling):
- Legacy community scripts attempted to disable the built-in controller by physically unbinding the kernel USB device:
echo 1-2:1.0 > /sys/bus/usb/drivers/xpad/unbind. This forcibly invalidated file descriptors inside Gamescope (Failed to open device /dev/input/event17) and flooded kernel logs with URB transfer errors (unable to receive magic message: -32). - HHD emulates an
Xbox Elitecontroller to expose the rear macro paddles (M1/M2) to Steam Input. Outdated scripts mistakenly identified this virtual Xbox Elite device as a physical external gamepad! - This triggered a recursive flapping loop (cycling 10+ times per minute): the system detected its own virtual gamepad, disabled the controller, noticed zero gamepads were present, re-enabled it, and repeated indefinitely.
- Legacy community scripts attempted to disable the built-in controller by physically unbinding the kernel USB device:
- The AllyDock Solution:
- Completely purged destructive
xpad unbindcalls. Controller arbitration is managed exclusively via the official HHD high-level API. - Strict udev filtering explicitly ignores
/devices/virtual/input/*, guaranteeing deterministic distinction between physical USB/Bluetooth gamepads and virtual emulated input nodes. - File-based mutex lock (
flockon/var/home/V/.local/share/ally-docked.lock) guarantees atomic execution and eliminates race conditions during rapid hotplug events.
- Completely purged destructive
- The Problem: PipeWire exposes 4 distinct audio endpoints on the ROG Ally: the raw Realtek ALC294 DAC (
analog-stereo), the HDMI audio output (hdmi-stereo), the spatial audio filtereffect_input.spatializer, and the hardware-calibratedROG AllyDSP speaker processing node. When docking to a TV, audio frequently routed to the raw ALC294 DAC (yielding flat, tinny sound without bass) or remained trapped on the handheld. - The AllyDock Solution:
ally-docked-mode.shautomatically arbitrates the active Default Audio Sink:- When docked to a TV: Audio routes to
alsa_output.pci-0000_09_00.1.hdmi-stereo(TV speakers or living-room soundbar). - When undocked: Audio returns to the hardware-calibrated
ROG AllyDSP equalizer sink, restoring rich acoustic dynamics and deep bass response.
- When docked to a TV: Audio routes to
- Dynamic Watchdog (
bin/hhd-watchdog.sh): Intelligently detects the active input daemon stack (hhd.serviceon Bazzite 43 orinputplumber.serviceon Bazzite 44) and manages service health. Runs seamlessly as asystemdtimer every 15 minutes with zero measurable CPU overhead. - Sleep Recovery Hook (
sleep/10-hhd-watchdog-sleep.sh): Installed into/etc/systemd/system-sleep/. Re-synchronizes controller states and restores proper input mappings immediately after the device wakes from suspend.
- The Problem: The stock Steam Desktop Layout configures analog sticks for discrete single keystrokes or arrow clicks, turning web browsing and document navigation into a painfully slow, staccato chore.
- The AllyDock Solution: In
desktop_xboxone.vdfanddesktop_neptune.vdf, the left analog stick is mapped tomouse_wheel SCROLL_UPandmouse_wheel SCROLL_DOWNwith calibrated Turbo Repeat:Tilting the left stick up or down delivers continuous, fluid, momentum-like scrolling through websites and documents."hold_repeats" "1" "repeat_rate" "20"
- The Problem: Cursor jitter when targeting fine desktop UI elements, or unpredictable non-linear cursor acceleration.
- The AllyDock Solution: Calibrated tracking parameters:
"sensitivity" "130"โ tuned baseline sensitivity."response_curve" "2"โ exponential response curve: micro-movements near deadzone provide sub-pixel accuracy, full deflections sweep rapidly across the 1080p display."mouse_smoothing" "1"โ hardware-level micro-jitter suppression for finger tremor elimination."deadzone_inner_radius" "6000"โ clean deadzone completely eliminating stick drift.
AllyDock/
โโโ VERSION # Version identifier (1.1.0)
โโโ README.md # Comprehensive documentation and technical specification
โโโ restore.sh # Unified bash deployment script (one-command setup)
โโโ bin/
โ โโโ ally-detect-display.py # Display detection engine: EDID, VESA checksum, FreeSync, HDMI VRR, Hz
โ โโโ ally-docked-mode.sh # Primary adaptive orchestrator (3 profiles, TDP, EPP, FPS, Audio)
โ โโโ hhd-watchdog.sh # Watchdog daemon for self-healing HHD / InputPlumber services
โโโ hhd/
โ โโโ state.yml # Exported working HHD configuration (DualSense/Xbox, paddles as Steam Input)
โโโ sleep/
โ โโโ 10-hhd-watchdog-sleep.sh # System sleep hook for /etc/systemd/system-sleep/ (suspend/resume handler)
โโโ steam/
โ โโโ desktop_neptune.vdf # Patched Steam Input Desktop Layout (Neptune / Deck style)
โ โโโ desktop_xboxone.vdf # Patched Steam Input Desktop Layout (Xbox One / Ally style)
โโโ systemd/
โ โโโ ally-docked.service # Oneshot system service executing dock state transitions
โ โโโ hhd-watchdog.service # Background service unit verifying input daemon health
โ โโโ hhd-watchdog.timer # Systemd timer unit triggering watchdog checks every 15 minutes
โโโ udev/
โโโ 99-ally-docked.rules # Udev event rules for DRM/HDMI display and USB gamepad hotplug
Whether you reinstalled Bazzite OS, performed a system rebase to a new Fedora release, or are deploying AllyDock on a fresh configuration:
git clone https://github.com/VadymTaras/AllyDock.git && cd AllyDock && sudo ./restore.sh- Creates required directory structures across
/etc/and the user home directory (/var/home/V/). - Installs and applies executable permissions to
ally-docked-mode.sh,ally-detect-display.py, andhhd-watchdog.sh. - Installs udev rules and executes
udevadm control --reload-rules && udevadm trigger. - Deploys
ally-docked.service,hhd-watchdog.service, and activateshhd-watchdog.timer. - Installs the system sleep hook
/etc/systemd/system-sleep/10-hhd-watchdog-sleep.sh. - Restores
/etc/hhd/state.ymlwith proper system permissions. - Installs the modified Steam Input Desktop Layout templates into
controller_base.
sudo systemctl rebootOperates directly at the hardware microcontroller level (0b05:1abe), remaining fully functional even if Steam is closed or unresponsive:
- ๐ Toggle ON / OFF: Press and hold the Armoury Crate button (top-right button with the ROG triangle logo) for ~1.5 seconds.
- Double Haptic Pulse: Hardware Mouse Mode ENABLED.
- Single Haptic Pulse: Reverted to standard gamepad mode.
- ๐น๏ธ Right Stick: Mouse cursor positioning.
- ๐ RB (Right Bumper): Left Mouse Button (LMB).
- ๐ RT (Right Trigger): Right Mouse Button (RMB).
- ๐น๏ธ Left Stick / D-Pad: Vertical mouse wheel scroll.
Active by default in KDE Plasma 6 Wayland desktop when Steam is running in the background:
- ๐น๏ธ Right Stick: High-precision cursor ballistics (exponential curve + jitter smoothing).
- ๐น๏ธ Left Stick: Smooth vertical turbo scrolling with rapid auto-repeat.
- ๐ RT (Right Trigger): Left Mouse Button (LMB).
- ๐ LT (Left Trigger): Right Mouse Button (RMB).
- โจ๏ธ HHD Shortcut: Quick single tap on the Armoury Crate button.
- ๐ Touchscreen Gesture: Swipe up with one finger from the bottom screen bezel.
- ๐ฎ Steam Shortcut: Press Command Center button (left side of display) +
X. - ๐ฅ๏ธ Wayland Virtual Keyboard: Automatically pops up upon focusing text input fields in KDE Plasma.
/var/home/V/.local/bin/ally-docked-mode.sh status# Human-readable diagnostic output:
/var/home/V/.local/bin/ally-detect-display.py
# Structured JSON output:
/var/home/V/.local/bin/ally-detect-display.py --json
# Shell environment format (for script evaluation):
/var/home/V/.local/bin/ally-detect-display.py --shell# Force handheld profile (15W Balanced, 45 FPS, internal DSP speakers):
/var/home/V/.local/bin/ally-docked-mode.sh handheld
# Force TV 60Hz profile (25W Performance, 60 FPS, HDMI audio):
/var/home/V/.local/bin/ally-docked-mode.sh docked-tv
# Force VRR Gaming profile (30W Turbo, Uncapped FPS, GPU High DPM, HDMI audio):
/var/home/V/.local/bin/ally-docked-mode.sh docked-vrr/var/home/V/.local/bin/ally-docked-mode.sh fps-45
/var/home/V/.local/bin/ally-docked-mode.sh fps-60
/var/home/V/.local/bin/ally-docked-mode.sh fps-uncapped# Route audio to HDMI (TV / soundbar):
/var/home/V/.local/bin/ally-docked-mode.sh audio-hdmi
# Route audio to calibrated ROG Ally DSP speakers:
/var/home/V/.local/bin/ally-docked-mode.sh audio-speaker/var/home/V/.local/bin/ally-docked-mode.sh log
systemctl status hhd-watchdog.timer
systemctl status hhd-watchdog.serviceThe AllyDock suite was designed, tuned, and tested for the ASUS ROG Ally on Bazzite OS. Distributed under the permissive MIT License โ feel free to use, modify, and integrate it into your own handheld builds!