基于CircuitPython与DotStar LED的智能光绘棒制作全攻略

1. 项目概述：当硬件编程遇上光影艺术

光绘，这个听起来有点“魔法”的摄影技巧，其实原理很简单：在黑暗环境中，让相机快门长时间打开，然后你拿着一个会发光的东西在镜头前“画画”，相机就会把你移动的光轨记录下来。以前大家用手电筒、烟花棒，现在，我们有了更酷的玩法——用一行由微控制器精确编程控制的LED灯带，在空中绘制出任何你想要的图案，从简单的几何图形到复杂的像素画，甚至是动态的动画帧。

这次我们要做的，就是一个这样的“智能光绘棒”。它的核心是一块Adafruit CLUE开发板，这是一块功能相当丰富的微控制器板子，自带屏幕和按键，正好给我们做一个简易的交互界面。驱动发光部分的，则是一串DotStar LED灯带。你可能更熟悉NeoPixel，但在这个项目里，DotStar是更合适的选择，因为它采用SPI协议驱动，刷新速度极快，这对于需要流畅、无闪烁地“播放”图像帧的光绘来说至关重要。整个系统的“大脑”是CircuitPython，这是一种在微控制器上运行的Python 3语言，让你能用写Python脚本的方式轻松操控硬件，免去了传统嵌入式开发中编译、烧录的繁琐步骤。

这个项目的挑战和乐趣在于“压榨”硬件性能。CLUE板子的性能比不上树莓派那样的微型电脑，但我们就是要看看，用CircuitPython在这块板子上，配合精心优化的代码，能否实现接近“黄油般顺滑”的视觉输出，超越以往CircuitPython项目里常见的“像素块”式图形效果。最终，你会得到一个握在手里的创作工具，通过几个按键就能选择图片、调整参数，然后在夜空中挥洒出你的数字艺术作品。

2. 核心硬件选型与电路设计解析

2.1 为什么是CLUE和DotStar？

选择CLUE开发板，不仅仅是因为它支持CircuitPython。它集成了nRF52840芯片，性能足够应对实时数据处理；自带一块小型显示屏和两个物理按键，这为我们提供了无需连接电脑即可进行项目配置和交互的可能，让光绘棒成为一个真正独立的设备。试想一下，你总不想每次换图案都抱着笔记本电脑蹲在野外吧？

而灯带选择DotStar（APA102），而非更常见的NeoPixel（WS2812B），是出于对速度的硬性要求。NeoPixel使用单线归零码协议，虽然节省引脚，但控制大量LED时，数据写入速度会成为一个瓶颈，尤其是在需要快速切换颜色以形成连续图像时，容易产生可见的延迟或闪烁。DotStar则使用标准的SPI（串行外设接口）协议。SPI是一种全双工、高速的同步通信协议，主控制器（CLUE）可以以很高的时钟频率（本项目设置为8MHz）向灯带“推送”数据。这意味着刷新一整条灯带所需的时间极短，对于光绘这种需要精确时序的应用来说，SPI带来的稳定性和速度优势是决定性的。

2.2 电源方案：简单可靠的3AA电池组

项目采用了3节AA电池串联的电池包，输出约4.5V电压。这是一个经典而稳妥的选择：

1. 电压匹配：DotStar LED的工作电压通常是5V，4.5V的电池电压虽然略低，但足以驱动LED发出足够亮度的光，且不会因电压过高而损坏LED。CLUE开发板本身有稳压电路，可以接受这个范围的输入电压（通过USB或电池接口）。
2. 简化电路：DotStar灯带内部集成了稳压芯片，对电源电压的要求相对宽松。4.5V电压直接供给灯带，无需额外的电平转换或升压电路，大大简化了硬件连接。
3. 容量与易得性：AA电池容易获取，容量选择也多。一个装着碱性电池的电池包，足以支持数小时的光绘创作。

