基于CircuitPython与加速度计的智能密码锁保险箱项目实践

1. 项目概述与核心思路

如果你对嵌入式开发感兴趣，想找一个能串联起传感器、执行器、编程和物理制作的项目，这个基于CircuitPython和加速度计的智能密码锁保险箱绝对是个绝佳的选择。它不像很多入门项目那样停留在点亮一个LED灯，而是完整地走完了“感知-决策-执行”的闭环：用开发板内置的加速度计感知你旋转“密码盘”的动作，用代码验证你输入的密码序列，最后驱动一个伺服电机来物理地打开或锁上一个真正的盒子。整个过程充满了交互的乐趣和完成的成就感。

这个项目的核心，是利用了Circuit Playground Express这块功能丰富的开发板。它集成了加速度计、可编程RGB灯、按钮、扬声器，让我们无需焊接任何额外的传感器模块，就能快速搭建原型。密码的载体不再是键盘或触摸屏，而是整个开发板本身——你通过旋转它到不同方位来输入密码。这种交互方式直观又有趣。伺服电机则扮演了锁舌的角色，通过PWM信号精确控制其旋转角度，实现锁闭和开启的机械动作。

从学习路径来看，这个项目覆盖了嵌入式开发的几个关键知识点：传感器数据读取与处理（加速度计）、执行器控制（伺服电机）、状态机逻辑编程（密码验证流程）以及用户交互设计（灯光、声音反馈）。无论你是想了解物联网设备的感知层如何工作，还是好奇智能硬件如何与物理世界互动，这个项目都能给你一次扎实的、手脑并动的实践体验。接下来，我会带你从电路连接、代码编写到机械组装，一步步实现这个会自己上锁的智能保险箱。

2. 核心硬件解析与选型考量

2.1 主控板：Circuit Playground Express为何是首选

在这个项目中，主控板的选择直接决定了开发的便捷性和最终成品的集成度。我们使用的是Adafruit的Circuit Playground Express。它之所以成为理想选择，核心在于其“All-in-One”的设计理念。对于这类交互式项目，我们通常需要多个离散的组件：一个微控制器、一个加速度计、几个LED、一个蜂鸣器或音频输出、几个按钮，以及用于连接外部设备的IO口。如果分开采购和连接，不仅会增加电路的复杂度和不稳定性，也会让后续的代码编写变得繁琐，需要管理多个不同厂商的传感器库。

Circuit Playground Express将这些功能全部集成在了一块直径约50mm的圆形板卡上。其核心是ATSAMD21微控制器，运行CircuitPython。围绕它，板载了以下关键外设：

• LIS3DH三轴加速度计：这是我们项目的“眼睛”，用于检测板子的旋转姿态。它精度足够，且通过I2C接口与主控通信，在CircuitPython中已有成熟的驱动库，一两行代码就能读取数据。
• 10个可编程NeoPixel RGB LED：均匀分布在板子周围，构成了我们的视觉反馈系统。不同的密码输入阶段可以用不同的颜色来指示，用户体验非常直观。
• 两个贴片按钮（A和B）：提供了直接的物理输入接口。按钮A用于确认输入一个密码位，按钮B用于重置或重新上锁。
• 蜂鸣器与音频输出：可以提供“嘀嘀”的提示音，增强交互反馈。成功或失败时不同的音调能立刻让用户知道结果。
• 丰富的GPIO扩展口：板子边缘的多个鳄鱼夹兼容焊盘，让我们可以轻松地通过夹子连接外部设备（如伺服电机），无需焊接，非常适合原型开发和教育场景。

选择它，意味着我们跳过了繁琐的硬件搭建和底层驱动调试阶段，可以直接聚焦在核心的应用逻辑和交互设计上，这对于学习和快速实现创意至关重要。

2.2 执行机构：微型伺服电机的工作原理与控制

