基于CircuitPython与asyncio的嵌入式异步编程实战：复刻经典记忆游戏

1. 项目概述：当经典记忆游戏遇上现代异步编程

如果你玩过上世纪七八十年代风靡一时的“西蒙”电子记忆游戏，一定会对那四个彩色按钮和不断重复、增长的音光序列印象深刻。今天，我们要用现代嵌入式开发的技术栈——CircuitPython和asyncio——来亲手复刻并深度改造这个经典，打造一个属于你自己的桌面街机游戏：“Blinka Says”。

这个项目远不止是一个简单的复刻。它的核心价值在于，它是一份绝佳的嵌入式异步编程实战案例。在传统的微控制器编程中，处理按钮输入、LED闪烁、屏幕刷新这些需要“同时”发生的任务时，我们往往要依赖复杂的状态机、中断或者笨拙的time.sleep()轮询，代码很快就会变得难以阅读和维护。而CircuitPython内置的asyncio库，为我们提供了一种更优雅的解决方案：协作式多任务。通过协程（Coroutine）和事件循环，我们可以用近乎同步的代码写法，实现真正的异步逻辑，让处理用户输入和生成游戏序列这两个核心任务并行不悖，互不阻塞。

整个项目基于一块Adafruit ESP32-S3 TFT Feather开发板（或其S2版本），它集成了彩色显示屏和Wi-Fi/蓝牙功能，但在这个项目中，我们主要利用其强大的GPIO和CircuitPython支持能力。四个带LED的30mm街机按钮（黄、绿、红、蓝）提供了直接的物理交互和视觉反馈。所有的硬件通过一块半尺寸的Perma-Proto原型板和鳄鱼夹跳线连接，这种设计在“可逆”与“永久”之间取得了巧妙的平衡——你可以轻松拆解部件用于其他项目，也可以一劳永逸地焊接成一个坚固的整体。

无论你是想学习CircuitPython下的异步编程范式，还是希望为你的工作台增添一个有趣的互动装置，亦或是寻找一个综合性的嵌入式项目来练手，“Blinka Says”都是一个从硬件连接到软件架构都极具学习价值的实践。接下来，我将带你从零开始，完整走通硬件组装、代码解析、编程思想到调试优化的全过程，分享那些官方教程里不会写的布线技巧、代码设计中的权衡考量，以及我踩过的一些坑。

2. 硬件选型、连接与可逆构建哲学

2.1 核心硬件解析与选型考量

项目的硬件清单看起来简单，但每一件选型都暗含考量。主控选择Adafruit ESP32-S3 TFT Feather，而不仅仅是普通的ESP32开发板，原因有三：其一，它板载的TFT显示屏可以直接用于显示分数和游戏状态，无需额外接线，极大简化了项目；其二，Feather生态的引脚布局标准统一，周边配件丰富；其三，ESP32-S3芯片性能足够强劲，运行CircuitPython和异步任务游刃有余，为未来可能的扩展（如声音、网络排行榜）留有余地。如果你手头是ESP32-S2 TFT版本，代码完全兼容，可以无缝替换。

四个30mm带LED的街机按钮是游戏的灵魂。选择透明款是为了让内置LED的光效更佳。每个按钮底部有四个接线端子，分别是LED正极、LED负极（GND）、按钮信号线（常开触点）和按钮负极（GND）。这里有一个关键技巧可以节省一半的接线：通过焊接一小段导线，将按钮的LED GND和按钮GND两个焊盘连接起来。这样，每个按钮就只需要三根线：共地线、LED控制线、按钮信号线。务必使用万用表确认你连接的是两个GND焊盘，如果误将信号线与GND短接，会导致按钮始终处于“按下”状态，电路无法正常工作。

