1. 项目概述与核心价值如果你对物联网开发感兴趣或者一直想做一个能摆在桌面上、实时显示环境数据的“小玩意儿”那么这个基于PyPortal和AirNow API的空气质量监测显示系统绝对是一个能让你从零到一跑通整个物联网数据流、并且最终获得一个实用成果的绝佳项目。我最初做这个就是想直观地看到自己所在区域的空气质量变化特别是PM2.5指数毕竟这玩意儿看不见摸不着但数据摆在眼前出门前看一眼心里就有底了。这个项目的核心逻辑非常经典一个联网的嵌入式设备定期向一个提供数据的远程服务器API发起请求拿到结构化的数据通常是JSON格式然后解析出我们需要的关键信息最后用最直观的方式——比如不同颜色的背景和醒目的数字——显示在一块屏幕上。整个过程涵盖了物联网开发的几个核心环节硬件初始化、网络连接、API调用、数据解析和图形化显示。通过复现这个项目你不仅能得到一个实用的空气质量监测仪更能透彻理解现代物联网应用是如何“呼吸”数据的。2. 硬件选型与核心组件解析2.1 为什么选择PyPortal在众多嵌入式开发板中我选择Adafruit的PyPortal作为这个项目的核心主要基于以下几个硬核理由这些理由也是你在为类似项目选型时需要重点考量的。首先开箱即用的显示与网络能力是PyPortal最大的优势。它集成了一块3.2英寸、320x240分辨率的彩色触摸屏这意味着你不需要再额外费心去连接和驱动一个显示屏省去了大量的硬件接线和底层驱动调试工作。对于数据可视化项目来说一个集成度高、驱动完善的显示模块能让你把精力完全集中在应用逻辑上。其次它内置了ESP32 Wi-Fi协处理器。ESP32以其稳定、成熟的Wi-Fi协议栈和社区支持而闻名PyPortal利用它来处理所有网络通信使得在MicroPython或CircuitPython环境中进行Wi-Fi连接和HTTP请求变得异常简单几乎就是几行代码的事。这种“网络显示”的一体化设计极大地降低了项目的入门门槛和复杂度。其次极佳的开发体验。PyPortal原生支持CircuitPython这是一种基于Python 3的嵌入式编程语言。对于熟悉Python的开发者来说这意味着几乎没有学习成本你可以直接使用requests类似的库在CircuitPython中是adafruit_requests来获取网络数据用PILPython Imaging Library类似的图像库来绘制界面。整个开发流程就像在写一个桌面Python脚本但最终它能跑在一个巴掌大的硬件上这种体验非常流畅。此外PyPortal还内置了SD卡槽、扬声器驱动、光线传感器等为项目未来的功能扩展比如数据本地存储、声音报警、根据环境光调节屏幕亮度预留了空间。最后丰富的社区与生态。Adafruit为其产品提供了极其详尽的教程、库文件和社区支持。你几乎能在其学习系统Learn Adafruit上找到任何关于PyPortal的示例项目从简单的网络时钟到复杂的物联网仪表盘。这种强大的生态支持能确保你在开发过程中遇到的大多数问题都能快速找到解决方案或参考代码。2.2 关键配件与物料清单除了PyPortal开发板本身为了让项目完整运行并有一个好的“归宿”你还需要准备以下物料。这份清单是我在实际搭建过程中总结出来的有些是必需品有些则能极大提升体验。PyPortal开发板项目核心无需多言。USB-C数据线用于供电和编程。建议选择质量好、带数据传输功能的线缆劣质线缆可能导致供电不稳或无法连接电脑。5V 2A以上的USB电源适配器项目最终需要长期插电运行一个稳定的电源至关重要。手机充电器通常可以胜任但务必确保其输出是5V电流不小于2A以保证PyPortal屏幕和Wi-Fi模块稳定工作。MicroSD卡可选但强烈推荐虽然PyPortal的板载闪存可以存储代码和字体但使用MicroSD卡会让文件管理更加灵活。你可以将大的背景图片、字体文件放在SD卡上方便更换而不必每次擦写整个板载存储。建议容量8GB或16GB格式化为FAT32格式。外壳可选但能极大提升完成度一个3D打印的外壳能让你的项目从“开发板加飞线”的实验室状态变成一件可以放在书架或冰箱上的精致产品。Adafruit官网提供了由Ruiz Bros.设计的PyPortal便携式外壳模型文件你可以选择自己打印或通过在线打印服务制作。在我的实现中我采用了这个外壳的基础版本但省略了电池、升压模块和扬声器因为我只需要它壁挂插电使用。磁铁或3M胶用于固定如果你想像我一样把它贴在冰箱上那么几片强力的钕铁硼磁铁或3M无痕胶贴就是必需品。我使用了带背胶的磁铁片粘在外壳背面效果非常牢固。注意电源是关键。我曾尝试用一个老旧的1A充电器供电在PyPortal全亮度显示并同时进行Wi-Fi数据传输时出现了屏幕闪烁甚至重启的情况。更换为2.4A的适配器后问题消失。因此为嵌入式设备提供充足且纯净的电源是保证长期稳定运行的第一步也是最容易忽视的一步。3. 软件环境搭建与核心库剖析3.1 CircuitPython固件刷写与初始化PyPortal出厂可能预装的是其他固件我们的第一步就是将其刷写成CircuitPython。这个过程非常简单但有几个细节需要注意。获取固件访问CircuitPython官网在下载页面找到PyPortal对应的.uf2固件文件。务必选择与你的硬件版本完全匹配的固件通常PyPortal只有一个型号但确认一下总没错。进入引导加载程序模式用USB线连接PyPortal和电脑。快速双击PyPortal板上的“Reset”按钮。此时电脑上会出现一个名为PORTALBOOT或CPLAYBOOT的U盘盘符。这个模式被称为“引导加载程序模式”是专门用来刷写固件的。刷写固件将下载好的.uf2文件直接拖拽或复制到PORTALBOOT盘符中。复制完成后PyPortal会自动重启。重启后电脑上会出现一个新的名为CIRCUITPY的U盘。恭喜这说明CircuitPython已经成功运行这个CIRCUITPY盘就是你后续存放代码和库文件的地方你可以像操作普通U盘一样操作它。3.2 核心Python库的安装与作用CircuitPython的核心功能通过库文件.mpy或.py文件扩展。我们需要将以下关键库复制到CIRCUITPY盘下的lib文件夹中。你可以通过Adafruit的CircuitPython库包Bundle一次性获取所有库。adafruit_pyportal.mpy这是本项目的“大脑”库。它封装了PyPortal硬件的所有高级操作包括网络请求、图形显示、触摸控制等。它内部会调用其他底层库为我们提供一个简洁的、面向对象的接口。在代码中我们通常只需创建一个PyPortal对象并配置好参数它就能帮我们处理大部分脏活累活。adafruit_requests.mpy用于发起HTTP/HTTPS请求的库。虽然adafruit_pyportal内部会用到它但有时我们可能需要更底层的控制了解这个库很有必要。它负责与ESP32 Wi-Fi协处理器通信执行实际的网络数据收发。adafruit_esp32spi/文件夹这是ESP32 Wi-Fi芯片的驱动库。如果你的项目使用ESP32作为网络接口PyPortal正是如此就需要这个库。它提供了连接Wi-Fi、创建Socket等底层网络功能。adafruit_bitmap_font/和adafruit_display_text/这两个库负责文本显示。adafruit_bitmap_font用于加载和解析点阵字体文件.bdf或.pcf格式adafruit_display_text则用于创建和管理屏幕上的文本标签对象。我们需要它们来显示AQI数值和描述文字。adafruit_io/可选如果你未来想将数据同步到Adafruit IO云平台这个库是必需的。虽然本项目直接显示数据但扩展数据上报功能时会用到。安装方法很简单从Adafruit的GitHub发布页下载对应版本务必与你的CircuitPython版本匹配的库包解压后将上述库文件或文件夹复制到CIRCUITPY盘的lib目录下即可。如果lib目录不存在就新建一个。3.3 项目文件结构与secrets.py安全管理一个清晰的文件结构有助于项目管理。在CIRCUITPY根目录下我建议这样组织CIRCUITPY/ ├── code.py # 主程序入口CircuitPython会自动运行此文件 ├── secrets.py # 保存Wi-Fi密码、API密钥等敏感信息 ├── lib/ # 第三方库目录 ├── fonts/ # 字体文件目录可存放.bdf字体 └── images/ # 背景图片目录可选本项目使用纯色背景其中secrets.py文件是安全管理的核心。我们绝对不应该将密码和API密钥硬编码在主程序里。secrets.py是一个Python模块它定义了一个包含敏感信息的字典。例如# secrets.py 内容 secrets { ssid: 你的Wi-Fi网络名称, password: 你的Wi-Fi密码, aio_username: 你的Adafruit IO用户名如需要, aio_key: 你的Adafruit IO密钥如需要, airnow_token: 你的AirNow API令牌, zip_code: 90210, # 你想查询的美国邮政编码 timezone: America/Los_Angeles, # 时区用于显示时间 }在主程序code.py中你可以这样引入并使用它们try: from secrets import secrets except ImportError: print(WiFi secrets are kept in secrets.py, please add them there!) raise WIFI_SSID secrets[ssid] WIFI_PASSWORD secrets[password] AIRNOW_TOKEN secrets[airnow_token] ZIP_CODE secrets[zip_code]这样做的好处是当你需要分享代码时只需分享code.py而将包含敏感信息的secrets.py排除在外有效避免了账号泄露的风险。这是嵌入式开发中的一个重要安全实践。4. AirNow API详解与数据获取策略4.1 API申请、配额与关键参数解读AirNow API是美国环境保护署EPA提供的官方空气质量数据接口对于美国境内的数据非常权威。要使用它你需要先在其官网免费注册一个账户并申请一个API密钥Token。这个过程通常很快密钥会通过邮件发送给你。拿到密钥后理解API的调用方式至关重要。根据项目资料我们使用的请求URL格式如下http://www.airnowapi.org/aq/forecast/zipCode/?formatapplication/jsonzipCode90210API_KEYYOUR_TOKEN我们来拆解这个URL中的关键查询参数formatapplication/json指定返回的数据格式为JSON这是最便于程序解析的格式。zipCode90210指定查询的邮政编码。这是定位数据的最核心参数确保你获取的是特定区域的空气质量预报。API_KEYYOUR_TOKEN你的身份凭证所有请求必须附带。这里需要特别注意API的调用配额Rate Limit。免费层级的AirNow API通常有每小时或每天的调用次数限制。我们的项目设定为每10分钟更新一次即每小时6次这完全在免费配额的安全范围内。但如果你打算部署多个设备或提高更新频率务必查阅最新的API条款避免因超限导致IP或密钥被临时封锁。4.2 JSON数据结构深度解析与遍历逻辑API返回的JSON数据是一个包含多个对象的数组List每个对象代表一种污染物在某个预报日期的数据。以下是针对一个污染物数据对象的深度解析{ DateIssue: 2019-03-09 , DateForecast: 2019-03-10 , ReportingArea: NW Coastal LA, StateCode: CA, Latitude: 34.0505, Longitude: -118.4566, ParameterName: PM2.5, AQI: 33, Category: { Number: 1, Name: Good }, ActionDay: false }ParameterName这是最关键的字段标识污染物类型。我们主要关注PM2.5细颗粒物。其他常见值还有O3臭氧、PM10可吸入颗粒物、NO2二氧化氮、CO一氧化碳。AQI该污染物的空气质量指数值是一个整数。这是我们最终要在屏幕上显示的核心数值。Category一个嵌套的子对象包含Number和Name直观地告诉我们AQI值对应的健康等级如“良好”。DateForecast该条数据所预报的日期。API通常会返回今天和明天的预报数据。ReportingAreaStateCode报告区域和州代码用于确认数据的地理位置。我们的目标是从返回的JSON数组中找到ParameterName为PM2.5并且DateForecast是今天或最近预报的那个对象然后提取出它的AQI值。在代码中这涉及到JSON的遍历和条件判断。原始资料提到使用json_path这是一种类似[1, AQI]的路径式访问。但在实际编程中更稳健的做法是使用循环遍历数组并检查每个对象的属性。因为API返回的数据顺序并非绝对固定使用硬编码的索引如[1]可能在API数据格式微调时导致程序出错。一个更健壮的解析代码片段如下import time def parse_airnow_data(json_data): # 获取当前日期用于匹配预报日期 current_date time.localtime() current_date_str {:04d}-{:02d}-{:02d}.format(current_date.tm_year, current_date.tm_mon, current_date.tm_day) pm25_data None for item in json_data: # 寻找PM2.5的数据并且预报日期是今天 if item.get(ParameterName) PM2.5 and item.get(DateForecast, ).startswith(current_date_str): pm25_data item break # 如果没找到今天的就找第一个PM2.5数据可能是明天的预报 if pm25_data is None: for item in json_data: if item.get(ParameterName) PM2.5: pm25_data item break if pm25_data: aqi pm25_data.get(AQI) category pm25_data.get(Category, {}).get(Name, Unknown) return aqi, category else: return None, Data not found这种解析方式不依赖于固定的数据顺序通过逻辑判断来定位所需数据鲁棒性更强是处理外部API数据时应养成的良好习惯。5. 核心代码实现与逐行解读5.1 主程序架构与初始化流程主程序code.py的架构遵循一个清晰的物联网设备典型工作流初始化 - 连接网络 - 进入主循环获取数据 - 解析数据 - 更新显示 - 等待。下面我们结合代码进行详细解读。首先是导入必要的库和配置参数import time import board from adafruit_pyportal import PyPortal try: from secrets import secrets except ImportError: print(请将WiFi和API信息配置在secrets.py文件中) raise # 从secrets.py中读取配置 ZIP_CODE secrets[zip_code] AIRNOW_TOKEN secrets[airnow_token] WIFI_SSID secrets[ssid] WIFI_PASSWORD secrets[password] # 构建API请求URL DATA_SOURCE fhttp://www.airnowapi.org/aq/forecast/zipCode/?formatapplication/jsonzipCode{ZIP_CODE}API_KEY{AIRNOW_TOKEN} # 我们关注PM2.5的AQI值这里使用一个更灵活的json_path示例。 # 实际上我们会在自定义函数中解析此处可先留空或设为通用路径。 JSON_PATH [, AQI] # 占位符实际解析在自定义函数中完成接下来是PyPortal对象的初始化这是整个项目的核心配置阶段# 初始化PyPortal对象 pyportal PyPortal(urlDATA_SOURCE, json_pathJSON_PATH, # 注意由于我们使用自定义解析此处的json_path可能不直接使用 status_neopixelboard.NEOPIXEL, default_bg0x000000, # 默认背景色为黑色 text_font/fonts/Helvetica-Bold-24.bdf, # 字体文件路径 text_position(160, 120), # 文本显示的中心坐标 (x, y) text_color0xFFFFFF, # 文本颜色为白色 text_maxlen50, # 文本最大长度 caption_textfAir Quality Index for {ZIP_CODE}, # 底部标题文字 caption_font/fonts/Helvetica-12.bdf, caption_position(160, 220), # 标题位置 caption_color0x808080) # 标题颜色为灰色在这段初始化代码中每一个参数都至关重要url和json_path定义了数据的来源和提取路径。但如前所述对于复杂解析我们可能需要重写数据获取逻辑。default_bg默认背景色。我们后续会根据AQI值动态改变它。text_font/caption_font指定了字体文件。.bdf是位图字体格式需要提前放入板子的fonts目录。你可以从Adafruit的库包中找到这些字体或者自己生成。text_position和caption_position决定了文字在屏幕上的位置。坐标系原点(0,0)在屏幕左上角(320,240)在右下角。通过调整这两个坐标可以精确控制文字布局。status_neopixel指定状态LED用于指示设备状态如连接中、错误等。5.2 自定义数据获取与解析函数由于标准的pyportal.fetch()方法可能无法满足我们复杂的、基于条件的JSON解析需求我们需要自定义一个数据获取函数。我们将重写PyPortal的数据处理部分。def fetch_and_parse_aqi(pyportal_instance): 自定义函数获取并解析AQI数据 try: # 1. 使用PyPortal内部的网络对象获取原始JSON数据 response pyportal_instance.network.fetch(DATA_SOURCE) json_data response.json() except (RuntimeError, ValueError) as e: print(网络请求或JSON解析失败:, e) return None, Error # 2. 调用我们之前写好的解析函数 aqi_value, category_name parse_airnow_data(json_data) if aqi_value is not None: # 3. 根据AQI值确定背景色和文本颜色 bg_color, text_color get_color_from_aqi(aqi_value) return aqi_value, category_name, bg_color, text_color else: return None, No Data, 0x000000, 0xFF0000 # 返回错误状态黑底红字这个函数做了三件事发起网络请求、解析数据、根据AQI值映射颜色。它将网络通信、数据清洗和业务逻辑封装在一起使得主循环非常简洁。5.3 动态颜色映射与显示更新逻辑颜色映射函数get_color_from_aqi是将数据转化为直观视觉反馈的关键def get_color_from_aqi(aqi): 根据AQI值返回背景色和文本颜色十六进制 if aqi 50: return 0x00FF00, 0x000000 # 绿色背景黑色文字 (Good) elif aqi 100: return 0xFFFF00, 0x000000 # 黄色背景黑色文字 (Moderate) elif aqi 150: return 0xFFA500, 0x000000 # 橙色背景黑色文字 (Unhealthy for Sensitive Groups) elif aqi 200: return 0xFF0000, 0xFFFFFF # 红色背景白色文字 (Unhealthy) elif aqi 300: return 0x800080, 0xFFFFFF # 紫色背景白色文字 (Very Unhealthy) else: # 301-500 return 0x800000, 0xFFFFFF # 栗色背景白色文字 (Hazardous)这个函数实现了美国EPA的AQI颜色标准。注意当背景色较深时如红色、紫色、栗色我们将文本颜色设置为白色0xFFFFFF以确保对比度和可读性当背景色较浅时绿色、黄色则使用黑色文字0x000000。5.4 主循环与错误处理机制最后我们将一切整合到主循环中# 主循环 update_interval 600 # 更新间隔单位秒 (10分钟) last_update time.monotonic() - update_interval # 确保启动后立即更新一次 while True: now time.monotonic() if now - last_update update_interval: print(正在获取空气质量数据...) try: aqi, category, bg_color, txt_color fetch_and_parse_aqi(pyportal) if aqi is not None: # 更新屏幕显示 pyportal.set_background(bg_color) # 设置背景色 pyportal.set_text(f{aqi}, index0) # 更新主AQI文本index0对应第一个文本框 # 可以更新标题文本显示类别 pyportal.set_caption(fAQI: {aqi} ({category}) | ZIP: {ZIP_CODE}) print(f更新成功: AQI{aqi}, Category{category}) else: pyportal.set_background(0x000000) # 黑色背景表示错误 pyportal.set_text(Err, index0) pyportal.set_caption(Failed to fetch data) print(获取数据失败) except Exception as e: print(主循环发生错误:, e) # 简单的错误显示 pyportal.set_background(0xFF0000) pyportal.set_text(!!!, index0) last_update now # 记录本次更新时间 # 短暂休眠以降低CPU占用也可以处理触摸事件等 time.sleep(0.1)这个主循环实现了定时触发每600秒的数据获取与更新流程。它包含了基本的try-except错误处理当网络异常或数据解析失败时会在屏幕上显示错误提示如“Err”并将背景设为黑色或红色让用户一眼就能看出设备状态异常。time.monotonic()用于获取单调递增的时间避免系统时间被调整带来的问题是嵌入式系统中实现定时器的推荐方法。6. 硬件组装、外壳定制与部署实践6.1 PyPortal组装与基础测试拿到PyPortal后建议先不要急着装进外壳而是进行“裸板测试”。用USB线将其连接到电脑按照前面所述刷好CircuitPython固件并上传最基本的code.py和secrets.py文件。确保Wi-Fi能连接API能正确获取数据屏幕能正常显示。这个步骤能排除软件配置问题避免装进外壳后因硬件接触不良还是软件错误导致的调试困难。6.2 3D外壳的选用、修改与打印Adafruit官网提供的Ruiz Bros.设计的便携式外壳是一个非常好的起点。它由多个部件组成前面板、后面板、内部支架、按钮帽等。如果你和我一样不需要电池供电和便携功能可以简化组装。获取模型文件从Adafruit学习系统的项目页面下载STL文件。切片与打印使用Cura、PrusaSlicer等软件进行切片。建议参数层高0.2mm在打印质量和时间间取得平衡。填充率15%-20%即可外壳不需要很高的结构强度。支撑对于有悬垂结构的部分如前面板包裹屏幕的边缘需要生成支撑。建议使用“树状支撑Tree Support”它更省材料且容易拆除。材料PLA是最常见且易打印的选择。PETG则更耐用、耐温适合放在可能被阳光照射的窗边。后期处理打印完成后仔细拆除支撑用砂纸打磨掉毛刺。特别是屏幕开口处务必确保平整以免刮伤PyPortal的屏幕。6.3 磁吸式安装方案实施我选择将设备贴在冰箱上因此采用了磁吸方案。具体操作如下选择磁铁推荐使用直径10-15mm厚度2-3mm的钕铁硼强磁铁N35或N42等级。需要4颗分别贴在外壳背面四个角附近。固定磁铁方案A可拆卸使用高强度的双面泡棉胶VHB胶带。将胶带剪成小方块一面粘在磁铁上另一面粘在外壳背面。这种方案的好处是未来如果想更换安装方式可以相对无损地取下磁铁。方案B永久固定使用环氧树脂或强力AB胶将磁铁直接粘在外壳上。这种连接更牢固但几乎不可逆。重要提示在粘贴前务必用酒精湿巾清洁外壳背面和磁铁表面确保无灰尘和油渍这是粘接牢固的关键。测试与调整粘贴后静置一段时间让胶水固化。然后吸附在冰箱上检查是否平整、牢固。由于PyPortal有一定重量确保磁力足够强不会因门开关的轻微震动而滑落。6.4 供电与布线优化长期部署供电稳定性是第一要务。电源适配器选择一个输出为5V/2A以上的优质USB电源适配器。避免使用那些标称电流虚高或纹波大的劣质充电器。线缆管理使用一根长度合适的USB-C线。如果从高处引电可以考虑使用带背胶的线缆固定夹让线缆沿墙脚或柜边走线保持美观。如果插座较远一个带USB口的插线板会是更灵活的解决方案。备用电源考虑可选如果你希望它在停电时也能短暂工作可以考虑在外壳内集成一块小容量锂电池和充电管理模块。但这会显著增加复杂度和成本对于纯桌面显示项目并非必需。7. 常见问题排查与深度优化技巧7.1 网络连接类问题问题无法连接Wi-Fi串口输出Connection Error。排查首先检查secrets.py中的ssid和password是否正确特别注意大小写和特殊字符。其次检查路由器是否设置了MAC地址过滤或其他连接限制。可以将PyPortal拿到离路由器更近的地方测试排除信号弱的问题。技巧在代码初始化Wi-Fi部分后增加print(连接到, WIFI_SSID)的语句并在连接成功后打印本地IP地址便于确认连接状态。问题能连上Wi-Fi但无法获取API数据返回HTTP错误如403、404。排查403 Forbidden几乎肯定是API密钥错误或已失效。请登录AirNow账户确认密钥并检查代码中是否有拼写错误或多余空格。404 Not Found检查请求URL是否拼写正确特别是zipCode参数的值是否合法美国邮政编码。Timeout网络延迟过高或DNS解析失败。可以尝试在代码中增加超时设置或使用更稳定的DNS如8.8.8.8这需要在PyPortal的网络初始化代码中配置。技巧在发起网络请求的代码段周围添加详细的异常捕获和打印将错误信息、HTTP状态码甚至响应体如果可能打印到串口这是定位网络问题最有效的方法。7.2 数据显示与刷新类问题问题屏幕显示乱码或方块而不是数字。排查这是典型的字体文件问题。首先确认text_font和caption_font指定的路径是否正确字体文件是否确实存在于CIRCUITPY盘的对应目录下。其次检查字体文件是否与CircuitPython版本兼容。有时从网络下载的.bdf文件编码可能有问题可以尝试使用Adafruit库包中自带的字体。技巧CircuitPython对中文字体支持有限且占用内存大。如果仅显示数字和英文使用库包自带的英文字体如Helvetica是最稳妥的。问题屏幕刷新缓慢或者更新数据时屏幕闪烁。排查电源不足这是最常见的原因。用万用表测量USB口电压在PyPortal全亮度工作时电压不应低于4.75V。更换更大电流如2.4A或3A的电源适配器。代码效率检查主循环中是否有不必要的延时或复杂的计算。确保网络请求和JSON解析是主要耗时操作图形更新应尽可能快。内存泄漏在长时间运行后如果设备变得异常缓慢甚至重启可能是内存未正确释放。确保在每次循环中对于创建的大型临时对象如从网络接收的字节数据在使用完毕后及时解除引用如设为None。问题背景颜色或文字位置不对。排查仔细检查get_color_from_aqi函数中的AQI阈值和颜色值是否正确。检查text_position和caption_position的坐标值。屏幕坐标系原点在左上角X向右增加Y向下增加。技巧可以写一个简单的测试程序在屏幕上不同位置画点或显示数字来校准坐标。例如在(0,0),(319,0),(0,239),(319,239)四个角显示标记看看是否与屏幕边缘对齐。7.3 稳定性与扩展性优化优化1增加重试机制。网络请求可能偶尔失败。一个健壮的程序不应因一次失败就停止工作。可以在fetch_and_parse_aqi函数中加入重试逻辑例如失败后等待5秒重试最多重试3次。max_retries 3 retry_delay 5 for attempt in range(max_retries): try: # ... 尝试获取数据 ... break # 成功则跳出循环 except Exception as e: print(f尝试 {attempt1} 失败: {e}) if attempt max_retries - 1: time.sleep(retry_delay)优化2实现离线缓存与显示。当网络长时间中断时设备可以显示上一次成功获取的数据和时间戳而不是一个错误页面。这需要将最后一次成功的AQI值、类别和时间戳保存到PyPortal的文件系统中例如一个last_data.json文件。每次启动或更新时先尝试读取这个文件作为显示内容然后在后台尝试获取新数据成功后再更新文件和屏幕。优化3添加触摸交互。PyPortal的屏幕是触摸屏。你可以增加触摸功能例如点击屏幕强制刷新数据或者滑动切换显示不同污染物PM2.5、O3等的AQI。这需要导入adafruit_touchscreen库并在主循环中检测触摸事件根据触摸坐标执行不同操作。优化4与环境光传感器联动。PyPortal板载了光线传感器board.LIGHT。你可以读取环境光强度动态调整屏幕亮度在夜晚自动调暗以节省电量如果使用电池并减少光污染在白天则调亮以保证清晰度。这只需要几行代码但能极大提升使用体验。这个项目从硬件组装、软件编程到最终部署完整地走通了一个物联网数据可视化应用的闭环。它不仅仅是一个空气质量显示器更是一个学习嵌入式Python编程、网络通信和API集成的绝佳模板。你可以很容易地将数据源从AirNow换成其他公开API比如天气、股市、公交到站信息打造属于你自己的个性化信息屏。