claude-desktop-buddy BLE 无线协议深度解析Nordic UART Service 与换行分隔 JSON 完整参考【免费下载链接】claude-desktop-buddyReference and an example for the Bluetooth API for makers in Claude Cowork Claude Code Desktop项目地址: https://gitcode.com/gh_mirrors/cl/claude-desktop-buddyclaude-desktop-buddy 是 Claude 桌面应用Claude Cowork / Claude Code Desktop面向硬件创客的 BLE 参考项目它把会话状态、权限审批请求通过BLE Nordic UART ServiceNUS以换行分隔的 JSON推送到 ESP32 桌面宠物M5StickC Plus并支持在设备上一键批准/拒绝工具调用。本文完整拆解这套无线协议——UUID、心跳快照、权限回传、命令应答与文件夹无线推送——帮你用最少的代码让任意 BLE 设备接上 Claude。协议概览3 个 UUID 定义一切设备侧不需要本项目中的任何代码只要满足两个条件即可接入广播Nordic UART Service业界事实标准的BLE 串口能解析换行分隔 JSON一个对象一行\n结尾。Arduino、ESP32、nRF52甚至树莓派加一块 BLE 蓝牙模块都能实现。Nordic UART Service 核心 UUID 对照表角色UUIDService6e400001-b5a3-f393-e0a9-e50e24dcca9eRX桌面 → 设备Write6e400002-b5a3-f393-e0a9-e50e24dcca9eTX设备 → 桌面Notify6e400003-b5a3-f393-e0a9-e50e24dcca9e设备命名技巧广播名必须以Claude开头桌面端的设备选择器会按此前缀过滤再追加 BT MAC 的几字节多台设备就不会混在一起。连接与配对硬件伴侣Hardware Buddy使用步骤BLE 桥默认关闭需要开发者模式Help → Troubleshooting → Enable Developer Mode菜单栏会多出 Developer 菜单Developer → Open Hardware Buddy…打开配对窗口点击Connect从扫描列表选中设备首次连接授权 macOS 的蓝牙权限。配对完成后桥会自动重连窗口只用于初始配对、查看状态面板或拖拽推送文件夹。传输层细节MTU 分片与行重组线上跑的一切都是UTF-8 编码的 JSON——每行一个对象\n结尾。两个方向都要处理碎片桌面 → 设备Notify 会在 MTU 边界处把一行切成多包设备端必须累积字节直到遇到\n再解析设备 → 桌面桌面端会自动重组多包行你只管按字节发回复由桥按协商 MTU 自动分片见 src/ble_bridge.h 中的 NUS 注释说明。参考实现在 src/ble_bridge.cpp行缓冲收发和 src/data.hJSON 解析入口_applyJson。心跳快照桌面端主动推送的核心消息桌面端在状态变化时发送快照并每 10 秒发一次保活{ total: 3, running: 1, waiting: 1, msg: approve: Bash, entries: [10:42 git push, 10:41 yarn test], tokens: 184502, tokens_today: 31200, prompt: { id: req_abc123, tool: Bash, hint: rm -rf /tmp/foo } }字段含义total/running/waiting全部会话数 / 正在生成 / 被权限提示阻塞msg适合小屏幕展示的一行摘要entries最近的转录行新的在前tokens/tokens_today会话启动以来的累计 token / 今日 token跨重启持久化本地午夜归零prompt仅在需要权限决策时出现其id是回传时要原样带回的凭证实用派生信号running 0表示有会话在跑waiting 0表示有权限提示在等total 0表示空闲。约 30 秒收不到快照就应视为连接已断参考实现里dataConnected()正是 30 秒阈值见 src/data.h。回合事件与权限审批回传每个回合完成会额外触发一条一次性事件携带原始 SDK 内容数组文本块、工具调用等。超过 4KB按 UTF-8 字节计的事件会被丢弃{ evt: turn, role: assistant, content: [{ type: text, text: ... }] }从设备端批准或拒绝工具调用当心跳里出现prompt时设备通过 TX 特征发回一条即可{cmd:permission,id:req_abc123,decision:once} {cmd:permission,id:req_abc123,decision:deny}id必须与prompt.id完全一致once批准本次工具调用deny拒绝。桌面端会把决定转发给会话管理器——这就是桌上小宠物帮你点批准的原理。连接时的一次性消息消息说明{ time: [1775731234, -25200] }时间同步epoch 秒 时区偏移秒设备据此校准 RTC{ cmd: owner, name: Felix }用户账户名名可显示在屏幕上命令与应答ack协议桌面端每发一条带cmd的命令都期望一条对应的 ack{ ack: 与cmd相同, ok: true, n: 0 }ok:false时可附带error:...n是通用计数器如 chunk 应答里的已写字节数。命令用途你应回传的 ack{cmd:status}桌面端每几秒轮询一次填充 Hardware Buddy 状态面板见下方状态响应{cmd:name,name:Clawd}设置设备显示名{ack:name,ok:true}{cmd:owner,name:Felix}设置用户名{ack:owner,ok:true}{cmd:unpair}清除已存绑定用户点忘记时触发{ack:unpair,ok:true}状态响应示例没有的字段可以直接省略{ ack: status, ok: true, data: { name: Clawd, sec: true, bat: { pct: 87, mV: 4012, mA: -120, usb: true }, sys: { up: 8412, heap: 84200 }, stats: { appr: 42, deny: 3, vel: 8, nap: 12, lvl: 5 } } }bat.mA为负值表示正在充电sec: true表示链路已加密下一节详述。文件夹推送BLE 无线文件传输Hardware Buddy 窗口里有个拖放区把一个文件夹拖进去其扁平内容会被流式推送到设备。传输层与内容无关——GIF、配置、固件镜像都行总量需在 1.8MB 以内。桌面: {cmd:char_begin,name:bufo,total:184320} 设备: {ack:char_begin,ok:true} 桌面: {cmd:file,path:manifest.json,size:412} 设备: {ack:file,ok:true} 桌面: {cmd:chunk,d:base64} → 设备逐块 ackn已写字节 桌面: {cmd:file_end} → 设备 ackn最终大小 每个文件重复 file/chunk/file_end … 桌面: {cmd:char_end} → 设备: {ack:char_end,ok:true}几个关键规则桌面端发送文件夹内所有普通文件不递归、跳过隐藏文件每块 base64 编码收到 ack 才发下一块——协议是顺序的无需整文件缓存char_begin.name取文件夹名若文件夹内有manifest.json且带name字段则以后者为准不想收文件不 ackchar_begin即可桌面端几秒超时后告知用户失败安全提醒写入前务必校验file.path拒绝..与绝对路径。设备端参考实现在 src/xfer.h。角色包格式可参考示例 characters/bufo/manifest.json离线烧录可用 tools/flash_character.py 走 USB 绕过 BLE 往返。安全配对LE Secure Connections 绑定转录片段和工具调用提示都会走这条链路——不加密的设备在无线电范围内可被廉价 nRF 嗅探棒直接嗅出。推荐做法NUS 特征及 TX CCCD标记为仅加密广播 DisplayOnly IO 能力首次 GATT 访问触发系统配对桌面端提示用户输入设备显示的6 位 passkey此后链路 AES-CCM 加密重连复用 LTK 无需再提示链路加密后在 status ack 中带sec: true收到{cmd:unpair}时清除本地绑定。设备端实现见 src/ble_bridge.h 中的bleSecure()/blePasskey()/bleClearBonds()三个接口。小结与参考入口整套协议可以浓缩为一句话NUS 三 UUID 每行一个 JSON 10 秒保活 30 秒判死 命令必须 ack。想动手实现前建议按这个顺序阅读协议权威定义REFERENCE.mdBLE 桥实现src/ble_bridge.cpp、src/ble_bridge.h快照解析与状态机src/data.h、src/stats.h文件推送接收端src/xfer.h工程配置ESP32 Arduino LittleFSplatformio.ini⚠️ 该 BLE API 仅在桌面应用开启开发者模式时可用面向创客与开发者不属于官方支持的产品功能。【免费下载链接】claude-desktop-buddyReference and an example for the Bluetooth API for makers in Claude Cowork Claude Code Desktop项目地址: https://gitcode.com/gh_mirrors/cl/claude-desktop-buddy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考