连接线材选择了鳄鱼夹转杜邦头跳线包。这可能是整个项目中最体现“可逆构建”思想的部件。鳄鱼夹可以牢固地夹在按钮的端子上，而杜邦头则可以轻松插拔Perma-Proto板上焊接的排母。如果你想永久固化这个项目，完全可以用导线直接焊接。但使用这种跳线，意味着你可以在一分钟内将四个按钮从游戏机上拆下来，用于下一个机器人或者控制面板项目，实现了硬件模块的最大化利用。

Perma-Proto半尺寸原型板是我们的“主板”。它比面包板稳固，又比直接飞线规整。我们需要在上面焊接若干排母（Female Header）。这里的方向很重要：用于插接Feather开发板的两排排母（一排16针，一排12针）应该从板子正面插入并焊接在板子背面，这样Feather可以像插在面包板上一样稳稳立住。而用于连接按钮和LED信号线的三排排母（每排至少4针），则应从板子背面插入，焊接在板子正面。这样，所有来自按钮的鳄鱼夹跳线都从板子下方接入，整个上部空间整洁，便于Feather插拔。

2.2 引脚分配与布线实战

清晰的引脚分配是项目成功的基石。下面这个表格总结了所有必要的连接关系，建议在焊接和接线时反复核对：

注意：代码中keypad.Keys初始化时设置了pull=True，这意味着我们在软件中启用了内部上拉电阻。因此，在硬件上，按钮信号线另一端只需接地即可，无需外部上拉电阻。当按钮未按下时，引脚被内部电阻拉高，读取为True或1；按下时，引脚接地，读取为False或0。value_when_pressed=False的设置正好与此匹配。

接线时，我建议遵循一定的颜色规范以减少混乱。虽然套件中的跳线颜色恰好对应按钮颜色，但为了更好地区分功能，我采用了另一套方案：黑色和蓝色线用于所有GND连接；黄色和红色线用于LED控制信号；绿色和白色线用于按钮信号输入。这样，即使不看线缆另一端，你也能大致判断其功能。

最后，别忘了在Perma-Proto板边缘的电源地轨（通常标有蓝色“-”线）和Feather的GND引脚之间焊接一根地线跳线。这是整个电路的公共参考点，至关重要。你可以用一根剪下的电阻腿或一小段导线，在板子背面完成这个连接。

3. 软件架构深度解析：状态机与异步任务的共舞

3.1 游戏状态机：数据的中央枢纽

整个游戏逻辑的核心是一个清晰的状态机，而GameState类就是这个状态机的数据中心。它不仅仅是一个存储变量的容器，更是协调两个异步任务（玩家动作和Blinka动作）之间通信的共享内存区。理解它的每个字段，就理解了游戏的全部规则。

class GameState: def __init__(self, difficulty: int, led_off_time: int, led_on_time: int): self.difficulty = difficulty # 当前序列长度 self.led_off_time = led_off_time # LED熄灭时长（毫秒） self.led_on_time = led_on_time # LED点亮时长（毫秒） self.score = 0 # 玩家当前得分 self.current_state = STATE_WAITING_TO_START # 核心状态变量 self.sequence = [] # 当前需要记忆的颜色序列 self.index = 0 # Blinka播放序列时的当前位置 self.btn_cooldown_time = -1 # 按钮冷却截止时间戳 self.highscore = None # 从NVM读取的最高分

**current_state**是状态机的引擎，它只在三个状态间循环：STATE_WAITING_TO_START（等待开始）、STATE_BLINKA_TURN（Blinka展示序列）、STATE_PLAYER_TURN（玩家重复序列）。两个任务通过检查这个变量来决定自己当前该做什么、不该做什么。

sequence列表存储的是像['Y', 'G', 'R', 'B']这样的字符序列。这里的设计很巧妙：它用一个简单的字符代表一种颜色，与COLORS元组和leds字典的键直接对应，避免了使用复杂的枚举或数字映射，让代码更直观。

**btn_cooldown_time**是一个防误触设计。在游戏结束、状态重置为“等待开始”的瞬间，程序会设置一个未来1.5秒的时间戳。在此时间之前，即使玩家立刻按按钮，player_action任务也会忽略它。这有效防止了因按钮抖动或玩家紧张连按导致的意外重启，提升了游戏体验的稳健性。

