基于CircuitPython与BLE的无线RGB调色器：从模拟信号到无线控制
1. 项目概述与核心思路
如果你玩过Arduino或者树莓派，可能会觉得无线通信和硬件交互是个挺复杂的事儿，动不动就得折腾一堆库和协议。但今天这个项目，我想分享一个特别“清爽”的玩法：用两块Adafruit的Circuit Playground Bluefruit开发板，加上三个滑动变阻器，做一个完全无线的RGB调色器。你在这边滑动电位器，那边的LED灯环就会实时变换颜色，中间没有一根线连着，全靠蓝牙低功耗（BLE）通信。
这个项目的魅力在于它的“完整性”和“可触达性”。它不是一个简单的点灯实验，而是融合了模拟信号采集（电位器）、无线数据传输（BLE）、以及执行器控制（NeoPixel）的一个微型物联网系统原型。更棒的是，得益于CircuitPython和Adafruit完善的生态库，整个开发过程异常简单，你几乎不用去深究蓝牙协议栈的细节，就能把功能跑起来。这对于想快速验证想法、制作互动装置或者学习无线传感网入门的朋友来说，是个绝佳的起点。
我选择Circuit Playground Bluefruit（后面简称CPB）作为核心，是因为它本身就是一个高度集成的学习平台，板载了加速度计、麦克风、温度传感器、按钮和最重要的——10颗可编程的RGB NeoPixel LED以及一个BLE芯片。这意味着我们不需要额外焊接任何LED或无线模块，大大降低了硬件门槛。整个系统的逻辑很清晰：一块CPB作为“中央设备”（Central），负责读取三个电位器的电压值，将其转换为RGB颜色数据，然后通过BLE发送出去；另一块CPB作为“外设设备”（Peripheral），持续广播自己的存在，等待连接，一旦收到颜色数据包，就立刻驱动自己的NeoPixel灯环显示对应的颜色。
2. 硬件选型与电路设计解析
2.1 核心控制器：为什么是Circuit Playground Bluefruit？
市面上能跑CircuitPython并支持BLE的开发板不少，比如ItsyBitsy nRF52840、CLUE等。但CPB在这个项目中有几个不可替代的优势。首先，它板载了10颗NeoPixel，我们无需为了显示端额外接线。其次，它的引脚布局清晰，特别是将多个模拟输入引脚（A1-A7）集中在一侧，方便我们连接多个电位器。最重要的是，Adafruit为其提供了高度封装的adafruit_ble和adafruit_bluefruit_connect库，使得BLE通信就像读写串口一样简单，这对于快速原型开发至关重要。
关于供电，CPB支持多种方式：通过USB口供电、连接3.7V锂电池，或者使用3节AAA电池盒。在无线项目中，移动性很重要，所以我强烈推荐使用锂电池供电，它体积小、重量轻，能让你的调色器真正“无线”起来。两块板子各配一块电池，整个系统就完全独立了。
2.2 输入设备：滑动电位器的考量与连接原理
为什么选择滑动电位器（Slider Potentiometer）而不是旋转电位器？核心原因是用户体验和视觉反馈。滑动电位器的滑块位置直观地代表了当前数值的大小，你可以一眼看出红、绿、蓝三个通道各自的“分量”，混合颜色时更有“调音台”的操作感。我们选用的这款35mm长的滑阻，其引脚间距完美匹配面包板，省去了焊接或扩展板的麻烦。
从电路原理上讲，我们这里将每个滑动电位器连接成一个分压电路。具体接法如下：
- Pin 1（左侧引脚）：接3.3V电源（VCC）。这是电压输入端。
- Pin 3（右侧引脚）：接电源地（GND）。这是参考地。
- Pin 2（中间引脚）：接CPB的模拟输入引脚（A4, A5, A6）。这是滑动抽头（Wiper）。
当滑块移动时，抽头Pin 2与两端引脚之间的电阻比例发生变化，从而在Pin 2上产生一个在0V到3.3V之间变化的电压。CPB内部的模数转换器（ADC）会读取这个电压值，并将其量化为一个0到65535之间的数字（因为CPB的ADC是16位的）。这个数字就对应了颜色值从0到255的强度。三个电位器分别对应R（红）、G（绿）、B（蓝）三个通道。
注意：关于电位器阻值教程中选用的是10KΩ电位器。这个阻值是一个很好的折中选择。阻值太小（如100Ω），在分压时会从电源消耗较大电流；阻值太大（如1MΩ），模拟输入引脚的高输入阻抗可能会使其更容易受到环境噪声干扰，导致读数不稳定。10KΩ在功耗和抗噪性上取得了良好平衡。
2.3 电路搭建实战与布线技巧
虽然教程图示很清晰，但在实际面包板上搭建时，有几个细节能让你事半功倍：
规划布局：先将三个滑动电位器并排插入面包板，确保它们之间留有空行，并且所有电位器的Pin 3（接地脚）都对齐在同一列，并插入标有蓝色“-”号的负极电源轨。这样，我们只需要用一根跳线将整个负极轨连接到CPB的GND，就完成了三个电位器的接地。
供电总线：用另一根跳线，将面包板标有红色“+”号的正极电源轨连接到CPB的3.3V引脚。然后，用三根短的“订书钉”式跳线，分别将每个电位器的Pin 1连接到这个正极轨。这样就建立了统一的3.3V供电。
信号线连接：这是关键。使用杜邦线或教程推荐的鳄鱼夹转杜邦头线，连接电位器的信号端（Pin 2）到CPB。
- 黄色线：连接最左边电位器的Pin 2 到 CPB的A4引脚（对应代码中的红色通道）。
- 绿色线：连接中间电位器的Pin 2 到 CPB的A5引脚（对应绿色通道）。
- 蓝色线：连接最右边电位器的Pin 2 到 CPB的A6引脚（对应蓝色通道）。
- 这种颜色对应（黄-红、绿-绿、蓝-蓝）的接线规则，在后期调试时能让你快速定位问题。
电源检查：在通电前，务必用万用表通断档或电压档快速检查一下：确保任何一根信号线（黄、绿、蓝）没有直接短路到电源（3.3V）或地（GND）。否则可能损坏CPB的模拟输入引脚。
3. 软件环境配置与代码深度剖析
3.1 CircuitPython固件与库的部署要点
首先，确保你的两块CPB都刷入了最新的CircuitPython固件。从circuitpython.org下载对应板型的.uf2文件。刷写过程很简单：用数据线连接CPB和电脑，快速双击板子中央的复位按钮，直到LED灯环变绿并出现一个名为CPLAYBTBOOT的U盘，把.uf2文件拖进去即可。完成后会出现一个CIRCUITPY盘符。
踩坑记录：USB数据线这里最容易出问题的是USB线。很多人手头只有充电线，它只能供电不能传输数据。务必使用一条“已知良好”的数据线。如果双击复位后灯环只变红不变绿，或者
CPLAYBTBOOT盘符不出现，第一个要怀疑的就是数据线。
接下来是库文件的安装。你需要从Adafruit的CircuitPython库包中，找到并复制以下三个.mpy文件到CPB的CIRCUITPY盘符下的/lib文件夹中：
neopixel.mpy：用于控制板载的NeoPixel LED。adafruit_ble：提供蓝牙低功耗通信的核心功能。adafruit_bluefruit_connect：这是Adafruit的“黑魔法”库，它定义了一套像ColorPacket这样的高级数据包，让你无需处理原始的字节流，就能在设备间发送颜色、按钮、加速度等标准化的信息。
3.2 中央设备（发送端）代码解读
中央设备的代码（我们保存为code.py）是调色器的“大脑”。它的核心任务就是循环读取三个模拟引脚的值，打包成颜色数据，并通过BLE发送出去。
# SPDX-FileCopyrightText: 2019 John Edgar Park for Adafruit Industries # SPDX-License-Identifier: MIT """ 中央设备：连接到一个BLE UART外设，读取三个电位器，发送ColorPacket数据包。 """ import time import board from analogio import AnalogIn from adafruit_bluefruit_connect.color_packet import ColorPacket # 导入颜色包类 from adafruit_ble import BLERadio from adafruit_ble.advertising.standard import ProvideServicesAdvertisement from adafruit_ble.services.nordic import UARTService def scale(value): """将0-65535（模拟输入范围）的值缩放至0-255（RGB范围）""" return int(value / 65535 * 255) # 初始化BLE无线电和模拟输入 ble = BLERadio() a4 = AnalogIn(board.A4) # 红色通道 a5 = AnalogIn(board.A5) # 绿色通道 a6 = AnalogIn(board.A6) # 蓝色通道 uart_connection = None # 启动后先检查是否已有连接（例如从之前的运行中恢复） if ble.connected: for connection in ble.connections: if UARTService in connection: uart_connection = connection break while True: # 如果没有连接，则开始扫描寻找提供UART服务的外设 if not uart_connection: print("正在扫描外设...") for adv in ble.start_scan(ProvideServicesAdvertisement, timeout=5): if UARTService in adv.services: print("找到外设，尝试连接...") uart_connection = ble.connect(adv) break ble.stop_scan() # 无论是否找到，停止扫描以省电 # 如果已连接，则持续读取并发送数据 while uart_connection and uart_connection.connected: r = scale(a4.value) g = scale(a5.value) b = scale(a6.value) color = (r, g, b) print("RGB:", color) # 在串口监视器中查看实时值 color_packet = ColorPacket(color) # 创建颜色数据包 try: # 通过UART服务写入数据包（底层是BLE） uart_connection[UARTService].write(color_packet.to_bytes()) except OSError: # 如果写入失败（如连接断开），忽略错误，外层循环会重连 pass time.sleep(0.3) # 控制发送频率，避免过快关键逻辑解析：
- 连接管理：代码采用了“扫描-连接-保持”的稳健策略。它先扫描5秒，寻找任何广播
UARTService的设备（即我们的外设CPB）。找到后建立连接并存储连接对象。在连接状态下，如果因为距离过远等原因断开，uart_connection.connected会变为False，从而跳出内层while循环，回到外层重新开始扫描。这保证了系统的自恢复能力。 - 数据缩放：
scale()函数至关重要。CPB的ADC读数是16位（0-65535），而RGB每个通道是8位（0-255）。这个函数通过一个简单的线性映射完成转换。int()确保了结果是整数。 - 数据包封装：
adafruit_bluefruit_connect库的妙处就在这里。我们不需要自己定义数据格式。只需创建一个ColorPacket对象，传入(r, g, b)元组，然后调用to_bytes()，库就会按照Adafruit定义好的协议将其转换为二进制流。接收端只要用同样的库，就能自动解析出颜色。 - 发送频率：
time.sleep(0.3)设置了约每秒发送3次数据的频率。这个值需要权衡：太快会浪费电量并可能造成数据拥塞；太慢则颜色更新会有明显延迟。0.3秒是一个在流畅性和功耗间取得平衡的经验值。
3.3 外设设备（接收端）代码解读
外设设备的代码（同样保存为code.py）相对更简单，它的核心是持续广播并等待连接，然后解析收到的数据包并驱动LED。
# SPDX-FileCopyrightText: 2019 John Edgar Park for Adafruit Industries # SPDX-License-Identifier: MIT """ 外设设备：广播UART服务，接收来自中央设备的ColorPacket，并用NeoPixel显示颜色历史。 """ import board import neopixel from adafruit_ble import BLERadio from adafruit_ble.advertising.standard import ProvideServicesAdvertisement from adafruit_ble.services.nordic import UARTService from adafruit_bluefruit_connect.packet import Packet from adafruit_bluefruit_connect.color_packet import ColorPacket # 初始化BLE、UART服务和NeoPixel ble = BLERadio() uart = UARTService() advertisement = ProvideServicesAdvertisement(uart) NUM_PIXELS = 10 np = neopixel.NeoPixel(board.NEOPIXEL, NUM_PIXELS, brightness=0.1) # 亮度设低点保护眼睛 next_pixel = 0 # 用于记录下一个要点亮的LED索引 def mod(i): """将索引i循环映射到0-9的范围内。""" return i % NUM_PIXELS while True: # 在未连接时持续广播 print("正在广播，等待连接...") ble.start_advertising(advertisement) while not ble.connected: pass # 阻塞等待，直到有中央设备连接 print("已连接！") # 连接后，持续监听数据流 while ble.connected: # 从UART流中尝试解析数据包 packet = Packet.from_stream(uart) if packet is None: continue # 没有收到完整数据包，继续循环 # 检查数据包类型是否为ColorPacket if isinstance(packet, ColorPacket): print("收到颜色:", packet.color) # 将当前颜色赋给下一个LED np[next_pixel] = packet.color # 将再下一个LED熄灭（实现“流动”效果，可选） np[mod(next_pixel + 1)] = (0, 0, 0) # 更新索引，为下一次接收做准备 next_pixel = (next_pixel + 1) % NUM_PIXELS关键逻辑与效果增强：
- 广播与连接：外设板一上电就开始广播自己提供了
UARTService。中央设备扫描到这个广播后即可发起连接。一旦连接建立，ble.connected变为True，代码进入数据接收循环。 - 数据包解析：
Packet.from_stream(uart)是一个阻塞式调用，它会等待直到一个完整且可识别的数据包从BLE通道送达。adafruit_bluefruit_connect库会自动匹配已知的数据包类型（这里我们只导入了ColorPacket）。这种设计非常优雅，省去了手动解析帧头、校验和等繁琐步骤。 - 视觉反馈设计：原代码实现了一个简单的“颜色历史”效果。每收到一个新颜色，就点亮一颗NeoPixel（
next_pixel指向的那一颗），同时熄灭它后面的一颗（next_pixel + 1），然后索引加一（循环）。这样，当你连续滑动电位器时，最新的10个颜色会依次留在灯环上，形成一个动态的历史轨迹，视觉效果比单纯改变所有灯的颜色要生动得多。你可以通过修改np[next_pixel] = packet.color这一行为np.fill(packet.color)来让所有灯同时显示同一颜色。
4. 系统集成、调试与功能扩展
4.1 上电、配对与操作流程
- 分别供电：将编写好代码的两块CPB，以及连接好电位器的发送端CPB，分别用锂电池或USB线上电。
- 观察启动：两块板子的NeoPixel灯环都会进行一个简短的启动自检（CircuitPython标准行为）。之后，接收端（外设）的灯环可能会保持某种状态或熄灭，串口输出（如果用Mu编辑器连接）会显示“正在广播，等待连接...”。
- 自动连接：发送端（中央）启动后，会开始扫描。几秒内，你会在它的串口输出中看到“找到外设，尝试连接...”，然后“RGB: (x, x, x)”开始滚动输出。与此同时，接收端的串口会显示“已连接！”和“收到颜色: (x, x, x)”。
- 调色操作：此时，滑动发送端的三个电位器，接收端的灯环就会实时显示出对应的混合颜色。如果使用了“颜色历史”模式，你还能看到色彩随时间流动的效果。
4.2 常见问题与排查技巧实录
即使按照教程操作，也可能会遇到一些小问题。下面是我在实际制作和教学中总结的排查清单：
| 现象 | 可能原因 | 排查步骤 |
|---|---|---|
| 两块板子无法连接 | 1. 其中一块板子代码未正确上传或文件名不是code.py。2. 库文件缺失或版本不匹配。 3. 两块板子距离过远或有强干扰。 | 1. 分别用Mu编辑器打开两块板子的CIRCUITPY盘，确认code.py内容正确，且/lib文件夹下有必需的三个.mpy库文件。2. 打开Mu的串口监视器，查看两块板子的输出信息。发送端应显示“正在扫描...”，接收端应显示“正在广播...”。如果没有任何输出，可能是代码没运行，尝试按一下复位键。 3. 将两块板子靠近（1米内），排除距离和障碍物干扰。 |
| 连接成功，但颜色不变或变化异常 | 1. 电位器接线错误（信号线接错引脚或接触不良）。 2. 代码中引脚定义与实际接线不符。 3. 电位器损坏或读数范围不对。 | 1.首先检查发送端串口输出：滑动电位器时，观察打印的RGB数值是否在0-255之间平滑变化。如果某个值始终为0或255，检查对应电位器的三根线是否接牢，特别是信号线（中间引脚）到CPB的连线。 2. 核对代码中 AnalogIn(board.A4)等语句是否与你的物理连接（黄->A4, 绿->A5, 蓝->A6）一致。3. 用万用表电压档，测量电位器中间引脚（Pin 2）对地的电压，滑动时看电压是否在0V-3.3V间平稳变化。 |
| 接收端灯环不亮或颜色错乱 | 1. 接收端代码中的NeoPixel初始化或赋值有误。 2. 数据包解析失败。 | 1. 在接收端代码中，尝试在连接成功后，直接写一句np.fill((255, 0, 0))测试灯环是否正常。如果还不亮，检查neopixel.mpy库是否正确安装，或尝试降低亮度brightness=0.05。2. 在接收端代码的 if isinstance(packet, ColorPacket):内部，先添加一句print(“Parsed OK”)，看是否能打印出来，确保数据包被正确解析。 |
| 通信延迟大或断断续续 | 1. BLE信号受干扰。 2. 发送端循环中的 time.sleep()时间过长。3. 电源电压不足。 | 1. 远离Wi-Fi路由器、微波炉等2.4GHz设备。 2. 可以尝试将发送端的 time.sleep(0.3)减小到0.1或0.05，但注意这会增加功耗和系统负载。3. 检查锂电池电量，电压过低会导致CPU和无线电工作不稳定。 |
4.3 项目扩展与创意改造思路
这个基础框架的潜力远不止调色。你可以把它看作一个无线模拟数据采集与控制系统的模板。以下是一些扩展方向：
增加控制维度：CPB还有A1, A2, A3等模拟引脚空闲。你可以增加更多的滑动电位器或旋转电位器，来控制NeoPixel的亮度、颜色切换模式（如渐变、彩虹）甚至动画速度。只需在发送端代码中增加对应的
AnalogIn，并考虑定义一个新的、包含更多数据的数据包类型（虽然需要更深入修改协议，但adafruit_bluefruit_connect也支持自定义数据包）。更换输入/输出设备：
- 输入：把电位器换成光敏电阻，做一个环境光感应夜灯，光线越暗，LED越亮。或者换成热敏电阻，用温度控制颜色（冷色到暖色）。
- 输出：接收端不一定要控制NeoPixel。你可以让接收端CPB连接一个舵机，用电位器无线控制舵机角度。或者连接一个小型OLED屏幕，显示发送过来的传感器数据。
引入板载传感器：CPB本身板载了众多传感器。你可以修改发送端代码，让它读取加速度计数据，然后将姿态信息（例如倾斜角度）发送给接收端，控制一个游戏中的角色或一个机械臂模型。或者读取声音传感器，做一个声控的彩色音乐灯。
一对多控制：BLE支持一个中央设备连接多个外设。你可以尝试编写一个发送端程序，同时连接多个作为外设的CPB（每个都有不同的名称或地址），让一组灯同步变化，打造分布式灯光系统。
添加物理交互：利用CPB板载的按钮。可以在发送端代码中加入按钮检测，按下按钮时，发送一个特殊的“保存当前颜色”或“切换模式”的数据包给接收端，增加交互的维度。
这个项目的核心价值在于，它用最简洁的硬件和代码，搭建了一个稳定可靠的无线通信桥梁。一旦你掌握了这个“中央-外设”通过UARTService和Bluefruit Connect数据包通信的模式，就可以将任意传感器数据无线传输到任意执行器，无限的可能性就此展开。我个人的体会是，从“有线思维”切换到“无线思维”是嵌入式项目中的一个重要台阶，而这个项目正是迈上这个台阶最平缓的那一步。