基于ESP32与电子墨水屏打造低功耗物联网状态显示器

1. 项目概述：打造你的桌面深空观测站

如果你和我一样，既是个天文爱好者，又是个硬件DIY的发烧友，那么把遥远宇宙的探索成果“搬”到自己的桌面上，绝对是一件充满成就感的事。詹姆斯·韦伯空间望远镜（JWST）作为人类目前最强大的太空之眼，它的每一次数据回传都牵动着无数人的心。与其不断刷新网页查看状态，不如自己动手，做一个专属的、低功耗的物理状态显示器，让望远镜的“体温”和状态实时呈现在眼前。

这个项目的核心，就是利用Adafruit MagTag这块神奇的开发板。它集成了ESP32-S2 Wi-Fi芯片和一块2.9英寸的灰度电子墨水屏，天生就是为了低功耗、常显的物联网信息牌而生的。我们通过CircuitPython这种对初学者极其友好的编程语言，编写一段代码，让MagTag定时醒来，去NASA的服务器“问”一下韦伯望远镜的最新状态数据，然后把关键信息——比如各个仪器和舱段的温度——优雅地显示在电子墨水屏上。完成后，它就会进入深度睡眠，直到下一个刷新周期，如此循环，一块小电池就能撑上很久。

整个流程听起来复杂，但拆解开来，其实就是几个清晰步骤的串联：硬件准备、环境搭建、网络连接、数据抓取、界面绘制、睡眠管理。无论你是想学习物联网设备开发，还是想为你的创客项目找一个有趣的切入点，这个项目都能提供一条从原理到实践的完整路径。接下来，我会带你一步步走通，并分享我在这个过程中踩过的坑和总结出的技巧。

2. 硬件选型与核心组件解析

工欲善其事，必先利其器。这个项目的硬件选择非常明确，核心就是Adafruit MagTag。但理解为什么选它，以及它周边的“配角”如何搭配，能让你在后续开发和问题排查时更加得心应手。

2.1 核心大脑：Adafruit MagTag开发板

MagTag并不是一个简单的ESP32开发板加屏幕的拼凑品，而是一个高度集成、为特定场景优化的解决方案。它的核心优势在于超低功耗设计和开箱即用的显示系统。

• ESP32-S2芯片：这是整个设备的“大脑”和“通信官”。相比经典的ESP32，S2版本去掉了蓝牙，专注于Wi-Fi连接，并且在深度睡眠模式下的功耗控制得更好。它负责执行我们的CircuitPython代码，发起网络请求，并控制屏幕刷新。
• 2.9英寸灰度电子墨水屏：这是项目的“脸面”。电子墨水屏的特性是只在刷新图像时才消耗电能，一旦图像显示完成，即使断电，画面也能持续保留。这完美契合了我们“定时更新、长期显示”的需求。MagTag的屏幕驱动已经集成在板子上，我们通过CircuitPython的displayio库就能轻松控制，无需关心底层时序。
• 内置电池管理：板载了锂电池充电电路和连接器，你可以直接接上一块3.7V的锂聚合物电池（比如常见的500mAh或更大容量的），它就能脱离USB线独立工作。充电和电量监控都交给了板载芯片，省去了额外设计的麻烦。
• 四个多功能按钮：板载的四个按钮（标记为A、B、C、D）在项目中可以作为手动触发刷新、切换显示模式或进入配置模式的入口，提供了交互的可能性。

实操心得：购买时请注意区分版本。早期的MagTag（正面为白色阻焊层）可能没有预装UF2引导程序，需要多一步刷机操作。而较新的版本（正面为黑色）通常已预装，使用起来更方便。在项目资料中提到的“2025 Edition”则必须使用CircuitPython 10.x或更高版本。

2.2 必要配件与选型建议

除了MagTag本体，你还需要准备以下几样东西：

