starman-tech/mousepods

项目介绍

MousePods 从已配对的 AirPods 3（通过 AACP 上的 Apple RemoteHID）或 AirPods Pro 2（通过 SensorDataWX）读取运动传感器，计算 yaw、pitch、roll，再通过虚拟 uinput 设备在 Wayland 或 X11 上移动光标。它面向想要免手或头部控制光标的 Linux 用户，也适合研究 AirPods 传感器协议的人。

仓库同时发布了项目所称的首份 Apple RemoteHID 公开文档：RTBuddy 0x800 通道上的虚拟 HID，包含线格式、传感器目录，以及「传感器只在 MTU 2582 而非 Linux 默认 672 下才宣告」的发现。可查看研究发现和RemoteHID 协议说明。

快速使用

前提：Linux 及 BlueZ，AirPods 已配对并连接，且对 /dev/uinput 有写权限（多数桌面发行版通过 uaccess 授予当前登录用户，无需 root）。

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

--ui 会打开本地设置应用并启动控制器。可选快捷键通过 airpods_mouse_controller.py --install-hotkeys 安装（GNOME）。只查看传感器速率、不控制光标时运行 --diag；协议、引擎和校准测试无需硬件，运行 python3 -m unittest discover -s tests 即可。

模式与操作

提供三种运动模式：Souris 通过转头或倾斜头部移动光标；Pointeur 在对两个角校准后像激光笔一样指向屏幕；Glisse 把一只耳机平放在桌面上滑动。点击可来自耳机柄按压、可选的快速歪头或悬停点击。默认快捷键包括 Ctrl+Alt+C 回中、Ctrl+Alt+P 暂停、Ctrl+Alt+M 切换模式、Ctrl+Alt+S 滚动。

使用约束与状态

AirPods 3 的头部追踪宣称在硬件上验证到约 210 Hz，AirPods Pro 2 为 25 Hz 且在硬件上验证。鼠标模式已在硬件上试用，仍在调优；指针模式只在模拟中测试过；滑动模式有漂移（单次采集调优后 5 次滑动漂移约 4 cm），不应期待达到光学鼠标水平。AirPods 3 放回充电盒后传感器断电，因此无法实现「用盒子当鼠标」。AirPods 2、Pro 1、Max 尚未测试。

代码采用 Apache-2.0 并附 NOTICE 文件；文档和采集数据采用 CC BY 4.0，复用需署名。项目与 Apple 无关。

HotRepo 点评

在 2026-11-06 的 Python 新项目榜中，MousePods 以 103 Star、约一小时窗口新增 3 Star、10 Fork 的记录出现。样本很小，不足以说明持续热度。技术上的重点在协议工作：README 用明确的已验证/未测试表格对应机型与功能，并把 RemoteHID 文档和光标应用分开。评估鼠标体验的读者应把指针模式和滑动模式视为实验性；证据最清楚的部分是协议发现。