NVM（非易失性存储器）的使用是另一个亮点。通过foamyguy_nvm_helper库，游戏将最高分以("bls_hs", score)的元组形式存储到微控制器的Flash中。即使断电重启，你的辉煌战绩依然得以保存。这种模式在需要保存用户设置或进度的嵌入式项目中非常常用。

3.2 异步任务剖析：协作而非抢占

CircuitPython的asyncio实现的是协作式多任务，这与操作系统中的抢占式多任务有本质区别。在协作式模型中，一个任务必须主动“让出”控制权（通过await asyncio.sleep(0)或其他await语句），其他任务才有机会运行。这要求开发者精心设计任务，确保没有某个任务长时间阻塞事件循环。

项目中的两个核心任务player_action和blinka_action是这种模式的典范。它们的主体都是一个while True无限循环，但在每次循环的末尾，都会执行await asyncio.sleep(0)。这行代码的魔力在于：它告诉事件循环，“我这一轮的事情做完了，虽然不需要真实等待时间，但请你检查一下有没有其他任务在等着运行”。这就给了另一个任务切入的机会。

player_action任务的工作流是一个典型的事件驱动模型。它不断从keypad.Keys对象的事件队列（buttons.events.get()）中获取按键事件。这个get()方法是非阻塞的，如果没有事件，它会立即返回None，任务随即让出控制权，效率很高。一旦有按键事件，任务就根据当前的game_state.current_state来决定如何响应。在“玩家回合”状态下，它会比对按下的按钮颜色是否与序列第一个颜色匹配，并更新分数或结束游戏。整个逻辑清晰地位于一个if-elif链中，状态机的优势得以体现。

blinka_action任务则是一个序列播放器。它只在current_state为STATE_BLINKA_TURN时工作。它的职责是：如果序列为空，就根据当前难度difficulty随机生成一个新序列；然后，按照LED_OFF -> LED_ON -> LED_OFF的节奏，依次点亮序列中的每个颜色对应的LED。播放完毕后，将状态切换为STATE_PLAYER_TURN。这里对时间的控制全部通过await asyncio.sleep(led_off_time / 1000)实现，在“睡眠”期间，事件循环可以自由地去执行player_action任务，处理可能的按钮事件（尽管在Blinka回合会被忽略），保证了系统的响应性。

main()函数作为程序的入口，扮演着调度者的角色。它创建GameState实例，然后通过asyncio.create_task()将两个动作函数包装成任务对象。最后，asyncio.gather(player_task, blinka_task)启动并等待这两个任务（实际上由于都是无限循环，会一直运行下去）。这种模式使得增加第三个任务（比如一个负责屏幕动画的任务）变得非常容易，只需创建并添加到gather列表中即可，架构扩展性很好。

4. 代码逐行解读与关键实现细节

4.1 初始化与硬件抽象层

代码的开头部分完成了所有硬件接口的抽象化，这是将物理世界映射到代码逻辑的关键一步。

import random import time import asyncio import board from digitalio import DigitalInOut, Direction from displayio import Group import keypad import terminalio from adafruit_display_text.bitmap_label import Label import foamyguy_nvm_helper as nvm_helper

keypad库是处理按钮输入的利器。它基于事件驱动，自动处理去抖动，比直接读取digitalio引脚更可靠。初始化时，我们传入了四个按钮对应的引脚元组(board.D5, board.D6, board.D9, board.D10)。value_when_pressed=False表明当按钮被按下时，读取到的值是False（因为引脚被拉低到地）。pull=True启用了内部上拉电阻，这是硬件接线采用共地方式的对应软件配置。

leds字典建立了颜色代码（‘Y‘, ‘G‘, ‘R‘, ‘B‘）到DigitalInOut对象的映射。这种数据结构让后续的代码非常清晰：要控制黄色LED，只需leds["Y"].value = True。初始化循环for color in COLORS: leds[color].direction = Direction.OUTPUT确保了所有LED引脚都被设置为输出模式。