1. USB-C数据线：必须是数据线，而不能是仅能充电的线。很多人在第一步就卡住，电脑识别不到设备，问题往往出在线上。一条质量可靠的USB-C to USB-A数据线是必备的。
2. 锂聚合物电池：推荐使用Adafruit推荐的500mAh或更高容量的电池。电池容量决定了设备在两次充电间能工作的时长。根据代码中设置的睡眠时间（例如每小时唤醒一次），一块500mAh的电池理论上可以持续工作数周甚至数月。电池的接口通常是JST-PH 2-pin，与MagTag上的插座匹配。
3. 可选配件：
   • 外壳与支架：Adafruit官方提供了亚克力面板和硬件套件，能让你的MagTag立起来，更像一个精致的桌面摆件。
   • 磁吸脚垫：如果你想把它吸附在冰箱、白板等金属表面，磁吸脚垫会非常方便。

这些配件并非必需，但它们能极大提升项目的完成度和美观性。我的建议是，至少把电池配上，体验一下它完全无线工作的魅力。

3. 软件环境搭建与CircuitPython固件烧录

硬件准备就绪后，我们要为它注入“灵魂”——CircuitPython固件。这个过程相当于给一块空白的单片机安装操作系统。

3.1 理解CircuitPython与MicroPython

CircuitPython是Adafruit基于MicroPython开发的一个分支，它最大的特点是极致的易用性。在CircuitPython中，你的代码文件（code.py）和库文件都存放在一个名为CIRCUITPY的U盘里。你只需要用电脑像操作普通文件一样编辑code.py，板子就会自动运行最新的代码。这彻底改变了传统嵌入式开发中“编译-烧录-调试”的循环，特别适合快速原型开发和教育。

3.2 固件烧录的三种方法

根据你的MagTag版本和电脑环境，有三种方法可以安装CircuitPython。我强烈推荐第一种方法，它是最简单的。

方法一：UF2引导程序拖放安装（推荐）这种方法适用于绝大多数新版MagTag。操作如同拷贝文件一样简单：

1. 前往CircuitPython官网，找到MagTag的页面，下载最新的.UF2文件。
2. 用USB线连接MagTag和电脑。
3. 快速双击MagTag上的Reset按钮（位于USB-C口旁边）。如果成功，电脑上会出现一个名为MAGTAGBOOT的U盘。
4. 将下载好的.UF2文件直接拖入MAGTAGBOOT盘符。完成后，设备会自动重启，此时会出现一个名为CIRCUITPY的新盘符。恭喜，固件安装成功！

注意事项：在Windows系统上，拖放完成后可能会弹出“设备不存在”的错误。这通常是正常的，因为引导程序在完成写入后会立即断开连接。只要CIRCUITPY盘符出现了，就说明安装成功。如果这个错误让你困扰，可以尝试更新板子的TinyUF2引导程序到最新版。

方法二：使用esptool通过串行引导程序安装如果你的MagTag是早期白色版本，可能无法进入UF2模式。这时需要使用更底层的工具esptool。

1. 在电脑上安装Python和esptool(pip install esptool)。
2. 下载CircuitPython的.bin文件。
3. 让MagTag进入“下载模式”：按住板上的“BOOT”按钮（如果有）或特定组合键，再按一下“Reset”，然后释放。
4. 使用esptool.py命令行工具，指定正确的串口和.bin文件路径进行烧录。命令类似：esptool.py --chip esp32s2 --port COM3 write_flash 0x1000 firmware.bin。
5. 烧录完成后，按Reset键，CIRCUITPY盘符应出现。

方法三：使用Chrome浏览器的Web Serial ESPTool这是为不熟悉命令行或Python环境的用户准备的“救星”方案。你只需要一个Chrome或Edge浏览器。

1. 打开 Web Serial ESPTool 页面。
2. 点击“Connect”并选择你的MagTag对应的串口。
3. 点击“Erase”擦除原有固件。
4. 点击“Program”并选择你下载的.bin或.uf2文件进行烧录。 这个工具的本质是一个运行在浏览器里的esptool，避免了本地环境配置的麻烦。

无论采用哪种方法，最终目标都是让电脑上出现CIRCUITPY这个可移动磁盘。这是你后续所有操作的“工作区”。

4. 网络配置与首次连接测试

让设备“上网”是物联网项目的第一步。CircuitPython通过一个名为settings.toml的配置文件来管理Wi-Fi密码等敏感信息，这是一个非常巧妙和安全的设计。

4.1 安全配置Wi-Fi：settings.toml文件详解

