HEADMOUSE · 入门指南 · 版本 0.3.1
简单设置，
然后开始移动。
初始桌面安装包适用于 Ubuntu 26.04、GNOME 50 和 TH21A 头环。本指南介绍安装、连接和调节方法。
检查使用环境。
- 桌面系统： Ubuntu 26.04 和 GNOME Shell 50。此安装包不保证兼容 Ubuntu 24.04、Ubuntu 22.04 或其他 GNOME 主版本。
- 硬件： SereniBrain® TH21A 头环，以及可正常使用的低功耗蓝牙适配器。后续计划支持更多追踪设备。
- 连接： 将头环放在附近并开机，拔掉充电线，并先断开手机应用的连接。
头部鼠标 是独立软件，与 SereniBrain 及其制造商无关联，也未获得其背书或赞助。
安装桌面软件包。
下载 Ubuntu 安装包 ，在保存文件的目录中打开终端，然后运行：
sudo apt install ./serenibrain-mouse_0.3.1-1_all.debAPT 会从 Ubuntu 软件仓库安装依赖。首次安装后，请注销并重新登录一次，让 GNOME 发现蓝牙菜单扩展。安装包不会重启桌面。
初始版本保留 serenibrain 软件包、启动器和命令的原有名称。在应用列表中启动 SereniBrain Mouse ，即可打开设置并启动当前会话的服务。
连接并设置中心位置。
打开 TH21A，面向前方并保持不动。会话服务发现头环后，会用最初 40 个连续数据包设置中心位置，大约需要从开始接收数据起 1.6 秒。重新连接后也会再次设置中心位置。
打开 Quick Settings → Bluetooth（快捷设置 → 蓝牙） ，选择 TH21A 的 Mouse settings（鼠标设置） 入口。如果菜单没有显示，请从应用列表打开设置窗口，再选择 Enable menu integration（启用菜单集成）.
切换到普通鼠标前，请先暂停 头部鼠标。初始版本运行时会持续控制指针位置。
调到适合自己的感觉。
设置窗口中的修改会自动保存，并立即生效。
| 控制项 | 默认值与作用 |
|---|---|
| 位置 / 速度平衡 | 默认位置牵引为 50%。值越低，同样的倾斜可以移动越远；值越高，头部姿态与指针位置的对应关系越强。 |
| 指针速度 | 默认每秒 360 个逻辑像素，用于调整移动速度。 |
| 启动阈值 | 默认为 4%，用于设置指针保持静止的小范围。 |
| 眨眼灵敏度 | 默认为 50。值越低，需要越强的匹配波形；值越高，可以响应更弱的波形。 |
| Use head mouse（使用头部鼠标） | 暂停或恢复使用，重启后仍保留该选择。 |
| Set head center（设置头部中心） | 面向前方并保持不动，重新设置中心位置。 |
| Reset cursor（重置指针） | 把指针模型移回当前显示器的中心。 |
抬头、低头、向左或向右倾斜都可以移动指针。头部回到中心时，指针会向当前显示器的中心回移，直到进入静止范围。跨入另一台显示器后，参考中心会切换到该显示器。
通过终端暂停。
serenibrain mouse-control pause
serenibrain mouse-control resume了解当前限制。
- Linux 绝对指针移动、跨显示器移动和实时眨眼点击已在本项目的 GNOME/Wayland 桌面上测试。目前仍是早期版本，硬件和用户验证范围有限。
- 眨眼检测使用随软件附带的个人配置，可能需要针对你调整灵敏度。类似的无意识眨眼、打哈欠或其他动作也可能触发点击。
- 当前点击为左键单击，尚未实现拖拽、右键或独立双击功能。
- 安装包使用绝对鼠标输出后端。独立的数位板后端仍处于实验阶段。
- 尚未实现或测试 macOS 原生输出，源代码中包含开发交接说明。暂不支持 Windows 桌面控制。
- 已安装的服务连接设备时，请不要同时启动另一个独立的蓝牙读取程序。
输入数据过期、桌面锁定或登录会话不活跃时，服务会冻结指针移动并松开鼠标按键。手动暂停会一直保持，直到你主动恢复。
查看源代码。
下载 0.3.1 版本源代码包 ，其中包含 Linux 服务、浏览器研究面板、测试、配置和 macOS 开发交接说明。需要 Python 3.11 或更高版本。解压后，在项目目录运行：
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[linux]'
.venv/bin/serenibrain mouse-layout在其他 Linux 桌面上通过源代码运行时，请参阅附带的 docs/LINUX_MOUSE.md 。源代码模式默认只模拟运行，需要明确启用才会控制实际指针。计划中的 Mac 移植请参阅 docs/MACOS_HANDOFF.md 。
低功耗蓝牙数据采集、EEG 研究功能和旧版虚拟游戏手柄是独立实验。EEG 功能尚未证明能够实现可靠的主动控制。头部鼠标使用观察到的头部动作和实验性眨眼检测。
下载 SHA-256 校验文件。在下载文件所在的目录中运行以下命令进行验证：
sha256sum --ignore-missing --check SHA256SUMS
排查问题或卸载。
打开设置窗口，查看会话服务状态或最近的日志：
serenibrain-settings
systemctl --user status serenibrain-mouse.service
journalctl --user -u serenibrain-mouse.service -n 50卸载已安装的软件包：
sudo apt remove serenibrain-mouse卸载会停止本软件包的用户服务并禁用其扩展。个人设置仍保留在 ~/.config/serenibrain/（或 $XDG_CONFIG_HOME 下的对应目录）。