基于CircuitPython与BLE的无线摩尔斯电码通信系统设计与实现

1. 项目概述用摩尔斯电码和BLE打造你的“秘密电台”几年前我在一个创客工作坊里看到两个小朋友用纸杯和棉线做“土电话”玩得不亦乐乎。那种最原始的、点对点的秘密通信方式有种独特的魅力。当时我就在想能不能用我们手头的技术做一个数字时代的“无线土电话”它应该足够简单让初学者也能上手又足够有趣能让人体会到通信协议和编码的奥妙。于是这个基于CircuitPython和蓝牙低功耗BLE的无线摩尔斯电码聊天系统就从想法变成了现实。这个项目的核心是让两块Adafruit CLUE开发板或者其他兼容硬件通过BLE相互发现、配对然后使用者通过板载的A、B两个按钮以摩尔斯电码的方式输入字母实现一对一的秘密文字聊天。屏幕上会实时显示摩尔斯电码对照表、你发送的信息以及对方发来的信息。整个过程从硬件初始化、无线寻址、连接建立到摩尔斯码的编码、发送、接收和解码形成了一个完整的嵌入式无线通信应用闭环。它非常适合用来学习几个关键的东西首先是蓝牙低功耗BLE在嵌入式设备上的实际应用你会接触到广播、扫描、连接、服务Service和特征值Characteristic这些核心概念。其次是CircuitPython的编程范式你会发现用Python在微控制器上开发交互应用可以如此直观和快速。最后当然是摩尔斯电码本身这是一种经典的二进制编码方式通过它来通信你会对信息编码和解码有更深刻的身体记忆。无论你是刚接触嵌入式开发的爱好者想找一个有趣的项目入门BLE还是有一定经验的开发者希望了解CircuitPython在物联网设备上的开发流程亦或是教育工作者在寻找一个能融合硬件、编程和通信原理的生动教学案例这个项目都能给你带来扎实的收获和乐趣。接下来我们就从硬件准备开始一步步拆解这个“秘密电台”是如何搭建起来的。2. 核心硬件与工具选型解析工欲善其事必先利其器。这个项目的硬件核心是Adafruit CLUE开发板但它的设计思想是模块化和可移植的。理解这些硬件的选型理由能帮助你在未来将其适配到其他平台上。2.1 为什么是Adafruit CLUE项目原文指定使用Adafruit CLUE这并非偶然。CLUE是一款基于Nordic nRF52840芯片的开发板这块芯片是项目的“心脏”。nRF52840集成了一个强大的ARM Cortex-M4 CPU和一个完整的蓝牙5.0/低功耗蓝牙射频模块。这意味着单芯片就能处理应用逻辑和无线通信无需额外的蓝牙模块极大地简化了硬件设计和电源管理。除了核心的无线能力CLUE板载的资源几乎是为这个项目量身定做的240x240像素的LCD彩色显示屏这是显示摩尔斯电码对照表和聊天信息的完美画布。尺寸适中分辨率足够清晰显示文本和简单图形。两个贴片按钮A和B这是输入“点”Dot和“划”Dash最自然、最直接的方式。物理按钮提供了明确的触觉反馈这是触摸屏或传感器输入无法比拟的对于需要快速、准确输入摩尔斯码的场景至关重要。丰富的传感器虽未使用CLUE还内置了加速度计、陀螺仪、温湿度传感器等。虽然本项目未使用但这说明了CLUE是一个功能强大的平台你完全可以在此基础上扩展比如摇动板子来发送特定信号或者根据环境温度自动加密信息等。 注意如果你手头没有CLUE完全不用担心。项目的可移植性很好核心依赖只是nRF52840或其他支持CircuitPython BLE的芯片、一个显示屏和两个按钮。后文会详细讲解如何迁移到其他硬件例如Circuit Playground Bluefruit搭配TFT Gizmo显示屏。2.2 软件基石CircuitPython与相关库CircuitPython是Adafruit主导开发的一个微控制器Python实现。它最大的优势在于“所见即所得”的开发体验。你把开发板通过USB连接到电脑它会显示为一个名为CIRCUITPY的U盘。直接编辑这个盘里的code.py文件保存后代码立即自动运行无需编译、上传。这极大地降低了嵌入式开发的门槛让你能像写桌面Python脚本一样与硬件交互。对于本项目我们需要几个关键的CircuitPython库它们都来自Adafruit维护的庞大“CircuitPython Library Bundle”adafruit_ble这是整个项目的通信基石。它提供了BLE Radio对象封装了广播、扫描、连接等底层操作。更重要的是它提供了UARTService这是一个模拟串口通信的BLE服务。我们可以像读写普通串口一样uart.read()和uart.write()通过BLE收发数据抽象掉了复杂的BLE数据包处理让编程逻辑变得异常清晰。adafruit_clue这是CLUE开发板的硬件抽象库。通过clue.button_a和clue.button_b我们可以轻松读取按钮状态通过clue.display我们可以控制屏幕。这个库把对硬件的操作封装成了简单的Python属性或方法。adafruit_display_text和displayio这两个库负责图形显示。displayio是CircuitPython的显示框架管理屏幕上的图层Group和元素TileGrid, Label等。adafruit_display_text则专门用于在屏幕上渲染文本标签Label我们可以方便地设置文本内容、字体、大小、颜色和位置。adafruit_imageload用于加载项目中的背景图片文件morse_bg.bmp这张图片就是屏幕上显示的摩尔斯电码对照表。 实操心得库的安装是CircuitPython开发的第一步也是最容易出错的一步。务必从Adafruit官方GitHub发布页下载与你的CircuitPython版本匹配的“Library Bundle”。解压后只将项目需要的库文件.mpy或.py文件复制到CIRCUITPY盘下的lib文件夹内。库版本不匹配是导致“ImportError”的最常见原因。2.3 辅助工具准备除了核心硬件你还需要一条可靠的数据USB线很多手机充电线只能供电不能传输数据。务必使用一条已知良好的USB数据线连接CLUE和电脑。一个文本编辑器用于编辑code.py。推荐使用VS Code、Atom或Mu Editor。Mu Editor是Adafruit官方推荐的CircuitPython集成编辑器内置了串口监视器和代码检查对新手非常友好。串口监视器可选但推荐当代码运行时可以通过串口监视器查看print()语句输出的调试信息这对于排查连接问题、观察摩尔斯码输入过程至关重要。Mu Editor内置此功能也可以使用PuTTY、CoolTerm等第三方工具。3. 系统设计与通信逻辑深度剖析在动手写代码之前我们必须把整个系统的运行逻辑特别是BLE的通信模型搞清楚。这能让你在调试时心中有数知道问题可能出在哪个环节。3.1 BLE角色模型中心设备与外围设备蓝牙低功耗通信基于一种“客户端-服务器”模型在这里称为中心设备Central和外围设备Peripheral。外围设备Peripheral / Server通常是比较简单、低功耗的设备比如传感器、手环。它的工作是广播Advertising自己的存在告诉周围“我是谁我能提供什么服务”。在本项目中它将自身定义为一个提供UARTService串口服务的设备。中心设备Central / Client通常是功能更强的设备比如手机、电脑。它的工作是扫描Scanning周围的广播发现感兴趣的外围设备后主动发起连接Connection。本项目的巧妙设计在于它通过一个配置变量BLE_MODE让同一份代码可以在两种角色间切换。在代码初始化时我们设置BLE_MODE A或B。角色为A的板子充当中心设备角色为B的板子充当外围设备。这样两块完全一样的硬件运行几乎一样的代码就能自动组成一对通信伙伴。3.2 连接建立流程详解让我们跟随代码看看两块板子是如何“握手”成功的。这个过程发生在scan_and_connect()函数中。命名与广播准备两块板子根据BLE_MODE设定自己的MY_NAME如“CENTRAL”和要寻找的FRIENDS_NAME如“PERIPHERAL”。外围设备B模式会创建一个UARTService实例并将其包裹在ProvideServicesAdvertisement中准备广播。广播与扫描阶段外围设备B调用ble.start_advertising(advertisement)开始周期性地向外发送广播包包内包含了自己的设备名称FRIENDS_NAME即“PERIPHERAL”和所能提供的服务信息这里有UARTService。中心设备A则进入一个循环调用ble.start_scan()开始扫描周围的广播。每收到一个广播包就检查其完整名称adv.complete_name是否等于自己要找的FRIENDS_NAME即“PERIPHERAL”。连接与配对一旦中心设备A扫描到目标广播立即调用ble.stop_scan()停止扫描然后使用ble.connect(adv)尝试连接该外围设备。此时外围设备B的ble.connected状态会变为True它随即调用ble.stop_advertising()停止广播因为已经成功配对。服务发现与通信通道建立连接建立后中心设备A的函数直接返回uart_service对象。外围设备B则需要遍历当前的连接找到那个提供了UARTService的连接并返回该服务对象。至此双方都获得了一个uart对象后续就可以通过这个对象的read()和write()方法进行双向通信了。 注意事项这个流程是“一次性”的。即中心设备主动扫描并连接外围设备。如果连接断开程序会回到主循环重新调用scan_and_connect()试图再次建立连接。这种设计保证了系统的健壮性即使信号短暂中断也能恢复。3.3 摩尔斯电码的输入与解析机制通信链路打通后信息的编码和输入就是下一个核心。我们用两个按钮来模拟电报键。编码字典代码中定义了一个Python字典morse_code将摩尔斯电码的“点划”序列映射到对应的英文字母。例如.-对应A-...对应B。这是解码的核心查询表。输入状态机程序的主聊天循环while ble.connected:持续检测按钮状态。这是一个简单的状态机按下按钮A触发“点”.。程序会记录按下时刻并在一个极短的时间窗口WAIT_FOR_DOUBLE 0.05秒内检查是否按钮B也被按下。如果没有则将一个点字符追加到当前编码序列code字符串中并在屏幕底部的编辑区显示。按下按钮B触发“划”-。逻辑同上追加划字符。几乎同时按下AB双击检测如果在按下A后的0.05秒内又按下了B或反之则程序认为用户意图是“发送”done True。这是发送当前字母的信号。发送与显示当done标志被置位程序用morse_code.get(code, )查询当前code序列对应的字母如果查询不到则返回空格。然后将这个字母追加到屏幕下方的“发出信息”区域out_label并通过uart.write(str.encode(letter))将字母编码为字节后通过BLE发送出去。同时清空当前编码序列code准备输入下一个字母。接收与显示在循环的另一部分程序不断检查uart.in_waiting看看是否有数据从对方传来。一旦有数据就读取它解码为字符串并追加到屏幕上方的“接收信息”区域in_label。 实操心得WAIT_FOR_DOUBLE和DEBOUNCE这两个延时参数至关重要。DEBOUNCE去抖延时防止一次物理按压被误判为多次按下。WAIT_FOR_DOUBLE决定了系统判断“同时按下”的时间窗口。如果你觉得按钮反应迟钝可以尝试适当减小DEBOUNCE比如从0.25秒降到0.15秒但减得太小可能导致按键抖动。WAIT_FOR_DOUBLE不建议小于0.03秒否则很难触发双击发送。4. 从零开始的完整实现步骤理论分析完毕现在让我们挽起袖子一步步实现这个项目。请严格按照步骤操作特别是库文件的安装。4.1 步骤一硬件准备与CircuitPython固件烧录连接硬件用数据USB线将第一块Adafruit CLUE开发板连接到电脑。此时板载的红色电源LED应亮起。进入引导加载模式快速双击CLUE板上的RESET按钮。双击成功后板载的RGB NeoPixel LED会亮起绿色如果亮红色说明USB线或端口可能有问题。此时电脑上会出现一个名为CLUEBOOT的磁盘驱动器。下载并烧录固件访问CircuitPython官网circuitpython.org找到Adafruit CLUE的页面下载最新的.uf2固件文件。将下载好的adafruit-circuitpython-clue-... .uf2文件直接拖拽或复制到CLUEBOOT磁盘中。磁盘会自动弹出几秒后电脑上会出现一个新的磁盘驱动器名为CIRCUITPY。这表明CircuitPython固件已经烧录成功板子现在是一个可以运行Python代码的微控制器了。重复操作对第二块CLUE板重复以上1-3步骤。4.2 步骤二安装必要的库文件库文件必须正确放置到CIRCUITPY盘的lib文件夹内。下载库合集访问Adafruit的CircuitPython Library Bundle发布页面通常在GitHub上。选择与你的CircuitPython版本号匹配的合集文件例如如果你的固件是8.x就下载8.x的合集。下载的是一个.zip压缩包。解压并寻找所需库解压下载的zip文件。你需要找到以下库文件或文件夹注意库文件可能是.mpy格式——已编译的MicroPython字节码也可能是.py格式adafruit_ble/adafruit_clue.mpyadafruit_display_text/adafruit_imageload/adafruit_displayio_layout/某些版本可能需要displayio/、terminalio/等基础库通常已在固件中但如果在合集里看到也一并拷贝。复制到开发板打开CIRCUITPY磁盘如果里面没有lib文件夹就新建一个。将步骤2中找到的库文件或文件夹全部复制到CIRCUITPY/lib/目录下。对于第一块板子操作完成后断开USB连接准备给第二块板子进行同样的操作。4.3 步骤三获取并配置项目代码项目代码主要是一个code.py文件和一些资源文件如图片。下载项目包从Adafruit的学习指南页面原文提供的链接找到“Download Project Bundle”按钮下载整个项目压缩包。解压并查看内容解压后你会看到一个名为CLUE_BLE_Morse_Code的文件夹。进入该文件夹你会看到针对不同CircuitPython版本的子文件夹如8.x等。进入与你固件版本匹配的文件夹。关键文件code.py主程序文件。morse_bg.bmp摩尔斯电码对照表的背景图片。可能还有其他字体文件或资源。配置设备名称关键这是让两块板子互相识别的关键。用文本编辑器打开code.py找到顶部的用户配置部分# --| User Config |--------------------------------------------------- # Set to either A or B. The other CLUE should be set to opposite mode. BLE_MODE A # --| User Config |---------------------------------------------------对于第一块板子设置BLE_MODE A。这意味着它将扮演中心设备Central主动扫描。将MY_NAME和FRIENDS_NAME修改为易于识别的名字例如if BLE_MODE A: MY_NAME CLUE_Central FRIENDS_NAME CLUE_Peripheral保存这个版本的code.py并将其连同morse_bg.bmp等所有文件复制到第一块板子的CIRCUITPY磁盘根目录。配置第二块板子再次用文本编辑器打开原始的code.py或从项目包中复制一份新的。设置BLE_MODE B。这意味着它将扮演外围设备Peripheral主动广播。相应地修改名字必须与第一块板子的配置对称if BLE_MODE B: MY_NAME CLUE_Peripheral # 与第一块板的FRIENDS_NAME一致 FRIENDS_NAME CLUE_Central # 与第一块板的MY_NAME一致保存并复制所有文件到第二块板子的CIRCUITPY磁盘根目录。4.4 步骤四运行与聊天测试上电运行将两块CLUE板子通过USB线供电可以连接到电脑或充电宝。代码会自动运行因为code.py是CircuitPython的默认主程序文件。观察启动过程屏幕上会显示摩尔斯电码对照表背景。顶部和底部的消息区域最初可能显示“Connecting...”或“Scanning.../Advertising...”。建立连接确保两块板子彼此距离在几米内BLE有效范围。扮演外围设备B模式的板子会持续广播。扮演中心设备A模式的板子会持续扫描。当中心设备扫描到外围设备时屏幕上的连接状态会更新。此时在任意一块板子上同时按下A和B按钮即可建立连接。连接成功后顶部和底部的消息区域会清空等待输入。开始摩尔斯电码聊天查看对照表屏幕中央的大图就是摩尔斯电码对照表。例如“A”是“.-”点划。输入字母假设你想发送字母“A”。按下按钮A点然后按下按钮B划。你会看到底部编辑区显示“.-”。发送字母快速同时按下A和B两个按钮双击操作。你会听到如果连接了串口监视器打印信息并且底部发送区会出现字母“A”同时这个字母会通过无线发送到对方板子。接收字母对方发送的字母会显示在你屏幕的顶部接收区。发送空格直接快速双击AB不输入任何点划即可发送一个空格。断开与重连如果断开USB线或距离过远导致连接断开两块板子会自动回到扫描/广播状态可以再次按下双键重新连接。5. 代码核心模块详解与自定义优化现在让我们深入code.py的细节理解每一部分是如何工作的以及你可以在哪里进行个性化修改。5.1 初始化与显示层搭建代码的开头部分进行了硬件和软件环境的初始化。import time import displayio import terminalio from adafruit_clue import clue from adafruit_display_text import label import adafruit_imageload from adafruit_ble import BLERadio from adafruit_ble.advertising.standard import ProvideServicesAdvertisement from adafruit_ble.services.nordic import UARTService这些导入语句引入了所有必需的模块。displayio.Group()创建了一个显示组作为所有显示元素的容器。display.root_group disp_group将这个组设置为屏幕的根内容。加载背景图片的代码adafruit_imageload.load(morse_bg.bmp, ...)将BMP文件加载为位图对象并添加到显示组中作为底层背景。创建三个文本标签是显示交互信息的关键in_label位于屏幕上方坐标(235, 4)用于显示接收到的消息。anchor_point(1.0, 0)和anchored_position的配合实现了文本右对齐这样新字符从右侧进入旧字符向左滚动视觉效果很直观。out_label位于屏幕下方坐标(235, 180)用于显示自己发送的消息。同样右对齐。edit_label位于屏幕底部中央坐标(115, 212)用于实时显示当前输入的摩尔斯码“点划”序列。{:4s}.format(code)确保它始终占4个字符宽度排版整齐。 自定义提示如果你想改变显示风格这里是重点。你可以修改anchored_position的坐标来调整标签位置修改scale参数改变字体大小修改color参数十六进制如0xFF0000代表红色改变字体颜色。甚至你可以尝试加载不同的背景图片或者完全不用图片用adafruit_display_shapes画一些图形元素。5.2 BLE连接核心函数剖析scan_and_connect()函数是通信的枢纽它完美体现了BLE的中心-外围模式。def scan_and_connect(): print(Connecting...) in_label.text out_label.text Connecting... if MY_NAME CENTRAL: # 或者你自定义的Central设备名 # 中心设备逻辑扫描 - 发现 - 连接 keep_scanning True print(Scanning...) while keep_scanning: for adv in ble.start_scan(): if adv.complete_name FRIENDS_NAME: ble.stop_scan() ble.connect(adv) keep_scanning False print(Connected. Done scanning.) return uart_service else: # 外围设备逻辑广播 - 等待连接 - 提供服务 print(Advertising...) ble.start_advertising(advertisement) while not ble.connected: pass print(Connected. Stop advertising.) ble.stop_advertising() print(Connecting to Central UART service.) for connection in ble.connections: if UARTService not in connection: continue return connection[UARTService] return None这个函数的返回值是一个UARTService对象即代码中的uart后续所有的数据收发都通过这个对象进行。中心设备直接返回自己创建的uart_service实例而外围设备则从已建立的连接中查找并返回该服务。5.3 主循环聊天状态机主循环while True:包含了整个应用逻辑。外层循环保证连接断开后能重连。内层while ble.connected:循环是真正的聊天会话。接收数据if incoming_bytes:块处理接收。uart.in_waiting返回接收缓冲区中的字节数。uart.read(incoming_bytes)读取这些字节。bytes_in.decode()将其转换为字符串。in_label.text in_label.text[incoming_bytes:] bytes_in.decode()这行代码实现了接收消息区的滚动效果去掉最左边的N个旧字符N为本次接收的字符数然后在右侧追加新字符。按钮检测与摩尔斯码输入两个大的if clue.button_a:和if clue.button_b:块结构对称分别处理“点”和“划”的输入。它们都使用了time.monotonic()来计时以实现双击检测。WAIT_FOR_DOUBLE这个时间窗口非常短要求两个按钮几乎同时按下才会触发done True。编码发送当done为真时morse_code.get(code, )用当前的点划序列code去字典里查找对应的字母找不到则返回空格。然后更新发送标签out_label.text并通过uart.write(str.encode(letter))发送出去。最后重置code和done准备下一次输入。 性能优化点主循环中使用time.sleep(DEBOUNCE)来进行简单去抖并降低CPU占用。在微控制器编程中适当的延时是必要的但如果你希望系统响应更迅速可以探索更高效的非阻塞式按钮检测库如adafruit_debouncer它可以在后台处理去抖逻辑让主循环更流畅。5.4 高级自定义与功能扩展基础功能运行稳定后你可以尝试以下高级玩法修改通信协议目前只发送单个字母。你可以修改代码增加一个“发送单词”或“发送整句”的功能。例如长按某个按钮或使用板载的加速度计检测摇晃作为“词尾/句尾”信号将累积的字母作为一个完整消息块发送。增加加密功能让聊天更“秘密”。可以在发送端对字母进行简单的替换加密如凯撒密码在接收端解密后再显示。这只需要在uart.write()前和bytes_in.decode()后增加几行处理代码。适配其他硬件正如项目原文提到的代码可以迁移。核心需求是支持CircuitPython BLE的板子如Circuit Playground Bluefruit、Feather nRF52840、一个显示屏如TFT Gizmo同样是240x240、两个按钮。你需要修改硬件初始化代码例如从from adafruit_clue import clue改为from adafruit_circuitplayground import cp并相应修改按钮引用为cp.button_a。根据新屏幕的尺寸和分辨率重新计算所有文本标签的anchored_position坐标。为新的屏幕尺寸重新制作或缩放背景图片morse_bg.bmp。增加声音和震动反馈CLUE板载有蜂鸣器。你可以在按下按钮时添加一个短促的“嘀”声在发送成功时添加一个不同的音调让交互更有质感。Circuit Playground Bluefruit则有更多的LED和扬声器效果可以更炫酷。6. 故障排除与常见问题实录在实际操作中你可能会遇到一些问题。这里我整理了可能遇到的坑及其解决方法很多都是我在工作坊中亲眼见到学员们踩过的。6.1 连接类问题问题现象可能原因排查步骤与解决方案两块板子始终显示“Scanning...”和“Advertising...”无法连接。1.设备名称不匹配MY_NAME和FRIENDS_NAME设置不对称或拼写错误。2.角色模式设置错误两块板子都设成了BLE_MODEA或都是B。3.BLE信号干扰或距离过远。1.检查代码仔细核对两块板子code.py中的BLE_MODE、MY_NAME、FRIENDS_NAME。确保一块是ACentral另一块是BPeripheral且名字互相对应。2.重启板子按复位键或重新插拔USB让代码重新运行。3.拉近距离确保板子在1-2米内无大型金属物体遮挡。4.查看串口输出连接串口监视器如Mu Editor查看打印的调试信息“Scanning...”, “Found: XXX”, “Advertising...”这是最直接的诊断方式。连接成功后突然断开然后又重新开始扫描/广播。1.物理距离超出范围或信号被严重遮挡。2.电源不稳定如USB线接触不良。3.代码跑飞或内存问题较少见。1. 保持设备在近距离无障碍环境下使用。2. 更换USB线或USB端口确保供电稳定。3. 这是设计行为代码的while True外层循环就是为了处理断线重连。断开是正常的BLE现象自动重连是功能。只有一块板子能收到消息另一块收不到。1.UART服务对象获取失败特别是在Peripheral端。2.代码逻辑错误导致只有一方在循环中读取uart.in_waiting。1. 检查Peripheral板子的scan_and_connect()函数确保成功进入了for connection in ble.connections:循环并返回了有效的UARTService对象。可以在返回前加print(“UART service obtained”)调试。2. 确保两块板子的主循环逻辑一致都在持续检查in_waiting。6.2 输入与显示类问题问题现象可能原因排查步骤与解决方案按下按钮屏幕上的点划符号不显示或显示延迟。1.按钮去抖延时DEBOUNCE设置过长。2.主循环阻塞可能因为某处有长时间的time.sleep()或复杂计算。3.显示刷新问题。1. 尝试逐步减小DEBOUNCE的值如从0.25到0.15再到0.1观察反应。2. 确保主循环中没有不必要的长时间延时。按钮检测逻辑本身是高效的。3. CircuitPython的displayio在某些复杂刷新时可能有延迟但本项目显示元素简单通常不是问题。双击AB发送不灵敏经常变成输入了两个单独的点或划。双击判定时间WAIT_FOR_DOUBLE太短。人的反应速度和按钮物理特性导致很难在0.05秒内同时按下。适当增加WAIT_FOR_DOUBLE的值例如从0.05调整到0.1甚至0.15。这给了你更宽松的时间去“同时”按下两个按钮。发送的字母是错的或者查询不到。1.摩尔斯码输入序列错误对照表不熟。2.morse_code字典定义错误或缺失条目但原代码是完整的。3.code变量在发送后没有正确清空导致前后输入粘连。1. 多练习看着屏幕上的对照表输入。2. 检查代码中morse_code字典的拼写确保是“.-”而不是“. -” (中间有空格)。3. 在done True的处理分支中确认有code “”这一行。屏幕显示混乱、花屏或完全不显示。1.库文件缺失或版本不兼容特别是displayio相关库。2.背景图片morse_bg.bmp损坏或未正确复制到板子。3.内存不足。1. 重新从匹配版本的Library Bundle中复制所有显示相关库到lib文件夹。2. 确认morse_bg.bmp文件存在于CIRCUITPY磁盘根目录且文件名拼写完全一致包括大小写。3. CircuitPython设备内存有限。确保代码没有创建大量无法释放的对象。本项目代码是内存友好的。6.3 库与环境类问题问题现象可能原因排查步骤与解决方案导入错误ImportError例如找不到adafruit_ble或adafruit_clue。1.库文件没有正确安装到CIRCUITPY/lib/目录下。2.库文件版本与CircuitPython固件版本不匹配。3.库文件路径错误比如放在了子文件夹里。1. 检查CIRCUITPY/lib/目录确认所需的.mpy或文件夹存在。2.这是最常见的原因务必下载与你的CircuitPython固件主版本号相同的Library Bundle例如固件是8.0.0就下载8.x的库。3. 库文件应直接放在lib下或lib下的对应文件夹内如lib/adafruit_ble/。代码保存后板子无反应或报错CIRCUITPY盘可能消失又出现。语法错误导致code.py无法运行。CircuitPython会在代码出错时进入安全模式有时会重置文件系统。1. 打开串口监视器如Mu Editor查看具体的错误信息。这是最重要的调试手段。2. 根据错误信息回溯代码检查拼写、缩进、括号匹配等。3. 一个常见错误是修改代码时不小心破坏了字符串或注释的格式。 终极调试心法当遇到任何诡异问题时第一反应应该是打开串口监视器。CircuitPython会将所有print()语句和运行时错误信息输出到串口。这些信息是照亮黑暗的明灯。在代码关键节点如进入函数、连接成功、收到数据增加print()语句是嵌入式开发最有效的调试方法没有之一。这个项目就像一把钥匙为你打开了基于CircuitPython和BLE的嵌入式物联网应用开发的大门。它麻雀虽小五脏俱全涵盖了硬件初始化、外设控制、无线通信协议、用户交互、状态机编程等多个核心概念。当你成功让两块板子用摩尔斯码聊上天的那一刻你所理解的远不止几行代码而是一整套从物理信号到数字信息再从本地输入到无线传输的完整链条。