锁的核心是一个微型伺服电机。它和我们常见的、只会连续转动的直流电机有本质区别。伺服电机内部包含了一个小型直流电机、一套减速齿轮组、一个电位器（用于检测输出轴角度）和一个控制电路。它的设计目标不是连续旋转，而是精确地控制输出轴旋转到指定的角度并保持在那里。

控制信号是PWM（脉冲宽度调制）。虽然我们常用PWM来控制LED亮度或电机速度（通过改变平均电压），但对于标准舵机，PWM信号的频率通常是固定的（例如50Hz，即周期20ms），我们通过改变每个周期内高电平的脉冲宽度（通常在0.5ms到2.5ms之间）来指定目标角度。例如，1.5ms的脉冲宽度通常对应中间位置（90度），0.5ms对应0度，2.5ms对应180度。

在CircuitPython中，我们无需手动计算和生成这些PWM脉冲。adafruit_motor.servo库为我们封装了这一切。我们只需要创建一个PWM输出对象，指定正确的引脚和频率（50Hz），然后创建一个伺服对象与之关联。之后，直接给servo.angle属性赋值（如servo.angle = 90），库函数就会自动计算出对应的占空比并输出正确的PWM信号。这种高层次的抽象让我们可以更关注“让舵机转到90度”这个业务逻辑，而不是“在A3引脚生成一个1.5ms宽、50Hz的脉冲”这种底层硬件操作。

注意：不同品牌、型号的舵机，其脉宽与角度的对应关系可能略有差异。常见的180度舵机，其实际运动范围可能在170度到190度之间。在代码中，如果发现锁闭和开启的位置不理想（比如锁舌卡不住或打不开），可以微调lock_servo()和unlock_servo()函数中的角度值（如将90改为85，180改为175）进行校准。

2.3 供电与连接：系统稳定性的基石

整个系统由两大部分供电：Circuit Playground Express和伺服电机。虽然CPX可以通过USB供电，但为了做成一个独立的、可移动的设备，我们使用了一个3节AAA电池盒。这里有一个关键细节：伺服电机在启动和堵转（即锁舌被卡住时试图转动）的瞬间，电流需求可能非常大，轻松超过500mA。如果和主控板共用USB的5V电源，很可能导致电压被拉低，造成主控板重启。

因此，项目中采用了电池盒直接为整个系统供电的方案。电池盒的红色（正极）线连接到CPX的VOUT引脚，黑色（负极）线连接到GND。VOUT引脚直接输出电池电压（约4.5V），这个电压同时通过另一根红色鳄鱼夹线提供给伺服电机的红色电源线。这样，电机的大电流需求由电池直接承担，避免了对主控芯片的电源系统造成冲击。

连接上，使用“鳄鱼夹转面包板插头”的线材是点睛之笔。伺服电机的接口通常是标准的3针杜邦头母座，而CPX的焊盘是平的。鳄鱼夹可以牢牢夹住焊盘，另一端的单排插针则可以轻松插入舵机的接口，实现了快速、可靠且无需焊接的连接。三根线的定义必须牢记：红色（VOUT）-> 舵机红线（电源），黑色（GND）-> 舵机棕/黑线（地），黄色（信号）-> 舵机橙/白线（信号）。接反电源可能会烧毁舵机。

3. 代码深度剖析与编程逻辑实现

3.1 项目初始化与库导入

代码的开始是导入必要的库，这是CircuitPython项目的基础。time库用于提供延时（time.sleep）。board库定义了开发板上所有引脚的名称（如board.A3），让我们可以用可读的名称来引用硬件，而不是难记的引脚编号。pwmio（在早期版本中可能是pulseio）库提供了生成PWM信号的低层能力。adafruit_motor.servo库则是在PWM基础上，提供了控制舵机的高级、易用的接口。最重要的adafruit_circuitplayground.express库，通常被实例化为cpx对象，它是我们与板载所有资源（加速度计、NeoPixel、按钮、蜂鸣器）交互的万能钥匙。

import time import board import pwmio from adafruit_motor import servo from adafruit_circuitplayground.express import cpx

