ThisWasAryan/MotoBudsDesktopUtility
GitHub: ThisWasAryan/MotoBudsDesktopUtility
一款逆向了 Motorola Moto Buds 专有蓝牙协议的开源跨平台桌面控制工具，让用户在 Linux 和 Windows 上直接配置和操控耳机。
Stars: 2 | Forks: 0
# Moto Buds Linux 桌面工具
这是一款开源且功能齐全的桌面工具，用于在 Linux 上配置和控制 Motorola Moto Buds。该项目成功逆向了官方 Android 应用使用的专有蓝牙 RFCOMM 通信协议，并使用 React 和 Electron 实现了精美的高级拟物化桌面用户界面。
**版本 2.1 新特性：** 我们已正式发布 **v2.1.0**，引入了持久的后台**系统托盘**，以便快速访问电量和 ANC 控制。我们还彻底重写了 UI 布局，采用了双窗格美学，通过 daemon 级别的适配器重连大幅提升了连接可靠性，并实现了与官方 Android 应用 100% 的功能对等（不包括自适应 ANC）。**每一个功能都经过了严格测试，确认在原生 Linux 上完全正常运行！**
## 🚀 系统托盘集成（v2.1 新增）
MotoBudsController 现包含完整的系统托盘集成功能，允许应用程序在主窗口关闭后继续在后台运行。用户可以直接在托盘中快速查看电量信息、切换噪声控制模式以及重新打开完整的应用程序。
### 后台运行设置
通过允许应用程序在关闭时最小化到系统托盘，来启用后台运行。
### 托盘功能
## 应用程序预览
## 硬件验证（Moto Buds 基础款）
所有当前的协议逆向工程、payload 加密和功能实现都已在 **Moto Buds（基础款）** 上经过严格测试和验证。
以下功能已确认 **100% 正常工作**：
* **手势控制（高级）**：为每个耳塞独立提供高度可自定义的点击设置（双击、三击、长按）。此桌面应用安全地注入 opcode `0x0100`，并提供比官方 Motorola 移动应用*更精细的自定义*。我们通过 `mpris-proxy` 实现了原生 AVRCP 桥接，确保您的点击操作能够在整个 Linux 桌面上准确地实现全局暂停、播放和跳过媒体。
* **信任协议集成**：我们实现了一个原生的 D-Bus 命令序列，使 Linux 主机设备能够自动信任耳塞。这确保了点击手势和入耳检测功能完美运行，无需手动进行蓝牙配对干预或使用信任相关的命令行操作。
* **自定义 10 段均衡器（带预设）**：完整实现了 `0x0306` 均衡器协议。使用自定义的 173 字节 payload，在 10 个频段上提供精确的浮点增益控制。您可以在预配置的自定义预设（平直、低音增强、高音增强等）之间无缝切换，或者调整您自己的自定义 EQ。
* **Hi-Res Audio (LDAC) 协商**：成功直接从桌面客户端实现了 codec 协商，完全复制了以前仅限 Android 应用使用的功能。我们的后端能够从容应对耳塞触发的故意蓝牙协议断开，并强制重新路由 Linux PipeWire A2DP 栈以接受新的 LDAC 采样率。开箱即处理了与 Game Mode 的互斥问题。
* **系统托盘集成**：直接通过您的 Linux 系统托盘/面板快速访问电量、切换噪声控制和管理连接，确保应用程序保持可访问状态而不会弄乱您的工作区。
* **入耳检测**：准确检测耳塞是否物理位于耳内，并无缝地自动暂停/恢复系统媒体。
* **贴合度测试（改进的诊断）**：使用专门的视觉指示器准确测试密封质量，并为左右耳塞提供独立、清晰的通过/失败结果。它利用状态机在诊断扫描期间跟踪来自耳塞的 `1024` 和 `1025` 响应代码。
* **查找我的设备**：单独使遗失的左耳塞或右耳塞响铃，并带有安全检查（如果物理检测到耳塞在耳内，则会阻止响铃以防止听力受损）。
* **连接状态机**：在耳塞短暂断开以重新协商 codec 或断开连接时，无缝的后台状态机提供视觉反馈（加载指示器、连接检查、断开状态），UI 会即时反映 daemon 的内部 RFCOMM socket 状态。
* **主动降噪 (ANC)**：已验证在所有状态下均能正常工作（关闭、通透模式、主动降噪）。
* **Game Mode**：通过降低延迟的 opcode 验证了其正常工作。通过自定义 UI 对话框自动处理与 Hi-Res Audio 的互斥问题。
* **音量增强器**：已验证正常工作。
* **电池与充电遥测**：
* 为单个耳塞（左/右）提供精细的电量报告。
* 准确的充电盒电量报告（即使充电盒内只有一个耳塞）。
* 实时充电跟踪。耳塞放入充电盒时会显示充电指示，并且充电盒在插入电源时会准确报告其自身的充电状态。
*注意：空间音频受部分支持，仅在连接的设备为 Moto Buds+ 时才会动态显示。*
## 打包与安装
我们严格维护代码仓库，使其仅包含原始源代码。所有运行时依赖项，包括 Python daemon 组件和蓝牙桥接工具，都会在打包过程中自动解决。
适用于 **基于 Debian 的系统** (`.deb`) 和 **其他 Linux 发行版** (`.AppImage`) 的预打包独立二进制文件可在本代码仓库的 **Releases** 部分获取。`.deb` 包明确声明了对 `python3` 和 `bluez` 的依赖，以确保您的系统上可以使用 `mpris-proxy` 来进行媒体手势控制。
## 架构：工作原理
该应用程序由两个完全解耦的组件组成：一个轻量级的 Python 后台 daemon，通过 RFCOMM 与耳塞进行原生通信；以及一个美观的 React/Electron 前端，为您提供可视化控制。
以下是您使用该应用程序时底层发生的具体过程：
### 1. Daemon 初始化与状态同步
1. 您启动应用程序。
2. 应用程序在“未连接”屏幕上启动。
3. 当您点击 **连接** 时，React 应用程序向 Electron 的主进程发送一条 IPC（进程间通信）消息。
4. Electron 使用 Node 的 `child_process.spawn()` 以 daemon 模式静默启动 `backend/moto_control.py`。
5. Python daemon 直接向您的耳塞打开一个经典蓝牙 RFCOMM socket（端口 16），并协商初始化握手。
6. 成功建立连接后，Python daemon 会在后台启动 `mpris-proxy` 以处理 AVRCP 手势桥接，并向其标准输出打印 `{"type": "status", "status": "connected"}`。
7. Electron 读取此输出，将其转发给 React 应用程序，UI 在视觉上过渡到主仪表板。
8. React 应用程序立即通过向 daemon 注入 `sync` opcode 序列来请求完整的状态同步，获取电量、ANC、手势和 Hi-Res 状态。
### 2. 事件驱动的 IPC 命令执行
1. 您在主仪表板上点击一个控件，例如“ANC”切换开关。
2. React UI **不会** 乐观地更改滑块位置。相反，它会触发一个 IPC 命令：`window.api.motoCommand({ op: 'anc', mode: 1 })`。*（注意：此规则的唯一例外是入耳检测切换开关，该开关会在本地进行乐观更新，因为耳塞的固件不会发出 opcode `1027` 的异步确认数据包。）*
3. Electron 接收此命令并将其通过管道传输到正在运行的 Python daemon 的 `stdin`（标准输入）中。
4. Python daemon 读取输入，格式化专有的协议数据单元 (PDU) 数据包，附加动态计算的 CRC32 校验和，并将其写入蓝牙 RFCOMM socket。
5. 耳塞接收到该数据包，在物理上启用主动降噪，并立即向主机广播回一个确认 PDU 数据包。
6. Python daemon 的异步轮询循环从 socket 读取原始的十六进制响应，并将其作为 JSON 事件打印到 `stdout`。
7. Electron 捕获 `stdout`，通过管道将其传回 React，Zustand 状态管理器 (`useDeviceStore.ts`) 随即解析该数据包。
8. Zustand 状态将 `ancMode` 更新为 `1`，这触发 React 重新渲染仪表板，最终更新 UI 中的 ANC 部分。
*这整个往返过程仅需几毫秒。由于 UI 仅在保证硬件广播的情况下进行更新，因此该界面反映了耳塞绝对真实的物理状态。*
## 文档
* **[PROTOCOL.md](PROTOCOL.md)**：对专有的逆向工程蓝牙协议、opcode、CRC32 算法和 payload 结构进行了完整、深入的解析。
* **[INTERFACE.md](INTERFACE.md)**：关于 React 前端与 Python 后端之间解耦的文档，为想要完全重新设计 UI 的开发者或 AI agent 解释了状态管理系统。
* [v2 演示/教程视频](https://youtu.be/_nepY64ECYo) *(最后更新于 2026 年 12 月 6 日)*
## 开发与构建
如果您希望从源代码构建应用程序或为该项目做出贡献：
### 前置条件与设置
1. 确保您的 Moto Buds 已通过标准操作系统蓝牙设置与您的 Linux 机器配对并连接。
2. 为 Electron 前端安装必要的 Node 模块：
npm install
3. Python 后端脚本完全依赖标准库（`socket`、`struct`、`binascii`、`subprocess`、`json`），因此不需要外部的 `pip` 包。
### 启动应用程序
只需运行：
```
npm run dev
```
### 构建发行版
要自行编译独立二进制文件：
```
npm run dist:linux
```
## 自动化测试
为了确保 SPP 解析器逻辑稳健且不会丢弃异步数据包，我们提供了一个模拟本地测试服务器，用于模拟确切的 Moto Buds PDU 流程。您无需物理连接耳塞即可运行完整的自动化集成测试：
```
source .venv/bin/activate
python backend/test_integration.py
```
通过允许应用程序在关闭时最小化到系统托盘，来启用后台运行。
### 托盘功能
|
Battery Monitoring
|
Quick Controls Access noise control modes, open the application, or quit directly from the tray menu. |
|
Sound Control ANC, Transparency, and audio settings. |
Equalizer Fine tune your listening experience. |
|
Gesture Configuration Customize earbud touch controls. |
Find My Device Locate misplaced earbuds. |
|
Ear Tip Fit Test Verify fit and seal quality. |
Additional Settings Advanced options and device information. |
标签：Electron, MITM代理, React, Syscalls, 云资产清单, 桌面应用, 物联网控制, 自动化攻击, 蓝牙工具, 逆向工具, 逆向工程