基于CircuitPython的声控灯光系统：从信号采集到NeoPixel实时响应

1. 项目概述：当经典玩具遇上可编程灯光

几年前，当我把Nintendo Labo的钢琴Toy-Con拼装好，看着孩子敲击那些硬纸板琴键发出电子音时，我就在想，如果能加上一些视觉反馈，这体验会不会更棒？Labo本身的设计哲学就是“制作、游玩、探索”，而为其添加自定义的声控灯光效果，正是将“探索”这一步推向深入的绝佳实践。这不只是一个简单的DIY，它触及了嵌入式开发中几个非常核心的概念：如何从物理世界（声音）采集模拟信号，如何通过代码处理这些信号以滤除噪声并提取有用信息，以及如何根据处理结果实时驱动执行器（LED灯带）做出响应。

这个项目的核心硬件是Adafruit的Circuit Playground Express开发板。我选择它，是因为它几乎是为教育和快速原型量身定制的：板载了10个可编程的RGB NeoPixel LED、一个运动传感器、多个触摸感应点，并且原生支持CircuitPython。CircuitPython是MicroPython的一个分支，其最大优势在于将开发板呈现为一个U盘，你可以直接用文本编辑器修改code.py文件，保存后代码立即运行，这种“所见即所得”的迭代速度，对于创意项目和教学来说是无价的。为了更精准地捕捉钢琴扬声器发出的声音，我们额外引入了一个Electret麦克风放大器模块。这是因为开发板自带的麦克风位置固定，而我们需要将拾音器尽可能靠近声源，以获得更清晰、干扰更少的信号。

整个项目的逻辑链条非常清晰：麦克风将声音的振动转化为连续的电压信号（模拟量），开发板上的模拟-数字转换器（ADC）将这个连续信号“采样”成一连串的数字，我们的代码则负责解读这些数字，判断声音的强弱，最终映射成LED灯的颜色和亮度。下面，我们就从硬件连接开始，一步步拆解这个让纸钢琴“光彩照人”的过程。

1.1 核心硬件选型与作用解析

工欲善其事，必先利其器。在这个项目里，每一件硬件都有其不可替代的角色，理解它们的作用，能帮助你在后续连接和调试时心里更有底。

Circuit Playground Express (CPX)：这是项目的大脑和视觉输出中心。它基于ATSAMD21微控制器，运行CircuitPython解释器。板载的10个NeoPixel LED是我们灯光效果的载体，每个LED都可以独立控制红、绿、蓝三色的亮度（每色8位，即256级亮度），这意味着它们可以组合出超过1600万种颜色。板子通过Micro USB接口供电和编程，也支持通过JST PH接口连接3.7V锂聚合物电池进行移动供电，这为我们把整个系统集成到Labo钢琴上提供了可能。

Electret麦克风放大器模块：这是项目的“耳朵”。为什么不用板载麦克风？原因有两个：一是位置，我们需要把麦克风贴在Nintendo Switch的扬声器附近，而CPX板需要放在钢琴顶部展示灯光，两者必须分离；二是信号质量，这个放大器模块对微弱的音频信号进行了预放大和调理，输出一个更“干净”、幅度更适合ADC读取的模拟电压信号。模块上通常有一个可调电阻，用于调节增益（灵敏度），在这个项目中，我们一般将其调到中间位置即可。

硅胶被覆绞合线：我强烈推荐使用这种线材，而不是单芯线。在项目里，我们需要三根约30厘米长的线来连接CPX和麦克风模块。硅胶外皮柔韧性极好，耐弯折，非常适合这种需要在小空间内布线、且可能被反复移动的场景。红、白、蓝三种颜色用于区分电源（3.3V）、信号（A7）和地（GND），能极大降低接错线的风险。如果你手头只有单芯线，也可以使用，但要注意避免在弯折处反复受力导致断裂。

3.7V锂聚合物电池：这是项目的移动能量站。CPX的工作电压范围是3.3V-5V，一块标称容量在350mAh到500mAh的电池，足以让灯光系统持续工作数小时。选择电池时，除了容量，更要关注其放电倍率（C数），对于这种低功耗的LED应用，任何标准的3.7V LiPo电池都绰绰有余。安全提醒：务必使用带有保护板的电池，并避免过充、过放或短路。