紧接着是硬件对象的初始化。创建PWM输出对象时，duty_cycle=2 ** 15将初始占空比设置为50%（因为PWM分辨率是16位，2^15即32768，是最大值65536的一半），这是一个安全的中间值。frequency=50设置了标准的50Hz舵机控制频率。然后用这个PWM对象创建了我们的舵机实例。同时，我们将NeoPixel的亮度设置为0.05（5%），这是一个非常实用的设置。在暗环境下，全亮度的NeoPixel非常刺眼，低亮度既能提供清晰的色彩反馈，又不会显得突兀，也更省电。

3.2 姿态感知：从加速度计数据到方向判断

整个密码输入系统的核心是姿态检测。我们依赖板载的LIS3DH加速度计。在静止状态下，加速度计主要感知的是地球重力（约9.8 m/s²）。当板子水平放置时，重力全部作用在Z轴上。当我们像转盘子一样旋转板子时，重力在X和Y轴上的分量就会发生变化。

代码中，我们通过cpx.acceleration读取三个轴的浮点数加速度值，并立即将其转换为整数。这个转换主要是为了简化后续的条件判断。在理想状态下，当板子的“A”边朝上时，Y轴会承受全部重力，读数应为+9（近似取整），X轴为0。同理，“B”边朝上对应X=9， Y=0；“C”边朝上对应Y=-9， X=0；“D”边朝上对应X=-9， Y=0。

x_float, y_float, z_float = cpx.acceleration x = int(x_float) y = int(y_float) z = int(z_float) if x == 0 and y == 9: current_dial_position = 'A' cpx.pixels.fill((0, 0, 255)) # 蓝色 if x == 9 and y == 0: current_dial_position = 'B' cpx.pixels.fill((80, 0, 80)) # 品红色 ...

这里有一个非常重要的实操细节：我们判断的是x == 0 and y == 9这样的精确值。在实际操作中，由于传感器误差、板子并非绝对水平、或者手抖，读到的值可能是(0, 8)或(1, 9)。如果坚持精确匹配，可能会导致检测不灵敏。一个更健壮的写法是判断范围，例如if abs(x) < 2 and y > 7:。在原代码基础上进行这个小改进，能极大提升用户体验。同时，为每个方向分配不同的NeoPixel颜色，提供了即时的视觉反馈，让用户知道系统识别到了哪个方向。

3.3 状态机与密码验证逻辑

整个程序运行在一个while True的无限循环中，其逻辑是一个典型的状态机。系统主要有以下几个状态：等待输入、接收第一位密码、接收第二位密码、接收第三位密码、验证成功、验证失败。我们用entered_combo这个列表来跟踪状态。

• 等待输入/重置状态：entered_combo为空列表。系统持续检测加速度计并更新current_dial_position和灯光颜色。此时按下B键，会执行锁定/重置操作：舵机回到锁定角度，LED变红提示，清空entered_combo列表。
• 密码输入过程：用户旋转板子到目标方位（如‘B’），按下A键。此时，current_dial_position的值（如‘B’）会被追加（append）到entered_combo列表中。同时播放一个短促提示音。这个过程重复，直到列表长度达到3。
• 验证状态：一旦len(entered_combo) == 3，程序立即将entered_combo列表与预设的correct_combo列表（如[‘B‘， ’D‘， ’C‘]）进行比较。这里使用的是Python的列表直接比较==，只有当顺序和内容完全一致时才返回True。
  • 成功：NeoPixel变绿，播放欢快的音调，调用unlock_servo()函数将舵机转到解锁角度，并清空entered_combo以备下次使用。
  • 失败：NeoPixel变红，播放低沉错误的音调，清空entered_combo，系统回到等待输入状态。

这个逻辑清晰且高效。correct_combo作为变量定义在代码开头，修改密码非常简单，只需改变这个列表中的字符顺序即可，例如将[‘B‘， ’D‘， ’C‘]改为[‘A‘， ’C‘， ’B‘]，就设定了一个全新的密码。