显示部分的初始化略显繁琐，但逻辑清晰。它创建了一个Group作为根容器，然后依次创建并定位了四个文本标签：高分标签、当前分标签、高分值、当前分值，以及一个初始隐藏的“Game Over”标签。anchor_point和anchored_position的配合使用，是实现相对定位的关键。例如，将高分标签的锚点设为(1.0, 0.0)（右上角），然后将其锚定位置设为(display.width - 4, 4)，就意味着标签的右上角将被固定在离屏幕右边缘4像素、上边缘4像素的位置。这种布局方式可以很好地适应不同分辨率的屏幕。

4.2 玩家动作任务的精妙逻辑

player_action任务是游戏交互的核心，它巧妙地处理了状态转换、得分逻辑和错误处理。

async def player_action(game_state: GameState): while True: key_event = buttons.events.get() # 非阻塞获取按键事件 if game_state.current_state == STATE_WAITING_TO_START: # 检查冷却时间，防止误触 if game_state.btn_cooldown_time < time.monotonic(): if key_event and key_event.released: # 注意是释放事件 # 隐藏“Game Over”，显示分数，并执行炫酷的“准备开始”灯光秀 game_over_lbl.hidden = True curscore_val.text = str(game_state.score) # ... 灯光闪烁序列 ... game_state.current_state = STATE_BLINKA_TURN # 状态转移

这里第一个技巧是使用了按钮释放事件（key_event.released）而非按下事件来触发游戏开始。这符合用户直觉——按下再松开才算一次完整的操作，也能避免按钮按下时间过长被误判为多次触发。灯光秀（所有LED同时闪烁三次）是一个很好的视觉反馈，明确告知玩家游戏即将开始。

在STATE_PLAYER_TURN状态下，逻辑变得有趣：

elif game_state.current_state == STATE_PLAYER_TURN: if key_event and key_event.pressed: leds[COLORS[key_event.key_number]].value = True # 按下即亮，即时反馈 if key_event and key_event.released: leds[COLORS[key_event.key_number]].value = False # 松开即灭 # 关键判断：按下的颜色是否匹配序列第一个？ if COLORS[key_event.key_number] == game_state.sequence[0]: game_state.sequence.pop(0) # 匹配，移除已匹配项 game_state.score += 1 curscore_val.text = str(game_state.score) if len(game_state.sequence) == 0: # 序列全部匹配完成 game_state.score += 1 # 完成关卡的额外奖励分 game_state.difficulty += 1 # 增加下一关难度 game_state.current_state = STATE_BLINKA_TURN # 交还给Blinka else: # 按错颜色 # 显示“Game Over”，处理最高分保存，重置游戏状态 game_over_lbl.hidden = False if game_state.highscore is None or game_state.score > game_state.highscore: nvm_helper.save_data(("bls_hs", game_state.score), test_run=False) game_state.highscore = game_state.score highscore_val.text = str(game_state.score) # 重置所有状态变量，并开启按钮冷却 game_state.current_state = STATE_WAITING_TO_START game_state.score = 0 game_state.difficulty = 1 game_state.btn_cooldown_time = time.monotonic() + 1.5 game_state.sequence = []

这里有几个值得称道的设计：第一，即时视觉反馈：按钮按下时对应LED立刻点亮，松开时熄灭，这让玩家的操作有了直接的物理关联，体验更佳。第二，序列的消费式匹配：使用sequence.pop(0)，每匹配成功一个颜色，就从列表头部移除它，这样sequence[0]永远指向玩家接下来需要按下的颜色，逻辑简洁。第三，状态重置的完整性：游戏结束时，不仅重置分数和难度，还清空了序列，并设置了冷却时间，确保游戏可以干净地进入下一轮。

4.3 Blinka动作任务与节奏控制

blinka_action任务相对单纯，它的核心是按节奏播放序列。

