1. 先弄清楚需求翻页器本质上是蓝牙键盘AlphaPi 完全能胜任1.1 翻页器到底是什么常说道理我都懂可就是差一个能用的小工具。我在做这个项目之前拆过一次朋友的翻页笔发现里面结构比想象中简单一个单片机、一个蓝牙模块、两三个微动开关、一颗纽扣电池没了。所有翻页笔本质上都在做同一件事——把自己模拟成一只蓝牙键盘然后向连接的电脑发送 PageDown、PageUp 这种标准键盘按键。演示软件PPT、Keynote、PDF阅读器其实并不认识翻页笔它们只认识键盘按键。翻页笔的按键被电脑识别成按键事件以后软件自然就翻页了。搞清楚这一点思路就通了。既然翻页笔 蓝牙键盘 两个按键那如果我有一块带蓝牙模块、带 GPIO 的开发板理论上完全可以自己做一个翻页器。AlphaPi 这块开发板本来就是 ARM 架构、跑完整 Linux 系统性能比翻页笔里的单片机强得多干这点活绰绰有余。它可以同时当一个可编程的蓝牙键盘既发翻页命令也能按需求扩展成打印当前页切换软件窗口播放暂停视频这类自定义快捷操作。1.2 为什么用 AlphaPi 改装而不是买一个这是每个人听到这个项目后问的第一句话。市面上翻页笔几十块就能买到用开发板改装体积又大功耗又高图什么呢我的回答是翻页笔只是顺带的结果真正想借这个项目搞明白的是Linux 开发板如何被识别成蓝牙外设这条知识线。这个问题的答案不只在翻页器上还能延伸到做蓝牙控制器、蓝牙手柄、蓝牙传感器节点等一堆场景。价格上算一笔账自然更清楚方案成本体积可扩展性学习价值买现成翻页笔40~200元极小基本为零低蓝牙BLE模块单片机自己写20~50元小一般中AlphaPi开发板改装0元吃灰板子中等很强高项目做完翻页器用在每周例会汇报上很顺手而掌握的那套HID over GATT注册流程以后做遥控小车、体感手柄、甚至做无障碍输入设备都能复用。这笔买卖我认为划算。1.3 项目拆解三个关键子问题把整个项目拆开看真正需要解决的问题只有三个板卡侧让 AlphaPi 的蓝牙协议栈注册一个 HID人机交互设备服务这样电脑才会把它识别成键盘而不是一个音频设备或者未知设备。交互侧用 GPIO 读取按钮按下去以后向已连接的电脑发送对应的 HID 报文模拟键盘按下 PageDown。运维侧供电、开机自启、意外断线后自动重连让它从一个开发板变成一个可以带出门的工具。这个项目里我用 Workbuddy 作为开发主力工具。它本质上是一个 AI 工作台能在一个界面里调度终端、编辑器、浏览器我可以用自然语言给它交代任务让它去查资料、写代码、看日志、改 bug。以前这种小项目最耗时的就是对着裁剪过的蓝牙协议栈文档啃半天现在 Workbuddy 帮我走通整个流程我只负责在关键节点上做判断项目推进速度快了很多。这篇文章就完整记录我用 Workbuddy 走通这条路的过程踩过的坑一个不少希望遇到同样需求的人能少走几步弯路。2. 开工准备烧系统、查蓝牙、初始化 Workbuddy 工作区2.1 烧录系统并确认蓝牙适配器AlphaPi 开发板拿到手第一步自然是烧系统。我选的是 Debian 系镜像背后没什么特殊理由就是蓝牙相关的软件包在 Debian 系下最全BlueZ 工具链基本是开箱即在。烧录用常规做法SD 卡格式化后用工具把镜像写入卡内插回板子通电网线或者 WiFi 连接然后通过 SSH 从电脑登录。整个过程十分钟左右。烧完系统最先要确认的不是跑分而是蓝牙适配器是否被内核识别systemctl status bluetooth bluetoothctl list重点看两件事第一bluetooth 服务有没有起来第二bluetoothctl list能不能列出本机的蓝牙适配器。如果这里什么都没有后面的步骤全部无从谈起。我手上这块 AlphaPi 板载蓝牙正常但如果你用的板子没有板载蓝牙花二十几块钱插一个 USB 蓝牙适配器也能达到同样的效果只是注意别买那种免驱只支持鼠标的老款要买支持 BlueZ 标准协议栈的。2.2 Workbuddy 的角色定位不是写码工具是带班工程师这个项目里 Workbuddy 在我的电脑上运行通过 SSH 连接 AlphaPi 开发板终端。用下来我最突出的感受是它不像一个代码补全工具更像一个能长期盯项目、帮我把步骤落实的带班工程师。我给它布置任务时并不局限于帮我写一个函数而是给它完整的项目上下文。比如我对它说当前有一个 AlphaPi 开发板运行 Debian已通过 SSH 连接内核版本是某某蓝牙芯片型号是某某我现在想让它被电脑识别成蓝牙键盘目标是按下 GPIO 物理按键后发送 PageDown 键。请先调研两条技术路线一条是基于 BlueZ D-Bus 注册 GATT 服务一条是使用第三方工具对比优缺点后给出推荐方案。它会真的去查资料然后把方案整理成表格交给我。这就是我说它像带班工程师的原因它处理的是任务不是片段。在整个开发过程中我几乎不需要去搜索引擎手动翻那些过时的教程遇到报错直接把终端输出贴给它它通常能指出问题出在哪一层。2.3 把需求描述成 AI 能执行的拆解任务用 Workbuddy 这类 AI 工作台有一个习惯必须养成任务描述里一定要包含环境信息、目标、限制条件三样东西。拿这个项目举例我给它的一条完整指令是这样的当前环境AlphaPi 开发板Debian 12内核 6.1BlueZ 版本 5.66蓝牙适配器为板载。目标让开发板通过蓝牙 HID over GATT 协议被外部电脑识别为标准键盘。限制不能修改内核不能使用闭源驱动。请给出实施方案并说明每步需要切换权限的地方。第一次用这种完整描述跑任务时效果和直接说帮我做蓝牙键盘完全不同。前者它知道去哪里查、用什么工具、要考虑什么约束后者它会反过来问你一堆问题。并不是 AI 变笨了而是我给的上下文越准确它越不需要猜。这个过程本身也是这个学用系列项目里最值得复制的一种工作方式把一个大任务拆成环境目标约束AI 才能真正替你干活。3. 核心攻坚HID over GATT让开发板变成隐形键盘3.1 原理蓝牙 HID 服务的 GATT 骨架整个项目最核心、也最劝退新人的部分就是让开发板变成蓝牙键盘。这句话说起来简单做起来涉及蓝牙协议栈里一个叫HID over GATT的规范。用生活类比解释一下。蓝牙设备之间通信就像两个人在一个房间聊天GATT 就是房间里的公告板公告板上挂着各种栏目。普通蓝牙耳机挂的是音频输出栏目蓝牙温度计挂的是温度测量栏目我们这次要挂的是人机交互设备栏目也就是 HID。电脑连上这块开发板后会去公告板上找这个栏目找到了它就相信对方是一只键盘或鼠标。技术上HID 服务有一个固定的 UUID0x1812里面包含若干个特性。最核心的两个一个是Report Map用来描述这个键盘有几个按键、报文是多长相当于说明书的目录一个是Report这是真正实时收发按键数据的地方。电脑读取了 Report Map知道该怎么解析数据开发板向 Report 特性写入PageDown 按下的报文电脑的蓝牙协议栈就会把它转成一个真实的键盘按键事件。这个流程听起来复杂但好消息是有 BlueZ 这套现成工具链我们不需要自己从零实现 GATT 协议。Workbuddy 帮我把 BlueZ 官方文档和社区实践整理成了几页可操作的步骤真正动手时只需要会改配置、会写一段注册服务的小代码。3.2 用 Workbuddy 生成 GATT HID 服务注册代码BlueZ 通过 D-Bus 向外部程序暴露 GATT 管理接口。我们要做的是向 BlueZ 注册一个应用程序其中包含 HID 服务和它下面的几个特性。这部分代码用 Python 调用 D-Bus 的方式编写结构大致如下# 简单示例向 BlueZ 注册 HID over GATT 服务 # 完整代码由 Workbuddy 生成这里只展示关键结构 HID_SERVICE_UUID 00001812-0000-1000-8000-00805f9b34fb REPORT_MAP_UUID 00002a4b-0000-1000-8000-00805f9b34fb REPORT_UUID 00002a4a-0000-1000-8000-00805f9b34fb HID_INFORMATION_UUID 00002a4a-0000-1000-8000-00805f9b34fb # Report Map描述这是一个标准 6 键键盘最多同时按 6 个键 report_map bytes([ 0x05, 0x01, # Usage Page (Generic Desktop) 0x09, 0x06, # Usage (Keyboard) 0xA1, 0x01, # Collection (Application) ... # 中间为键盘用的报告描述符较长此处省略 0xC0 # End Collection ]) def register_hid_service(bus): # 通过 D-Bus 创建 GATT 服务、添加特性、启动服务 # 具体调用 org.bluez.GattManager1.RegisterApplication pass def send_key(device_path, keycode): # 构造 HID 键盘报文 8 字节 # 结构Modifier 1字节 | Reserved 1字节 | Keycode 6字节 report_with_key bytearray(8) report_with_key[2] keycode # 把按键码放入第一个键位 # 写入 Report 特性并通知已连接的电脑 write_report(device_path, bytes(report_with_key))这段代码里的关键常量一个都不能写错。特别是 Report Map它决定电脑如何理解后面收到的报文。如果 Report Map 里声明的是 8 字节键盘报文实际发送时却只发 6 字节电脑端会直接忽略或报协议错误。所以 Workbuddy 生成完代码我第一件事就是逐字段核对 Report Map 的长度和 Report 报文长度是不是对得上。3.3 发送一次 PageDown按下与释放的报文节奏很多人第一次做这里会卡住明明往 Report 特性里写了 PageDown 键码电脑一点反应都没有。原因多半在于只发了按下没发释放。真实的键盘工作方式是这样的按下按键时发送包含键码的报文松开按键时发送全部为零的报文。如果只发按下的报文电脑会认为这个键一直被按着在演示文稿里表现为连续翻页翻到了底。正确的节奏是import time def tap_page_down(device_path): # PageDown 在 USB HID 键盘页中的键码是 0x4E keycode 0x4E # 按下 press_report bytearray(8) press_report[2] keycode send_hid_report(device_path, bytes(press_report)) # 等待 20~50 毫秒让电脑有时间识别按键 time.sleep(0.03) # 释放 release_report bytearray(8) send_hid_report(device_path, bytes(release_report))时间间隔我实测下来 20 毫秒到 50 毫秒都行太短了电脑有可能没收干净太长了连续翻页时会明显变慢。至于键码PageDown 是0x4EPageUp 是0x4B左方向键是0x50右方向键是0x4F。我最初以为需要在代码里写复杂的扫描码实际上 BlueZ 层接收的就是 HID 标准键码写对数字就行。3.4 第一次连接成功从配对到看到键盘图标服务注册完成接下来就是一对一连接的见证时刻。开发板默认处于可发现状态之后我打开演示电脑的蓝牙设置列表里出现了一串字符设备名点击配对。这时开发板侧需要执行一个动作来接受配对否则电脑会一直转圈或提示失败。我是在 SSH 终端里进入bluetoothctl交互模式操作的bluetoothctl agent on default-agent做完这两步电脑端那边立即就配对完成了。紧接着我打开设备与打印机里面出现了一个键盘图标那一刻项目的难度已经过去了一半。从这时起开发板在电脑眼里就是一只标准的蓝牙键盘后面所有功能性工作都建立在它对电脑来说就是键盘这个事实之上。第一次看到键盘图标出现时印象很深速度比想象中快整个前期调研和代码修补虽然折腾但总算从不可能变成了可行。4. 按键与交互逻辑GPIO 检测、防抖、组合键设计4.1 按键规划三键方案蓝牙键盘这个底层能力打通之后翻页器就只差物理按钮 按键逻辑这部分了。AlphaPi 的 GPIO 引脚很充足我最终做了三个按键而不是两个。布局逻辑是这样的按键 A放在左手拇指位置负责下一页。按键 B放在左手食指位置负责上一页。按键 C放在侧面靠内的位置是一个功能键短按切换模式长按发送 F5 进入放映模式。三键方案比两键多一个模式键可玩性高很多。按下模式键以后整个设备在不同演示场景里的表现是不一样的默认模式发 PageDown/PageUp适合 PDF 和 PPT 的逐页浏览切换到方向键模式后发送右方向键/左方向键兼容某些只认方向键的软件放映模式下的下一页则发送回车键方便一些特定的演示流程。每个按键在 GPIO 上的连接方式一端接 GPIO 针脚另一端接 GND。代码里设置上拉电阻平时读到高电平按下变成低电平以此来识别按键事件。每个按键对应一个引脚三个按键互不影响。4.2 防抖和长按/短按识别物理按键第一次按下会有机械抖动电气层面表现为在一个极短的时间内电平反复跳变。如果不做处理一次实际按压会被识别成好几次翻页器按下一次翻好几页非常尴尬。最简单的防抖方式是软件延时判断检测到电平变化后等待 20 毫秒再读一次如果还是稳定状态才确认是一次有效按下。这套逻辑在手写代码时挺容易写错交给 Workbuddy 生成初稿几乎一次就对了但校验点还是要自己把握延时太短防不住抖动太长会让按键失去跟手感。我实测大约 15 毫秒到 25 毫秒之间手感最好。长按和短按的区分核心是计时。检测到按键按下后记录时间戳一直等它释放如果释放时按压时长小于 500 毫秒算短按执行某一套动作如果超过 800 毫秒则算长按执行另一套动作。用来区分模式键的短按切换与长按 F5 的正好是这套逻辑。4.3 模式切换方向键模式、阅读器模式、放映模式设计模式切换的出发点是不同应用对翻页指令的口味不一样。我做了一个简单状态机把模式保存在内存变量里每次按键时先查当前模式再决定发什么键码。模式按键A下一页按键B上一页适合场景0 默认模式PageDownPageUpPPT、PDF阅读器1 方向键模式右方向键左方向键网页横向滚动、某些白板工具2 演示模式回车PageUp特定放映流程模式切换后我让开发板通过蓝牙发送一个当前模式的无声按键作为反馈什么反馈最直观呢我用的是发送一个键盘按键作为确认信号比如切换模式时发送一次 Alt 键的按下释放这样电脑端可能表现为无操作或窗口菜单弹出少量干扰换来了明确感知。当然也可以在开发板上加一个 LED 灯做指示那个方案外观上更友好但需要多占一个引脚、多几行代码。这套逻辑看着不复杂但它是整个翻页器过程体验的核心。按键好按下去翻得干净利落、模式切换不迷路才是能日常使用的工具否则只是能跑通的模块。5. 实测排坑四个把我折磨到大半夜的问题5.1 问题一开发板默认没有注册 HID 服务第一次测试时我打开电脑蓝牙扫描开发板的设备名看得见但是配对之后弹出的类型是其他设备而不是键盘。说明开发板虽然开启了广播但它的 GATT 服务里根本没有 HID 栏目电脑不知道该怎么理解这个设备。这个问题的根源是BlueZ 默认只提供 SPP、A2DP 等常规服务HID over GATT 的注册工作必须由应用层自己完成。换句话说光有 bluetoothd 还不够还必须把前文提到的 RegisterApplication 那段代码跑起来。排查思路是在开发板上执行bluetoothctl查看已注册的服务列表发现里面没有 0x1812 服务 UUID立刻定位到了问题。把 HID 服务注册代码作为 systemd 服务随系统启动问题才真正解决。5.2 问题二电脑配对成功却没有弹出键盘类型这个坑比前一个更隐蔽。服务注册代码确实跑起来了电脑端也能配对但是设备类型依然是未知设备。检查代码时发现Report Map 里的描述符声明的是一个键盘集合但 HID 服务里还需要包含HID Information特性其中有一个字段是 bcdHID 版本号和一个 country code 国家代码。当时生成的代码里 HID Information 特性的值全部为零电脑端识别不出这是一个合法的 HID 设备。把 HID Information 特性值修正为标准的 1.11 版本号并正确设置 boot protocol 标志后插上重新连接电脑立刻识别出了键盘字样。这个坑让我意识到GATT 服务不是把一个 UUID 挂上去就完事里面每个特性的内容都要符合规范少一个字段主设备端就可能拒绝承认你的身份。5.3 问题三翻页信号到了但按一下出一页半功能通了之后还有一个体验问题折磨人明明做了防抖偶尔按一下还是会连续翻页。排查了一轮发现问题不在 GPIO 抖动而在蓝牙 HID 报文本身。之前提到发送按键时要按下释放成对发送我在释放之后没有任何间隔导致电脑端在极短时间内收到了两次按键事件。有时候释放报文和下一次按下的报文在蓝牙协议栈里被合并到了一起电脑端解析成了两次按键。修复方式是在一次完整的按下释放之后再加 50 毫秒的静默期保证每次翻页事件之间有足够的分隔。这个细节直接影响使用体验如果没有耐心测试很难注意到。5.4 问题四休眠唤醒后连接丢失重连不上开发板跑的是完整 Linux 系统平时插着电源用没问题但你想把它带出门就要考虑断电、休眠、蓝牙断连之后的恢复。AlphaPi 默认的电源管理会在系统空闲一段时间后挂起蓝牙模块醒来后电脑端显示设备连接失败。处理办法分两层第一层修改电源管理策略禁止蓝牙 USB 设备自动挂起第二层在开发板侧写一个守护脚本定时检查是否有已配对设备连接如果没有就主动发起重连。脚本逻辑很简单但很实用#!/bin/bash # 每 30 秒检查一次如果有配对的键盘主机不在线尝试重连 while true; do if ! bluetoothctl info 对端MAC | grep -q Connected: yes; then bluetoothctl connect 对端MAC /dev/null 21 fi sleep 30 done这台翻页器实际用起来稳定性的主要障碍就是这个。每次重连恢复正常之后我出门都敢直接带它往包里一塞到会场开机、翻页基本无障碍。6. 从原型到口袋设备供电、自启与外壳6.1 供电方案对比充电宝最省事18650 最便携开发板做翻页器功能完全跑通后供电是个绕不开的问题——你不能在讲台上放一个拖着电源线的翻页器那太另类了。我先后试过三种方案USB 充电宝直接供电、手机充电器直插、锂电池模块供电。充电宝最稳定但体积太大完全违背了翻页器该有的便携属性。手机充电器供电干脆不现实讲台上极少有能随手插电的插座。最终还是选了 18650 锂电池加充放电保护模块的方案容量 2000mAh 左右实测给这块开发板供电能撑一个晚上完全够用。接线时注意一点锂电池必须走保护板绝对不能直接焊到开发板的 5V 引脚上不然过放一次电池就废了。这一点我在焊接时尤其小心。6.2 做成开机自启的 systemd 服务开发板作为翻页器如果每次开机都要手动运行脚本那就没有工具的意义了。我把翻页服务的进程和重连守护脚本都做成了 systemd 服务设置开机自启。这里有个容易忽略的点服务的启动顺序依赖蓝牙服务先就绪。我给翻页服务加了一条Afterbluetooth.service同时在实际执行的脚本开头加了 5 秒等待确保 bluetoothd 完全起来再注册 GATT 服务。没有这个等待动作开机后偶尔会出现注册失败表现就是电脑那边搜不到开发板的键盘。做一个便捷开关也很有用我在系统里添加了一个别名指令输入presentation-on或presentation-off就能手动启动或停止翻页服务。实际使用场景中有时候并不希望开发板立刻变成键盘设备比如需要先用它做别的调试任务。6.3 外壳与按键手感一个 3D 打印小盒子翻页器的最终形态不能是裸露的 PCB那既不安全也不好用。我用 3D 打印做了一个上下盖结构的小盒子整体尺寸大约 100×60×25 毫米内部刚好放下开发板、锂电池、充放电模块和三个微动开关。外壳设计上三个关键点第一三个按键的位置要贴合握持手势不能按照 PCB 排布来而是按键通过飞线连接到 GPIO再把按键固定在外壳的按钮位上第二电池仓和主板之间加了一层绝缘隔板防止移动中短路第三开发板的 USB 口在侧面开一个缺口露出来充电和调试都方便。按键手感方面试过两种开关薄膜按键和微动开关。薄膜按键安静但回弹软微动开关干脆利落但按多了手指累。最终选了手感适中的轻触微动开关并在按钮盖上加了一圈增高帽使手指按下去时的受力面积更大长时间演讲时不容易疲劳。6.4 最终效果与进一步扩展做完之后我拿它在周例会上实测了几次稳定性和可玩性都远超预期。设备在演示电脑上显示为键盘翻页响应基本感觉不到延迟长按模式键切换模式也正常。整机的续航足够覆盖几场连续会议充电 2 小时能用很久。最让人欣慰的地方是它不是一次性玩具而是一个可以随意改写的设备。换个脚本它下一秒就能变成 PPT 遥控、视频播放暂停快捷键、甚至音量控制器。如果继续扩展我下一个想加的是 OLED 小屏幕用来显示当前模式和电池电量再往下走可以用蓝牙低功耗连接方式降低功耗让同样的电池容量续航翻几倍。但这些都不影响它在当前状态下的实用价值——一个从吃灰开发板里变出来的翻页器就这么稳定地在每个周一早晨替我翻完二十几页汇报材料了。这个项目的完整形态就是这样。我个人的体会是用 Workbuddy 帮助做这类硬件小项目最宝贵的不是它替你写的那些代码而是它帮你把我不知道从哪开始缩短成了我知道下一步该验证什么。从需求到成品在 AI 工作台的辅助下一个不算小的硬件改造项目断断续续几天就能走完并且最终的产品还能在日常工作中持续使用。下次我再看到某个开发板吃灰大概会先想想能不能把它变成身边另一个趁手的小工具。
1. 先弄清楚需求翻页器本质上是蓝牙键盘AlphaPi 完全能胜任1.1 翻页器到底是什么常说道理我都懂可就是差一个能用的小工具。我在做这个项目之前拆过一次朋友的翻页笔发现里面结构比想象中简单一个单片机、一个蓝牙模块、两三个微动开关、一颗纽扣电池没了。所有翻页笔本质上都在做同一件事——把自己模拟成一只蓝牙键盘然后向连接的电脑发送 PageDown、PageUp 这种标准键盘按键。演示软件PPT、Keynote、PDF阅读器其实并不认识翻页笔它们只认识键盘按键。翻页笔的按键被电脑识别成按键事件以后软件自然就翻页了。搞清楚这一点思路就通了。既然翻页笔 蓝牙键盘 两个按键那如果我有一块带蓝牙模块、带 GPIO 的开发板理论上完全可以自己做一个翻页器。AlphaPi 这块开发板本来就是 ARM 架构、跑完整 Linux 系统性能比翻页笔里的单片机强得多干这点活绰绰有余。它可以同时当一个可编程的蓝牙键盘既发翻页命令也能按需求扩展成打印当前页切换软件窗口播放暂停视频这类自定义快捷操作。1.2 为什么用 AlphaPi 改装而不是买一个这是每个人听到这个项目后问的第一句话。市面上翻页笔几十块就能买到用开发板改装体积又大功耗又高图什么呢我的回答是翻页笔只是顺带的结果真正想借这个项目搞明白的是Linux 开发板如何被识别成蓝牙外设这条知识线。这个问题的答案不只在翻页器上还能延伸到做蓝牙控制器、蓝牙手柄、蓝牙传感器节点等一堆场景。价格上算一笔账自然更清楚方案成本体积可扩展性学习价值买现成翻页笔40~200元极小基本为零低蓝牙BLE模块单片机自己写20~50元小一般中AlphaPi开发板改装0元吃灰板子中等很强高项目做完翻页器用在每周例会汇报上很顺手而掌握的那套HID over GATT注册流程以后做遥控小车、体感手柄、甚至做无障碍输入设备都能复用。这笔买卖我认为划算。1.3 项目拆解三个关键子问题把整个项目拆开看真正需要解决的问题只有三个板卡侧让 AlphaPi 的蓝牙协议栈注册一个 HID人机交互设备服务这样电脑才会把它识别成键盘而不是一个音频设备或者未知设备。交互侧用 GPIO 读取按钮按下去以后向已连接的电脑发送对应的 HID 报文模拟键盘按下 PageDown。运维侧供电、开机自启、意外断线后自动重连让它从一个开发板变成一个可以带出门的工具。这个项目里我用 Workbuddy 作为开发主力工具。它本质上是一个 AI 工作台能在一个界面里调度终端、编辑器、浏览器我可以用自然语言给它交代任务让它去查资料、写代码、看日志、改 bug。以前这种小项目最耗时的就是对着裁剪过的蓝牙协议栈文档啃半天现在 Workbuddy 帮我走通整个流程我只负责在关键节点上做判断项目推进速度快了很多。这篇文章就完整记录我用 Workbuddy 走通这条路的过程踩过的坑一个不少希望遇到同样需求的人能少走几步弯路。2. 开工准备烧系统、查蓝牙、初始化 Workbuddy 工作区2.1 烧录系统并确认蓝牙适配器AlphaPi 开发板拿到手第一步自然是烧系统。我选的是 Debian 系镜像背后没什么特殊理由就是蓝牙相关的软件包在 Debian 系下最全BlueZ 工具链基本是开箱即在。烧录用常规做法SD 卡格式化后用工具把镜像写入卡内插回板子通电网线或者 WiFi 连接然后通过 SSH 从电脑登录。整个过程十分钟左右。烧完系统最先要确认的不是跑分而是蓝牙适配器是否被内核识别systemctl status bluetooth bluetoothctl list重点看两件事第一bluetooth 服务有没有起来第二bluetoothctl list能不能列出本机的蓝牙适配器。如果这里什么都没有后面的步骤全部无从谈起。我手上这块 AlphaPi 板载蓝牙正常但如果你用的板子没有板载蓝牙花二十几块钱插一个 USB 蓝牙适配器也能达到同样的效果只是注意别买那种免驱只支持鼠标的老款要买支持 BlueZ 标准协议栈的。2.2 Workbuddy 的角色定位不是写码工具是带班工程师这个项目里 Workbuddy 在我的电脑上运行通过 SSH 连接 AlphaPi 开发板终端。用下来我最突出的感受是它不像一个代码补全工具更像一个能长期盯项目、帮我把步骤落实的带班工程师。我给它布置任务时并不局限于帮我写一个函数而是给它完整的项目上下文。比如我对它说当前有一个 AlphaPi 开发板运行 Debian已通过 SSH 连接内核版本是某某蓝牙芯片型号是某某我现在想让它被电脑识别成蓝牙键盘目标是按下 GPIO 物理按键后发送 PageDown 键。请先调研两条技术路线一条是基于 BlueZ D-Bus 注册 GATT 服务一条是使用第三方工具对比优缺点后给出推荐方案。它会真的去查资料然后把方案整理成表格交给我。这就是我说它像带班工程师的原因它处理的是任务不是片段。在整个开发过程中我几乎不需要去搜索引擎手动翻那些过时的教程遇到报错直接把终端输出贴给它它通常能指出问题出在哪一层。2.3 把需求描述成 AI 能执行的拆解任务用 Workbuddy 这类 AI 工作台有一个习惯必须养成任务描述里一定要包含环境信息、目标、限制条件三样东西。拿这个项目举例我给它的一条完整指令是这样的当前环境AlphaPi 开发板Debian 12内核 6.1BlueZ 版本 5.66蓝牙适配器为板载。目标让开发板通过蓝牙 HID over GATT 协议被外部电脑识别为标准键盘。限制不能修改内核不能使用闭源驱动。请给出实施方案并说明每步需要切换权限的地方。第一次用这种完整描述跑任务时效果和直接说帮我做蓝牙键盘完全不同。前者它知道去哪里查、用什么工具、要考虑什么约束后者它会反过来问你一堆问题。并不是 AI 变笨了而是我给的上下文越准确它越不需要猜。这个过程本身也是这个学用系列项目里最值得复制的一种工作方式把一个大任务拆成环境目标约束AI 才能真正替你干活。3. 核心攻坚HID over GATT让开发板变成隐形键盘3.1 原理蓝牙 HID 服务的 GATT 骨架整个项目最核心、也最劝退新人的部分就是让开发板变成蓝牙键盘。这句话说起来简单做起来涉及蓝牙协议栈里一个叫HID over GATT的规范。用生活类比解释一下。蓝牙设备之间通信就像两个人在一个房间聊天GATT 就是房间里的公告板公告板上挂着各种栏目。普通蓝牙耳机挂的是音频输出栏目蓝牙温度计挂的是温度测量栏目我们这次要挂的是人机交互设备栏目也就是 HID。电脑连上这块开发板后会去公告板上找这个栏目找到了它就相信对方是一只键盘或鼠标。技术上HID 服务有一个固定的 UUID0x1812里面包含若干个特性。最核心的两个一个是Report Map用来描述这个键盘有几个按键、报文是多长相当于说明书的目录一个是Report这是真正实时收发按键数据的地方。电脑读取了 Report Map知道该怎么解析数据开发板向 Report 特性写入PageDown 按下的报文电脑的蓝牙协议栈就会把它转成一个真实的键盘按键事件。这个流程听起来复杂但好消息是有 BlueZ 这套现成工具链我们不需要自己从零实现 GATT 协议。Workbuddy 帮我把 BlueZ 官方文档和社区实践整理成了几页可操作的步骤真正动手时只需要会改配置、会写一段注册服务的小代码。3.2 用 Workbuddy 生成 GATT HID 服务注册代码BlueZ 通过 D-Bus 向外部程序暴露 GATT 管理接口。我们要做的是向 BlueZ 注册一个应用程序其中包含 HID 服务和它下面的几个特性。这部分代码用 Python 调用 D-Bus 的方式编写结构大致如下# 简单示例向 BlueZ 注册 HID over GATT 服务 # 完整代码由 Workbuddy 生成这里只展示关键结构 HID_SERVICE_UUID 00001812-0000-1000-8000-00805f9b34fb REPORT_MAP_UUID 00002a4b-0000-1000-8000-00805f9b34fb REPORT_UUID 00002a4a-0000-1000-8000-00805f9b34fb HID_INFORMATION_UUID 00002a4a-0000-1000-8000-00805f9b34fb # Report Map描述这是一个标准 6 键键盘最多同时按 6 个键 report_map bytes([ 0x05, 0x01, # Usage Page (Generic Desktop) 0x09, 0x06, # Usage (Keyboard) 0xA1, 0x01, # Collection (Application) ... # 中间为键盘用的报告描述符较长此处省略 0xC0 # End Collection ]) def register_hid_service(bus): # 通过 D-Bus 创建 GATT 服务、添加特性、启动服务 # 具体调用 org.bluez.GattManager1.RegisterApplication pass def send_key(device_path, keycode): # 构造 HID 键盘报文 8 字节 # 结构Modifier 1字节 | Reserved 1字节 | Keycode 6字节 report_with_key bytearray(8) report_with_key[2] keycode # 把按键码放入第一个键位 # 写入 Report 特性并通知已连接的电脑 write_report(device_path, bytes(report_with_key))这段代码里的关键常量一个都不能写错。特别是 Report Map它决定电脑如何理解后面收到的报文。如果 Report Map 里声明的是 8 字节键盘报文实际发送时却只发 6 字节电脑端会直接忽略或报协议错误。所以 Workbuddy 生成完代码我第一件事就是逐字段核对 Report Map 的长度和 Report 报文长度是不是对得上。3.3 发送一次 PageDown按下与释放的报文节奏很多人第一次做这里会卡住明明往 Report 特性里写了 PageDown 键码电脑一点反应都没有。原因多半在于只发了按下没发释放。真实的键盘工作方式是这样的按下按键时发送包含键码的报文松开按键时发送全部为零的报文。如果只发按下的报文电脑会认为这个键一直被按着在演示文稿里表现为连续翻页翻到了底。正确的节奏是import time def tap_page_down(device_path): # PageDown 在 USB HID 键盘页中的键码是 0x4E keycode 0x4E # 按下 press_report bytearray(8) press_report[2] keycode send_hid_report(device_path, bytes(press_report)) # 等待 20~50 毫秒让电脑有时间识别按键 time.sleep(0.03) # 释放 release_report bytearray(8) send_hid_report(device_path, bytes(release_report))时间间隔我实测下来 20 毫秒到 50 毫秒都行太短了电脑有可能没收干净太长了连续翻页时会明显变慢。至于键码PageDown 是0x4EPageUp 是0x4B左方向键是0x50右方向键是0x4F。我最初以为需要在代码里写复杂的扫描码实际上 BlueZ 层接收的就是 HID 标准键码写对数字就行。3.4 第一次连接成功从配对到看到键盘图标服务注册完成接下来就是一对一连接的见证时刻。开发板默认处于可发现状态之后我打开演示电脑的蓝牙设置列表里出现了一串字符设备名点击配对。这时开发板侧需要执行一个动作来接受配对否则电脑会一直转圈或提示失败。我是在 SSH 终端里进入bluetoothctl交互模式操作的bluetoothctl agent on default-agent做完这两步电脑端那边立即就配对完成了。紧接着我打开设备与打印机里面出现了一个键盘图标那一刻项目的难度已经过去了一半。从这时起开发板在电脑眼里就是一只标准的蓝牙键盘后面所有功能性工作都建立在它对电脑来说就是键盘这个事实之上。第一次看到键盘图标出现时印象很深速度比想象中快整个前期调研和代码修补虽然折腾但总算从不可能变成了可行。4. 按键与交互逻辑GPIO 检测、防抖、组合键设计4.1 按键规划三键方案蓝牙键盘这个底层能力打通之后翻页器就只差物理按钮 按键逻辑这部分了。AlphaPi 的 GPIO 引脚很充足我最终做了三个按键而不是两个。布局逻辑是这样的按键 A放在左手拇指位置负责下一页。按键 B放在左手食指位置负责上一页。按键 C放在侧面靠内的位置是一个功能键短按切换模式长按发送 F5 进入放映模式。三键方案比两键多一个模式键可玩性高很多。按下模式键以后整个设备在不同演示场景里的表现是不一样的默认模式发 PageDown/PageUp适合 PDF 和 PPT 的逐页浏览切换到方向键模式后发送右方向键/左方向键兼容某些只认方向键的软件放映模式下的下一页则发送回车键方便一些特定的演示流程。每个按键在 GPIO 上的连接方式一端接 GPIO 针脚另一端接 GND。代码里设置上拉电阻平时读到高电平按下变成低电平以此来识别按键事件。每个按键对应一个引脚三个按键互不影响。4.2 防抖和长按/短按识别物理按键第一次按下会有机械抖动电气层面表现为在一个极短的时间内电平反复跳变。如果不做处理一次实际按压会被识别成好几次翻页器按下一次翻好几页非常尴尬。最简单的防抖方式是软件延时判断检测到电平变化后等待 20 毫秒再读一次如果还是稳定状态才确认是一次有效按下。这套逻辑在手写代码时挺容易写错交给 Workbuddy 生成初稿几乎一次就对了但校验点还是要自己把握延时太短防不住抖动太长会让按键失去跟手感。我实测大约 15 毫秒到 25 毫秒之间手感最好。长按和短按的区分核心是计时。检测到按键按下后记录时间戳一直等它释放如果释放时按压时长小于 500 毫秒算短按执行某一套动作如果超过 800 毫秒则算长按执行另一套动作。用来区分模式键的短按切换与长按 F5 的正好是这套逻辑。4.3 模式切换方向键模式、阅读器模式、放映模式设计模式切换的出发点是不同应用对翻页指令的口味不一样。我做了一个简单状态机把模式保存在内存变量里每次按键时先查当前模式再决定发什么键码。模式按键A下一页按键B上一页适合场景0 默认模式PageDownPageUpPPT、PDF阅读器1 方向键模式右方向键左方向键网页横向滚动、某些白板工具2 演示模式回车PageUp特定放映流程模式切换后我让开发板通过蓝牙发送一个当前模式的无声按键作为反馈什么反馈最直观呢我用的是发送一个键盘按键作为确认信号比如切换模式时发送一次 Alt 键的按下释放这样电脑端可能表现为无操作或窗口菜单弹出少量干扰换来了明确感知。当然也可以在开发板上加一个 LED 灯做指示那个方案外观上更友好但需要多占一个引脚、多几行代码。这套逻辑看着不复杂但它是整个翻页器过程体验的核心。按键好按下去翻得干净利落、模式切换不迷路才是能日常使用的工具否则只是能跑通的模块。5. 实测排坑四个把我折磨到大半夜的问题5.1 问题一开发板默认没有注册 HID 服务第一次测试时我打开电脑蓝牙扫描开发板的设备名看得见但是配对之后弹出的类型是其他设备而不是键盘。说明开发板虽然开启了广播但它的 GATT 服务里根本没有 HID 栏目电脑不知道该怎么理解这个设备。这个问题的根源是BlueZ 默认只提供 SPP、A2DP 等常规服务HID over GATT 的注册工作必须由应用层自己完成。换句话说光有 bluetoothd 还不够还必须把前文提到的 RegisterApplication 那段代码跑起来。排查思路是在开发板上执行bluetoothctl查看已注册的服务列表发现里面没有 0x1812 服务 UUID立刻定位到了问题。把 HID 服务注册代码作为 systemd 服务随系统启动问题才真正解决。5.2 问题二电脑配对成功却没有弹出键盘类型这个坑比前一个更隐蔽。服务注册代码确实跑起来了电脑端也能配对但是设备类型依然是未知设备。检查代码时发现Report Map 里的描述符声明的是一个键盘集合但 HID 服务里还需要包含HID Information特性其中有一个字段是 bcdHID 版本号和一个 country code 国家代码。当时生成的代码里 HID Information 特性的值全部为零电脑端识别不出这是一个合法的 HID 设备。把 HID Information 特性值修正为标准的 1.11 版本号并正确设置 boot protocol 标志后插上重新连接电脑立刻识别出了键盘字样。这个坑让我意识到GATT 服务不是把一个 UUID 挂上去就完事里面每个特性的内容都要符合规范少一个字段主设备端就可能拒绝承认你的身份。5.3 问题三翻页信号到了但按一下出一页半功能通了之后还有一个体验问题折磨人明明做了防抖偶尔按一下还是会连续翻页。排查了一轮发现问题不在 GPIO 抖动而在蓝牙 HID 报文本身。之前提到发送按键时要按下释放成对发送我在释放之后没有任何间隔导致电脑端在极短时间内收到了两次按键事件。有时候释放报文和下一次按下的报文在蓝牙协议栈里被合并到了一起电脑端解析成了两次按键。修复方式是在一次完整的按下释放之后再加 50 毫秒的静默期保证每次翻页事件之间有足够的分隔。这个细节直接影响使用体验如果没有耐心测试很难注意到。5.4 问题四休眠唤醒后连接丢失重连不上开发板跑的是完整 Linux 系统平时插着电源用没问题但你想把它带出门就要考虑断电、休眠、蓝牙断连之后的恢复。AlphaPi 默认的电源管理会在系统空闲一段时间后挂起蓝牙模块醒来后电脑端显示设备连接失败。处理办法分两层第一层修改电源管理策略禁止蓝牙 USB 设备自动挂起第二层在开发板侧写一个守护脚本定时检查是否有已配对设备连接如果没有就主动发起重连。脚本逻辑很简单但很实用#!/bin/bash # 每 30 秒检查一次如果有配对的键盘主机不在线尝试重连 while true; do if ! bluetoothctl info 对端MAC | grep -q Connected: yes; then bluetoothctl connect 对端MAC /dev/null 21 fi sleep 30 done这台翻页器实际用起来稳定性的主要障碍就是这个。每次重连恢复正常之后我出门都敢直接带它往包里一塞到会场开机、翻页基本无障碍。6. 从原型到口袋设备供电、自启与外壳6.1 供电方案对比充电宝最省事18650 最便携开发板做翻页器功能完全跑通后供电是个绕不开的问题——你不能在讲台上放一个拖着电源线的翻页器那太另类了。我先后试过三种方案USB 充电宝直接供电、手机充电器直插、锂电池模块供电。充电宝最稳定但体积太大完全违背了翻页器该有的便携属性。手机充电器供电干脆不现实讲台上极少有能随手插电的插座。最终还是选了 18650 锂电池加充放电保护模块的方案容量 2000mAh 左右实测给这块开发板供电能撑一个晚上完全够用。接线时注意一点锂电池必须走保护板绝对不能直接焊到开发板的 5V 引脚上不然过放一次电池就废了。这一点我在焊接时尤其小心。6.2 做成开机自启的 systemd 服务开发板作为翻页器如果每次开机都要手动运行脚本那就没有工具的意义了。我把翻页服务的进程和重连守护脚本都做成了 systemd 服务设置开机自启。这里有个容易忽略的点服务的启动顺序依赖蓝牙服务先就绪。我给翻页服务加了一条Afterbluetooth.service同时在实际执行的脚本开头加了 5 秒等待确保 bluetoothd 完全起来再注册 GATT 服务。没有这个等待动作开机后偶尔会出现注册失败表现就是电脑那边搜不到开发板的键盘。做一个便捷开关也很有用我在系统里添加了一个别名指令输入presentation-on或presentation-off就能手动启动或停止翻页服务。实际使用场景中有时候并不希望开发板立刻变成键盘设备比如需要先用它做别的调试任务。6.3 外壳与按键手感一个 3D 打印小盒子翻页器的最终形态不能是裸露的 PCB那既不安全也不好用。我用 3D 打印做了一个上下盖结构的小盒子整体尺寸大约 100×60×25 毫米内部刚好放下开发板、锂电池、充放电模块和三个微动开关。外壳设计上三个关键点第一三个按键的位置要贴合握持手势不能按照 PCB 排布来而是按键通过飞线连接到 GPIO再把按键固定在外壳的按钮位上第二电池仓和主板之间加了一层绝缘隔板防止移动中短路第三开发板的 USB 口在侧面开一个缺口露出来充电和调试都方便。按键手感方面试过两种开关薄膜按键和微动开关。薄膜按键安静但回弹软微动开关干脆利落但按多了手指累。最终选了手感适中的轻触微动开关并在按钮盖上加了一圈增高帽使手指按下去时的受力面积更大长时间演讲时不容易疲劳。6.4 最终效果与进一步扩展做完之后我拿它在周例会上实测了几次稳定性和可玩性都远超预期。设备在演示电脑上显示为键盘翻页响应基本感觉不到延迟长按模式键切换模式也正常。整机的续航足够覆盖几场连续会议充电 2 小时能用很久。最让人欣慰的地方是它不是一次性玩具而是一个可以随意改写的设备。换个脚本它下一秒就能变成 PPT 遥控、视频播放暂停快捷键、甚至音量控制器。如果继续扩展我下一个想加的是 OLED 小屏幕用来显示当前模式和电池电量再往下走可以用蓝牙低功耗连接方式降低功耗让同样的电池容量续航翻几倍。但这些都不影响它在当前状态下的实用价值——一个从吃灰开发板里变出来的翻页器就这么稳定地在每个周一早晨替我翻完二十几页汇报材料了。这个项目的完整形态就是这样。我个人的体会是用 Workbuddy 帮助做这类硬件小项目最宝贵的不是它替你写的那些代码而是它帮你把我不知道从哪开始缩短成了我知道下一步该验证什么。从需求到成品在 AI 工作台的辅助下一个不算小的硬件改造项目断断续续几天就能走完并且最终的产品还能在日常工作中持续使用。下次我再看到某个开发板吃灰大概会先想想能不能把它变成身边另一个趁手的小工具。