重要警告：电路连接中有一个至关重要的安全细节。CLUE板的STEMMA QT连接器（一个方便的I2C/GPIO扩展口）上有四根线：黑（GND）、红（VCC）、蓝（SDA）、黄（SCL）。在我们的电路中，STEMMA连接器的红色（VCC）线绝对不可以连接到电池的正极！CLUE板的STEMMA VCC是输出引脚，用于给外部传感器供电（通常是3.3V）。如果将其连接到4.5V的电池正极，会造成反向供电，极有可能瞬间损坏CLUE主板。原项目作者甚至建议将STEMMA连接器里的红线直接拔掉，以绝后患。我们连接电池正极的，只能是DotStar灯带的VCC输入线和电池包自身的正极线。

2.3 电路连接图与实操要点

虽然原文提供了示意图，但我们可以更具体地拆解每一步连接，特别是对于没有太多电子制作经验的朋友。

所需材料清单（除核心三大件外）：

• 连接线：一根STEMMA QT/Qwiic转4针杜邦线（母头）的电缆。或者，你也可以使用单独的杜邦线进行焊接。
• 4针JST SM连接器（可选但强烈推荐）：焊接在DotStar灯带的输入端，这样灯带可以轻松插拔，便于后续在其他项目中复用。
• 鳄鱼夹测试线或一小段导线：用于在需要编辑代码时，短接CLUE的Pin 0和GND。
• 焊接工具：电烙铁、焊锡、助焊剂。
• 热缩管：用于绝缘和保护焊接点。
• 支撑结构材料：木条、方铝管、PVC水管，甚至坚固的卡纸板都行。长度建议比灯带长一些，两端留出持握空间。

接线步骤详解：

1. 准备DotStar灯带：如果你的灯带是裸板，需要先焊接导线。灯带输入端通常有四个焊盘：VCC（电源正极，+5V）、GND（电源地，0V）、DI（数据输入）、CI（时钟输入）。对应焊接上红（VCC）、黑（GND）、绿（DI）、黄（CI）四根线。如果使用JST SM接头，则将这四根线焊接到接头的对应引脚上。
2. 连接CLUE与灯带：
   • GND（地）：将电池包的黑色负极线、DotStar灯带的黑色GND线、以及STEMMA线的黑色线，三者拧在一起焊接，或者接到一个公共的接线端子上。这是整个电路的公共参考地。
   • VCC（电源）：将电池包的红色正极线与DotStar灯带的红色VCC线连接。切记，STEMMA的红线悬空不接！
   • 数据线：将STEMMA线的蓝色线（SDA）连接到DotStar灯带的绿色数据线（DI）。
   • 时钟线：将STEMMA线的黄色线（SCL）连接到DotStar灯带的黄色时钟线（CI）。
3. 安装支撑与扩散罩：将CLUE板、电池包用双面胶或扎带固定在支撑杆上。将DotStar灯带粘贴在支撑杆的一侧。为了获得柔和、连续的光带效果而非一颗颗独立的亮点，需要在灯带表面覆盖一条白色弹力布作为扩散罩。这能有效混合相邻LED发出的光，使最终光绘图案的线条更平滑。

3. 软件环境搭建与代码深度剖析

3.1 CircuitPython固件与库部署

首先，确保你的CLUE板运行的是最新版的CircuitPython。

1. 下载固件：访问Adafruit的CLUE CircuitPython下载页面，找到最新的.uf2固件文件。
2. 进入引导加载程序模式：用USB线连接CLUE和电脑。快速双击CLUE板背面的复位（RESET）按钮。此时，电脑上会出现一个名为CLUEBOOT的U盘。
3. 刷写固件：将下载好的.uf2文件拖入CLUEBOOT盘。完成后，CLUE会自动重启，并出现一个名为CIRCUITPY的新U盘。这表明CircuitPython系统已就绪。
4. 安装必要库：下载对应版本的CircuitPython库包（Library Bundle）。解压后，找到adafruit_display_shapes和adafruit_display_text这两个文件夹，将它们复制到CIRCUITPY盘里的lib文件夹内。

3.2 核心代码机制与文件系统“魔术”

