ESP32物联网实战：从API获取JSON数据到OLED屏显示的完整开发指南

1. 项目概述：一个实时疫情数据看板的诞生

几年前，我手头正好有几块闲置的ESP32开发板和OLED小屏幕，琢磨着做个什么小玩意儿既能练手又有实际意义。当时全球疫情数据是大家关注的焦点，但每次打开手机App或网页查看，总觉得不够“物理化”。于是，一个想法冒了出来：能不能做一个摆在桌面的、像老式收音机一样的小设备，实时显示关键疫情数据？这就是“ESP32 COVID-19数据可视化系统”的由来。它本质上是一个典型的物联网终端应用，核心逻辑非常简单：让微控制器（ESP32）通过Wi-Fi联网，从指定的数据源（API）获取结构化的疫情信息（JSON格式），解析后，将我们关心的几个数字（如累计确诊、新增、死亡等）显示在一块小小的OLED屏幕上。

这个项目非常适合刚接触物联网（IoT）或Arduino平台的开发者，尤其是那些已经点亮过LED、驱动过屏幕，想尝试网络通信和数据处理“硬骨头”的朋友。它麻雀虽小，五脏俱全：涵盖了无线网络连接、HTTP客户端请求、JSON数据解析、以及外设驱动显示这几个物联网最核心的环节。通过完成它，你不仅能得到一个有趣的桌面摆件，更能透彻理解从“云端数据”到“物理显示”的完整链路。下面，我就把自己从硬件选型、代码调试到最终稳定运行的整个过程，以及踩过的坑和总结的经验，毫无保留地分享出来。

2. 核心硬件选型与电路设计思路

2.1 为什么是ESP32？

在开始动手前，硬件选型是第一步。市面上常见的微控制器很多，比如经典的Arduino Uno、功能更强的STM32系列等。我最终选择ESP32，是基于以下几个非常实际的考量：

首先，内置无线网络功能是刚需。这个项目的灵魂在于实时获取网络数据。如果使用Arduino Uno，你需要额外搭配一个以太网扩展板或Wi-Fi模块（如ESP8266），这不仅增加了成本，更让电路连接和代码编写变得复杂。ESP32则原生集成了Wi-Fi和蓝牙，一颗芯片搞定通信，极大地简化了设计和开发流程。

其次，性能与资源的平衡。ESP32是一颗双核处理器，主频高达240MHz，内存也有520KB SRAM。处理HTTP请求和解析JSON数据，虽然数据量不大，但解析过程（特别是使用ArduinoJson库时）需要一定的内存来创建文档对象。ESP32的资源完全能够轻松应对，避免了在内存紧张的MCU上可能出现的解析失败或系统崩溃。

再者，丰富的IO口与广泛的社区支持。驱动I2C接口的OLED屏幕只需要两个IO口（SDA, SCL），ESP32绰绰有余。更重要的是，ESP32拥有极其庞大的用户社区和资料库，无论是开发环境配置、库文件支持还是遇到问题时的解决方案，都能很容易地找到参考，这对项目顺利推进至关重要。

注意：ESP32开发板型号繁多，如ESP32 DevKit V1、NodeMCU-32S等。它们核心芯片相同，主要区别在于USB转串口芯片、引脚排列和板载LED。对于本项目，任何一款常见的ESP32开发板都可以，购买时确认其引脚定义即可。

2.2 OLED显示屏的选择与连接逻辑

显示部分我选择了最普遍的0.96英寸、128x32像素的I2C接口OLED屏。选择它也有几个原因：

1. 低功耗与高对比度：OLED是自发光器件，显示黑色时像素点不工作，功耗极低，适合长期通电的桌面设备。其对比度远超LCD，显示文字清晰锐利。
2. I2C接口简化布线：I2C通信只需要两根数据线（SDA, SCL），加上电源和地线，总共四根线就能完成所有通信，比并口屏节省了大量IO口，让电路非常简洁。
3. 尺寸与分辨率适中：128x32的分辨率足以分多行显示多组数据（如国家名、累计确诊、新增、死亡等），0.96英寸的尺寸也适合做成一个精致的小设备。

硬件连接是整个项目中最简单的一环，遵循“电源同源、信号直连”的原则：

连接时，建议使用杜邦线在面包板上先进行测试。确保ESP32先不要通电，连接好所有线后再上电。通电后，ESP32板载的电源指示灯应亮起。如果OLED屏幕也瞬间闪亮一下然后熄灭，这通常是正常的初始化过程，如果屏幕持续发烫或出现焦味，请立即断电检查VCC是否错接5V。

3. 软件开发环境搭建与核心库解析

