基于CircuitPython的互动雪花球：从传感器滤波到状态机设计的嵌入式实践

1. 项目概述与核心思路

如果你玩过微控制器，尤其是像Adafruit Circuit Playground Express（CPX）这类自带一堆传感器和LED的板子，可能会觉得官方示例有些“玩具感”。但恰恰是这种看似简单的板子，结合正确的思路，能做出非常出彩的互动作品。今天分享的这个互动雪花球项目，就是一个绝佳的例子。它不仅仅是一个“摇一摇就亮灯”的小玩意儿，而是完整地串联了传感器数据采集与滤波、状态机逻辑控制、多任务（灯光与声音）的协同处理这几个嵌入式开发中的核心概念。对于想从点灯、读传感器跨越到做出一个完整互动产品的朋友来说，这个项目的代码结构和实现思路很有嚼头。

整个项目的核心逻辑非常清晰：一个基于加速度传感器的“摇晃检测”触发器，去驱动两套独立的输出系统——10颗可编程RGB LED（NeoPixel）组成的灯光秀，以及一个微型扬声器播放的音乐。听起来简单，但里面有几个关键点决定了最终体验的好坏：如何准确、稳定地检测“摇晃”动作，避免误触发？如何在检测到动作后，设计一段视觉上吸引人、且能与“雪花飘落”意境契合的灯光动画？又如何让灯光和音乐这两件事有条不紊地进行，不互相阻塞？这个项目的代码给出了一个简洁而有效的参考答案。它没有用到复杂的实时操作系统，仅用CircuitPython的基础循环和函数封装，就实现了流畅的交互体验，这对于资源有限的微控制器项目来说，是非常实用的设计模式。

接下来，我会带你深入代码和硬件组装细节，不仅复现这个雪花球，更关键的是拆解其中每个设计选择背后的“为什么”，并分享我在实际制作过程中踩过的坑和优化技巧。无论你是刚接触CircuitPython的新手，还是想寻找一个完整项目来练手的开发者，相信都能从中获得启发。

2. 硬件选型与物料清单解析

工欲善其事，必先利其器。这个项目的硬件选型经过精心考虑，在成本、易用性和效果之间取得了很好的平衡。我们逐一分析：

2.1 核心控制器：Circuit Playground Express

选择CPX作为大脑，是项目成功的一大半原因。它绝不是“又一个Arduino板”，而是一个高度集成化的交互开发平台。

• 内置传感器丰富：板载LIS3DH三轴加速度计，这正是我们检测摇晃的核心。它精度足够，且通过cpx.acceleration即可直接读取，省去了连接外部传感器、调试I2C/SPI总线的麻烦。
• 输出设备现成：10颗NeoPixel RGB LED环形排列，一个微型扬声器。这意味着我们无需焊接任何LED或连接音频放大器，极大地降低了硬件门槛。
• CircuitPython原生支持：CPX是Adafruit主打CircuitPython的板子之一，固件和库支持最为完善。其USB磁盘拖放编程的方式，让代码调试和更新像修改文本文件一样简单。

注意：市面上有Classic（经典版）和Express（快车版）两种Circuit Playground。务必确认你手上的是“Express”版本。经典版使用Arduino IDE编程，且处理器和内存资源较少，无法运行本项目所需的CircuitPython代码。

2.2 供电方案：3x AAA电池盒与开关

项目选用了一个带开关和JST-PH接口的3节AAA电池盒。这里有几个细节考量：

• 电压匹配：3节碱性AAA电池提供约4.5V电压，完美落在CPX的3.3V-6V输入电压范围内。锂电池（3.7V）单节电压稍低，两节串联（7.4V）又略高且需考虑充电管理，因此3节AAA碱性电池是最简单、安全的选择。
• JST-PH接口：这是一种小尺寸、带防呆设计的连接器，比普通的杜邦线接口更牢固，适合在成品中反复插拔。电池盒的线序通常是红色为正极，黑色为负极，与CPX上的电源接口对应。
• 物理开关的必要性：雪花球作为一个摆件，不可能每次都插拔USB线来开关。一个物理开关是必须的。电池盒自带的拨动开关方便集成到外壳上。

2.3 容器与装饰：雪花球套件与素材

这是赋予项目“灵魂”的部分。专用的DIY雪花球套件（直径108mm）比随便找一个玻璃罐要好得多。

• 专业设计：套件通常包含一个带螺纹的平顶盖和一个按压式橡胶塞。平顶盖为内部电子元件提供了稳定的安装平面，橡胶塞则用于密封并固定内部的人偶。
• 液体配方：使用蒸馏水是为了防止水垢和微生物滋生，保持长期清澈。添加甘油是关键一步，它能增加液体粘度，让亮片（ glitter ）下落速度变慢，模拟雪花飘落的悠扬感。比例通常是水与甘油约10:1，你可以通过实验调整到你喜欢的“飘雪”速度。
• 人偶选择：任何防水的小物件都可以。乐高小人、树脂模型、甚至一个精心涂装的3D打印模型都是不错的选择。核心是底部要有足够的平面，以便用胶水牢固地粘在橡胶塞上。