4. 机械组装与调试实战指南

4.1 密码盘与锁体的制作

电路和代码就绪后，我们需要给这个电子系统一个物理载体。选择一个带盖的硬质盒子作为保险箱本体。原项目推荐Adafruit的包装盒，其实任何尺寸合适、盖子开合紧密的小盒子都可以，比如精致的礼品盒或坚固的纸盒。

密码盘（Dial）的制作：其核心是让Circuit Playground Express能够被用户旋转，同时又要稳固地吸附在箱盖上。实现方法是利用磁力。首先，在CPX的背面贴上带有泡沫胶的金属针座。然后，在箱盖外侧确定好密码盘的中心位置，在箱盖内侧的对应位置，用胶带固定一块强磁铁（钕铁硼磁铁）。这样，当把CPX放到箱盖外侧时，背面的金属片会被箱盖内侧的磁铁牢牢吸住，形成了可自由旋转又不会掉落的“密码盘”。这个设计巧妙避免了在精致的开发板上钻孔或使用胶水。

锁舌机构的安装：这是机械部分的关键。微型伺服电机需要固定在箱体内部，其舵盘（舵臂）要能伸出来卡住箱盖的边缘，实现上锁。首先，你需要确定箱盖关闭时，边缘的哪个位置适合被卡住。然后，用厚双面泡沫胶或热熔胶将伺服电机机身牢固地粘在箱体内壁的对应位置。粘接前，务必通过代码测试，找到舵机“锁定”（卡住箱盖）和“解锁”（放开箱盖）的两个准确角度。原代码中使用90度和180度，你需要根据实际安装位置进行微调。

重要提示：在安装舵盘前，务必先给舵机通电，并运行一个测试程序（如sweep扫掠程序），观察其完整的运动范围。然后，手动将输出轴转到你希望的“解锁”位置（即箱盖可以自由打开的位置），再安装舵盘，使其方向与你设计的锁舌运动方向一致。最后，在代码中调整lock_servo()和unlock_servo()的角度值，确保物理动作与程序指令匹配。避免在未知角度时强行安装舵盘，否则可能因为机械限位导致电机堵转，轻则抖动无法到位，重则烧毁电机。

4.2 布线、供电与系统集成

机械结构固定后，进行最后的系统集成。将电池盒放入箱内，用其自带的夹子或胶带固定在箱体后壁，避免晃动。使用一根JST延长线连接电池盒和CPX的电源接口，预留出足够的长度，确保CPX在作为密码盘旋转时不会拉扯线路。

将连接伺服电机的三根鳄鱼夹线按照“红-红”、“黑-黑”、“黄-A3”的规则，分别夹到CPX的焊盘和舵机的接头上。为了更可靠，可以用一小块胶带将鳄鱼夹与舵机插头的连接处包裹一下，防止因线材自重或意外拉扯导致脱落。

关闭箱盖前，先打开电池盒的开关，此时CPX会上电启动。你会听到启动音，NeoPixel可能会闪烁，舵机也会运动到初始位置（锁定位置）。然后合上箱盖，从外部将CPX“密码盘”吸附在磁铁对应位置。现在，一个完整的、自供电的智能密码保险箱就组装完成了。

4.3 功能测试与用户体验优化

首次使用，建议先测试基本功能。按下B键，应听到锁定音，红灯亮起，舵机运动到锁定位。然后，按照预设密码（例如B->D->C）依次旋转密码盘并按下A键。每按一次，应有确认音，并且NeoPixel颜色应与方向对应。输入三位后，若正确，应听到成功音，绿灯亮起，同时箱盖应能被轻松打开（舵机解锁）。若错误，则是红灯和错误音。

在这个过程中，你可能会发现一些可以优化的点，这正是嵌入式开发的乐趣所在：