这个项目的软件部分设计得很巧妙，尤其是它处理文件读写权限的方式，是理解其运行的关键。

boot.py的“守门人”角色：通常，当CircuitPython板通过USB连接到电脑时，CIRCUITPY盘是可读写的，方便你修改代码。但在这个项目中，主程序需要频繁、快速地向板载存储（Flash）写入图像处理后的临时数据。如果电脑操作系统同时也在读写这个盘，就会产生冲突，导致程序错误或文件损坏。

解决方案在boot.py文件中。它利用CLUE的一个GPIO引脚（Pin 0）作为“模式开关”：

• 默认模式（Pin 0悬空）：启动时，boot.py将文件系统设置为只读状态。这样，主程序code.py可以毫无顾忌地高速读写/led.dat这个临时工作文件，但你无法通过电脑编辑或删除CIRCUITPY盘上的任何文件。
• 编辑模式（Pin 0连接GND）：在板子启动或复位前，用一根跳线或鳄鱼夹将Pin 0和GND短接。此时boot.py检测到这个连接，会将文件系统设置为可写状态。你可以自由地通过电脑上传、修改或删除文件，但主程序code.py将不会运行（因为文件系统状态不符预期）。

这种设计保证了运行时性能的最大化和数据安全。你需要习惯这种工作流：要修改代码或图片时，短接Pin 0与GND，复位板子，进行编辑；编辑完成后，断开短接，再次复位板子，光绘程序开始运行。

3.3 主程序code.py工作流解析

主程序的逻辑清晰，是一个状态机，主要在“配置模式”和“绘画模式”之间切换。

1. 初始化与图像加载：

   • 程序启动后，首先扫描PATH指定目录下的BMP图片文件。
   • 用户通过左右按键选择图像、设置曝光时间、循环模式、亮度等参数。
   • 当用户确认开始绘画（长按右键）时，程序调用bmp2led.py模块的核心函数。
   • bmp2led.process()函数是关键：它读取选中的BMP图片，根据设定的总绘画时间（如2秒）和测速得到的每秒可播放行数，计算出需要将图片缩放到多少“行”。然后对图片进行缩放、颜色空间转换（应用伽马校正使亮度变化更符合人眼感知）、有序抖动处理（在有限的颜色深度下模拟更多色彩），最后将处理好的每一行LED颜色数据预先写入到/led.dat临时文件中。这个预处理过程较慢，但一劳永逸。

2. 进入绘画模式：

   • 屏幕背光关闭以省电。
   • 禁用垃圾回收（GC）：这是实现流畅输出的关键技巧。Python的自动垃圾回收会在不可预知的时间点暂停一切操作来清理内存，这种停顿在光绘中会导致光轨出现难看的缺口。通过gc.disable()在绘画循环前禁用GC，确保了数据输出的最高优先级和时序稳定性。
   • 循环读取/led.dat文件中的每一行数据，通过SPI接口飞速发送给DotStar灯带。
   • 循环中会不断检测按键状态。短按任意键可暂停/继续绘画，长按任意键则退出绘画模式，返回配置界面。

3. 性能优化“黑魔法”：

   • SPI预配置与锁定：在初始化时一次性配置好SPI总线（8MHz速率）并锁定，避免在每次发送数据时重复配置带来的开销。
   • 内存视图与readinto()：使用bytearray和readinto()方法，直接操作内存缓冲区，避免在循环中创建新的对象，从而防止在GC禁用时意外触发内存分配。
   • 基准测试：程序开始时运行一个1秒的基准测试，向灯带写入空白数据，测算出当前硬件下每秒能传输的最大数据行数。这个值用于精确计算图像缩放比例，确保在设定的曝光时间内刚好播放完整个图像。

3.4 图像准备：BMP图片的制作规范

程序对图片有特定要求，并非任何图片都能直接使用：