在CIRCUITPY盘符的根目录下，你会找到一个（可能是空的）settings.toml文件。用任何文本编辑器（如VS Code、Notepad++）打开它。这个文件的作用是存储所有需要保密的配置信息，比如Wi-Fi密码、API密钥等。这样做的好处是，当你分享code.py主程序时，不会不小心把密码也泄露出去。

对于我们的项目，最基本的配置如下：

CIRCUITPY_WIFI_SSID = "你的Wi-Fi网络名称" CIRCUITPY_WIFI_PASSWORD = "你的Wi-Fi密码"

请务必将双引号内的内容替换成你实际的网络信息。非常重要：保存这个文件后，永远不要把它上传到GitHub或其他公开代码仓库。

4.2 编写并运行网络测试代码

在确认settings.toml配置正确后，我们需要一个简单的程序来测试网络是否连通。将下面的代码保存为CIRCUITPY盘根目录下的code.py文件。CircuitPython会自动运行这个文件。

# SPDX-FileCopyrightText: 2020 Brent Rubell for Adafruit Industries # SPDX-License-Identifier: MIT import os import wifi import socketpool import adafruit_requests import ssl import ipaddress # 测试用的URL TEXT_URL = "http://wifitest.adafruit.com/testwifi/index.html" JSON_URL = "https://api.github.com/repos/adafruit/circuitpython" print("MagTag 网络连接测试") print(f"MAC地址: {[hex(i) for i in wifi.radio.mac_address]}") # 扫描并列出附近的Wi-Fi网络（可选，用于诊断） print("可用的Wi-Fi网络:") for network in wifi.radio.start_scanning_networks(): print(f"\t{str(network.ssid, 'utf-8')}\t信号强度: {network.rssi} dBm") wifi.radio.stop_scanning_networks() # 从settings.toml读取配置并连接 ssid = os.getenv("CIRCUITPY_WIFI_SSID") password = os.getenv("CIRCUITPY_WIFI_PASSWORD") print(f"正在连接到: {ssid}") wifi.radio.connect(ssid, password) print(f"已连接到: {ssid}") print(f"获取到的IP地址: {wifi.radio.ipv4_address}") # 测试网络连通性：ping一个DNS服务器 ping_ip = ipaddress.IPv4Address("8.8.8.8") # Google DNS ping_time = wifi.radio.ping(ip=ping_ip) if ping_time is None: ping_time = wifi.radio.ping(ip=ping_ip) # 再试一次 if ping_time is not None: print(f"Ping 8.8.8.8 耗时: {ping_time * 1000:.0f} ms") else: print("Ping 测试失败，但可能仍可连接。") # 创建网络会话 pool = socketpool.SocketPool(wifi.radio) requests = adafruit_requests.Session(pool, ssl.create_default_context()) # 测试获取网页文本 print(f"\n从 {TEXT_URL} 获取文本...") response = requests.get(TEXT_URL) print("-" * 40) print(response.text) print("-" * 40) # 测试获取并解析JSON数据 print(f"\n从 {JSON_URL} 获取JSON数据...") response = requests.get(JSON_URL) data = response.json() print("-" * 40) print(f"CircuitPython GitHub 星标数: {data['stargazers_count']}") print("-" * 40) print("\n网络测试完成！")

将代码保存后，MagTag会自动重启并运行。要查看打印信息，你需要一个串口监视器。推荐使用Mu Editor（CircuitPython官网推荐），或者Thonny，或者任何能打开串口的工具（如VS Code的Serial Monitor扩展、PuTTY等）。连接端口后，你应该能看到类似以下的输出：

MagTag 网络连接测试 MAC地址: ['0xde', '0xad', '0xbe', '0xef', '0x00', '0x01'] 可用的Wi-Fi网络: MyHomeWiFi 信号强度: -45 dBm ... 正在连接到: MyHomeWiFi 已连接到: MyHomeWiFi 获取到的IP地址: 192.168.1.123 Ping 8.8.8.8 耗时: 23 ms ... CircuitPython GitHub 星标数: 15000 网络测试完成！

如果看到了IP地址和成功的网络请求，恭喜你，最关键的联网步骤已经打通了！如果失败，请按以下步骤排查：