焊接工具：一个温度可控的烙铁（建议设置在320°C-350°C）、焊锡丝和助焊剂是必备的。你还需要一把尖嘴钳或镊子来固定导线，以及一块“第三只手”工具来固定电路板，这会让焊接过程安全轻松很多。

2. 硬件连接：从焊接开始构建可靠链路

硬件连接是项目的地基，稳固与否直接决定了后续软件调试的难度。这一步的核心目标是：在Circuit Playground Express和麦克风放大器之间，建立三条可靠、绝缘良好的电气连接。

2.1 导线准备与预处理

首先，截取红、白、蓝三种颜色的硅胶线各约30厘米。这个长度经过实测，足以从Labo钢琴内部的Switch扬声器附近，宽松地布线至顶部的CPX板，并留有余量。长度宁长勿短，因为多余的线可以整齐地盘绕或隐藏，但线太短会导致安装时拉扯，增加焊点脱落的风险。

用剥线钳剥去每根线两端约7毫米的绝缘皮。这里有个细节：硅胶皮非常柔韧，用普通的剥线钳可能不太容易切断，你可以先用刀片轻轻环切外皮（切勿伤到内部金属丝），再用手拧下。露出内部的金属绞合线后，你会看到很多细小的铜丝。下一步至关重要：上锡。用烙铁加热裸露的铜丝，同时将焊锡丝送上去，让熔化的焊锡充分浸润每一根铜丝。这个过程称为“搪锡”或“预上锡”。它的目的有两个：一是将多股散乱的铜丝整合成一根牢固的、易于焊接的“金属棒”，防止个别铜丝散开造成短路；二是让焊点本身更易于形成，因为已经上锡的导线和焊盘更容易被熔化的焊锡“润湿”。

实操心得：给绞合线上锡时，烙铁头温度可以稍高一点（比如350°C），并配合使用少量助焊剂（松香芯焊锡丝自带助焊剂通常足够）。将烙铁头压在铜丝上，等待1-2秒，看到铜丝被加热到足以熔化焊锡时，再从侧面送入焊锡丝。确保焊锡完全包裹住所有铜丝，形成一个光滑、圆锥形的焊点，没有尖刺或毛糙。

2.2 焊接至Circuit Playground Express

CPX板边缘有一圈巨大的、带孔的焊盘，这正是为这种外部连接设计的。我们需要将三根线焊接到三个特定的焊盘上：

• 红色线 -> 3.3V Pad：这是电源输出端，为麦克风放大器提供3.3伏的工作电压。
• 蓝色线 -> GND Pad：这是公共地线，为整个电路建立共同的电压参考点。
• 白色线 -> A7 Pad：这是模拟信号输入口，麦克风放大后的音频电压信号将通过这根线传入。

焊接步骤：

1. 定位：在板子上找到标有“3.3V”、“GND”和“A7”的焊盘。它们通常分布在板子边缘的不同位置。
2. 穿线：将已经上好锡的线端，从电路板正面（有元件和LED的一面）穿过对应的焊盘孔。
3. 固定：将穿过孔的导线在焊盘背面弯折大约90度，勾住焊盘。这个小小的机械固定，可以在你焊接时防止导线移动，也能分担一部分焊点所受的应力。
4. 焊接：用烙铁头同时加热焊盘和导线，约1-2秒后，送入焊锡丝。焊锡应流畅地包裹住焊盘和导线，形成一个光滑、呈小山丘状的焊点。焊点应明亮有光泽，而不是灰暗粗糙的。
5. 检查：焊接完成后，轻轻拉扯导线，确认焊接牢固。用放大镜检查焊点，确保没有与相邻焊盘发生桥接（短路）。

2.3 焊接至麦克风放大器模块

麦克风放大器模块通常更小巧，焊盘间距更近，需要更精细的操作。模块上一般有三个焊盘：V+（或VCC）、GND和Out（或AUD）。

• 红色线 -> V+：连接来自CPX的3.3V电源。
• 蓝色线 -> GND：连接回CPX的地线，形成回路。
• 白色线 -> Out：这是信号输出端，将放大后的音频信号送至CPX的A7引脚。

