1. 项目概述与核心价值如果你和我一样对物联网项目感兴趣同时又希望手头的设备能真正“干点实事”那么这个基于ESP32-S2和电子墨水屏的疫苗接种数据追踪器项目绝对值得你花上一个周末的时间来折腾。它不是一个简单的“Hello World”式演示而是一个从硬件选型、环境搭建、网络连接到数据处理和低功耗显示都涵盖的完整物联网应用案例。这个项目的核心是利用Adafruit MagTag这块集成了ESP32-S2 WiFi模块和2.9英寸电子墨水屏的开发板制作一个可以贴在冰箱上、靠电池供电的“信息看板”。它能自动从GitHub上的公开数据源Our World in Data项目获取指定国家或地区的COVID-19疫苗接种数据计算接种百分比并用进度条和文字的形式清晰地展示在屏幕上。完成一次数据更新和显示后设备会进入深度睡眠模式直到24小时后才再次唤醒工作从而实现长达数周甚至数月的超长续航。为什么说这个项目有嚼头首先它完美诠释了物联网的典型架构感知联网获取数据、处理微控制器计算、执行屏幕显示和优化深度睡眠。其次它避开了Arduino IDE采用了CircuitPython这一对开发者更友好的微控制器编程环境。CircuitPython让你可以直接在开发板的存储盘里像编辑文本文件一样写Python代码库管理也异常简单复制粘贴即可极大降低了嵌入式开发的门槛。最后电子墨水屏的应用本身就是一大亮点它只在刷新图像时耗电显示静态内容时零功耗这种特性使得它成为信息展示类物联网设备的绝配。无论你是想学习如何让一块开发板“自己上网找数据”还是想体验电子墨水屏在低功耗项目中的魅力亦或是想找一个结构清晰、可扩展性强的CircuitPython实战项目这个疫苗接种追踪器都能满足你。接下来我会带你一步步拆解这个项目不仅告诉你“怎么做”更会分享我在复现过程中踩过的坑和总结出的技巧。2. 硬件选型与核心组件解析工欲善其事必先利其器。这个项目的硬件核心是Adafruit MagTag但理解其每个组成部分的选型理由对你未来设计自己的物联网设备至关重要。2.1 主控单元为什么是ESP32-S2项目选用ESP32-S2作为主控芯片而非更常见的ESP32或ESP8266这背后有细致的考量。ESP32-S2是乐鑫Espressif推出的一款单核Xtensa® 32位LX7处理器最大亮点在于其极佳的成本与功耗平衡。集成WiFi与低功耗管理它内置了802.11 b/g/n WiFi满足了项目联网获取数据的基本需求。更重要的是ESP32-S2支持多种低功耗模式特别是深度睡眠Deep Sleep模式。在此模式下仅RTC实时时钟和极少量内存保持供电电流可降至10微安级别。这正是本项目实现“每日一更新续航数周”的物理基础。相比之下早期的ESP8266在深度睡眠下的功耗控制不如ESP32系列精细。丰富的接口与安全性ESP32-S2提供了足够的GPIO、SPI、I2C、UART等接口以驱动电子墨水屏和其他外设。它还内置了硬件加密加速器和安全启动功能虽然在这个开源数据项目中不是必须但对于需要连接私有云或涉及敏感数据的商业项目这是一个有价值的加分项。对CircuitPython的良好支持Adafruit团队对ESP32-S2的CircuitPython支持非常成熟提供了稳定的WiFi库、网络请求库和深度睡眠API让开发者能专注于应用逻辑而非底层驱动。注意Adafruit在2025年推出了MagTag 2025 Edition其硬件略有更新。最关键的区别是新版必须使用CircuitPython 10.x.x或更高版本旧版的9.x.x固件将无法运行。购买或使用前务必确认版本。2.2 显示单元电子墨水屏的独特优势项目使用的2.9英寸灰度电子墨水屏E-Ink是另一个灵魂组件。它的工作原理与我们的手机或电脑液晶屏截然不同。双稳态显示原理电子墨水屏内部有许多微小的“微胶囊”里面充满带负电的黑色粒子和带正电的白色粒子。通过施加不同方向的电场可以控制黑、白粒子移动到胶囊顶部从而形成图像。一旦粒子位置固定即使撤掉电场图像也会保持不变。这就是其“仅在刷新时耗电”的根本原因。低功耗与可视性对于这个数据看板项目屏幕大部分时间都是静态显示。传统LCD屏需要持续供电以维持图像而E-Ink屏在显示时零功耗只有在你调用magtag.refresh()进行内容更新时才会消耗一次相对较高的刷新电量。此外E-Ink屏依靠环境光反射阅读体验类似纸张无闪烁在强光下反而更清晰非常适合作为常显信息牌。刷新率限制E-Ink屏的缺点是刷新速度慢通常需要1-3秒完成一次全局刷新且有刷新寿命限制通常几十万次。因此它不适合需要快速动态变化的场景。本项目每天只刷新1-2次完美避开了它的短板。2.3 电源与辅助组件锂聚合物电池3.7V 420mAh选择扁平的LiPo电池是因为其能量密度高、形状灵活可以轻松贴在MagTag背面。420mAh的容量结合ESP32-S2深度睡眠模式下极低的待机电流和E-Ink屏的零显示功耗是实现长续航的关键。你可以根据需要的续航时间选择更大容量的电池但要注意物理尺寸。磁吸脚垫这是一个提升用户体验的细节。通过磁吸脚垫你可以轻松地将MagTag固定在冰箱门、金属白板或任何铁质表面上随时查看数据也方便取下充电。USB-C数据线用于供电、编程和调试。务必使用一条支持数据传输的USB线很多廉价的充电线只有电源线无法识别设备会让你在第一步就卡住。3. 开发环境搭建与CircuitPython固件烧录拿到硬件后第一步是给它装上“操作系统”——CircuitPython。这个过程比传统的Arduino IDE开发更接近“即插即用”。3.1 CircuitPython简介与优势CircuitPython是Adafruit主导开发的一款基于MicroPython的开源解释型语言专为教育和小型物联网设备设计。它的最大优势是简化了开发流程无需编译代码以.py文本文件形式存在CircuitPython解释器实时执行。文件系统即IDE连接电脑后开发板会作为一个名为CIRCUITPY的U盘出现。你只需用任何文本编辑器如VS Code, Thonny, 甚至记事本编辑code.py文件保存后设备会自动重新运行代码。库管理简单第三方库就是.mpy或.py文件直接复制到CIRCUITPY盘下的lib文件夹即可。3.2 固件烧录详细步骤根据你的MagTag版本主要是Bootloader不同有几种烧录方式。我强烈推荐优先尝试UF2方式它最简单。第一步下载固件访问CircuitPython官网的MagTag下载页面根据你的板子版本选择正确的.bin和.uf2文件。对于2025版务必选择10.x.x版本对于旧版9.x.x也可用。两个文件都下载下来备用。第二步进入Bootloader模式用数据线连接MagTag和电脑。快速双击MagTag上靠近USB-C接口的Reset按钮。这个操作需要一点手感如果一次没成功没出现新的磁盘多试几次注意双击的速度要快。成功后电脑上会出现一个名为MAGTAGBOOT或类似的可移动磁盘。第三步拖放烧录UF2方式将下载好的.uf2文件直接拖拽或复制到MAGTAGBOOT磁盘中。复制完成后磁盘会自动弹出设备重启。稍等片刻电脑上会出现一个新的名为CIRCUITPY的磁盘。恭喜CircuitPython安装成功第四步备用方案esptool或Web Serial如果双击Reset无法进入UF2模式可能你的板子是很早期的版本就需要使用esptool通过串行协议烧录。安装esptool在电脑终端运行pip install esptool。查找端口在Windows设备管理器或macOS/Linux的终端中用ls /dev/tty.*或ls /dev/cu.*查找类似COM3或/dev/tty.usbmodemXXXX的端口。擦除并烧录在终端中执行命令替换/dev/ttyYOURPORT为你的实际端口firmware.bin为下载的.bin文件esptool.py --chip esp32s2 --port /dev/ttyYOURPORT erase_flash esptool.py --chip esp32s2 --port /dev/ttyYOURPORT --baud 921600 write_flash 0x0 firmware.bin对于不熟悉命令行的用户还可以使用Chrome浏览器的 Web Serial ESPTool 页面这是一个图形化工具同样可以完成.bin文件的烧录。实操心得在Windows上使用UF2方式时有时文件复制到最后会弹出“错误 0x800701B1指定不存在的设备”的警告。这通常是Bootloader在烧录完成后提前断开了连接而Windows还没反应过来。你可以直接忽略这个错误大多数情况下固件已经烧写成功。如果觉得烦人可以按照Adafruit指南更新一下板子的TinyUF2 Bootloader新版本修复了这个问题。4. 网络配置与物联网连接实战让设备“上网”是物联网项目的第一步。在CircuitPython中这个过程通过配置settings.toml文件和编写网络测试代码来完成。4.1 安全配置settings.toml文件详解CircuitPython采用settings.toml文件来管理敏感信息这是一个非常棒的安全实践。它避免了将WiFi密码、API密钥等硬编码在code.py里从而在分享代码时不会意外泄露隐私。打开CIRCUITPY磁盘你会看到一个可能是空的settings.toml文件。用文本编辑器打开它。按照以下格式填入你的网络信息CIRCUITPY_WIFI_SSID 你的WiFi名称 CIRCUITPY_WIFI_PASSWORD 你的WiFi密码格式必须严格遵循变量名全大写用下划线连接等号两边有空格字符串值用双引号括起来。4.2 网络连接测试代码解析将提供的网络测试代码复制到CIRCUITPY盘根目录下的code.py文件中覆盖原有内容。这段代码做了以下几件事扫描网络wifi.radio.start_scanning_networks()会列出周围所有WiFi热点及其信号强度RSSI和信道。这在你调试信号问题时很有用。连接WiFi使用settings.toml中配置的SSID和密码进行连接。os.getenv()函数用于读取配置文件中的变量。测试连通性通过wifi.radio.ping(“8.8.8.8”)向Google的DNS服务器发送ICMP ping包。成功会返回延迟秒失败则返回None。这里有个细节代码中ping了一次如果失败会再试一次。因为初始连接有时可能不稳定重试一次能提高成功率。但即使ping失败程序也会继续因为有些网络环境可能禁ping不代表HTTP访问不行。发起HTTP请求使用adafruit_requests库发起GET请求分别获取一个纯文本网页和一个JSON格式的API数据并打印出来证明网络功能完全正常。连接失败排查症状串口输出卡在Connecting to...或提示连接失败。检查1确认settings.toml中的SSID和密码完全正确注意大小写和特殊字符。检查2确认你的WiFi是2.4GHz网络。ESP32-S2不支持5GHz频段。检查3路由器是否设置了MAC地址过滤如果是需要将ESP32-S2的MAC地址代码开头会打印加入白名单。检查4信号是否太弱尝试让设备靠近路由器。4.3 获取网络时间NTP的替代方案很多物联网设备需要准确的时间例如用于定时任务或给数据打时间戳。在微控制器上实现完整的NTP客户端并处理时区、夏令时非常复杂。Adafruit提供了一个更简单的方案使用Adafruit IO的免费时间服务。注册Adafruit IO账号访问io.adafruit.com用邮箱注册一个免费账户。获取AIO Key登录后点击右上角“My Key”你会看到AIO_KEY和用户名。更新settings.tomlCIRCUITPY_WIFI_SSID 你的WiFi名称 CIRCUITPY_WIFI_PASSWORD 你的WiFi密码 ADAFRUIT_AIO_USERNAME 你的Adafruit IO用户名 ADAFRUIT_AIO_KEY 你的AIO Key TIMEZONE Asia/Shanghai # 时区从worldtimeapi.org/timezones查找运行时间测试代码将项目资料中获取时间的Python代码复制到code.py并运行。如果串口打印出了格式化的本地时间如2023-10-27 14:30:00.000说明时间服务配置成功。注意事项Adafruit IO时间服务虽然方便但它依赖于你的设备能成功连接到Adafruit的服务器。对于网络环境特殊的地区可能需要确保设备能正常访问io.adafruit.com。此外免费账号有请求频率限制但对于本项目“一天一次”的更新频率来说绰绰有余。5. 疫苗接种追踪器应用代码深度剖析这是项目的核心我们将一步步拆解代码理解其如何获取数据、解析数据并控制显示。5.1 项目库与代码结构部署不要手动一个个下载库文件。Adafruit为这个项目提供了“项目包”Project Bundle。在项目页面找到“Download Project Bundle”按钮并点击下载一个.zip文件。解压该zip文件。将解压后文件夹内的lib文件夹包含所有依赖库和code.py文件整体复制到CIRCUITPY磁盘的根目录覆盖原有文件。确保你的settings.toml文件已经正确配置了WiFi信息以及可选的Adafruit IO信息。此时你的CIRCUITPY磁盘应该包含以下关键内容CIRCUITPY/ ├── code.py # 主程序 ├── settings.toml # 配置文件含WiFi密码 ├── lib/ # 库文件夹 │ ├── adafruit_magtag/ │ ├── adafruit_progressbar/ │ ├── adafruit_requests/ │ └── ... (其他依赖库) └── bmps/ # 可能包含背景图片 └── background.bmp5.2 主程序代码逐行解读让我们打开code.py看看这个物联网追踪器是如何工作的。第一部分初始化与网络连接from adafruit_magtag.magtag import MagTag from adafruit_progressbar.progressbar import ProgressBar DATA_SOURCE https://raw.githubusercontent.com/owid/covid-19-data/master/public/data/vaccinations/country_data/United%20States.csv magtag MagTag(urlDATA_SOURCE) magtag.network.connect()MagTag类是一个高级封装它集成了对显示屏、网络、深度睡眠等所有硬件的控制。DATA_SOURCE指向Our World in Data项目在GitHub上托管的美国疫苗接种数据CSV文件。这是一个公开、结构化的数据源。magtag.network.connect()会读取settings.toml中的WiFi信息并连接网络。第二部分构建用户界面UI代码通过多次调用magtag.add_text()创建了四个文本标签分别用于显示标题、日期、接种百分比和完全接种百分比。每个add_text都指定了字体文件位置、文本在屏幕上的坐标(x, y)以及锚点。is_dataFalse表示这些是静态标签后续会用set_text动态更新其内容。 接着代码创建了两个ProgressBar进度条对象定义了它们的位置、大小和颜色并将它们添加到显示组中。最后设置了一张背景图片。第三部分数据获取、解析与显示逻辑核心逻辑包裹在一个try...except块中这是为了捕获任何网络或数据处理错误并执行降级处理例如缩短重试间隔。获取数据magtag.fetch()方法会向DATA_SOURCE发起HTTP GET请求并返回CSV格式的文本数据。解析数据原始代码使用了一个自定义的l_split函数来解析CSV行。这个函数比简单的split(,)更健壮因为它能处理字段内包含逗号被引号包裹的情况。解析后我们得到表头列表columns和最新数据行列表latest。数据计算将columns和latest组合成字典value方便通过键名如”people_vaccinated”访问数据。然后用接种人数除以美国总人口代码中硬编码为331984513得到接种比例。关键点这个分母人口数是需要你根据所选国家/地区手动修改的如果追踪其他国家必须更新这个数字否则百分比计算会完全错误。你可以在Our World in Data的数据集中找到对应的人口数据。更新UI使用magtag.set_text()和索引号0,1,2,3来更新之前创建的四个文本标签。同时将计算出的比例赋值给两个进度条的.progress属性。刷新屏幕调用magtag.refresh()。这是最耗电的操作E-Ink屏会进行全局刷新更新所有像素点。第四部分低功耗循环SECONDS_TO_SLEEP 24 * 60 * 60 # 24小时 magtag.exit_and_deep_sleep(SECONDS_TO_SLEEP)数据显示完毕后程序计算24小时的秒数并调用magtag.exit_and_deep_sleep()。这个函数会保存状态然后让ESP32-S2进入深度睡眠模式。此时CPU、WiFi、大部分内存都会断电仅由RTC计时。24小时后RTC定时器会触发复位设备重启从头开始执行code.py从而完成一次数据更新循环。 如果在try块中发生任何错误网络错误、数据格式错误等程序会跳转到except块打印错误信息并将睡眠时间设置为1小时然后进入深度睡眠。这意味着设备会在1小时后重试而不是傻等到明天。6. 项目定制化、优化与深度问题排查原项目是一个很好的起点但要让其更实用或适配你的需求还需要一些调整和优化。6.1 如何追踪其他国家或地区的数据这是最常被问到的定制需求。Our World in Data项目提供了全球数据。修改数据源URL访问其GitHub仓库找到你想要的国家文件。例如德国的数据文件是Germany.csv。将DATA_SOURCE变量中的文件名改为Germany.csv。更新人口基数这是必须修改的一步原代码中的331984513是美国2020年左右的估算人口。你需要查找你目标国家的最新人口数据可以从世界银行等机构获取并替换这个分母。调整显示文本你可能还想修改magtag.set_text中的标题文字例如将”United States Vaccination Rates”改为”Germany Vaccination Rates”。6.2 功耗分析与续航估算理解功耗是优化电池寿命的关键。设备的工作周期分为几个阶段启动与连接约10-20秒电流峰值可能达到100mA以上。数据获取与处理约2-5秒电流与连接阶段类似。屏幕刷新约2-3秒这是另一个电流峰值可能超过150mA。深度睡眠23小时59分钟电流可低至10-20µA微安。续航估算 假设使用420mAh电池。活跃期功耗取高值150mA持续30秒消耗电量 ≈ (150mA * 30s) / 3600s/h 1.25 mAh。睡眠期功耗取20µA持续24小时消耗电量 ≈ (0.02mA * 24h) 0.48 mAh。每日总耗电约 1.25 0.48 1.73 mAh。理论续航420 mAh / 1.73 mAh/天 ≈243天。当然这是理想情况。实际中电池自放电、WiFi连接不稳定导致重试、极端温度等因素都会缩短续航。但即便如此持续工作数月是完全可以期待的。6.3 常见问题与排查实录在复现和调试过程中我遇到了以下几个典型问题问题1屏幕刷新后残留鬼影现象更新数据后屏幕上留有上一屏内容的浅色痕迹。原因电子墨水屏在长时间显示静态图像后可能会产生“残影”。这是其物理特性并非故障。解决方案在magtag.refresh()之前可以尝试先调用一次magtag.display.show(None)清空显示组或者确保每次刷新都是完整的全局刷新。Adafruit的库通常已做处理但偶尔仍会出现。可以尝试在代码中定期比如每10次刷新插入一次全屏反色刷新来缓解。对于本项目一天一次的频率鬼影影响不大。问题2设备无法从深度睡眠中唤醒现象设备运行一次后沉睡再也没醒过来。排查检查magtag.exit_and_deep_sleep()的参数是否正确单位是秒。确保电池电量充足。深度睡眠需要RTC模块维持供电如果电池电压过低RTC可能无法工作。检查USB线如果在通过USB供电调试时进入深度睡眠有些电脑的USB端口在设备进入深度睡眠后可能会停止供电导致设备“假死”。最好在测试深度睡眠功能时断开USB使用电池供电。问题3网络请求失败程序陷入每小时重试循环现象串口日志显示一直在重试错误。排查首先运行最基本的网络测试代码确认WiFi连接本身没问题。检查DATA_SOURCE的URL是否有效可以直接在电脑浏览器打开这个链接看是否能返回CSV数据。检查GitHub的Raw文件访问是否在你的网络环境中受限某些网络环境可能对GitHub raw域名有限制。可以尝试将数据文件缓存到更稳定的服务器上并修改URL。在except块中增加更详细的错误类型捕获和打印例如打印出e的具体内容帮助定位是网络超时、DNS解析失败还是数据解析错误。问题4进度条或文本显示位置错乱现象文字重叠、进度条跑出屏幕外。原因add_text和ProgressBar初始化时设置的坐标(x, y)不准确。解决方案2.9英寸屏幕的分辨率是296x128像素。坐标原点(0,0)在屏幕左上角。你可以通过计算来精确定位。例如(magtag.graphics.display.width // 2) - 1是屏幕水平中心点。通过串口打印出这些坐标值进行调试。对于进度条BAR_X, BAR_Y, BAR_WIDTH, BAR_HEIGHT这四个参数共同决定了其位置和大小。这个项目就像一把钥匙帮你打开了使用CircuitPython和ESP32-S2构建实用物联网设备的大门。它的代码结构清晰将网络、显示、低功耗逻辑分离得很好你可以很容易地将数据源替换成天气预报API、股票价格、待办事项列表或者你自家传感器的读数。电子墨水屏的低功耗特性与ESP32-S2的深度睡眠能力相结合为那些需要长期、安静、免维护运行的户外或室内信息显示场景提供了一个极具性价比的解决方案。我个人的体会是成功跑通这个项目后你再去看其他类似的物联网显示项目会发现思路都大同小异无非是换换数据源、改改UI布局底层的那套连接、获取、解析、显示、休眠的流程你已经完全掌握了。