1. 检查settings.toml中的SSID和密码是否正确，大小写和特殊字符尤其要注意。
2. 检查USB线是否是数据线。
3. 检查Wi-Fi是否是2.4GHz网络（ESP32-S2不支持5GHz）。
4. 在串口监视器中查看具体的错误信息。

5. 项目文件部署与代码结构剖析

网络测试通过后，我们就可以开始部署真正的韦伯望远镜状态监控项目了。这个项目不仅仅是一个code.py文件，它还需要特定的字体文件和库支持。

5.1 获取并部署项目文件包

最可靠的方式是从Adafruit学习系统的项目页面（原资料中的链接）下载完整的“项目文件包”（Project Bundle）。这个ZIP包通常包含：

• code.py：主程序文件。
• lib/文件夹：包含所有必需的CircuitPython库文件，如adafruit_requests,adafruit_display_text等。
• fonts/文件夹：包含用于显示的定制字体文件（例如LeagueSpartan-Light.bdf）。

部署步骤：

1. 下载ZIP包并解压。
2. 将解压后得到的code.py文件、整个lib文件夹和fonts文件夹，复制到你的CIRCUITPY盘根目录。
3. 如果CIRCUITPY盘上已有旧的code.py或lib文件夹，请覆盖它们。

完成后，你的CIRCUITPY盘的文件结构应该大致如下：

CIRCUITPY/ ├── code.py ├── settings.toml ├── lib/ │ ├── adafruit_requests.mpy │ ├── adafruit_display_text/ │ └── ... (其他依赖库) └── fonts/ └── LeagueSpartan-Light.bdf

5.2 核心代码逻辑深度解读

现在，让我们打开code.py，像读一篇技术小说一样，逐段理解作者的构思。代码虽长，但结构清晰。

5.2.1 初始化与配置代码开头导入必要的库，并从settings.toml读取Wi-Fi配置。这里有一个关键设计：如果找不到配置，程序会直接抛出错误，防止无意义的运行。

ssid = getenv("CIRCUITPY_WIFI_SSID") password = getenv("CIRCUITPY_WIFI_PASSWORD") if None in [ssid, password]: raise RuntimeError("请将Wi-Fi配置置于settings.toml文件中...")

接下来，定义了更新间隔SLEEP_TIME（默认为1小时）和数据源URL。这里有一个至关重要的点：原项目依赖的第三方API服务器可能已失效。代码中预留了TEST_RUN = True的开关和FAKE_DATA模拟数据，就是为了在开发时，即使没有网络也能测试显示效果。在实际部署前，你需要将TEST_RUN改为False，并确保数据URL有效。根据资料提示，可能需要寻找新的NASA官方JSON数据源或自行搭建解析服务器。

5.2.2 显示系统的构建：Group与Label这是图形界面的核心。CircuitPython的displayio库采用“显示组（Group）”和“标签（Label）”的层级结构。

# 创建主显示组，所有元素都放在这里面 main_group = displayio.Group() # 加载自定义字体，提升显示美观度 font = bitmap_font.load_font("fonts/LeagueSpartan-Light.bdf")

然后，代码创建了多个Label对象来显示不同的数据块：

• top_left_value: 显示望远镜“热侧”和“冷侧”的温度（摄氏度）。
• top_right_value: 显示五个核心科学仪器的温度（开尔文）。
• timestamp_val: 显示数据获取的时间戳。
• middle_left_name和top_center_name: 作为上述数据值的标题标签。

每个Label都通过anchor_point（锚点，如(0,0)代表左上角）和anchored_position（基于锚点的绝对坐标）进行精确定位。这种定位方式比直接设置x, y坐标更灵活，特别是在元素大小动态变化时。

5.2.3 数据获取与错误处理在if not TEST_RUN:的代码块中，程序执行真正的网络操作：

1. 连接Wi-Fi：使用配置的SSID和密码。
2. 创建网络会话：adafruit_requests.Session用于管理HTTP请求。
3. 发起GET请求：向指定的NASA JSON数据URL发起请求，并设置超时（timeout=30秒）。
4. 错误处理：如果连接或请求失败，程序会打印错误并调用supervisor.reload()在3秒后重启。这是一个非常实用的设计，因为物联网设备在无人值守时，网络波动是常事，自动重启是最简单的恢复手段。
5. 解析JSON：成功获取响应后，使用.json()方法解析数据，并从中提取我们需要的温度字段。