焊接方法与在CPX上类似：穿线、弯折固定、焊接。但由于模块焊盘小，要特别注意：

• 使用更细的焊锡丝（如0.8mm）。
• 烙铁头最好用尖头或刀头，以便精确加热。
• 焊接时间不宜过长，避免过热损坏麦克风元件。
• 焊接完成后，务必用斜口钳或剪线钳，紧贴着焊点剪掉多余的线头。这些裸露的金属线头如果相互触碰，会导致短路，可能烧毁模块或CPX。

完成两边焊接后，你可以将三根线松散地编成辫子，这不仅能显得整洁，也能减少线材在移动中的相互摩擦和缠绕。至此，硬件连接部分全部完成。在通电前，我强烈建议用万用表的通断档，快速检查一下：红-红、蓝-蓝是否导通？红-蓝、红-白、蓝-白之间是否绝缘（不导通）？这能排除最致命的短路和断路问题。

3. 软件编程：用CircuitPython解读声音

硬件是躯干，软件才是灵魂。接下来，我们要让CPX“听懂”声音，并指挥NeoPixel做出反应。整个过程无需复杂的编译环境，只需一个文本编辑器。

3.1 环境准备与库安装

首先，用Micro USB线将CPX连接到电脑。如果这是你第一次使用这块板子，你需要先将其刷写成CircuitPython固件。从 CircuitPython官网 下载对应板型的最新.uf2固件文件。按住CPX板上的“Reset”按钮，然后快速双击它，此时板子上的所有LED会变成红色，电脑上会出现一个名为CPLAYBOOT的U盘。将下载的.uf2文件拖入这个U盘，板子会自动重启。之后，电脑上就会出现一个名为CIRCUITPY的新U盘，这表示CircuitPython系统已经运行起来了。

接下来安装必要的库。我们的代码需要用到neopixel库来控制LED。访问 Adafruit的CircuitPython库包页面 ，下载与你的CircuitPython版本匹配的库包。解压后，找到lib文件夹里的neopixel.mpy文件，将其复制到CIRCUITPY盘符下的lib文件夹中（如果不存在就新建一个）。这就是CircuitPython安装库的全部过程——简单得像复制文件。

3.2 核心代码逐行解析

现在，在电脑上创建一个纯文本文件，将下面的代码粘贴进去。我强烈建议使用专为编程设计的编辑器，如Mu Editor（它内置了CircuitPython模式，能高亮语法并直接保存到CIRCUITPY盘）或VS Code。将文件保存到CIRCUITPY盘的根目录下，并命名为code.py。一旦保存，CPX会自动重启并运行新代码。