1. 密码反馈增强：目前输入密码时，只有声音和当前方向颜色。可以修改代码，让输入成功的每一位密码，其对应的那个NeoPixel（或一组LED）保持一种特定颜色（如白色），这样用户能更直观地看到自己已经输入了哪几位。
2. 错误处理与防抖：当前的按钮检测是简单的轮询。在实际中，机械按钮可能存在抖动，导致一次按下被误判为多次。可以加入简单的防抖逻辑，例如在检测到按钮按下后，延时一小段时间（如50毫秒）再次检测，如果仍然按下才确认为有效动作。
3. 加速度计容错：如前所述，将精确的数字判断改为范围判断，能适应更宽松的操作姿势。
4. 低功耗考虑：目前系统持续运行，耗电主要来自NeoPixel和CPU。如果希望更省电，可以设计一个休眠模式：长时间无操作后，熄灭所有LED，CPU进入低功耗状态，当检测到密码盘被转动（加速度计数据变化）时再唤醒。这需要更深入的CircuitPython电源管理知识。

5. 常见问题排查与进阶思路

5.1 硬件连接与供电问题

5.2 软件逻辑与交互调试

• 密码验证总是失败：首先检查correct_combo列表中的字符是否与你旋转输入的方向一致。注意，列表是[‘B‘， ’D‘， ’C‘]，意味着你需要依次将“B边”、“D边”、“C边”转到朝上位置并按下A键。方向字母（A，B，C，D）与板子上的丝印或NeoPixel位置有关，务必在代码中通过打印current_dial_position来确认你旋转到的方向被识别成了哪个字母。
• 舵机角度不准：servo.angle的理论范围是0到180度，但实际舵机的物理范围可能略小。如果发现锁舌无法完全卡住或收回，不要强行修改代码到超出范围的值（如-10或190），这可能会损坏舵机。应该在物理允许的范围内微调，例如锁定角度从90度改为85度，解锁角度从180度改为175度。同时，确保舵盘安装的位置正确，使其在有效角度内能达到预期的机械行程。
• 按钮响应太灵敏或太迟钝：这是机械开关的“抖动”特性导致的。可以在按钮检测代码中加入防抖延时。例如，在if cpx.button_a:之后，加入time.sleep(0.05)，然后再执行后续的追加密码、播放声音等操作。这能过滤掉大部分因抖动产生的误信号。

5.3 项目扩展与进阶玩法

这个基础项目是一个完美的起点，你可以在此基础上进行无限扩展：

1. 多用户与密码管理：将correct_combo从硬编码改为存储在文件或EEPROM中。通过长按某个按钮进入“管理模式”，用旋转和按钮来设置新密码，实现密码的可更改。
2. 增加复杂度：将3位密码扩展到4位或5位。或者，引入“转向”概念，像老式机械转盘密码锁那样，需要先顺时针转到某个数，再逆时针转到另一个数。这需要代码记录连续的旋转方向序列，挑战更大。
3. 网络功能与远程控制：为CPX增加一个WiFi或蓝牙模块（如AirLift协处理器）。你可以通过手机APP或网页来远程锁定/解锁保险箱，或者查看开锁记录。这便将一个本地项目升级为了一个真正的物联网设备。
4. 生物特征集成：这需要额外的硬件，但思路很有趣。例如，增加一个电容式指纹传感器（如Adafruit的FPM10A），将指纹验证作为开锁的另一种方式，甚至可以将指纹与旋转密码结合，实现双重认证。
5. “错误陷阱”与安全增强：实现一个简单的防破解机制。例如，连续输错密码3次，系统会锁定30秒并发出警报声（利用板载蜂鸣器），同时NeoPixel闪烁红光。这增加了试错成本，让项目更像一个真正的安全设备。

通过这个项目，你亲手实践了从传感器数据采集、嵌入式逻辑处理到机电控制的完整流程。它生动地展示了，几行简洁的Python代码如何赋予硬件智能，并与物理世界产生有趣的互动。这种将想法一步步实现为实物的能力，正是创客精神和嵌入式开发的魅力所在。