starman-tech/mousepods

What it does

MousePods reads motion sensors from paired AirPods 3 (via Apple RemoteHID over AACP) or AirPods Pro 2 (via SensorDataWX), converts them into yaw, pitch and roll, and drives a virtual uinput pointer on Wayland or X11. It targets Linux users who want hands-free or head-controlled cursor input and researchers interested in the AirPods sensor protocols.

The repository also publishes what it describes as the first public documentation of Apple's RemoteHID: a virtual-HID channel at RTBuddy 0x800, with wire format, sensor catalog, and the L2CAP MTU finding that sensors are only announced at 2582 rather than the Linux default 672. See the findings and RemoteHID protocol notes.

Quick start

Prerequisites: Linux with BlueZ, AirPods already paired and connected, and write access to /dev/uinput (normally granted to the logged-in desktop user through uaccess; no root needed).

git clone https://github.com/starman-tech/mousepods && cd mousepods
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/python airpods_mouse_controller.py --ui

The --ui launch opens the local settings-style app and starts the controller. Optional GNOME shortcuts are installed with airpods_mouse_controller.py --install-hotkeys. To check sensor rates without cursor control, run --diag; protocol, engine and calibration tests run without hardware via python3 -m unittest discover -s tests.

Modes and controls

Three motion modes are available: Souris moves the cursor by turning or tilting your head, Pointeur aims at the screen like a laser pointer after corner calibration, and Glisse slides a bud across a table. Clicks can come from a stem press, an optional quick head tilt, or dwell. Default shortcuts include Ctrl+Alt+C to recenter, Ctrl+Alt+P to pause, Ctrl+Alt+M to switch mode and Ctrl+Alt+S to scroll.

Constraints and status

Head tracking from AirPods 3 is reported as hardware-verified at up to ~210 Hz; AirPods Pro 2 motion is hardware-verified at 25 Hz. Mouse mode is tried on hardware but still being tuned. Pointer mode has only been tested in simulation, and Glide mode drifts (about 4 cm over 5 strokes in one capture), so it is not expected to match an optical mouse. Using the case as a mouse is impossible on AirPods 3 because the buds' sensors power off inside it. AirPods 2, Pro 1 and Max are untested.

The code is Apache-2.0 with a NOTICE file; documentation and captures are CC BY 4.0 and require attribution. The project is not affiliated with Apple.

HotRepo's take

On the 2026-11-06 Python new-project list, MousePods entered at 103 stars with 3 stars gained in a roughly one-hour window and 10 forks. That is a small sample, so it says little about sustained traction. What stands out technically is the protocol work: the README ties the supported models and features to an explicit verified/untested table, and separates the RemoteHID documentation from the cursor application. Readers evaluating the mouse behavior should treat Pointer and Glide as experimental, while the protocol findings are the part with the clearest evidence trail.