ESP32 实战教程：用 ST7789 彩屏制作设备状态仪表盘
本文按实际动手和排错顺序整理。不同芯片、开发板、库版本和模块批次可能存在差异，示例参数需要以手中硬件和当前官方文档为准。
一、项目目标与使用场景
彩屏项目最容易从一句“把数值画出来”发展成满屏闪烁和主循环卡顿。ST7789 速度快、模块多、资料丰富，适合做设备本地仪表盘。真正值得学习的是布局、局部刷新、字体资源和数据快照，而不是每一轮 loop 都重新粉刷整块屏幕。
本次仍采用“最小闭环、分层验证、异常优先”的方式：先证明硬件与驱动能通信，再处理数据和状态，最后加入网页、存储或自动化。一次堆满功能看起来进度很快，出了问题却容易把一下午变成大型猜谜现场。
二、硬件准备与接线
准备 ESP32、ST7789 SPI 彩屏和稳定 3.3 V 供电。SCK、MOSI、CS、DC、RST 按模块接线，背光脚通过限流或驱动控制。先确认屏幕分辨率、偏移和颜色顺序，不同批次可能使用不同面板参数。屏幕刷新电流和背光电流都要计入电源预算。
接线前先断电并核对电压、电平、公共地和启动相关引脚。第一次实验使用短线、单个外设和稳定电源，保留串口日志。涉及电机、市电、锂电池或人体数据时，硬件保护、合格外壳和使用边界必须独立考虑，示例代码不能替代安全设计。
三、核心工作原理
SPI 将像素数据串行送入显示控制器。全屏 240x240、16 位颜色一次就有 115200 字节，频繁全屏重画会占用明显总线时间。更稳妥的做法是固定背景只画一次，数值变化时只刷新对应矩形，并在数据模型中比较新旧值，真正变化才绘制。
建议把系统分成接口驱动、原始数据、业务状态、输出执行和展示记录五层。每层保留明确观测点：初始化返回、原始帧、处理值、状态变化原因和最终执行反馈。页面没数据显示时，从底层证据逐层排查，比一次更换三个库更可靠。
四、首次验证与标定
先画红、绿、蓝和白色测试块，确认 RGB/BGR 与反色设置；再画四角坐标，检查旋转和偏移。用毫秒计时测量全屏与局部刷新耗时，记录 SPI 频率。最后同时运行传感器和网络，确认屏幕刷新不会拖慢采样。
标定和验证都要保留原始值、环境、时间、固件版本与参考条件。只保存最终系数，下一次出现偏差时很难判断是模块更换、安装变化、算法升级还是当初计算错误。
五、最小代码骨架
下面代码用于说明核心流程。安装库后先打开当前版本自带示例，核对 API、引脚和分区设置，再把结构合并进自己的项目：
#include <TFT_eSPI.h>
TFT_eSPI tft;
float lastTemp = -999;
void drawTemperature(float value) {
if (fabs(value - lastTemp) < 0.1f) return;
tft.fillRect(20, 80, 200, 55, TFT_BLACK);
tft.setTextColor(value > 35 ? TFT_RED : TFT_GREEN, TFT_BLACK);
tft.drawString(String(value, 1) + " C", 24, 88, 4);
lastTemp = value;
}
void setup() {
tft.init();
tft.setRotation(1);
tft.fillScreen(TFT_BLACK);
tft.drawString("DEVICE STATUS", 20, 20, 2);
}
void loop() { drawTemperature(25.3f); delay(200); }
启动时输出固件版本、初始化状态和关键参数；运行中记录第一笔有效数据、连续错误与恢复。正式产品可以降低日志量，但开发阶段不要主动关掉最有用的线索。
六、数据模型与状态机
界面读取一个完整状态快照，包括值、单位、有效性、更新时间和错误码。显示层不直接访问慢速传感器。对于频繁变化的数据设置显示刷新上限，例如采样 50 Hz、屏幕只更新 5 Hz；既保留实时感，也不给 SPI 总线安排不必要的健身计划。
统一数据结构可以包含 raw、value、unit、valid、sequence、timestamp 和 error。状态机至少区分初始化、正常、降级、错误和恢复，所有重试设置间隔与上限。展示层读取快照，不直接触发耗时采样或越过业务层操作硬件。
七、常见问题与排错顺序
白屏先查供电、CS、DC、RST 和驱动配置。颜色颠倒检查色序与反色命令，画面偏移检查面板尺寸。频率过高、杜邦线过长会产生花屏。多个 SPI 设备共享总线时必须各自使用 CS，并协调多任务访问。
推荐排错顺序：测量供电与地线，核对引脚和地址，运行官方最小示例，打印原始数据，最后恢复滤波、网络和控制。每次只修改一个变量，并把失败输出保留下来。偶然成功一次只能说明问题暂时没有出现，不代表问题已经被理解。
八、工程化与安全边界
将页面分为标题、主数据、网络状态和告警区，颜色含义保持一致。缺失数据明确显示离线，不能保留旧值冒充最新值。字体与图片存入 Flash 时估算空间；大量绘图可使用精灵缓冲，但也要评估 RAM。
配置写入 NVS 前进行范围检查、版本迁移与默认值处理；网络请求使用超时和退避；日志分级并限制容量；关键输出具有本地停止方式、最大持续时间和启动安全态。软件复位不是硬件保护，过流、限位、隔离与保险应由相应电路承担。
九、测试清单
- 冷启动、软件复位和突然断电后，设备是否进入明确状态；
- 外设拔掉、地址错误、输入越界时，主循环是否仍然工作；
- 连续运行两小时后，内存、温度、供电和错误计数是否稳定；
- 网络、服务器或存储不可用时，本地核心功能是否保留；
- 阈值附近变化时，是否有迟滞、去抖和速率限制；
- 更换同型号模块后，原配置与标定是否仍然合理；
- 故障解除后，恢复行为是否符合预期且不会产生重复动作；
- 日志能否解释最后一次状态变化的来源和结果。
建议把测试日期、板型、库版本、接线、供电、原始值和结论整理成实验表。教程真正有复用价值的部分，往往不是一张成功截图，而是读者遇到同类失败时知道下一步测什么。
十、可继续扩展的方向
可以加入多页面、旋转编码器、趋势小图和夜间亮度。数据记录器可在屏幕显示 SD 卡余量和写入状态；控制设备则应把操作确认与状态反馈分开，避免按钮看起来按下了，负载其实没有动作。
扩展时一次增加一个变量：新硬件先独立运行，新算法先用保存数据离线验证，新网络功能先测试断线。每增加一层都重复冷启动、拔插和长时间测试，设备会比“功能全开后祈祷一次通过”可靠得多。
十一、总结
这篇教程的重点不是记住某个库函数，而是完成一条可观测、可验证、可恢复的系统链路。能运行是起点，能解释数据、定位错误并在异常时安全退化，才算真正完成。实物制作后建议继续补充接线照片、串口截图、实测参数和一次真实排错记录。
参考资料
打赏
如果这篇学习记录对你有帮助，欢迎扫码支持后续整理。
打赏支持：王庆岩
浙公网安备 33010602011771号