ESP32无线调试新方案：用PyBLE和MicroPython实现BLE串口

1. 为什么我要在平板上折腾 ESP32 的调试环境手里攥着好几块 ESP32 开发板电脑上装了 Arduino IDE、PlatformIO、ESP-IDF 好几套环境但真正让我头疼的从来不是写代码而是调试。尤其是板子焊在设备里、装在壳子里、放在桌角那一堆杜邦线中间的时候想改一行print语句得把笔记本搬过去、插上 USB 线、等串口监视器打开一套流程下来五分钟没了。更别提有时候板子跑在移动平台上比如小车、机械臂你根本没法把电脑一直挂在上面。后来我在 GitHub 上翻到一个项目叫PyBLE作者的想法很直接既然 ESP32 自带 BLE那为什么不用 BLE 做无线串口把平板或手机变成调试终端这个思路一下子戳中了我。它做的事情说起来不复杂——在 ESP32 上跑一个 MicroPython 脚本通过 BLE 暴露一个类似串口的服务然后你在平板或手机上装一个对应的 App就能像用串口监视器一样收发数据、执行代码片段。但真正用起来之后我发现它解决的不只是“少插一根线”的问题而是把调试这件事从“固定工位”变成了“随身携带”。这篇文章我会从项目结构、BLE 通信原理、MicroPython 端的实现细节、平板端 App 的使用、常见坑和排查方法几个角度把这个项目彻底拆开讲一遍。不管你是刚接触 ESP32 的新手还是已经用过 MicroPython 的老手应该都能从中找到可以直接抄作业的东西。尤其是那些经常需要现场调试、又不想背着电脑到处跑的人这个方案值得你花一个下午试一次。2. PyBLE 项目整体设计与核心思路拆解2.1 这个项目到底解决了什么问题传统 ESP32 调试方式无非几种USB 串口、WiFi Telnet、WebSocket、MQTT。USB 串口最稳定但线缆束缚太强WiFi Telnet 需要先配网现场环境不一定有可用的 APWebSocket 和 MQTT 都要依赖网络基础设施而且延迟和稳定性受路由器影响很大。BLE 的好处在于它是点对点直连不需要任何网络配置功耗低平板和手机原生支持连接建立后延迟在几十毫秒级别对于调试输出和简单交互来说完全够用。PyBLE 的核心设计思路就是把 BLE 当成一条透明的数据通道上面跑一个极简的 REPL 协议。ESP32 端用 MicroPython 的bluetooth模块创建一个 GATT 服务里面有两个特征值一个用于接收平板发来的命令一个用于向平板推送输出。平板端 App 负责扫描、连接、订阅通知、发送数据。整个链路不涉及任何云端服务所有数据都在本地 BLE 连接上传输。这个设计有几个明显的好处。第一零配置板子上电就开始广播平板打开 App 就能看到第二低依赖不需要路由器、不需要配网、不需要额外库第三可移植只要芯片支持 BLE 和 MicroPython理论上都能跑不限于 ESP32。当然它也有局限比如 BLE 的吞吐量有限不适合传大文件或高频数据流但对于调试打印和命令交互来说绰绰有余。2.2 为什么选 MicroPython 而不是 Arduino 或 ESP-IDF这个问题我一开始也纠结过。Arduino 生态里有BLEKeyboard、BLESerial这类库ESP-IDF 也有完整的 GATT 示例为什么作者偏偏选了 MicroPython用下来之后我理解了几个关键原因。首先是开发速度。MicroPython 改一行代码只需要重新上传一个.py文件甚至可以直接在 REPL 里动态改不需要编译、不需要烧录固件。对于调试工具这种需要频繁迭代的东西来说这个优势太大了。其次是代码可读性MicroPython 的bluetooth模块 API 设计得很直观创建一个 BLE 服务大概二十行代码就能搞定换成 C 语言至少要一百多行还要处理各种回调和内存管理。第三是资源占用可控ESP32 跑 MicroPython 虽然比 C 慢但 BLE 协议栈本身是底层实现的Python 层只负责数据搬运实际性能瓶颈不在 Python 这边。当然如果你已经有一套成熟的 Arduino 或 ESP-IDF 项目硬要换成 MicroPython 也不现实。PyBLE 更适合那些以 MicroPython 为主力开发环境的人或者愿意为了调试便利单独跑一个调试固件的人。我的做法是在主固件里保留业务逻辑另外准备一块 ESP32 专门跑 PyBLE 做调试桥需要的时候接上去不需要的时候拔掉互不干扰。2.3 BLE GATT 服务的设计细节PyBLE 在 ESP32 端创建的是一个自定义 GATT 服务里面包含两个特征值。第一个是RX 特征接收属性为WRITE和WRITE_NO_RESPONSE平板往这个特征写数据ESP32 收到后当作命令执行。第二个是TX 特征发送属性为NOTIFYESP32 把输出结果通过这个特征推送给平板平板订阅后就能实时收到。这里有个细节值得说一下为什么 TX 用NOTIFY而不是INDICATEINDICATE需要接收方确认可靠性更高但速度慢NOTIFY不需要确认速度快但理论上可能丢包。对于调试输出这种场景丢一两条打印问题不大速度更重要所以选NOTIFY是合理的。如果你传的是关键控制指令那应该用WRITE带响应确保对方收到了。UUID 方面PyBLE 用的是自定义 UUID不是标准串口服务的 UUID。这样做的好处是不会和系统里其他 BLE 设备冲突坏处是平板端 App 必须知道这些 UUID 才能正确订阅。如果你打算自己写平板端 App记得把 UUID 硬编码进去或者做成可配置的。3. ESP32 端 MicroPython 实现与关键代码解析3.1 环境准备与固件选择在开始之前你需要一块支持 BLE 的 ESP32 开发板。注意ESP32-S2 没有 BLE只有 WiFi所以不能用。ESP32、ESP32-S3、ESP32-C3 都支持 BLE其中 C3 是 RISC-V 架构价格便宜跑 MicroPython 也没问题。我手头用的是 ESP32-S3 和 ESP32-C3 各一块实测都能正常工作。固件方面去 MicroPython 官网下载最新稳定版即可。下载的时候注意选择带BLE支持的版本有些精简版固件为了节省空间去掉了蓝牙模块。烧录工具用esptool.py就行命令大概是这样的esptool.py --chip esp32s3 --port /dev/ttyUSB0 erase_flash esptool.py --chip esp32s3 --port /dev/ttyUSB0 write_flash -z 0x0 firmware.bin烧录完成后用串口工具连上去应该能看到 MicroPython 的 REPL 提示符。先跑一句import bluetooth确认 BLE 模块可用如果没有报错就说明固件没问题。3.2 BLE 服务初始化代码逐行拆解PyBLE 的核心代码其实不长我把它拆成几个部分来讲。首先是导入和基础配置import bluetooth import struct import time from micropython import const _IRQ_CENTRAL_CONNECT const(1) _IRQ_CENTRAL_DISCONNECT const(2) _IRQ_GATTS_WRITE const(3) _FLAG_WRITE const(0x0008) _FLAG_NOTIFY const(0x0010) _UART_UUID bluetooth.UUID(6E400001-B5A3-F393-E0A9-E50E24DCCA9E) _TX_UUID bluetooth.UUID(6E400003-B5A3-F393-E0A9-E50E24DCCA9E) _RX_UUID bluetooth.UUID(6E400002-B5A3-F393-E0A9-E50E24DCCA9E)这里用的 UUID 是 Nordic UART Service 的标准 UUID很多 BLE 串口工具都认这个兼容性比较好。如果你要用自定义 UUID把上面三行换掉就行但记得平板端也要同步改。接下来是服务注册和中断处理class BLEUART: def __init__(self, ble, namePyBLE, rxbuf100): self._ble ble self._ble.active(True) self._ble.irq(self._irq) ((self._tx_handle, self._rx_handle),) self._ble.gatts_register_services(( (_UART_UUID, (_TX_UUID, _FLAG_NOTIFY,), (_RX_UUID, _FLAG_WRITE,)), )) self._connections set() self._rx_buffer bytearray() self._handler None self._payload None self._advertise() def _irq(self, event, data): if event _IRQ_CENTRAL_CONNECT: conn_handle, _, _ data self._connections.add(conn_handle) elif event _IRQ_CENTRAL_DISCONNECT: conn_handle, _, _ data self._connections.discard(conn_handle) self._advertise() elif event _IRQ_GATTS_WRITE: conn_handle, attr_handle data if attr_handle self._rx_handle: self._rx_buffer self._ble.gatts_read(self._rx_handle) if self._handler: self._handler()这段代码有几个关键点。gatts_register_services返回的是句柄元组顺序和注册时一致所以_tx_handle对应 TX 特征_rx_handle对应 RX 特征。中断处理里_IRQ_CENTRAL_CONNECT和_IRQ_CENTRAL_DISCONNECT用来维护连接状态断开后自动重新广播这样平板掉线后还能重连。_IRQ_GATTS_WRITE是核心平板往 RX 写数据时触发把数据追加到_rx_buffer然后调用注册的回调函数。发送数据的方法也很简单def send(self, data): for conn_handle in self._connections: self._ble.gatts_notify(conn_handle, self._tx_handle, data)遍历所有连接逐个发送通知。如果你只允许一个连接可以简化成只发第一个。3.3 REPL 协议与命令解析PyBLE 的 REPL 不是完整的 Python REPL而是一个简化版。它支持几种命令直接执行单行 Python 代码、查看变量、调用函数。实现方式是把收到的字节流按行分割每行当作一个语句用exec执行然后把输出重定向到 BLE 发送。这里有个坑要注意MicroPython 的exec默认输出到串口要重定向到 BLE需要替换sys.stdout。我的做法是写一个简单的BLEWriter类实现write方法把数据通过 BLE 发出去然后赋值给sys.stdout。这样print的内容就会自动走 BLE 通道。import sys class BLEWriter: def __init__(self, bleuart): self._bleuart bleuart def write(self, data): self._bleuart.send(data) def flush(self): pass sys.stdout BLEWriter(bleuart)这个方案简单有效但有个小问题如果 BLE 发送速度跟不上print的速度数据会堆积。解决办法是在send里加一个简单的流控或者限制print的频率。实测下来每秒几十条短消息完全没问题超过这个频率就要考虑合并输出了。4. 平板端 App 使用与连接流程实操4.1 平板端工具选择与安装平板端我用的是现成的 BLE 串口 AppAndroid 上推荐Serial Bluetooth Terminal或者nRF ConnectiOS 上可以用LightBlue或者BLE Scanner。这些 App 都能扫描 BLE 设备、连接、订阅通知、发送数据功能上完全够用。如果你想要更定制化的界面也可以自己用 Flutter 或 React Native 写一个核心就是调用系统的 BLE API。以 nRF Connect 为例安装后打开扫描周围设备应该能看到一个叫PyBLE的设备。点击连接然后展开服务列表找到 Nordic UART Service里面有两个特征TX 和 RX。点击 TX 特征旁边的订阅按钮通常是三个箭头或者一个铃铛图标然后点击 RX 特征旁边的上传按钮就可以发送数据了。4.2 连接建立与数据收发实测连接过程我实测了几次从扫描到连接成功大概需要 2 到 5 秒取决于平板和 ESP32 的距离以及周围 BLE 设备的干扰程度。连接成功后ESP32 端的_connections集合里会多一个句柄平板端会收到一个连接事件。发送数据的时候在 nRF Connect 的 RX 特征输入框里输入print(hello)点击发送ESP32 端执行后会把hello通过 TX 特征推回来平板端就能在通知日志里看到。整个过程延迟大概在 50 到 100 毫秒之间对于调试来说完全感觉不到卡顿。这里有个细节nRF Connect 默认发送的是 UTF-8 文本如果你要发二进制数据需要切换到 HEX 模式。PyBLE 的 REPL 只处理文本命令所以保持 UTF-8 就行。4.3 多设备切换与连接管理如果你有多块 ESP32 都跑了 PyBLE它们会同时广播名字可能都一样。这时候平板端会看到多个PyBLE设备分不清哪个是哪个。解决办法是在初始化的时候给每个设备设置不同的名字比如PyBLE_01、PyBLE_02或者把 MAC 地址后几位拼进去。import ubinascii name PyBLE_ ubinascii.hexlify(bluetooth.BLE().config(mac)[-2:]).decode()这样每个设备的名字都是唯一的平板端一眼就能认出来。连接管理方面PyBLE 默认允许同时连接多个中心设备但实际用的时候一般只连一个。如果你只想允许一个连接可以在_IRQ_CENTRAL_CONNECT里判断len(self._connections) 1就主动断开多余的。5. 常见问题排查与避坑经验实录5.1 连接失败与广播消失问题最常见的问题是平板搜不到设备或者连上一次之后再也搜不到。原因通常有几个一是 ESP32 端程序崩溃了BLE 广播停止二是平板端缓存了旧的连接信息没有正确断开三是周围 BLE 设备太多广播包被淹没。排查方法先看 ESP32 的串口输出确认程序还在跑。如果串口没输出可能是代码里有异常导致重启检查boot.py和main.py有没有语法错误。如果串口正常但搜不到试试重启平板蓝牙或者在 App 里清除缓存。实在不行把 ESP32 断电重启通常能解决。注意MicroPython 的 BLE 模块在异常重启后有时不会自动重新广播需要在main.py里加一个看门狗或者定时检查广播状态。5.2 数据丢包与乱码处理BLE 的NOTIFY不保证可靠传输数据量大或者发送频率高的时候会丢包。表现就是平板端收到的输出不完整或者出现乱码。解决办法有几个一是降低发送频率把多条短消息合并成一条长消息二是加一个简单的序号机制平板端发现序号跳变就知道丢包了三是改用INDICATE牺牲速度换可靠性。乱码问题通常是编码不一致导致的。ESP32 端发的是 UTF-8平板端如果按 GBK 解码就会乱。在 App 里把编码设置成 UTF-8 就行。如果发的是二进制数据记得在 App 里切换到 HEX 显示模式。5.3 供电与信号干扰问题ESP32 跑 BLE 的时候功耗会比纯 WiFi 低但如果你用的是电池供电还是要注意电压稳定。电压不稳会导致 BLE 连接断续甚至芯片重启。我遇到过一块用旧电池供电的板子BLE 连上几秒就断换了新电池就好了。信号干扰方面2.4GHz 频段很拥挤WiFi 路由器、微波炉、无线鼠标都会干扰 BLE。调试的时候尽量让平板和 ESP32 之间没有遮挡距离不要超过 5 米。如果实在干扰严重可以尝试在代码里调整 BLE 的发射功率不过 MicroPython 的bluetooth模块对发射功率的控制有限可能需要改底层固件。5.4 常见问题速查表问题现象可能原因排查方法解决方案平板搜不到设备程序崩溃或广播停止查看串口输出重启 ESP32检查代码异常连接后立即断开供电不稳或信号弱换电源靠近设备使用稳定电源缩短距离输出乱码编码不一致检查 App 编码设置统一使用 UTF-8数据丢包NOTIFY 不可靠降低发送频率合并消息或改用 INDICATE多设备分不清广播名相同查看 MAC 地址设置唯一设备名重连失败平板缓存旧连接清除 App 缓存重启平板蓝牙或清除配对6. 进阶玩法与个人实操体会6.1 把 PyBLE 集成到现有项目里如果你已经有一个 MicroPython 项目在跑不想单独维护一个调试固件可以把 PyBLE 的代码作为一个模块导入。在main.py里初始化 BLEUART然后把sys.stdout重定向过去这样所有的print都会走 BLE。业务逻辑照常跑调试输出走无线通道互不干扰。需要注意的是BLE 中断处理会占用一定的 CPU 时间如果你的业务逻辑对实时性要求很高可能会受影响。我的做法是在关键代码段临时关闭 BLE 通知等执行完再打开。MicroPython 里没有直接的开关但可以通过清空_connections集合来临时停止发送。6.2 自定义命令与快捷操作PyBLE 默认只支持 Python 语句执行但你可以扩展它加入自定义命令。比如定义一个cmd字典把led on、led off、reboot这样的短命令映射到对应的函数。平板端输入led on比输入machine.Pin(2, machine.Pin.OUT).value(1)方便多了。commands { led on: lambda: machine.Pin(2, machine.Pin.OUT).value(1), led off: lambda: machine.Pin(2, machine.Pin.OUT).value(0), reboot: lambda: machine.reset(), }然后在命令解析里先查字典找不到再当 Python 语句执行。这样既保留了灵活性又提高了常用操作的效率。6.3 我踩过的几个坑第一个坑是UUID 写错。我一开始自己编了一组 UUID结果平板端 App 不认折腾了半天才发现是 UUID 格式不对。后来换成 Nordic UART 的标准 UUID一次就通了。所以如果你不是非要自定义直接用标准 UUID 最省事。第二个坑是MTU 协商。BLE 默认的 MTU 是 23 字节实际能传的数据只有 20 字节。如果你发的消息超过这个长度会被自动分片平板端可能拼不回来。解决办法是在连接后主动协商更大的 MTUAndroid 上可以请求 512 字节iOS 上最大 185 字节。MicroPython 端可以通过gatts_set_buffer调整缓冲区大小但 MTU 协商主要由中心设备发起。第三个坑是异常处理。BLE 操作随时可能因为连接断开而抛异常如果不捕获程序直接崩溃。我在所有 BLE 发送的地方都加了try...except出错就忽略等重连后继续。虽然简单粗暴但实测下来最稳定。6.4 后续可以怎么扩展这个项目本身已经够用了但如果你想继续折腾有几个方向值得试试。一是加一个简单的 Web 界面用 ESP32 的 WiFi 跑一个网页通过 BLE 桥接这样电脑浏览器也能调试。二是支持文件传输把 BLE 当通道实现 OTA 更新或者日志下载。三是多设备组网一个平板同时连多个 ESP32做批量调试。不过说实话对于日常调试来说PyBLE 现有的功能已经覆盖了 90% 的场景。我用了几个月下来最大的感受是调试这件事终于不再被线缆绑住了。板子放在哪里都能改代码、看输出效率提升非常明显。如果你也经常和 ESP32 打交道强烈建议花一个下午把这个环境搭起来后面省下的时间绝对值得。