3.1 Arduino IDE的深度配置：不止于安装

虽然PlatformIO等现代开发环境更强大，但Arduino IDE对于入门和快速验证来说依然直观。为ESP32开发，需要对其进行“扩容”。

第一步：添加ESP32开发板支持在Arduino IDE中，进入“文件 -> 首选项”，在“附加开发板管理器网址”中填入：https://espressif.github.io/arduino-esp32/package_esp32_index.json。这里注意，原项目资料中的URL可能已过期，Espressif官方的这个索引地址是最稳定的。你可以添加多个URL，用逗号分隔。

点击“好”之后，进入“工具 -> 开发板 -> 开发板管理器”。这会打开一个列表，在搜索框输入“esp32”。你应该会看到由“Espressif Systems”提供的“esp32”平台。点击“安装”。这个过程会下载数百MB的文件，包括所有ESP32系列芯片的工具链、库和示例，请保持网络通畅。

第二步：关键库的安装与作用剖析安装完开发板后，还需要两个核心库：

1. Adafruit SSD1306：这是驱动OLED屏幕的库。在“项目 -> 加载库 -> 管理库”中搜索“SSD1306”，选择由Adafruit发布的“Adafruit SSD1306”进行安装。安装时，它会提示你同时安装依赖库“Adafruit GFX Library”，务必一起安装。这个库封装了在屏幕上画点、线、图形和文字的复杂操作，我们只需要调用简单的print()函数就能显示文字。
2. ArduinoJson：这是本项目的数据处理核心。同样在库管理中搜索“ArduinoJson”，选择由Benoit Blanchon发布的版本进行安装。强烈建议安装v6.x或v7.x版本，新版本在API和内存管理上更为优化。这个库负责将我们收到的、像一团乱麻的JSON文本，反序列化成程序中可以轻松访问的变量。

实操心得：库版本冲突是嵌入式开发常见坑。如果代码编译报错，提示某个函数找不到，首先检查库的版本。例如，Adafruit SSD1306库的新版本可能对初始化函数有更新。一个稳妥的方法是，在GitHub上找到项目原作者使用的库版本号，在Arduino IDE的库管理界面选择安装特定版本。

3.2 代码结构全景解读

拿到示例代码（例如从GitHub克隆）后，不要急于上传。先花十分钟通读一遍，理解其骨架。一个典型的ESP32网络数据获取程序包含以下几个部分：

// 1. 头文件引入区 #include <WiFi.h> #include <HTTPClient.h> #include <ArduinoJson.h> #include <Adafruit_GFX.h> #include <Adafruit_SSD1306.h> // 2. 网络凭证与API配置区 const char* ssid = "你的Wi-Fi名称"; const char* password = "你的Wi-Fi密码"; String serverURL = "https://disease.sh/v3/covid-19/countries/india"; // 示例API // 3. 对象定义与屏幕参数区 Adafruit_SSD1306 display(128, 32, &Wire, -1); // 定义OLED对象 // 4. 初始化设置（setup函数） void setup() { Serial.begin(115200); // 启动串口调试，这是我们的“眼睛” // 初始化屏幕 if(!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) { // 0x3C是常见I2C地址 Serial.println(F("SSD1306分配失败")); for(;;); // 卡死，提示硬件错误 } display.clearDisplay(); display.setTextSize(1); display.setTextColor(SSD1306_WHITE); display.setCursor(0,0); display.println("Connecting..."); display.display(); // 连接Wi-Fi WiFi.begin(ssid, password); while (WiFi.status() != WL_CONNECTED) { delay(500); Serial.print("."); } Serial.println("Connected!"); } // 5. 主循环（loop函数） void loop() { if (WiFi.status() == WL_CONNECTED) { // 确保网络畅通 getCOVIDData(); // 执行数据获取和显示的核心函数 } delay(30000); // 每30秒更新一次，过于频繁请求可能被API限制 } // 6. 核心功能函数（getCOVIDData） void getCOVIDData() { HTTPClient http; http.begin(serverURL); // 指定请求地址 int httpCode = http.GET(); // 发送GET请求 if (httpCode == HTTP_CODE_OK) { // 如果返回成功（200） String payload = http.getString(); // 拿到原始的JSON字符串 Serial.println(payload); // 打印到串口，用于调试 parseAndDisplay(payload); // 解析并显示 } else { Serial.printf("HTTP请求失败，错误码: %s\n", http.errorToString(httpCode).c_str()); displayError("HTTP Error"); } http.end(); // 释放资源 } // 7. 数据解析与显示函数（parseAndDisplay） void parseAndDisplay(String jsonString) { // 此处使用ArduinoJson进行解析，详见下一节 }

