1. 项目概述当硬件遇上玄学用代码打造你的专属“决策神器”在嵌入式开发的世界里我们常常与传感器、显示屏和逻辑代码打交道构建着一个个解决实际问题的智能设备。但谁说硬件项目就一定要严肃刻板今天我想分享一个将技术趣味化、生活化的项目——基于Adafruit HalloWing M0 Express和CircuitPython的“魔法9号球”。这个项目完美地融合了加速度计的姿态检测、随机数生成的逻辑以及TFT显示屏的图像渲染最终封装进一个充满神秘流体的水晶球中。它的核心功能很简单当你心中有一个“是或否”的问题时摇晃或翻转这个球它就会像经典的魔法8号球玩具一样随机显示一个答案。这不仅仅是一个玩具更是一个绝佳的嵌入式系统学习案例涵盖了从传感器数据采集、事件驱动编程到用户交互设计的完整流程。无论你是想入门CircuitPython还是想寻找一个有趣的周末项目这个魔法9号球都能让你在动手的乐趣中深入理解微控制器如何感知物理世界并作出智能响应。2. 核心硬件选型与设计思路拆解2.1 为什么是HalloWing M0 Express选择硬件平台是项目的第一步它决定了项目的上限和实现的复杂度。在这个项目中Adafruit的HalloWing M0 Express几乎是“开箱即用”的完美选择这主要基于以下几个关键考量首先高度集成化是HalloWing最大的优势。它在一块骷髅形状的板卡上集成了ATSAMD21 Cortex-M0微处理器、1.44英寸128x128分辨率的TFT彩色显示屏、三轴加速度计LIS3DH以及一个用于声音输出的板载扬声器。对于魔法9号球项目而言我们核心需要的显示和运动感知功能都已内置无需再额外连接和焊接任何屏幕或传感器模块极大地简化了硬件连接降低了入门门槛和出错概率。其次对CircuitPython的完美支持。HalloWing预装了CircuitPython的引导程序其UF2引导加载模式使得刷写固件如同拖放文件一样简单。CircuitPython作为一种基于Python的微控制器编程语言其语法简单、库丰富特别适合快速原型开发和教育。HalloWing的显示、加速度计等硬件都有官方维护的、稳定易用的CircuitPython库这意味着我们可以用很少的代码就驱动起整个系统。最后供电与尺寸的平衡。HalloWing设计紧凑并配有标准的JST-PH电池接口可以方便地连接一块3.7V的锂聚合物电池实现移动供电。这对于一个需要被拿在手中摇晃的交互设备来说至关重要。其板载的电池充电管理电路也让我们可以通过USB接口随时为电池充电兼顾了便携性与便利性。实操心得对于初学者我强烈建议从HalloWing这类高度集成的开发板开始。它能让你避开硬件连接中的诸多“坑”如I2C地址冲突、引脚接错、电平不匹配等将精力集中在软件逻辑和创意实现上。等吃透了整个流程再尝试用基础MCU搭配分立模块的方案你会对系统有更深刻的理解。2.2 外围配件构建沉浸式体验的关键硬件平台确定了但要让它从一个开发板变成一个具有魔力的“球”我们需要一些外围配件来构建完整的物理形态和交互体验。DIY水晶球套件这是项目的“外壳”和氛围担当。我们选择了一个直径108mm的DIY雪景球套件。它通常包含一个玻璃或亚克力球体、一个带螺纹的塑料底座帽、一个用于密封的橡胶塞。透明的球体为内部电子设备和神秘流体提供了展示窗口而标准的螺纹接口则方便我们进行改装和固定。锂聚合物电池我们选用了一块3.7V、500mAh的电池。500mAh的容量对于驱动HalloWing的屏幕和主控来说可以提供数小时的连续使用时间对于间歇性使用的玩具来说完全足够。选择电池时除了容量更要关注其尺寸和重量需要能稳妥地安置在球帽内部空间且不会因过重影响整体重心。固定与结构件为了将HalloWing牢固地安装在球帽上我们需要一些机械结构。原项目使用了3D打印的定制件包括一个适配球帽螺纹的转接环、一个固定HalloWing的底壳以及一个垫高用的 spacer。固定螺丝则选用了M2.5规格的黑色尼龙螺丝和螺母。尼龙材质的好处是绝缘、轻便且不易划伤PCB。如果无法进行3D打印用厚实的双面泡沫胶带将HalloWing直接粘在球帽内侧也是一种可行的“快速原型”方案但稳固性和美观度会打折扣。“神秘流体”原料这是营造视觉效果的灵魂。你需要水作为基础载体食用色素任何颜色来赋予流体颜色超闪珍珠粉一种烘焙用的装饰粉主要成分是云母钛来制造悬浮闪烁的颗粒模拟星空或魔法光尘的效果甘油可选增加流体的粘稠度可以让珍珠粉下落得更慢流体运动更柔和、更有“质感”。这些材料在烘焙用品店或网上都很容易买到。这个硬件组合的巧妙之处在于它用最低的成本和最简单的工艺将一个技术项目包装成了一个具有强烈仪式感和趣味性的实体产品。从技术到体验的转换往往就靠这些看似不起眼的外围设计。3. 魔法流体的制备与硬件组装全流程3.1 调配属于你的“预言药剂”流体的调配是整个项目中最具手工乐趣的一环其效果直接决定了成品的视觉魅力。这个过程需要一些耐心和实验精神。首先确保水晶球内部完全清洁、干燥没有任何灰尘或指纹。然后用一个小勺子或纸片将极少量的超闪珍珠粉倒入球体底部。这里的关键是“极少”通常绿豆大小的一撮就足够了。因为珍珠粉的反射效果很强过多会导致流体浑浊反而看不清闪烁的颗粒。你可以先少放一些测试效果后再酌情添加。接下来向球体内注入约占一半容积的清水。此时加入你选择的食用色素。颜色的选择决定了球的“主题”例如深蓝色配银色珍珠粉像星空绿色配金色像魔法药水。建议从2-3滴开始用一根干净的搅拌棒如一次性筷子轻轻搅动观察颜色扩散和浓度。记住颜色在水中的表现和在小瓶子里看是不同的在球体中会显得更淡一些所以可以稍微大胆一点。将颜色搅拌均匀。现在如果你希望流体运动更优雅持久可以加入大约5-10毫升的甘油。甘油能增加液体的密度和粘度让珍珠粉像在梦境中一样缓缓飘落。不加甘油的话颗粒下落会更快动态更活泼。两种风格各有千秋我个人的偏好是加入少量甘油让运动带有一点“粘滞感”更像神秘的魔法流体。最后用清水将球体填充至接近瓶口但务必留出一点点空间约几毫米为液体热胀冷缩和安装橡胶塞留有余地。轻轻摇晃球体让所有成分充分混合。此时你可以暂时拧上球体原配的塑料盖尽情摇晃和观察流体效果根据闪烁度和颜色进行微调直到满意为止。注意事项1.安全第一所有操作远离电子设备。万一液体洒出立即彻底擦干。2.密封测试在最终封口前务必确保橡胶塞和瓶口干燥、清洁。将塞子用力按入瓶口倒置球体并轻轻摇晃检查是否有渗漏。对于追求万无一失的制作者可以在橡胶塞侧面涂上一圈薄薄的E6000胶水或硅酮密封胶再压入能提供极强的防水保障。但请注意一旦用胶封死后续再想更换流体或维修内部硬件就几乎不可能了。3.2 HalloWing的准备工作与供电系统在将电子部分装入球体之前我们需要先对其进行预处理和测试确保核心功能一切正常。首先为HalloWing刷入最新的CircuitPython固件。用一条质量可靠的USB数据线将HalloWing连接到电脑。快速双击板载的复位按钮RESET板载的红色LED将呈现呼吸灯效果此时电脑会识别到一个名为HALLOWBOOT的U盘。从CircuitPython官网下载对应HalloWing M0 Express的最新版本.uf2固件文件版本需在4.0及以上直接将其拖入HALLOWBOOT盘符。复制完成后开发板会自动重启电脑上会出现一个名为CIRCUITPY的新盘符这表示CircuitPython系统已成功运行。接下来处理供电。将锂聚合物电池的JST-PH插头插入HalloWing板上标有BAT的端口。注意正负极方向通常红线为正。连接后HalloWing即可脱离USB线由电池供电运行。为了在后续组装中固定电池防止其在球内晃动导致连接松动我们需要用双面泡沫胶带将电池粘贴在HalloWing板背面的空白区域。泡沫胶带具有一定的厚度和弹性既能粘牢又能缓冲震动。粘贴时注意避开板子上的元器件和测试点。3.3 机械结构的组装与固定这是将电子设备与球体物理结合的关键步骤需要一些精细操作。如果你采用了3D打印方案你会得到三个主要零件球帽转接环用于拧在球体上、HalloWing固定底壳、垫高隔片。首先将HalloWing屏幕朝外卡入固定底壳中通常会听到“咔哒”一声表示卡扣到位。然后将垫高隔片放入球帽转接环内部。使用两根10mm长的M2.5尼龙螺丝从球帽转接环的底部预留孔穿入穿过垫高隔片再对准HalloWing固定底壳背面的螺丝孔。在螺丝另一端拧上尼龙螺母。用一把小螺丝刀和钳子配合将螺母初步拧紧使整个结构稳固但不至于压坏塑料件。接下来是一个重要的安全步骤用斜口钳将伸出螺母的过长螺丝部分剪掉并稍微打磨一下切口使其平整。这一步至关重要因为球体内部空间有限这些突出的螺丝尖可能会在剧烈摇晃时刺破电池或划伤电线造成短路风险。修剪后整个组装体的背面应该是平整的。最后将组装好的“电子帽”组件对准已注入流体并塞好橡胶塞的球体瓶口小心地旋转拧紧。拧紧的过程中感受阻力确保密封可靠但不要过度用力导致塑料螺纹滑丝。确认拧紧后将HalloWing的塑料面盖扣上整个魔法9号球的硬件组装就大功告成了。4. CircuitPython代码深度解析与图像处理4.1 项目代码逻辑架构剖析魔法9号球的“大脑”全部由一段不到100行的CircuitPython代码驱动。让我们逐层拆解理解其如何将硬件动作转化为魔法预言。程序的核心是一个事件驱动循环它持续监听加速度计的状态并在特定触发条件翻转或摇晃满足时执行“更换答案图像”的动作。整个流程可以概括为初始化 - 显示随机图片 - 等待触发 - 触发后淡出旧图 - 选择新图 - 淡入新图 - 继续等待。首先看初始化部分。代码开头导入了必要的库time用于控制延时和淡入淡出速度os用于列出存储设备中的文件random用于生成随机数board和displayio是CircuitPython的核心显示库adafruit_lis3dh则是专门驱动LIS3DH加速度计的库。import time import os import random import board import displayio import adafruit_lis3dh接下来它创建了一个显示组splash并设置为根组所有图像都将在这个组里加载。SENSITIVITY 5这个变量是整个交互灵敏度的关键。它定义了触发动作所需的Z轴加速度阈值。当球被翻转Z轴加速度方向改变且数值超过阈值或剧烈摇晃时Z轴加速度的绝对值会超过这个值。splash displayio.Group() board.DISPLAY.root_group splash SENSITIVITY 5 # reading in Z direction to trigger, adjustable然后代码使用os.listdir(/)列出CIRCUITPY磁盘根目录下的所有文件并用filter函数过滤出所有以.bmp结尾的图像文件存入images列表。随后随机选择一个索引i作为启动时显示的第一张图片。images list(filter(lambda x: x.endswith(bmp), os.listdir(/))) i random.randint(0, (len(images)-1)) # initial image is randomly selected加速度计的初始化通过I2C总线完成并设置其量程为±4G这对于检测手持设备的翻转和摇晃来说足够了。i2c board.I2C() ACCEL adafruit_lis3dh.LIS3DH_I2C(i2c, address0x18) ACCEL.range adafruit_lis3dh.RANGE_4_G4.2 主循环与图像显示机制程序进入while True主循环。在循环的每一轮它首先尝试加载images[i]对应的图片文件并创建一个OnDiskBitmap对象和TileGrid对象将其添加到显示组splash中。这里有一个重要的错误处理机制用try...except ValueError包裹图像加载过程。这是因为不是所有的.bmp文件都能被CircuitPython的显示引擎解码例如位深不是24位或压缩格式不支持。如果遇到不支持的图片程序会打印错误信息并将该文件从images列表中删除然后continue到下一轮循环尝试下一张图片。这个设计保证了程序的健壮性不会因为一张坏图而崩溃。图片加载后程序通过一个for循环将屏幕背光亮度从0逐步提升到100%实现一个柔和的淡入效果每次增加1%间隔10毫秒。这个视觉效果极大地提升了产品的质感和神秘感。for b in range(101): board.DISPLAY.brightness b / 100 time.sleep(0.01) # default (0.01)淡入完成后程序进入一个内层的while not shaken:循环这是等待触发的状态。在这个循环里它不断地读取加速度计的Z轴数据ACCEL.acceleration[2]。当检测到Z轴加速度的绝对值大于设定的SENSITIVITY阈值时即球体被翻转或快速摇晃就将shaken标志设为True跳出等待循环。一旦触发程序立刻执行一个淡出效果将背光亮度从100%降到0%。然后使用splash.pop()将当前显示的图片从显示组中移除。接着重新生成一个随机索引i指向下一张要显示的图片。最后主循环回到开头加载新图片并淡入显示等待下一次触发。实操心得灵敏度调参SENSITIVITY 5是一个经验值。如果你发现球需要非常用力地摇晃才能触发可以尝试将这个值降低到3或4。反之如果放在桌上轻微震动就会误触发则可以提高到7或8。你可以在代码中取消# print(ACCEL_Z)的注释通过串口监视器查看实时的Z轴加速度数值从而找到一个最适合你使用习惯的阈值。4.3 图像素材的准备与优化代码逻辑清晰了但“魔法”的内容——那些预言答案则需要我们精心准备图像素材。代码要求图像必须是128x128像素、24位色的BMP位图。这是由HalloWing屏幕的物理分辨率和CircuitPythondisplayio库对OnDiskBitmap的支持格式所决定的。你可以使用任何图像处理软件来制作例如Photoshop、GIMP甚至在线的图片编辑器。制作要点如下尺寸精确务必调整为128x128像素其他尺寸会导致显示错误或拉伸变形。背景与文字由于屏幕本身是黑色的设计时应以亮色白色、黄色、绿色作为文字或图案的主色以确保清晰可见。背景可以设为透明或黑色以融入屏幕。内容设计经典的魔法8号球答案包括“是”、“否”、“可能”、“再问一次”等。你可以完全复刻也可以发挥创意制作属于自己的答案库比如“专心写代码”、“该休息了”、“问ChatGPT”等趣味回答。文件命名虽然代码不关心文件名但为了管理方便建议按数字或内容顺序命名如01_yes.bmp,02_no.bmp等。文件存放将制作好的所有.bmp文件直接拖入CIRCUITPY磁盘的根目录。代码只会读取根目录下的BMP文件。这是一个非常巧妙的管理技巧你可以在CIRCUITPY盘上创建一个文件夹例如old_images将暂时不想显示的图片移入文件夹它们就不会被程序加载。通过简单的文件拖拽就能实现“答案库”的热更新。将代码保存为code.py并放入CIRCUITPY根目录或者直接通过Mu编辑器保存到板子。设备会自动重启并运行。现在拿起组装好的球体尝试翻转或摇晃它见证第一句“预言”的出现吧5. 功能扩展与深度定制指南5.1 超越“是或否”打造你的专属神谕基础版的魔法9号球已经很有趣但CircuitPython的灵活性让我们能轻易地将其改造成更多样化的工具。关键在于理解我们本质上构建的是一个由姿态触发的随机内容显示器。这个“内容”远不限于简单的文字答案。创意扩展一每日名言/笑话球你可以将BMP图片内容换成名人名言、冷知识、编程笑话或者每日任务。每天早上摇一摇获取今日的激励语句或待办事项。制作图片时可以设计统一的模板只替换文字部分这样看起来会更像一款产品。创意扩展二随机选择器这是原项目文档中提到的“微控制器选择器”的泛化。你可以为任何需要做选择的情景制作图片库。比如午餐吃什么图片面条、米饭、沙拉、汉堡今晚看什么电影图片不同电影海报周末去哪玩这相当于一个实体化的“随机决策轮盘”。技术实现要点扩展功能无需修改核心代码逻辑只需要替换图像素材库。但如果你希望增加交互模式例如长按某个按钮切换不同的图片库如“答案库”和“笑话库”则需要引入数字输入并修改代码。HalloWing上有多个可用的按钮和触摸引脚。你可以定义当触摸引脚Y被触摸时改变images列表的路径从一个子目录中加载另一套图片。5.2 传感器数据的进阶玩法目前我们只使用了加速度计的Z轴数据。实际上LIS3DH能提供X, Y, Z三轴的加速度数据和敲击检测。这为我们提供了更丰富的交互可能性。区分“摇晃”和“翻转”当前代码将Z轴加速度绝对值超过阈值统一视为触发。我们可以通过逻辑判断来区分不同手势。例如如果X或Y轴加速度变化剧烈而Z轴相对稳定可以判定为“摇晃”如果Z轴加速度从正变负或负变正穿越零点可以判定为“翻转”。为不同手势分配不同的图像切换动画或逻辑比如摇晃随机换图翻转则按顺序换图。实现“敲击”交互LIS3DH支持敲击检测中断。我们可以配置传感器当检测到单次或双击时触发一个硬件中断。在代码中我们可以监听这个中断来执行一个特殊动作比如点亮/熄灭屏幕、切换静音模式或者触发一个特殊的“彩蛋”答案。数据可视化我们可以让屏幕本身显示加速度的实时数据做成一个“物理实验可视化球”。当球静止时显示一个十字准心当球运动时一个点根据X, Y加速度在屏幕上移动。这能让你直观地看到自己的动作如何被传感器捕捉。注意事项功耗管理任何新增的功能都要考虑对电池续航的影响。持续高速读取传感器数据或让屏幕常亮会显著增加功耗。对于电池供电的设备好的做法是让主循环在等待触发时进入低功耗状态或者降低传感器和屏幕的刷新率。HalloWing的CircuitPython固件目前对深度睡眠支持有限但我们可以通过优化代码比如在等待循环中增加time.sleep(0.1)来降低轮询频率从而在一定程度上节省电量。5.3 常见问题排查与故障解决在制作和调试过程中你可能会遇到一些问题。这里汇总了一些典型情况及解决方法问题一屏幕不亮或CIRCUITPY盘未出现。检查步骤确认USB线既可传输数据又能供电。尝试更换一条线或USB端口。双击复位按钮检查电脑是否出现HALLOWBOOT盘符。如果没有可能是引导程序损坏需要重新刷写UF2引导程序可在Adafruit官网找到。如果出现HALLOWBOOT但刷入CircuitPython固件后不出现CIRCUITPY尝试换一个版本的CircuitPython固件如从7.x换到6.x有时最新版可能存在未知兼容性问题。问题二摇晃球体没有反应不切换图片。检查步骤首先检查串口输出。在Mu编辑器或任何串口终端如PuTTY, screen中打开对应的串口如COMx, /dev/ttyACM0波特率115200。观察摇晃时是否打印出加速度数值。如果没有数据可能是加速度计初始化失败或I2C连接问题虽然HalloWing是内置的但固件问题可能导致驱动加载失败。如果串口有数据但数值变化很小始终在1以内可能是灵敏度阈值SENSITIVITY设得太高了。尝试将其修改为3。检查代码中触发条件判断的逻辑是否正确。确保你读取的是ACCEL.acceleration[2]Z轴并且判断条件是if ACCEL_Z SENSITIVITY:。注意由于安装方向你可能需要取绝对值abs(ACCEL_Z)或判断小于负阈值这取决于你把HalloWing哪一面朝上安装。问题三图片显示花屏、颜色错误或不显示。检查步骤确认图片格式是24位BMP。在Windows画图中“另存为”时务必选择“24位位图(*.bmp)”。256色或16位BMP将无法正确解码。确认图片分辨率是128x128。其他尺寸会导致displayio库报ValueError。检查串口输出。代码中捕获了ValueError并会打印Image unsupported的错误信息。根据提示找到有问题的图片并重新制作。确保图片文件直接放在CIRCUITPY盘根目录而不是任何子文件夹内。问题四电池耗电极快或设备发热。检查步骤检查代码中是否有死循环或非常密集的运算导致CPU持续高负荷运行。确保主循环中有适当的延时如time.sleep(0.05)。屏幕背光是主要的耗电源。检查背光亮度是否被设置为常亮100%。我们的代码在显示图片时是100%但在等待触发时背光会淡出到0%这是正确的省电设计。如果问题依旧断开电池仅用USB供电运行一段时间触摸HalloWing芯片区域。如果仍有异常发热可能是硬件故障或代码造成了短路如某个GPIO被错误配置为输出并持续拉高/拉低。这个项目从硬件组装、流体调配到软件编程覆盖了一个完整嵌入式产品原型的多个方面。它最吸引我的地方在于用相对简单的技术创造出了一个体验感十足、充满仪式感的物件。每一次摇晃等待答案的过程都是对物理世界与数字世界交互的一次微小而有趣的验证。