尧图网站建设 
使用 TRAE CN 进行 ESP32 固件开发与刷写 —— 技术文档本文基于本仓库（ESP32-LCD）从零到可运行固件的完整开发过程整理，覆盖环境搭建、项目结构、硬件接线、核心代码解析、编译与刷写、OTA 无线更新，以及使用 TRAE CN 辅助开发的具体方法。文中所有命令、引脚、库版本均为本项目实际验证过的真实配置。目录项目概览开发环境搭建项目结构硬件接线核心代码解析编译与刷写OTA 无线更新TRAE CN 辅助开发工作流常见问题与排错1. 项目概览本项目是一台桌面天气站，由 ESP32 驱动一块 ST7735S（128×128）彩色 LCD，联网后通过和风天气（QWeather）API 获取实时天气与 7 日预报，并渲染为多页卡片式界面。维度实现方案主控ESP32（NodeMCU-32S 开发板）屏幕ST7735S 128×128，SPI（4 线，无 MISO、无触摸）图形库LovyanGFX（本地库，含 efontCN 中文字体）网络配网WiFiManager（网页配网，凭证存 NVS）时间同步NTP + POSIX TZ（CST-8）天气数据和风天气v7/weather/now与v7/weather/7dJSON 解析ArduinoJson v7定位公网 IP 反查（ip-api.com 主、ipwho.is 备）无线更新ArduinoOTA + 双 OTA 分区构建系统PlatformIO Core 6.2.02. 开发环境搭建2.1 前提Linux（本机为 Ubuntu 系，/home/zhj为家目录）Python 3（本机3.14.4）一条 USB 数据线（需支持数据传输，非纯充电线）一个可用的 ESP32 开发板2.2 安装 PlatformIO Core（独立虚拟环境，避免污染系统）重要：本机此前已有另一套「成绩统计」系统依赖特定 Python 环境。为避免pip全局安装破坏既有环境，必须在独立 venv 中安装 PlatformIO。# 1. 创建独立虚拟环境（目录自选，此处放在家目录）python3-mvenv ~/.platformio-venv# 2. 激活环境source~/.platformio-venv/bin/activate# 3. 在 venv 内安装 PlatformIO Corepipinstall-Uplatformio# 4. 验证安装pio--version# 输出：PlatformIO Core, version 6.2.0安装完成后，pio/platformio命令位于 venv 的bin/下（本机软链/暴露为~/.local/bin/pio）。每次新开终端开发时，需先激活 venv：source~/.platformio-venv/bin/activate也可在~/.bashrc中写入alias pio='~/.platformio-venv/bin/pio'以便快速调用，但不要把 venv 的bin永久加入全局PATH，以保持隔离。2.3 初始化项目mkdir-p~/Public/ESP32-LCDcd~/Public/ESP32-LCD pio project init--boardesp32dev该命令会生成标准 PlatformIO 目录骨架：ESP32-LCD/ ├── platformio.ini # 项目核心配置 ├── src/ # 源码（main.cpp 等） ├── include/ # 项目内头文件 ├── lib/ # 本地/私有库（LovyanGFX 放这里） └── .pio/ # 构建产物（自动生成，勿手动改）3. 项目结构本仓库实际结构（已剔除.pio/构建产物）：ESP32-LCD/ ├── platformio.ini # 双环境配置（USB + OTA） ├── partitions.csv # 自定义 4MB 双 OTA 分区表 ├── src/ │ ├── main.cpp # 主固件：显示、WiFi、OTA、天气、四屏 UI │ ├── settings.h # 集中配置（WiFi/时间/天气/引脚/刷新） │ ├── QWeatherClient.h # 天气数据结构 + 客户端接口 │ └── QWeatherClient.cpp # 和风天气 HTTPS 请求 + gzip 解压 + JSON 解析 ├── lib/ │ └── LovyanGFX/ # 本地图形库（GitHub 直连慢，镜像下载后本地引用） ├── include/ # （本项目未使用，保留） └── weather-station/ # 原始 GitHub 参考代码（ESP8266 版，仅作参考）3.1platformio.ini详解[platformio] default_envs = esp32dev ; 默认编译/上传环境 [env:esp32dev] platform = espressif32 ; 使用乐鑫官方平台 board = esp32dev ; 开发板：NodeMCU-32S framework = arduino ; 使用 Arduino 框架 monitor_speed = 115200 ; 串口监视波特率 upload_speed = 921600 ; 串口上传波特率 board_build.partitions = partitions.csv ; 指定自定义分区表 lib_deps = ; 依赖库（联网自动下载） bblanchon/ArduinoJson@^7.0.4 tzapu/WiFiManager@^2.0.17 build_flags = -fno-exceptions ; 禁用 C++ 异常，减小固件体积 -DARDUINO_LOOP_STACK_SIZE=16384 ; 放大 loop 任务栈（LovyanGFX 渲染需要）关键点说明：board_build.partitions指向自定义分区表，是 OTA 双分区的核心。-fno-exceptions：Arduino + LovyanGFX 默认不用异常，禁用可显著缩小 ROM 占用。-DARDUINO_LOOP_STACK_SIZE=16384：默认loop()运行在loopTask中，栈较小；LovyanGFX 及ArduinoJson的栈上大对象（JsonDocument）可能溢出，故放大到 16KB。LovyanGFX没有写进lib_deps，而是放在lib/LovyanGFX本地目录。原因：GitHub 直连拉取过慢，改用镜像下载后本地引用，构建更快更稳。3.2partitions.csv详解# Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x5000, otadata, data, ota, 0xe000, 0x2000, app0, app, ota_0, 0x10000, 0x1E0000, app1, app, ota_1, 0x1F0000, 0x1E0000, coredump, data, coredump,0x3D0000,0x10000,4MB Flash 布局，app0/app1各 1.875MB。由于 LovyanGFX 内置了多套字体（尤其efontCN中文字体体积较大），默认 1.2MB 的 OTA 分区不够，因此自定义为双 1.875MB 大分区。otadata保存当前运行分区标志，coredump用于崩溃分析。4. 硬件接线显示屏：ST7735S 128×128，走 VSPI 总线，4 线 SPI（无 MISO，故readable=false，屏幕内容只写不读）。ST7735S 引脚ESP32 GPIO说明SCLK18SPI 时钟MOSI (SDA/DIN)23SPI 数据CS5片选DC26数据/命令选择RST (RES)4复位BLK (LED)27背光（GPIO 拉高点亮）MISO不接本屏无需读回对应settings.h中的宏定义：#defineTFT_CS5#defineTFT_DC26#defineTFT_LED27#defineTFT_RST4接线建议：杜邦线插接时，SPI 频率不宜过高。本固件将freq_write设为20MHz（而非屏幕标称的 40/80MHz），以保证杜邦线下的稳定性。5. 核心代码解析5.1 LovyanGFX 显示初始化（main.cpp）通过继承 使用 TRAE CN 进行 ESP32 固件开发与刷写
使用 TRAE CN 进行 ESP32 固件开发与刷写 —— 技术文档本文基于本仓库（ESP32-LCD）从零到可运行固件的完整开发过程整理，覆盖环境搭建、项目结构、硬件接线、核心代码解析、编译与刷写、OTA 无线更新，以及使用 TRAE CN 辅助开发的具体方法。文中所有命令、引脚、库版本均为本项目实际验证过的真实配置。目录项目概览开发环境搭建项目结构硬件接线核心代码解析编译与刷写OTA 无线更新TRAE CN 辅助开发工作流常见问题与排错1. 项目概览本项目是一台桌面天气站，由 ESP32 驱动一块 ST7735S（128×128）彩色 LCD，联网后通过和风天气（QWeather）API 获取实时天气与 7 日预报，并渲染为多页卡片式界面。维度实现方案主控ESP32（NodeMCU-32S 开发板）屏幕ST7735S 128×128，SPI（4 线，无 MISO、无触摸）图形库LovyanGFX（本地库，含 efontCN 中文字体）网络配网WiFiManager（网页配网，凭证存 NVS）时间同步NTP + POSIX TZ（CST-8）天气数据和风天气v7/weather/now与v7/weather/7dJSON 解析ArduinoJson v7定位公网 IP 反查（ip-api.com 主、ipwho.is 备）无线更新ArduinoOTA + 双 OTA 分区构建系统PlatformIO Core 6.2.02. 开发环境搭建2.1 前提Linux（本机为 Ubuntu 系，/home/zhj为家目录）Python 3（本机3.14.4）一条 USB 数据线（需支持数据传输，非纯充电线）一个可用的 ESP32 开发板2.2 安装 PlatformIO Core（独立虚拟环境，避免污染系统）重要：本机此前已有另一套「成绩统计」系统依赖特定 Python 环境。为避免pip全局安装破坏既有环境，必须在独立 venv 中安装 PlatformIO。# 1. 创建独立虚拟环境（目录自选，此处放在家目录）python3-mvenv ~/.platformio-venv# 2. 激活环境source~/.platformio-venv/bin/activate# 3. 在 venv 内安装 PlatformIO Corepipinstall-Uplatformio# 4. 验证安装pio--version# 输出：PlatformIO Core, version 6.2.0安装完成后，pio/platformio命令位于 venv 的bin/下（本机软链/暴露为~/.local/bin/pio）。每次新开终端开发时，需先激活 venv：source~/.platformio-venv/bin/activate也可在~/.bashrc中写入alias pio='~/.platformio-venv/bin/pio'以便快速调用，但不要把 venv 的bin永久加入全局PATH，以保持隔离。2.3 初始化项目mkdir-p~/Public/ESP32-LCDcd~/Public/ESP32-LCD pio project init--boardesp32dev该命令会生成标准 PlatformIO 目录骨架：ESP32-LCD/ ├── platformio.ini # 项目核心配置 ├── src/ # 源码（main.cpp 等） ├── include/ # 项目内头文件 ├── lib/ # 本地/私有库（LovyanGFX 放这里） └── .pio/ # 构建产物（自动生成，勿手动改）3. 项目结构本仓库实际结构（已剔除.pio/构建产物）：ESP32-LCD/ ├── platformio.ini # 双环境配置（USB + OTA） ├── partitions.csv # 自定义 4MB 双 OTA 分区表 ├── src/ │ ├── main.cpp # 主固件：显示、WiFi、OTA、天气、四屏 UI │ ├── settings.h # 集中配置（WiFi/时间/天气/引脚/刷新） │ ├── QWeatherClient.h # 天气数据结构 + 客户端接口 │ └── QWeatherClient.cpp # 和风天气 HTTPS 请求 + gzip 解压 + JSON 解析 ├── lib/ │ └── LovyanGFX/ # 本地图形库（GitHub 直连慢，镜像下载后本地引用） ├── include/ # （本项目未使用，保留） └── weather-station/ # 原始 GitHub 参考代码（ESP8266 版，仅作参考）3.1platformio.ini详解[platformio] default_envs = esp32dev ; 默认编译/上传环境 [env:esp32dev] platform = espressif32 ; 使用乐鑫官方平台 board = esp32dev ; 开发板：NodeMCU-32S framework = arduino ; 使用 Arduino 框架 monitor_speed = 115200 ; 串口监视波特率 upload_speed = 921600 ; 串口上传波特率 board_build.partitions = partitions.csv ; 指定自定义分区表 lib_deps = ; 依赖库（联网自动下载） bblanchon/ArduinoJson@^7.0.4 tzapu/WiFiManager@^2.0.17 build_flags = -fno-exceptions ; 禁用 C++ 异常，减小固件体积 -DARDUINO_LOOP_STACK_SIZE=16384 ; 放大 loop 任务栈（LovyanGFX 渲染需要）关键点说明：board_build.partitions指向自定义分区表，是 OTA 双分区的核心。-fno-exceptions：Arduino + LovyanGFX 默认不用异常，禁用可显著缩小 ROM 占用。-DARDUINO_LOOP_STACK_SIZE=16384：默认loop()运行在loopTask中，栈较小；LovyanGFX 及ArduinoJson的栈上大对象（JsonDocument）可能溢出，故放大到 16KB。LovyanGFX没有写进lib_deps，而是放在lib/LovyanGFX本地目录。原因：GitHub 直连拉取过慢，改用镜像下载后本地引用，构建更快更稳。3.2partitions.csv详解# Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x5000, otadata, data, ota, 0xe000, 0x2000, app0, app, ota_0, 0x10000, 0x1E0000, app1, app, ota_1, 0x1F0000, 0x1E0000, coredump, data, coredump,0x3D0000,0x10000,4MB Flash 布局，app0/app1各 1.875MB。由于 LovyanGFX 内置了多套字体（尤其efontCN中文字体体积较大），默认 1.2MB 的 OTA 分区不够，因此自定义为双 1.875MB 大分区。otadata保存当前运行分区标志，coredump用于崩溃分析。4. 硬件接线显示屏：ST7735S 128×128，走 VSPI 总线，4 线 SPI（无 MISO，故readable=false，屏幕内容只写不读）。ST7735S 引脚ESP32 GPIO说明SCLK18SPI 时钟MOSI (SDA/DIN)23SPI 数据CS5片选DC26数据/命令选择RST (RES)4复位BLK (LED)27背光（GPIO 拉高点亮）MISO不接本屏无需读回对应settings.h中的宏定义：#defineTFT_CS5#defineTFT_DC26#defineTFT_LED27#defineTFT_RST4接线建议：杜邦线插接时，SPI 频率不宜过高。本固件将freq_write设为20MHz（而非屏幕标称的 40/80MHz），以保证杜邦线下的稳定性。5. 核心代码解析5.1 LovyanGFX 显示初始化（main.cpp）通过继承