async def blinka_action(game_state: GameState): while True: if game_state.current_state == STATE_BLINKA_TURN: # 如果序列为空，生成新序列 if len(game_state.sequence) == 0: for _ in range(game_state.difficulty): game_state.sequence.append(random.choice(COLORS)) # 播放序列中的当前颜色 await asyncio.sleep(game_state.led_off_time / 1000) # 熄灭间隔 leds[game_state.sequence[game_state.index]].value = True # 点亮 await asyncio.sleep(game_state.led_on_time / 1000) # 点亮持续时间 leds[game_state.sequence[game_state.index]].value = False # 熄灭 await asyncio.sleep(game_state.led_off_time / 1000) # 熄灭间隔 # 移动索引，判断是否播放完毕 game_state.index += 1 if game_state.index >= len(game_state.sequence): game_state.index = 0 game_state.current_state = STATE_PLAYER_TURN # 交还给玩家

节奏感是记忆游戏体验的关键。这里通过两个参数led_off_time和led_on_time（初始化均为500毫秒）来控制闪烁的节奏。OFF -> ON -> OFF的模式构成了一个完整的“闪一下”动作，两个OFF间隔确保了每次闪烁之间有清晰的分隔。你可以通过调整GameState初始化时的这两个参数（单位是毫秒）来改变游戏速度，让挑战性更高或更低。

任务协作点就发生在每一个await asyncio.sleep()处。在等待的几百毫秒里，player_action任务有机会检查按钮事件。虽然在Blinka回合这些事件会被忽略，但这种设计保证了系统在任何时候都对用户输入保持响应，这是编写友好交互程序的重要原则。

5. 项目构建、调试与深度优化指南

5.1 从零开始的系统化构建流程

拿到所有零件后，不要急于焊接。我建议遵循以下系统化流程，可以最大程度避免错误：

1. 预处理按钮：首先处理四个街机按钮。使用烙铁和一小段电阻腿或导线，仔细地将每个按钮上的“按钮GND”和“LED GND”两个焊盘连接起来。完成后，务必用万用表的通断档位，确认这两个焊盘之间是短路（连通）状态，而它们与“LED+”和“按钮信号”焊盘之间是开路（不连通）状态。这是硬件成功的基础。

2. 规划与焊接排母：在Perma-Proto板上规划好排母的位置。先用Feather开发板和排母在板子上比划，确保Feather插上后位置合适，不会挡住其他排母。用胶带临时固定排母，翻过板子进行焊接。关键技巧：先焊接排母的两个对角引脚，检查位置是否端正，确认无误后再焊接其余引脚。对于地线排母，可以将其焊接在板子边缘的电源地轨上，确保电气连接良好。

3. 焊接地线跳线：在板子背面，用一根短线将Feather的GND引脚孔与板子边缘的地轨连接起来。确保焊点圆润光滑，无虚焊。

4. 初步功能测试（至关重要）：先不要连接按钮！将Feather插入主板，通过USB连接电脑。将项目代码code.py及相关库文件复制到CIRCUITPY驱动器。打开串行监视器（如Mu编辑器、Thonny或screen /dev/ttyACM0）。修改代码，在初始化leds字典后，添加一个简单的测试循环：

   for color, led in leds.items(): print(f"Testing {color} LED") led.value = True time.sleep(0.5) led.value = False time.sleep(0.5)

   运行后，你应该看到四个LED依次点亮半秒。这验证了LED控制引脚（A0, A1, A2, A3）的焊接和代码配置是正确的。然后，用一根杜邦线，一端插入按钮信号排母的某个孔（如对应D5的孔），另一端短暂触碰GND排母。在串行监视器中，你应该能看到对应的按键事件打印出来。这验证了输入引脚和上拉电阻配置正确。

5. 连接按钮与最终组装：通过鳄鱼夹跳线，按照之前确定的颜色方案，将每个按钮的三根线（GND, LED, Button）连接到对应的排母上。建议一次连接一个按钮，并运行测试代码，确认该按钮的LED可控、按键可检测。全部连接完成后，将主板、按钮合理布局在桌面上或你准备好的外壳内。