# SPDX-FileCopyrightText: 2018 Collin Cunningham for Adafruit Industries # SPDX-License-Identifier: MIT import board from rainbowio import colorwheel import neopixel from analogio import AnalogIn # ===== 用户可调参数 ===== n_pixels = 10 # 使用的像素数量，CPX是10 dc_offset = 0 # 麦克风信号中的直流偏移量，如果不确定就保持为0 noise = 100 # 麦克风信号中的噪声/干扰基底 lvl = 10 # 当前“阻尼化”后的音频电平值 maxbrt = 127 # NeoPixel的最大亮度 (0-255) wheelStart = 0 # 使用的RGB光谱起始值 (0-255) wheelEnd = 255 # 使用的RGB光谱结束值 (0-255) # ======================== mic_pin = AnalogIn(board.A7) # 指定模拟信号从A7引脚读取 # 初始化NeoPixel，亮度设为10%，并关闭所有灯 strip = neopixel.NeoPixel(board.NEOPIXEL, n_pixels, brightness=0.1, auto_write=False) strip.fill(0) strip.show() def remapRangeSafe(value, leftMin, leftMax, rightMin, rightMax): # 这个函数将一个值从一个区间（左）安全地重新映射到另一个区间（右） # 1. 将输入值强制限制在左区间内 if value < leftMin: value = leftMin if value > leftMax: value = leftMax # 2. 计算每个区间的“宽度” leftSpan = leftMax - leftMin rightSpan = rightMax - rightMin # 3. 将左区间转换为一个0-1之间的比例值（浮点数） valueScaled = (value - leftMin) / leftSpan # 4. 将这个比例值转换为右区间内的一个值 return rightMin + (valueScaled * rightSpan) # 主循环 while True: # 1. 读取原始音频数据 n = int((mic_pin.value / 65536) * 1000) # 将16位ADC值转换为0-1000范围的整数 # 2. 中心化处理：减去零点偏移（512是0-1000范围的中心点） n = abs(n - 512 - dc_offset) # 3. 噪声滤除：只有信号超过噪声阈值才被认为是有效声音 if n >= noise: n = n - noise else: n = 0 # 低于噪声阈值，信号视为0 # 4. 阻尼处理：平滑变化，避免灯光抖动过于频繁 # 公式: 新电平 = (旧电平 * 7 + 新采样值) / 8 # 这相当于一个简单的低通滤波器，当前值受历史值影响很大，变化更平滑 lvl = int(((lvl * 7) + n) / 8) # 5. 将处理后的音频电平映射到颜色 vlvl = remapRangeSafe(lvl, 0, 255, wheelStart, wheelEnd) for i in range(0, len(strip)): strip[i] = colorwheel(vlvl) # 所有LED显示同一彩虹色 # 6. 将音频电平映射到亮度 brightness = remapRangeSafe(lvl, 50, 255, 0, maxbrt) strip.brightness = float(brightness) / 255.0 # 亮度值需归一化到0.0-1.0 # 7. 更新显示 strip.show()

代码逻辑深度解析：

1. 信号读取 (mic_pin.value)：AnalogIn对象从A7引脚读取一个0到65535（16位）的整数值，对应0V到3.3V的电压。代码中(mic_pin.value / 65536) * 1000将其线性映射到0-1000的范围，纯粹是为了后续计算更直观。

2. 中心化与整流 (abs(n - 512 - dc_offset))：麦克风输出的信号是交流信号，以某个中间电压（约1.65V，对应数值512）为基准上下波动。减去512是为了得到以零为中心的波形。abs()函数取绝对值，将负半周的信号也翻转到正半周，这样我们只关心声音的“幅度”，而不关心其相位。dc_offset用于微调这个中心点，如果发现安静时灯光也常亮，可以尝试调整此值。

3. 噪声门限 (noise)：任何电子系统都有本底噪声。noise = 100这个阈值意味着，只有当信号强度超过这个基底时，我们才认为是有意义的声音。这能有效过滤掉环境嗡嗡声或电路本身的杂音。你可以通过后续的“测试与调优”环节来校准这个值。

4. 阻尼处理（低通滤波）：lvl = int(((lvl * 7) + n) / 8)是整段代码的精华所在。这是一个极其简洁但有效的一阶无限脉冲响应（IIR）低通滤波器。新计算出的信号值n只占最终结果lvl的1/8权重，而历史值lvl占了7/8。这带来的效果是：灯光对突然的、短暂的声音（比如拍手）反应迅速但不过激，而对持续的声音（比如音乐）能保持平滑的亮度变化，不会随着音频波形剧烈闪烁。调整公式中的系数（7和8），可以改变滤波的“强度”。系数越大，灯光变化越平滑，但延迟也越明显。

5. 双映射策略：

   • 颜色映射：将滤波后的lvl映射到wheelStart到wheelEnd的色轮值上，然后通过colorwheel()函数转换为RGB颜色。默认0-255覆盖了整个彩虹光谱。你可以修改wheelStart和wheelEnd来限定颜色变化的范围（例如，wheelStart=170, wheelEnd=255会得到从蓝到紫的渐变）。
   • 亮度映射：将lvl映射到0-maxbrt的亮度值。注意这里映射的输入区间是[50, 255]，这意味着只有当lvl大于50时，亮度才开始增加。这相当于第二个阈值，确保了在非常微弱的声音下，LED保持熄灭或微亮状态，提升视觉体验。maxbrt控制最大亮度，设为127（半亮）既能保证效果，又非常省电。

3.3 测试与初步调优