2.4 粘接与固定材料

电子部分和装饰部分的固定，选择了不同的材料，这是出于对强度、减震和可维修性的考虑。

• E6000或类似多功能胶：用于粘接人偶与橡胶塞，以及密封橡胶塞与瓶口。这种胶固化后具有柔韧性，能耐受一定程度的晃动和温差变化，且防水性好。切勿使用502这类脆性瞬间胶，震动容易开裂导致漏水。
• 双面泡沫胶带：用于固定电池盒到顶盖以及CPX到顶盖。泡沫胶带具有厚度和弹性，能起到缓冲减震的作用，避免硬连接在摇晃时对电路板焊点造成应力。同时，它也提供了非永久性固定的可能，未来需要更换电池或维修时更容易拆卸。

3. 代码深度解析与实现逻辑

项目的代码是典型的“状态机”驱动模式，结构清晰。我们跳过简单的库导入和变量定义，直接深入核心函数和主循环。

3.1 摇晃检测的算法：不只是读一个值

检测“摇晃”听起来简单，但直接读取一次加速度值并判断是否超过阈值是非常不可靠的（容易受瞬时震动或放置不平的影响）。原代码采用了一种简易的滑动平均滤波法来提升稳定性。

# 在主循环中 x_total = 0 y_total = 0 z_total = 0 for count in range(10): # 进行10次采样 x, y, z = cpx.acceleration x_total = x_total + x y_total = y_total + y z_total = z_total + z time.sleep(0.001) # 短暂延迟，避免采样过快 # 计算10次采样的平均值 x_avg = x_total / 10 y_avg = y_total / 10 z_avg = z_total / 10 # 计算合成加速度向量的大小 total_accel = math.sqrt(x_avg*x_avg + y_avg*y_avg + z_avg*z_avg)

为什么要这么做？

1. 滤波降噪：连续采样10次取平均，可以平滑掉传感器本身的微小噪声和偶然的抖动。
2. 计算矢量幅度：cpx.acceleration返回的是X, Y, Z三个方向上的分量。当雪花球静止时，它只受到重力（约9.8 m/s²）在一个方向上的作用。当被摇晃时，三个方向的分量会快速变化。计算矢量幅度sqrt(x² + y² + z²)可以得到设备所受总加速度的大小。在静止状态下，这个值应接近重力加速度。剧烈摇晃时，该值会显著增大。
3. 阈值判断：代码中设定ROLL_THRESHOLD = 30。这个30的单位是m/s²。为什么是30？这大致是重力加速度的3倍。通过实验，这个值能较好地区分“拿起来移动”和“故意摇晃”的动作。你可以根据自己摇晃的力度调整这个值，调低会更敏感，调高则需要更用力摇晃。

实操心得：time.sleep(0.001)这1毫秒的延迟很重要。如果没有它，for循环会以CPU全速运行，10次采样几乎在瞬间完成，失去了“在一小段时间内平均”的意义。这个延迟让采样间隔开，更能反映一段时间内的运动状态。

3.2 灯光动画函数：打造柔和的呼吸效果

fade_pixels函数是实现灯光渐亮渐暗（呼吸效果）的核心。它通过循环改变所有LED的整体亮度（brightness）来实现，而非逐个改变RGB值，效率更高。

def fade_pixels(fade_color): # 渐亮过程 for j in range(25): pixel_brightness = (j * 0.01) # 从0线性增加到0.24 cpx.pixels.brightness = pixel_brightness for i in range(10): cpx.pixels[i] = fade_color # 将所有LED设置为目标颜色 # 渐暗过程 for k in range(25): pixel_brightness = (0.25 - (k * 0.01)) # 从0.25线性减少到0.01 cpx.pixels.brightness = pixel_brightness for i in range(10): cpx.pixels[i] = fade_color

代码细节剖析：

• 亮度与颜色分离：NeoPixel库允许分别设置颜色（cpx.pixels[i] = (R,G,B)）和整体亮度（cpx.pixels.brightness）。亮度是一个0.0到1.0之间的浮点数。这种方式在创建平滑的淡入淡出效果时，比直接计算并设置每个颜色通道的值要简单高效得多。
• 范围选择：循环range(25)，亮度步进为0.01，因此最大亮度是0.24。为什么不调到1.0？一是因为CPX的LED在最高亮度下非常刺眼，不适合作为氛围灯；二是为了省电。0.24的亮度在装有水和亮片的雪花球内部，漫反射效果已经足够好。
• 双循环结构：外层循环（j/k）控制亮度等级，内层循环（i）遍历所有10个LED。在每次亮度改变后，都需要重新为所有LED设置一次颜色。这是因为brightness属性是一个全局乘数，在改变亮度后，需要“应用”颜色的操作来生效。