5.2.4 数据填充与屏幕刷新解析出数据后，将其填充到之前创建好的Label对象的.text属性中。例如：

top_right_value.text = "{}K\n{}K\n{}K\n{}K\n{}K".format( json_data["currentState"]["tempInstNirCamK"], json_data["currentState"]["tempInstNirSpecK"], ...)

所有数据填充完毕后，通过display.root_group = main_group将主显示组设置为当前显示内容。最后，调用一个自定义的try_refresh()函数来更新电子墨水屏。

5.2.5 深度睡眠与定时唤醒：低功耗的秘诀这是本项目实现超长续航的关键。代码没有使用常见的while True循环，而是在执行完一次所有任务后，安排一个“闹钟”，然后进入深度睡眠。

# 创建一个在‘SLEEP_TIME’秒后触发的闹钟 time_alarm = alarm.time.TimeAlarm(monotonic_time=time.monotonic() + SLEEP_TIME) # 退出并深度睡眠，直到闹钟唤醒 alarm.exit_and_deep_sleep_until_alarms(time_alarm)

time.monotonic()返回一个从开机起持续递增的时间（秒），不受系统时间更改影响。SLEEP_TIME是之前定义的间隔（如3600秒）。执行alarm.exit_and_deep_sleep_until_alarms()后，ESP32-S2的绝大部分电路会被关闭，仅保留维持RTC（实时时钟）和唤醒逻辑的极微小电流，功耗可以低至几十微安。当设定的时间到达，硬件会自动将芯片唤醒，并从程序开头重新执行code.py。这种“执行-睡眠-唤醒”的范式，是电池供电物联网设备的黄金标准。

5.2.6 针对E-Ink的“小心机”：try_refresh函数电子墨水屏有一个物理限制：两次完整刷新之间需要一定的时间间隔（通常是几秒）。如果代码试图过快刷新，会抛出RuntimeError。原代码中的try_refresh()函数优雅地处理了这个问题：

def try_refresh(): try: board.DISPLAY.refresh() except RuntimeError as too_soon_error: print(too_soon_error) print("刷新过快，等待10秒后重试...") time.sleep(10) board.DISPLAY.refresh()

它尝试刷新，如果捕获到“刷新太快”的异常，就等待10秒再试一次。这种防御性编程在硬件交互中非常重要。

6. 高级定制、问题排查与优化建议

当你的设备成功运行起来后，你可能不满足于仅仅复现。这里有一些进阶玩法和常见问题的解决方案。

6.1 项目定制化改造思路

1. 更换数据源：这是最大的挑战，也是最大的乐趣。原API失效后，你可以：

   • 寻找替代API：搜索是否有其他天文机构或爱好者提供了JWST状态的JSON接口。
   • 自行搭建解析服务器：使用Python（Flask/Django）、Node.js等，写一个简单的服务，定期抓取NASA官方状态页（HTML），解析出需要的数据，然后提供干净的JSON API给你的MagTag。这需要你有一台能运行Python的服务器（甚至可以是树莓派）。
   • 修改为其他数据源：这个项目的框架是通用的。你可以轻松地将数据源URL换成任何返回JSON的公开API，比如天气预报、股票价格、加密货币行情、待办事项列表等，打造属于你自己的信息牌。

2. 调整显示布局与样式：

   • 修改坐标：调整anchored_position的参数，可以改变文字的位置。
   • 更换字体：你可以使用任何.bdf格式的位图字体。在网上找到喜欢的字体，用工具转换成.bdf格式，放入fonts/文件夹，并在代码中修改load_font的路径即可。
   • 改变颜色：MagTag是灰度屏，颜色用十六进制表示，如0x000000（黑）、0xFFFFFF（白）、0x888888（灰）。调整background_color和color参数可以改变标签的背景色和文字颜色。

3. 调整更新频率：修改SLEEP_TIME变量。60 * 60是一小时，60 * 60 * 24是一天。更短的间隔意味着更耗电，你需要权衡信息的及时性和电池续航。

