Mac 与 Xcode
macOS 14 或更高版本，安装 Xcode 16 或更新版本。
安装前
先准备这些
耳机要先与 Mac 配对。iPhone 和 Mac 还需要连在同一个局域网。
iPhone
iOS 18 或更高版本。按 Xcode 提示完成开发者模式和设备信任。
Galaxy Buds3 Pro
耳机型号 SM-R630，并已在 macOS 蓝牙设置里与这台 Mac 配对。
同一局域网
iPhone 通过局域网查找 BudsBridge，首次启动时要允许本地网络访问。
Xcode 安装
Mac 和 iPhone 都要运行一个目标
先启动 Mac 桥接，再把 iOS App 装到手机。桥接进程不能关。
获取源码并打开工程
终端执行下面三行，或者在 GitHub 页面下载 ZIP。工程文件已经包含在仓库里，不需要先运行 XcodeGen。
git clone https://github.com/xiaoxuesheng123467/BudsControl.git
cd BudsControl
open BudsControl.xcodeproj确认 Mac 能看到耳机
打开 macOS 的蓝牙设置，确认 Galaxy Buds3 Pro 已配对。运行桥接时打开充电盒；如果耳机正被手机占用，先在手机上断开，再让 Mac 重试控制通道。
运行 BudsBridge
在 Xcode 顶部选择 BudsBridge scheme，运行设备选 My Mac，然后点运行。控制台会显示一条 32 位配对密钥：
BudsBridge pairing secret: 32 位十六进制字符保持这个进程运行。每次重新启动 BudsBridge 都会生成新密钥。
签名并安装到 iPhone
把 scheme 切到 BudsControl，运行设备选你的 iPhone。在 Signing & Capabilities 里选择自己的 Apple ID 团队，然后点运行。
如果 Xcode 提示 Bundle Identifier 不可用，把 com.qiao.budscontrol 改成只属于你的标识，例如 com.yourname.budscontrol。签名到期后，用 Xcode 再运行一次即可。
允许本地网络并输入密钥
第一次打开 App 时允许本地网络访问。把 Mac 控制台刚显示的 32 位密钥粘贴进去。页面出现“已通过 BudsBridge 连接”和耳机电量后，就可以打开全部设置页逐项调节。
蓝牙权限只用于手动诊断页，正常的桥接控制不要求你先打开诊断。
以后怎么用
不用每次重装，也不用重新设置
打开 Mac 上的 BudsBridge，再启动 iPhone App 即可。0.2.0 会记住成功修改的设置，连接后再用耳机真实状态逐项校正；只有签名失效时才需要回到 Xcode。
- 1
打开耳机盒，确认 Mac 蓝牙里能看到耳机。
- 2
运行 BudsBridge，并让 Mac 保持唤醒。
- 3
桥接重启后，把新生成的密钥粘贴到 App。
- 4
状态变为已连接后，验证中心会分别记录耳机 ACK、已写入和失败。
当前版本
已验证与待验证分开标记
原有控制保留真机结论；0.2.0 新命令已完成协议映射、值域校验和离线构建，等待下一次 SM-R630 真机逐项确认。
| 功能 | 状态 | 说明 |
|---|---|---|
| 主动降噪与环境声 | 真机确认 | 耳机返回匹配 ACK 后，App 才更新选中状态。 |
| 关闭噪音控制 | 已实现 | 使用同一条已验证命令路径。 |
| 六组 EQ 预设 | 真机确认 | 正常、低音增强、柔和、动态、清晰和高音增强。 |
| 左右耳与充电盒电量 | 真机读取 | 数据来自三星状态包。 |
| 自适应、环境声定制、语音检测与单耳控制 | 待真机验证 | 命令、值域与扩展状态解析已经接入。 |
| 触控锁、捏合手势、左右长捏与噪音循环 | 待真机验证 | 使用 Buds3 Pro 双耳动作格式，多字节负载由桥接白名单校验。 |
| 左右平衡、无缝连接、通话与佩戴设置 | 待真机验证 | 成功后写入本地配置记忆，状态包到达后再校正。 |
| 耳塞贴合度测试与查找耳机 | 待真机验证 | 离开页面自动停止；查找响铃前会先确认。 |
| 离线演示、命令记录与配置记忆 | 已实现 | 无需耳机可走完页面，并导出完整数据包与结果。 |
| 自适应音量与警笛检测 | 实验功能 | 默认关闭，只确认了消息 ID，需在验证中心主动放行。 |
| Blade Light 写入、9 段 EQ、固件与三星账号 | 未开放 | 没有可靠写入格式或依赖三星服务，不发送猜测数据。 |
排错
卡住时先看状态文字
一直显示“正在寻找 Mac 桥接”
确认 BudsBridge 仍在运行，iPhone 和 Mac 在同一个局域网，并在 iOS 设置里允许 BudsControl 访问本地网络。
Mac 显示控制通道打开失败
打开充电盒，确认耳机已经与 Mac 配对。如果耳机正连接手机，先断开手机上的耳机连接，再等待桥接重试。
App 提示配对密钥不正确
复制本次 BudsBridge 进程打印的完整 32 位密钥。旧进程的密钥不能用于新启动的桥接。
Xcode 无法完成签名
在 BudsControl target 里选择自己的 Team。Bundle Identifier 冲突时，换成个人唯一值，再重新运行。
为什么需要 Mac
iOS 不能直接打开三星 RFCOMM 控制服务
普通 iOS App 无法用公开 SDK 打开任意 Bluetooth Classic RFCOMM 服务。BudsBridge 在 macOS 上连接耳机，再接收 iPhone 发来的局域网请求。
iPhone == TLS-PSK over LAN ==> BudsBridge == RFCOMM ==> Buds3 Pro