5.2 常见问题排查与实战技巧

即使按照步骤操作，你也可能会遇到一些问题。下面是我在多次构建和教学中总结的常见问题速查表：

独家调试技巧：在代码中灵活使用print()语句是调试嵌入式Python程序最强大的武器。你可以在状态改变、按键触发、序列生成等关键位置添加print，通过串行监视器实时观察程序流。例如，在player_action任务中，取消注释#print(key_event)和#print(game_state.sequence)，你就能在每次按键时看到具体是哪个键被按下以及当前剩余的序列，这对于验证游戏逻辑是否正确至关重要。

5.3 性能优化与功能扩展思路

当前的项目已经是一个完整可玩的游戏，但它还有巨大的优化和扩展潜力。

1. 视觉与交互优化：

• 渐变动画：目前的LED开关是瞬间的。你可以使用PWMOut来控制LED引脚，实现按下时的呼吸灯效果或闪烁时的淡入淡出，体验会更柔和。
• 屏幕动画：在displayio的Group里添加图形或动画精灵（Sprite）。例如，在Blinka回合，可以在屏幕中央同步显示闪烁的颜色方块；游戏结束时，可以显示一个爆炸动画。这需要创建另一个异步任务来管理屏幕动画。
• 声音反馈：通过一个简单的无源蜂鸣器连接到另一个GPIO引脚，并利用pwmio生成不同频率的方波，可以为按钮按下、正确/错误匹配、游戏结束等事件添加音效，沉浸感倍增。

2. 游戏性扩展：

• 多难度模式：修改GameState，增加一个mode变量。例如，模式1（经典）：速度不变，序列增长；模式2（急速）：每过一关，led_on_time和led_off_time按比例减少；模式3（地狱）：序列会包含重复颜色。可以通过长按某个按钮或在游戏开始前按特定组合键来切换模式。
• 得分系统丰富化：引入连击（Combo）机制。如果玩家在极短时间内按对，可以获得额外加分。这需要在player_action任务中记录上次按对的时间戳。
• 序列生成算法：目前的random.choice(COLORS)是完全随机的。可以设计更“狡猾”的算法，比如避免生成过长单一颜色的序列，或者偶尔生成“红-蓝-红”这种容易混淆的短模式来增加难度。

3. 工程化改进：

• 配置化：将led_on_time、led_off_time、初始难度等参数移到一个单独的config.py或settings.toml文件中，甚至通过屏幕菜单让玩家可以调整，而无需修改主代码。
• 错误恢复：增加看门狗（Watchdog）机制。虽然asyncio任务通常很稳定，但可以引入asyncio.wait_for()为某些操作设置超时，防止因意外阻塞导致整个游戏无响应。
• 电源管理：如果改用电池供电，可以增加一个“自动休眠”功能。当检测到长时间无操作时，自动调暗屏幕、关闭LED，并进入低功耗模式，通过按键唤醒。

实现这些扩展，本质上就是在现有的两个异步任务基础上，增加更多的任务，并通过GameState这个共享数据中心进行协调。这正是asyncio架构的优势所在——它让复杂的、多事件的嵌入式应用逻辑变得模块化且清晰。例如，增加一个sound_task，它监听GameState中的一个sound_event队列；其他任务只需要向队列放入一个如("beep", 440, 100)（音调，频率，时长）的事件，声音任务就会异步处理播放，完全不影响主游戏循环。

这个“Blinka Says”项目就像一个功能完备的引擎，你可以在它之上尽情发挥创意，打造出独一无二的桌面街机体验。从理解硬件交互到掌握异步协作，再到按需扩展功能，每一步都是嵌入式开发者成长的坚实脚印。希望这份超详细的拆解，能让你不仅成功复现项目，更能透彻理解其设计精髓，并将其运用到更多有趣的创造中去。