3.3 音乐播放函数：将乐谱转换为代码

play_song函数展示了一种优雅的将音乐编码到程序中的方法。它没有使用复杂的MIDI库，而是用最基础的数组和频率定义来实现。

def play_song(song_number): whole_note = 1.5 # 基准节拍，调整此处可改变整首曲子速度 quarter_note = whole_note / 4 dotted_quarter_note = quarter_note * 1.5 eighth_note = whole_note / 8 # 定义音符频率 C4 = 262 D4 = 294 E4 = 330 G4 = 392 # ... 其他音符 if song_number == 1: jingle_bells_song = [ [E4, quarter_note], [E4, quarter_note], [E4, half_note], # ... 后续音符 ] for note, duration in jingle_bells_song: cpx.start_tone(note) time.sleep(duration) cpx.stop_tone()

设计亮点：

1. 变量定义节拍：通过一个whole_note变量定义全音符的时长，其他音符时长都基于它计算。这意味着你只需要修改whole_note的值（比如从1.5改为1.2），整首曲子的演奏速度就会同步改变，无需逐个修改每个音符的休眠时间。
2. 二维数组存储乐谱：每个音符用一个[频率, 时长]的小数组表示，整首曲子就是这些小组组成的列表。这种结构极其清晰，易于阅读和修改。你可以像读简谱一样对照着修改这个数组来编曲。
3. 使用for note, duration in song:进行迭代：这是Python中非常简洁的元组解包写法，直接在一个循环里获取音符和时长，代码可读性比使用索引（如song[n][0]）高很多。

避坑指南：cpx.start_tone()会占用处理器。在播放一个长音时，如果主循环检测摇晃的代码被阻塞，就会导致交互不灵敏。原代码将播放歌曲放在摇晃检测之后、状态切换时执行，这是一个好的设计。但如果你设计的灯光动画很长，也要注意避免使用长时间的time.sleep，可以考虑用状态机和时间戳来管理非阻塞的动画。

3.4 主循环状态机：协调一切的核心逻辑

这是整个项目的“指挥官”。它管理着“静止”、“检测到摇晃”、“播放中”等多个状态之间的切换。

rolling = False # 当前是否处于“雪花飘落”状态 new_roll = False # 是否刚刚结束了一次摇晃（用于触发歌曲播放） while True: # 1. 计算当前加速度（经过滤波） total_accel = compute_acceleration() # 此处为示意，实际是前面那段滤波代码 # 2. 状态转移：检测到剧烈摇晃，进入“滚动”状态 if total_accel > ROLL_THRESHOLD: roll_start_time = time.monotonic() # 记录状态开始时间 new_roll = True # 标记这是一个新的摇晃动作 rolling = True # 进入“雪花飘落”展示状态 # 3. 状态维持：“雪花飘落”状态持续一段时间（如2秒） if new_roll: if time.monotonic() - roll_start_time > 2: rolling = False # 2秒后，结束“飘落”状态 # 4. 状态输出： # a) 如果处于“飘落”状态，执行灯光秀 if rolling: fade_pixels(SKYBLUE) fade_pixels(WHITE) cpx.pixels.fill(WHITE) # b) 如果刚刚结束“飘落”状态（new_roll为True但rolling已变为False），播放歌曲并回归待机 elif new_roll: new_roll = False # 重置标志位 play_song(2) # 播放第二首歌 fade_pixels(GREEN) # 渐变为绿色待机状态 cpx.pixels.fill(GREEN)

状态机解读：

• rolling：核心状态标志。为True时，意味着用户正在摇晃或刚刚摇完，系统应该执行“雪花飘落”的灯光秀。
• new_roll：边缘触发标志。它记录了一次“摇晃事件”的发生。用于在rolling状态结束后，准确地触发一次“播放歌曲并回归待机”的动作，且仅触发一次。
• 使用时间戳：time.monotonic()获取一个单调递增的时间（不受系统时间调整影响），用于精确控制rolling状态的持续时间（2秒）。这比用循环计数更可靠。

这种清晰的状态分离，使得灯光秀和歌曲播放这两个相对耗时的任务能够有序进行，不会互相干扰，也确保了交互响应的即时性。

4. 硬件组装与密封工艺详解

代码烧录测试无误后，硬件组装是决定项目成败和寿命的关键。这一步需要耐心和细致。

4.1 电路部分安装