4. 增加交互功能：利用板载的四个按钮（A, B, C, D）。你可以在代码开头检查supervisor.runtime.safe_mode_reason或通过alarm.wake_alarm来判断是定时唤醒还是按钮唤醒，从而实现“手动刷新”或“切换显示页面”的功能。

6.2 常见问题与故障排除速查表

6.3 功耗优化与续航估算

对于这类显示设备，功耗主要来自三部分：Wi-Fi连接/数据传输、屏幕刷新和待机（睡眠）。

• Wi-Fi活动期：ESP32-S2在全力工作（射频开启）时，电流可达100mA以上。一次网络连接和数据获取可能持续2-5秒。
• 屏幕刷新期：电子墨水屏刷新全屏时，电流峰值也可能达到几十mA，持续1-2秒。
• 深度睡眠期：这是绝大部分时间所处的状态。ESP32-S2在深度睡眠下，电流可以低至20µA左右。

做一个简单的续航估算： 假设使用一块500mAh的电池。

• 每小时唤醒一次，每次活跃（Wi-Fi+刷新）耗时5秒，消耗电流平均100mA。
• 每次活跃消耗的电量：100mA * (5/3600)h ≈ 0.139 mAh。
• 每小时睡眠59分55秒，消耗电流20µA (0.02mA)。
• 每小时睡眠消耗的电量：0.02mA * (3595/3600)h ≈ 0.020 mAh。
• 每小时总耗电：约0.159 mAh。
• 理论续航：500 mAh / 0.159 mAh/h ≈ 3145小时 ≈ 131天。

这只是一个理想估算，实际会因网络信号强度（重试会增加功耗）、环境温度、电池自放电等因素缩短。但即便如此，持续工作数月是完全可能的。如果将更新频率改为每天一次，续航时间将以年计。

7. 从项目实践中提炼的嵌入式开发思维

完成这个项目后，你收获的不仅仅是一个酷炫的桌面摆件，更是一套适用于众多低功耗物联网（IoT）场景的开发模式。我们可以把这个项目的架构抽象成一个通用模板，其核心流程是：初始化 -> 联网 -> 获取数据 -> 处理/显示数据 -> 进入低功耗睡眠 -> （定时/事件）唤醒 -> 重复。

这个模式可以迁移到无数场景中：

• 环境监测站：连接温湿度、空气质量传感器，每小时上报一次数据到云端，并在本地小屏显示。
• 邮箱/快递通知器：通过查询API，在有新邮件或快递更新时，点亮一个LED或更新屏幕提示。
• 简易信息看板：抓取新闻头条、TODO列表、倒计时等信息进行轮播显示。

在开发这类项目时，有几点思维至关重要：

1. 状态无记忆设计：由于每次唤醒都相当于重启，你的代码必须假设这是“第一次运行”。所有需要持久化的配置（如Wi-Fi密码）应放在settings.toml或单独的配置文件里，而非代码变量中。
2. 防御性编程：网络是不稳定的，外设可能出错。代码中必须包含充分的错误处理（try...except）和恢复机制（如重启supervisor.reload()）。原项目中处理网络失败和屏幕刷新过快的方式就是典范。
3. 功耗意识：任何不必要的延迟(time.sleep)、常亮的LED、未关闭的外设，都在消耗宝贵的电池电量。设计时要时刻思考“这个操作是否必要？能否在睡眠前关闭？”
4. 离线能力：考虑网络完全不可用的情况。是否可以显示上次成功获取的数据？是否可以给出一个友好的错误提示，而不是白屏或乱码？原项目的TEST_RUN和FAKE_DATA就是一种离线兜底策略。

最后，关于这个韦伯望远镜项目本身，我最大的体会是：开源硬件和生态的魅力在于连接。它连接了遥远的星空与你的桌面，连接了复杂的航天工程与个人可及的编程乐趣，也连接了全球开发者分享的代码与灵感。当屏幕上那些代表着零下两百多度的数字真实地更新时，你能真切地感受到，自己通过几行代码，参与到了人类最前沿的宇宙探索之中。这种跨越空间的连接感，正是创客项目最迷人的地方。希望这个详细的指南，能帮你顺利搭建起这座连接你与星辰的小小桥梁。如果在制作过程中遇到任何新的问题，不妨回到代码和原理本身，耐心分析串口输出，那里面通常藏着所有问题的答案。