• 格式：必须是24位色的BMP文件。这是最简单的位图格式之一，没有压缩，程序可以直接读取像素数据。
• 尺寸：图片的宽度必须严格等于LED灯带的像素数量（例如72像素）。高度则任意，它决定了图像纵向的“长度”或细节量。
• 内容设计：
  • 留白：如果你希望光绘图案是悬浮在空中的，记得在图片的顶部和底部留出足够的黑色（RGB 0,0,0）区域。这样在挥舞光绘棒时，黑色部分对应的LED不发光，在照片中就是透明的，只有中间有颜色的部分会被记录。
  • 像素艺术：由于LED数量有限（72或60），复杂图像会被压缩。像素风、高对比度的图标、文字或简单图形效果最好。可以使用像Aseprite、Photoshop或甚至Windows画图工具来创建或调整图片。

将做好的BMP图片放入CIRCUITPY盘上对应的文件夹（例如/bmps-72px），程序就能识别并列表显示了。

4. 光绘拍摄实战技巧与高级玩法

硬件和软件都准备好后，真正的艺术创作才开始。光绘摄影是一门结合了设备操作和艺术构思的技术。

4.1 相机参数设置黄金法则

1. 模式：使用全手动模式（M档）。你需要完全控制曝光三要素。
2. 光圈（Aperture）：为了获得清晰的整个光轨，建议使用较小的光圈，如f/8至f/16。这能提供更大的景深，确保光绘棒在移动过程中即使前后稍有晃动，记录下的光迹也是清晰的。
3. 快门速度（Shutter Speed）：这就是“长曝光”的核心。根据你程序中设置的绘画时间（如2秒、4秒）来设定。通常设置为比绘画时间稍长1-2秒，给开始和结束留出缓冲。例如，程序设2秒，相机快门可设4秒。
4. 感光度（ISO）：尽可能低！如ISO 100或200。高ISO会引入噪点，在黑暗背景下尤其明显。低ISO能保证画面纯净。
5. 对焦：在黑暗中自动对焦通常会失败。请手动对焦。可以先让助手站在光绘者位置，用手电筒照亮自己，相机对其对焦后，将镜头切换为手动对焦模式锁定焦点。
6. 格式：拍摄RAW格式文件，它能保留更多细节，方便后期调整白平衡、对比度，以及降噪。

4.2 拍摄环境与操作要领

1. 环境：越暗越好。室内需关灯拉窗帘，户外选择无月光的黑夜，远离路灯等杂光。
2. 稳定：相机必须用三脚架绝对固定。任何轻微抖动都会导致背景模糊。使用快门线或相机自带的2秒延时拍摄功能来触发快门，避免手按快门时的震动。
3. 着装与动作：光绘者应穿深色、不反光的衣服。动作要平稳、匀速。程序的“循环”模式可以用来绘制重复图案，你需要练习让每次挥动的路径和速度保持一致。
4. “漂浮”效果：这就是为什么图片上下要留黑边。挥动光绘棒时，在开始和结束阶段，让留黑的部分经过镜头，只有中间有图像的部分在镜头前停留并移动，这样在成片中，图案看起来就像是悬浮在空中，没有连接的“光柄”。

4.3 创意扩展与故障排查

创意玩法：

• 多重曝光：在同一张照片中，让程序播放不同的图片，你按顺序绘制，可以创造出故事性的叠加画面。
• “光之舞”：不用局限于水平挥动。尝试旋转、画圈、快速抖动，配合不同的图案，可以产生意想不到的流体效果。
• 背景融合：寻找有微弱光线的城市夜景作为背景，将光绘图案作为前景，能创造出超现实的作品。

常见问题与排查：

最后一点心得：光绘的成功，三分靠设备，七分靠耐心和练习。第一次尝试很可能拍出一团模糊的光晕，这很正常。多试几次，调整挥动速度，和摄影师（可能是你自己）沟通好节奏，你会逐渐掌握这种用光作画的技巧。这个项目最迷人的地方在于，它完美地融合了代码的逻辑之美和光线的艺术之魅，当你第一次在照片中看到自己编程创造的图案出现在夜空时，那种成就感是无与伦比的。