保存code.py后，拔掉USB线，接上锂电池。现在，试着用手指轻轻弹击或对着麦克风模块说话。你应该能看到NeoPixel随着声音亮起并变换颜色。

如果灯光反应不灵敏或一直常亮，你需要调整两个关键参数：

1. 调整noise值：在安静的环境下，观察CPX板上的LED。如果它们一直微微发亮，说明noise值设低了，需要提高（比如调到150）。如果用力拍手灯光反应也很弱，说明noise值设高了，需要降低。
2. 调整麦克风增益：麦克风放大器模块上的蓝色可调电阻就是增益电位器。用小螺丝刀缓慢旋转它，同时持续发出测试音（如哼唱）。找到一个点，使得灯光能对正常演奏音量有明确反应，但又不会因环境噪声而误触发。

实操心得：调试时，可以临时在代码的while True循环开头添加print(lvl)语句，并通过Mu Editor的串行监视器查看实时的lvl数值。这样你就能直观地看到安静时的噪声水平、拍手时的峰值，从而科学地设定noise和亮度映射区间，而不是盲目猜测。

4. 系统集成与安装：让Labo钢琴焕发新生

软件硬件都调试完毕后，最后一步就是将它们优雅地藏进Labo钢琴里，完成从原型到成品的蜕变。

4.1 麦克风的隐藏式安装

Labo钢琴的巧妙之处在于其内部空间。我们需要把麦克风模块尽可能贴近Nintendo Switch主机底部的扬声器格栅。

1. 轻轻向后推压支撑Switch的那个大纸板背板，直到其前端的卡扣舌片弹起、脱离。
2. 将背板稍微向前拉出一点，形成一个缝隙。把麦克风模块的银色咪头一面朝前（即朝向Switch扬声器），从侧面滑入这个缝隙，放置在背板与钢琴主体之间的空腔里。确保咪头没有被纸板完全遮挡。
3. 将连接麦克风的三根导线，顺着背板右侧的缝隙向上理线。你会发现在钢琴顶部右侧附近，有一个三角形的开口或通道，正好可以将导线引到钢琴顶部表面。

4.2 CPX与电池的固定

灯光效果需要被看到，所以CPX板必须安装在钢琴顶部显眼位置。

1. 用一小块双面泡棉胶，将锂电池粘贴在CPX板的背面（即没有元件的一面）。注意避开板子中央的复位按钮和JST电池接口。
2. 再用一块稍大的双面胶，将“CPX+电池”这个组合体，牢固地粘贴在钢琴顶部的平坦区域。位置建议靠后居中，这样既不影响放入和取出Switch，又能让10个LED的光效得到最佳展示。
3. 将麦克风引上来的导线与CPX上的导线对接（红对红，白对白，蓝对蓝）。可以用一小段电工胶布或扎带将接头处简单固定，防止被扯开。

4.3 最终调试与玩法

安装好右Joy-Con，放入Switch主机，将系统音量调到最大（以确保麦克风拾取到足够强的信号）。启动Labo Variety Kit中的钢琴演奏模式。

现在，当你按下纸板琴键，伴随着每一个音符，顶部的LED灯环就会流淌出相应的色彩和光晕。声音越大、越急促，灯光就越亮、颜色变化也越快；声音平缓时，灯光也会温柔地渐变。这完全是一个独一无二的、属于你自己的Labo钢琴Plus版本。

重要注意事项：出于安全和使用寿命考虑，长时间不玩时，务必断开锂电池与CPX板JST接口的连接。CircuitPython板在即使程序不运行的情况下，也可能存在微小的待机电流，长期连接会导致电池过放损坏。同时，避免将钢琴长时间放置在阳光直射或高温环境中，以防锂电池和纸模型受损。

这个项目成功地桥接了物理建造与软件编程、音频信号与视觉反馈。它所用的技术——模拟信号采集、数字滤波、实时映射——是无数物联网设备、交互式艺术装置和智能玩具的基石。你可以基于这个框架进行无限扩展：比如，将声音频率（而不仅仅是幅度）映射到不同的LED上，实现频谱可视化；或者加入板载的加速度计，让灯光随着钢琴的晃动而摇摆。希望这次深入的拆解，能为你打开一扇通往软硬件互动世界的大门。