1. 电池盒处理：用螺丝刀卸下电池盒背面的腰带夹。我们的目标是将电池盒平整地粘贴在顶盖外侧。用双面泡沫胶将电池盒粘在顶盖中央，确保开关部分悬空在顶盖边缘之外，以便后续操作。粘贴前，用酒精棉片清洁顶盖粘贴位置，去除油污。
2. 开孔走线：将电池盒的JST插头线穿过顶盖。你需要用笔在顶盖上标记出线缆位置，然后使用小电钻或尖锐的手工刀，小心地开一个刚好能让插头穿过的孔。孔不宜过大，以免影响密封和美观。
3. 固定CPX：将CPX的电源接口与电池盒插头连接。同样使用双面泡沫胶，将CPX粘贴在顶盖内侧的中心位置。粘贴时注意方向，确保板载的麦克风、光线传感器等（如果你未来想扩展功能）不被遮挡，且USB接口朝向便于后期更新的方向（通常朝向顶盖边缘）。按压牢固，确保连接线不会绷得太紧。

4.2 液体配制与人偶密封

这是最具“手艺活”特色的一步，直接关系到视觉效果和长期可靠性。

1. 配制“雪花液”：在干净的容器中，先倒入蒸馏水至雪花球容积的90%左右。然后加入甘油，比例建议从水:甘油=10:1开始尝试。充分搅拌使其混合。接着加入亮片，用量取决于你想要的“雪密度”，建议先少加，通过摇晃观察效果再酌情添加。记住一个原则：液体总量不要超过雪花球容积的95%，必须为插入人偶和塞子预留空间。
2. 人偶与橡胶塞的粘接：
   • 使用E6000这类柔性粘合剂。在人偶的底部和橡胶塞的顶部都薄薄地、均匀地涂上一层胶。
   • 将两者对准按压在一起，并保持按压约一分钟初步固定。
   • 至关重要的一步：将粘好人偶的塞子放在一边，静置至少24小时，让胶水完全固化。切勿急于进行下一步，否则在插入水中时，未固化的胶水可能失效导致人偶脱落。
3. 灌装与最终密封：
   • 将配制好的“雪花液”小心倒入雪花球主体。最好使用漏斗，避免洒出。
   • 在水池或大盆上方操作！拿起已固化的人偶塞子，将其缓慢、垂直地插入瓶口。随着塞子深入，液体会被排出。你需要控制下压的速度和力度，目标是让塞子完全压入后，液体刚好充满整个球体，顶部不留或只留极少气泡。如果气泡过大，可以用滴管吸出一些液体再补充。
   • 塞子就位后，用纸巾擦干瓶口和塞子边缘的水分。
   • 在橡胶塞的侧面圆周和与瓶口的接触面上，再涂上一圈薄薄的E6000胶水。这步是二次防水密封。同样，静置24小时让密封胶完全固化。
4. 最终组装：确认密封胶干透且无漏水后，将已经安装好CPX和电池盒的顶盖拧到雪花球主体上。拧紧即可，不必过度用力，以免压裂塑料螺纹。

5. 调试优化与常见问题排查

即使完全按照教程操作，你也可能会遇到一些小问题。这里总结了一份常见问题排查清单和我的优化建议。

5.1 功能调试清单

5.2 个性化优化建议

1. 自定义灯光效果：原代码的灯光秀是“天蓝渐亮 -> 白渐亮 -> 常亮白”。你可以修改fade_pixels的调用顺序、颜色和次数。例如，可以创建一个颜色列表，让LED轮流显示不同颜色，模拟五彩斑斓的雪花。

   colors = [SKYBLUE, WHITE, (100, 100, 255), (200, 200, 255)] # 添加淡紫色等 if rolling: for color in colors: fade_pixels(color)

2. 增加更多歌曲：在play_song函数中增加song_number == 3、4等分支，定义新的歌曲数组。你甚至可以从简单的《欢乐颂》或《生日快乐歌》开始。
3. 利用其他传感器：CPX还自带光线传感器和温度传感器。你可以让雪花球在环境光变暗时自动进入低亮度睡眠模式，或者根据温度改变灯光的颜色（冷色调/暖色调）。
4. 优化功耗：如果希望电池更耐用，可以在待机状态（绿色常亮）时进一步降低亮度，比如将cpx.pixels.brightness从0.05调到0.02。甚至可以在长时间无操作后，用cpx.pixels.fill((0,0,0))关闭所有LED，仅通过敲击（利用加速度计检测短促冲击）来唤醒。

这个项目最吸引我的地方在于，它用一个具体的、有趣的实物，把嵌入式开发中那些抽象的概念——传感器采样、事件驱动、状态机、非阻塞任务管理——都生动地展现了出来。当你亲手摇动它，看到灯光随之舞动，听到音乐响起时，你对代码和硬件之间联系的理解会变得更加深刻。希望你在复现和改造它的过程中，也能获得同样的乐趣和成就感。