这个结构清晰地划分了功能模块：配置、初始化、网络连接、周期执行、数据获取、数据处理与显示。理解这个结构后，无论你想显示天气、股价还是其他任何API数据，只需替换serverURL和parseAndDisplay函数内的解析逻辑即可。

4. JSON数据解析：从字符串到屏幕数字的关键一跃

这是本项目最核心、也最容易出错的技术环节。网络请求成功，我们拿到的是一个长长的字符串（payload），它遵循JSON格式，包含了嵌套的键值对。ArduinoJson库的作用，就是帮我们在这个字符串迷宫里，精准地找到需要的值。

4.1 动态JSON文档与内存管理

首先，我们需要在内存中创建一个用来映射JSON结构的文档（Document）。这里有一个至关重要的概念：动态JsonDocument。在ArduinoJsonv6及以上版本中，推荐使用DynamicJsonDocument，因为它的大小可以在解析时自动调整（在合理范围内）。

void parseAndDisplay(String jsonString) { // 创建一个动态JSON文档，容量是关键参数！ DynamicJsonDocument doc(2048); // 预留2048字节内存 // 反序列化：将JSON字符串解析到doc对象中 DeserializationError error = deserializeJson(doc, jsonString); // 错误检查是必须的！ if (error) { Serial.print(F("反序列化JSON失败: ")); Serial.println(error.f_str()); displayError("JSON Error"); return; // 解析失败就退出，避免后续操作崩溃 } // 现在，我们可以像访问对象属性一样访问数据了 const char* country = doc["country"]; // 获取国家名称 long cases = doc["cases"]; // 获取累计确诊 long todayCases = doc["todayCases"]; // 获取今日新增 long deaths = doc["deaths"]; // 获取累计死亡 long recovered = doc["recovered"]; // 获取累计康复 // 在屏幕上显示 display.clearDisplay(); display.setCursor(0,0); display.print(country); display.setCursor(0,10); display.print("C:"); display.print(cases); display.print(" N:"); display.print(todayCases); display.setCursor(0,20); display.print("D:"); display.print(deaths); display.print(" R:"); display.print(recovered); display.display(); }

如何确定DynamicJsonDocument doc(2048);中的容量大小？这是新手最常见的困惑。容量预留太小，会导致解析失败；预留太大，又会浪费宝贵的内存。最科学的方法是使用ArduinoJson Assistant（原项目也提到了）。

1. 从串口监视器复制一次完整的、成功的JSON响应字符串。
2. 访问https://arduinojson.org/v6/assistant/（注意版本号，v6或v7）。
3. 将JSON字符串粘贴到左侧的输入框。
4. 工具会自动在右侧生成解析代码，并明确给出建议的容量（例如“2048 bytes”）。直接使用这个值即可。对于疫情数据API，1024-3072字节通常是足够的。

4.2 处理不同的API响应格式

原项目使用的API (corona.lmao.ninja) 可能已变更或关闭。现在更常用的公共API是disease.sh。不同API返回的JSON结构可能略有不同。例如，disease.sh返回的数据中，今日新增的字段名可能是todayCases，而另一个API可能叫newCases。

因此，在编写解析代码前，必须首先查看API文档或实际响应。打开浏览器，直接访问你计划使用的API URL（如https://disease.sh/v3/covid-19/countries/india），你会看到返回的原始JSON。仔细查看其结构：

{ "country": "India", "cases": 44986461, "todayCases": 1254, "deaths": 531832, "recovered": 44446514, "active": 80895, ... }

确认了字段名后，代码中的doc["todayCases"]才能正确取值。如果字段名写错，程序不会报错，但会取到空值或默认值0。

5. 硬件集成、调试与稳定性优化

5.1 分步调试法：让问题无处遁形

当所有代码准备就绪，硬件也连接好后，不要指望一次上传就能成功。采用分步调试，能快速定位问题阶段。

1. 第一步：测试屏幕。先上传一个最简单的屏幕测试程序（比如Adafruit SSD1306库自带的示例ssd1306_128x32_i2c）。确保屏幕硬件、连接、库驱动都没问题。如果这里失败，检查接线、I2C地址（尝试0x3C或0x3D）、以及begin()函数中的参数。
2. 第二步：测试Wi-Fi连接。注释掉数据获取和显示部分，在setup()里只做Wi-Fi连接，并在loop()里打印WiFi.status()和本地IP地址到串口监视器。确保ESP32能成功连接到你的路由器。
3. 第三步：测试HTTP请求。在能连Wi-Fi的基础上，在loop()里添加HTTP GET请求代码，并将返回的HTTP状态码（httpCode）和原始的payload字符串打印到串口。观察状态码是否为200，以及payload是否是一段完整的JSON文本。
4. 第四步：测试JSON解析。在收到正确payload的基础上，单独测试解析函数。将payload字符串硬编码在程序里（作为字符串常量），直接调用parseAndDisplay函数，看能否正确提取出数值并在串口打印出来。
5. 第五步：全功能集成。当以上每一步都独立验证通过后，再将所有代码整合起来，上传运行。

5.2 提升系统稳定性的关键技巧

一个需要长期运行的设备，稳定性比功能更重要。以下是几个经过实测有效的优化点：

1. 健壮的网络连接处理：

void connectToWiFi() { display.clearDisplay(); display.setCursor(0,0); display.print("Wi-Fi..."); display.display(); WiFi.mode(WIFI_STA); // 设置为站点模式 WiFi.begin(ssid, password); int attempts = 0; while (WiFi.status() != WL_CONNECTED && attempts < 20) { // 限制尝试次数 delay(500); Serial.print("."); attempts++; } if (WiFi.status() == WL_CONNECTED) { Serial.println("\nConnected! IP: " + WiFi.localIP().toString()); } else { Serial.println("\nConnection Failed!"); // 可以在这里让屏幕显示错误，或进入深度睡眠后重启 display.clearDisplay(); display.setCursor(0,0); display.print("Wi-Fi Fail"); display.display(); delay(5000); ESP.restart(); // 重启尝试 } }

在loop()中，每次执行数据获取前，都检查WiFi.status()。如果断线，则尝试重连，而不是直接执行请求导致错误。

2. 优雅的API请求与错误处理：

• 设置超时：http.setTimeout(10000); // 设置10秒超时，防止网络不佳时程序卡死。
• 检查返回值：不仅检查httpCode是否为200，还要处理其他情况，如301/302重定向、404未找到、429请求过多等。
• 释放资源：无论成功与否，务必在请求结束后调用http.end()，释放TCP连接。

3. 合理的请求频率与电源考虑：

• 疫情数据变化以天为单位，完全不需要每秒更新。delay(300000)（5分钟）或更长的间隔是合理的，也是对API提供方的尊重，避免被限制IP。
• 如果需要长期离线运行，可以考虑使用锂电池和充电管理模块，并在代码中实现深度睡眠（esp_deep_sleep_start()），让ESP32在每次更新数据后睡眠一段时间，极大降低功耗。

6. 功能扩展与个性化定制思路

基础功能实现后，这个项目可以作为一个平台，进行各种有趣的扩展：

1. 多国数据切换：可以在代码中定义一个国家代码数组，通过一个物理按钮（连接到ESP32的某个GPIO引脚并配置中断）来切换。每次按下按钮，就改变serverURL中的国家代码，然后重新获取并显示该国数据。

2. 显示更多信息或图形化：128x32的屏幕确实有限，但也可以做些文章。例如，可以分屏轮播显示：第一屏显示累计数据，5秒后切换到第二屏显示今日新增和死亡率等。或者，用简单的柱状图来对比今日新增与昨日新增。这需要更深入地使用Adafruit GFX库的绘图功能。

3. 更换数据源：完全可以将API换成任何你感兴趣的公开数据源。比如：

• 天气API：显示实时温度、湿度。
• 金融API：显示比特币价格、股价。
• 公共交通API：显示下一班地铁到站时间。
• 自定义服务器：从你自己搭建的服务器获取传感器数据。

更换的关键在于：a) 理解新API的调用方式（URL、请求头、参数）；b) 解析新的JSON响应结构；c) 调整屏幕显示格式以适应新数据。

4. 外壳设计与桌面美化：用3D打印或激光切割制作一个精致的外壳，将ESP32和OLED屏幕封装进去，背面留出USB供电口。一个美观的外壳能让项目从“开发板堆”变成真正的“桌面摆件”。

7. 常见问题排查与解决方案实录

在实际制作过程中，你几乎一定会遇到下面这些问题。这里是我和许多爱好者总结出的“药方”：

最后，我想分享一个最深的体会：物联网项目的魅力在于，它打通了虚拟与现实的边界。当你看到网络上瞬息万变的数据，通过自己编写的代码和搭建的电路，最终稳定地呈现在一块小小的实体屏幕上时，那种成就感远超在电脑上完成一个纯软件程序。这个项目虽然小，但它为你打开了一扇门，门后是智能家居、环境监测、工业控制等无数可能。从读懂一行JSON数据开始，你的想法已经可以触摸到真实的世界。