全栈自造 Status Deck（四）：硬件终于到了，从点亮屏幕到跑通第一个 Demo

一、开篇：硬件终于到了

1.1 等待的焦虑与期待

在前几期文章中，我们完成了项目的整体规划和软件框架的初步设计。然而，硬件是这一切的基础------没有屏幕显示，没有处理器运行，再好的想法也只是空中楼阁。

快递信息从"已揽收"到"运输中"，再到"派送中"，每一天都在刷新物流状态。等待的过程中，脑子里不断闪过各种可能：

屏幕的驱动芯片到底好不好驱动？
ESP32-S3 的性能够不够用？
接线会不会遇到兼容性问题？

这种等待既是焦虑，也是期待。终于，快递到了，拆开包裹的那一刻，项目正式进入"动真格"的阶段。

1.2 实验室现有设备盘点

在正式上手 ESP32-S3 之前，先来看看目前实验室手头有哪些设备可以利用：

设备	型号/规格	状态	用途
主控开发板	ESP32-S3	已到货	用于前期验证及正式开发
显示屏幕	2.8 寸 TFT LCD	已到货	主屏幕，用于 UI 显示
电源模块	可调稳压电源	常备工具	供电与调试

这些设备虽然不算豪华，但对于跑通第一个 Demo、验证整体方案可行性来说，已经完全够用了。

1.3 策略：直接使用 ESP32-S3 进行验证与开发

为什么选择直接使用 ESP32-S3 而不先用经典版？这是一个基于项目需求和芯片特性的决定：

性能匹配：ESP32-S3 的双核 LX7 处理器、更大的 PSRAM 以及 AI 加速能力，更符合 Status Deck 未来可能涉及的数据处理和复杂 UI 渲染需求。
原生 USB 支持：ESP32-S3 支持 USB OTG，为后续可能的 USB 外设扩展或固件更新提供了便利，这是经典版不具备的优势。
一步到位：既然最终目标就是 S3，直接使用它可以避免从经典版迁移时可能遇到的适配问题，节省后期移植时间。
生态成熟：ESP32-S3 作为较新的芯片，其开发生态（如 ESP-IDF、Arduino 支持）已经非常完善，遇到问题同样有丰富的社区资源可供参考。

简单来说，ESP32-S3 的性能与特性更契合本项目的长期目标，且其开发环境已足够成熟，直接上手是高效且务实的选择。

二、硬件介绍

2.1 ESP32-S3 开发板

本次测试与开发的主控是 ESP32-S3 开发板。作为乐鑫 ESP32 系列的高性能成员，它不仅继承了 ESP32 家族出色的无线连接能力和低功耗特性，还通过引入 AI 加速指令和更丰富的外设接口，为物联网与边缘计算应用提供了强大支持。

核心参数

参数	规格
主控芯片	ESP32-S3
CPU	Xtensa® 双核 32 位 LX7 处理器，主频最高 240 MHz
内存	512 KB SRAM + 8 MB PSRAM（视具体模组）
Flash	外置 SPI Flash，通常为 4 MB 或 8 MB
Wi-Fi	802.11 b/g/n，2.4 GHz
蓝牙	Bluetooth 5.0 LE
USB	原生 USB OTG
AI 加速	支持向量指令扩展
工作电压	3.0 ~ 3.6 V（开发板通过 USB 可输出 5V/3.3V）

为什么选择这款芯片

选择 ESP32-S3 作为本项目的主控，主要基于以下几点考虑：

性能充足：双核 LX7 处理器主频高达 240 MHz，配合 8 MB PSRAM，能够轻松应对 TFT 屏幕驱动、UI 渲染以及后续可能加入的数据处理任务。
AI 加速：内置的向量指令扩展为未来可能涉及的轻量级机器学习推理（如状态识别、预测）提供了硬件加速基础，无需外挂专用 AI 芯片。
原生 USB：支持 USB OTG，方便进行固件烧录、调试，甚至未来可连接 USB 外设，扩展性强。
低功耗与无线集成：在提供高性能的同时，依然保持了 ESP32 系列优秀的低功耗特性和稳定的 2.4 GHz Wi-Fi / BLE 5.0 连接能力，非常适合物联网项目。
开发生态完善：Espressif 为 S3 提供了完善的 ESP-IDF 开发框架，同时 Arduino IDE 和 PlatformIO 也提供了良好支持，社区资源和示例代码丰富。

简单总结就是：性能强、接口全、生态好。它为 Status Deck 项目提供了从原型验证到功能扩展的坚实硬件基础。

2.2 2.8寸显示屏幕

屏幕是整个项目的"脸面"------所有数据展示、UI 交互、状态反馈都要通过它呈现。本次选用的是一块 2.8 寸 ST7789 SPI 串口 TFT LCD 显示屏 ，价格仅 18 元，性价比极高。

基本规格

参数	规格
屏幕尺寸	2.8 英寸
显示类型	TFT LCD（薄膜晶体管液晶显示器）
分辨率	240 × 320 像素（QVGA）
驱动芯片	ST7789V
接口类型	SPI（4 线串行）
工作电压	3.3V（部分模块板载 3.3V 稳压，可兼容 5V）
触摸功能	无（本次项目仅用于显示）
购买价格	18 元

为什么选择这个屏幕

在选型阶段，其实考虑过几种方案：

屏幕类型	优点	缺点	选择结果
OLED 0.96 寸	驱动简单、功耗低	尺寸太小，信息展示有限	❌
TFT 1.8 寸	体积小巧	分辨率低，显示面积小	❌
TFT 2.8 寸	尺寸合适、分辨率够用、价格便宜	不支持触摸	✅ 选择
TFT 3.5 寸	显示面积大	分辨率提升不明显，体积偏大	❌

综合考虑项目需求（状态展示面板）和空间限制（需要集成到桌面设备中），2.8 寸是一个尺寸与便携性的最佳平衡点。240×320 的分辨率足以显示多行文字、图表和图标，同时 18 元的价格也让试错成本降到最低。

2.3 屏幕驱动转接板

裸屏无法直接连接 ESP32 进行开发。这类 2.8 寸 TFT 屏幕通常通过 FPC 排线引出大量引脚，排线间距非常小，普通杜邦线和面包板根本无法直接对接。因此，本项目额外搭配了一块 LCD 屏幕驱动转接板，由屏幕店家配套出售。

转接板的作用

转接板将 FPC 排线的细密引脚转换为标准 2.54mm 间距的排针接口，使得杜邦线可以直接连接 ESP32 开发板，极大简化了接线流程。

实际到货情况

本次购买的屏幕不带触摸功能，因此转接板上与触摸相关的引脚（如 T_IRQ、T_DO、T_DIN、T_CS、T_CLK）处于悬空或未焊接状态。到货时，转接板已与屏幕通过 FPC 排线连接完毕，无需自行组装，可直接使用杜邦线与 ESP32 连接。

价格：8 元

2.4 电源模块

为什么需要独立电源

ESP32 开发板的板载 3.3V 稳压器虽然可以输出一定电流，但对于驱动 2.8 寸 TFT 屏幕这类外设来说，供电能力可能略显不足------尤其是在屏幕显示复杂内容或高亮度时，电流需求会明显增加。供电不稳轻则导致屏幕闪烁、颜色异常，重则导致 ESP32 反复重启。

多路电源模块的优势

为了确保供电稳定可靠，我额外使用了一块多路电源模块。它能提供独立的 3.3V 和 5V 输出，不仅满足屏幕的供电需求，还能同时为传感器、LED 等其他外设供电。多路独立输出也便于调试时隔离不同模块的电源，方便排查问题。

需要注意的是，电源模块是可选的。 如果开发场景比较简单且屏幕工作正常，可以直接使用开发板的板载 3.3V 供电。电源方案的选择取决于实际需求和测试情况，本文仅作为参考。

三、硬件连接：让屏幕与 ESP32 对话

3.1 接线方案

本次连接共使用 8 根杜邦线，将屏幕与 ESP32-S3 开发板连接。按屏幕排针从下到上的顺序，接线如下：

屏幕引脚	功能说明	连接到 ESP32-S3 引脚
VCC	电源正极	3V3
GND	电源地	GND
CS	片选	IO5
RESET	复位	IO7
DC	数据/命令选择	IO6
SDI (MOSI)	主设备输出，从设备输入	IO17
SCK	SPI 时钟	IO18
LED	背光控制	IO4
SDO (MISO)	主设备输入，从设备输出	不接

注意事项：

屏幕的 SDO (MISO) 引脚在本项目中不需要连接，因为仅进行屏幕驱动，不读取屏幕数据。
触摸接口 T_IRQ / T_SDO / T_SDI / T_CS / T_CLK 全部不接，因为本屏幕不带触摸功能。
所有连接线请确保牢固，避免接触不良导致屏幕工作异常。

3.2 连接实物图

接线完成后的实物展示如下图所示。可以清晰地看到杜邦线从屏幕转接板连接到 ESP32-S3 开发板的对应引脚。

建议在接线完成后仔细检查每一根线的连接是否正确，特别是电源和地线，避免接反导致硬件损坏。

四、开发环境搭建

4.1 开发工具选择：PlatformIO

在开发工具的选择上，本项目采用 PlatformIO 作为主要的集成开发环境（IDE）和构建系统。

为什么选择 PlatformIO

虽然 Arduino IDE 上手简单，但在实际项目开发中，PlatformIO 具有明显优势：

对比项	Arduino IDE	PlatformIO
依赖管理	手动安装库，版本难以控制	`platformio.ini` 统一管理，版本锁定
项目结构	扁平化，所有文件堆在一起	标准化目录结构，清晰规范
多环境构建	不支持	支持多环境配置，一键切换
代码补全	基础支持	基于 IntelliSense，补全体验优秀
版本控制	不友好	原生支持 Git，便于协作
调试支持	有限	支持 OpenOCD 等调试器，功能强大

对于 Status Deck 这样需要长期迭代的项目，PlatformIO 的工程化管理能力能有效避免后期"配置地狱"。

PlatformIO 安装

PlatformIO 以 VS Code 扩展的形式提供，安装步骤如下：

在 VS Code 中搜索并安装 PlatformIO IDE 扩展
扩展安装完成后，侧边栏会出现 PlatformIO 的图标
首次使用时，PlatformIO 会自动安装核心工具链（PlatformIO Core）

提示：如果网络环境不佳，安装核心工具链可能较慢，可参考官方文档配置镜像源。

ESP32-S3 开发板支持包安装

PlatformIO 通过 Board 定义文件管理开发板支持。对于 ESP32-S3，需要安装对应的平台包：

打开 PlatformIO 主页，进入 Boards 搜索页面
搜索 esp32-s3，可以看到多种 ESP32-S3 开发板定义
根据实际使用的开发板型号选择对应的 Board 配置

在 platformio.ini 中，Board 配置示例如下：

ini 复制代码

[platformio]
boards_dir = boards
default_envs = esp32-s3-n16r8

; Status Deck 固定使用 ESP32-S3 N16R8：16MB Flash + 8MB Octal PSRAM。
; 执行 `pio run -t upload` 会直接构建并烧录这个目标。
[env:esp32-s3-n16r8]
platform = espressif32
board = esp32-s3-n16r8
framework = arduino
monitor_speed = 115200
upload_speed = 921600
lib_deps =
  h2zero/NimBLE-Arduino@^1.4.3
  bblanchon/ArduinoJson@^6.21.5
  adafruit/Adafruit GFX Library@^1.12.3
  adafruit/Adafruit ST7735 and ST7789 Library@^1.11.0
build_flags =
  ; 2.8 英寸 ST7789 SPI 屏。N16R8 的 GPIO26-32 被板载 Flash/PSRAM 使用，
  ; 因此只选开发板排针上可用的 GPIO4-7、17、18；GPIO19/20 留给原生 USB。
  -D STATUS_DECK_DISPLAY_CS=5
  -D STATUS_DECK_DISPLAY_DC=6
  -D STATUS_DECK_DISPLAY_RESET=7
  -D STATUS_DECK_DISPLAY_BACKLIGHT=4
  -D STATUS_DECK_DISPLAY_SCK=18
  -D STATUS_DECK_DISPLAY_MOSI=17
  -D STATUS_DECK_DISPLAY_SPI_FREQUENCY=40000000
  -D STATUS_DECK_ACTIVITY_LED_PIN=2

五、跑通第一个 Demo

完成 ESP32-S3、ST7789 屏幕接线与 PlatformIO 工程配置后，先通过一个简单的屏幕 Demo 验证三件事：

ESP32-S3 的 SPI 引脚接线正确
ST7789 屏幕可以正常初始化
屏幕能够完成颜色填充、文字与图形绘制

本项目使用 240 × 320 分辨率的 ST7789 SPI 彩屏，并为 ESP32-S3 N16R8 配置了 16MB Flash 和 8MB Octal PSRAM。PSRAM 用于存放完整帧缓冲，后续可以减少动态数据刷新时的闪烁。

5.1 Demo 功能设计

第一个 Demo 包含以下内容：

黑色背景初始化
红、绿、蓝三种颜色块填充测试
标题文字显示
简单矩形和进度条绘制
背光控制测试

屏幕使用的引脚定义如下：

屏幕引脚	ESP32-S3 GPIO
VCC	3V3
GND	GND
CS	GPIO5
RESET	GPIO7
DC	GPIO6
SDI / MOSI	GPIO17
SCK	GPIO18
LED	GPIO4
SDO / MISO	不接

注意：ESP32-S3 N16R8 的 GPIO26 至 GPIO32 被 Flash 和 PSRAM 占用，不能沿用经典 ESP32 的 GPIO26、GPIO27 接法。

5.2 Demo 完整代码

在当前工程中，屏幕初始化与绘制逻辑位于：

firmware/src/display/StatusDisplay.cpp
firmware/include/display/StatusDisplay.h
firmware/src/app/main.cpp

下面是一份可独立理解的最小 Demo 核心代码：

cpp 复制代码

#include <Arduino.h>
#include <SPI.h>
#include <Adafruit_GFX.h>
#include <Adafruit_ST7789.h>

constexpr int TFT_CS = 5;
constexpr int TFT_DC = 6;
constexpr int TFT_RST = 7;
constexpr int TFT_BL = 4;
constexpr int TFT_SCK = 18;
constexpr int TFT_MOSI = 17;

Adafruit_ST7789 display(TFT_CS, TFT_DC, TFT_RST);

void setup() {
  Serial.begin(115200);

  // ESP32-S3 使用自定义 SPI 引脚。
  SPI.begin(TFT_SCK, -1, TFT_MOSI, TFT_CS);

  // 打开屏幕背光。
  pinMode(TFT_BL, OUTPUT);
  digitalWrite(TFT_BL, HIGH);

  // 初始化 240 x 320 的 ST7789 屏幕。
  display.init(240, 320);
  display.setRotation(0);
  display.setSPISpeed(40000000);
  display.setTextWrap(false);

  // 背景填充测试。
  display.fillScreen(ST77XX_BLACK);

  // 颜色块测试。
  display.fillRect(16, 50, 64, 64, ST77XX_RED);
  display.fillRect(88, 50, 64, 64, ST77XX_GREEN);
  display.fillRect(160, 50, 64, 64, ST77XX_BLUE);

  // 文字显示测试。
  display.setTextColor(ST77XX_WHITE);
  display.setTextSize(2);
  display.setCursor(16, 16);
  display.println("Status Deck");

  display.setTextSize(1);
  display.setCursor(16, 140);
  display.println("ESP32-S3 + ST7789");

  // 简单进度条测试。
  display.drawRect(16, 180, 208, 20, ST77XX_WHITE);
  display.fillRect(18, 182, 140, 16, ST77XX_CYAN);

  display.setCursor(16, 220);
  display.println("Display demo ready.");
}

void loop() {
  // 第一个 Demo 不需要循环刷新。
}

5.3 编译与烧录

进入固件目录后执行：

复制代码

cd firmware
pio run -t upload

串口监视器可使用：

复制代码

pio device monitor -b 115200

正常启动时，串口会输出类似信息：

复制代码

ST7789 framebuffer ready: 153600 bytes
ST7789 ready: CS=5 DC=6 RESET=7 BL=4 SPI=40000000Hz

其中 153600 bytes 表示已经成功申请到一块 240 × 320 × 2 字节的 RGB565 帧缓冲。

5.4 运行效果展示

烧录成功后，屏幕应当显示：

顶部白色标题 Status Deck
中间的红、绿、蓝三个颜色块
一条青色进度条
底部的 Display demo ready. 文本

如果背光亮起但屏幕没有内容，优先检查：

CS、DC、RESET 是否接错。
SCK 是否接到 GPIO18，MOSI 是否接到 GPIO17。
屏幕供电是否为 3.3V，并且 ESP32-S3 与屏幕已经共地。
LED 是否接到 GPIO4；如果未接，屏幕背光可能不会亮。
将 SPI 频率从 40000000 降低到 32000000 后重新测试。

实际调试说明：当前阶段并没有逐步演示上述基础 Demo 的运行过程，而是直接将所有功能整合到最终效果中进行展示。这样做的原因在于------基础的颜色块填充、文字显示等测试步骤属于验证性质，而项目真正要呈现的是一个完整的状态面板。因此在确认硬件接线与 SPI 通信无误后，便直接推进到了最终效果的调试阶段。以下就是实际烧录后的屏幕效果：

从上面的实拍图可以看到，屏幕已经能够正常显示完整的状态面板界面，包括各项数据指标和布局排版。这标志着硬件层面已经完全跑通------ESP32-S3 可以通过 SPI 驱动 ST7789 屏幕，完成任意 UI 元素的渲染。这个里程碑的达成，为后续的固件功能开发打下了坚实的基础。

5.5 调试过程中的经验总结

在从接线到最终效果跑通的过程中，踩了不少坑，这里把关键经验总结出来，供后续开发或类似项目参考：

先验证最简通信 ：拿到屏幕后不要急着上最终效果，先用 fillScreen() 填满纯色确认 SPI 通信正常，再逐步叠加文字、图形等功能。
GPIO 选择要注意引脚复用：ESP32-S3 的部分 GPIO 被板载 Flash 和 PSRAM 占用（GPIO26-32），选引脚时务必查阅开发板的引脚映射表，避免使用被占用的引脚。
供电要充足：屏幕背光全亮时电流需求不低，如果同时外接其他传感器，建议使用独立电源模块供电，或者至少确认开发板的 LDO 能够承受总电流。
SPI 频率不要贪高：初次调试建议先使用 20MHz 或 30MHz，确认稳定后再逐步提升到 40MHz。杜邦线的接触质量会直接影响高频 SPI 的稳定性。
串口日志是好帮手：在初始化阶段加入 Serial.println 输出，可以帮助快速定位问题出在哪个环节------是 SPI 初始化失败、屏幕 ID 读取异常还是显示方向设置错误。

六、本篇总结与下期预告

6.1 本篇做了什么

回顾本篇文章，我们完成了以下里程碑：

✅ 硬件到货与设备盘点：确认 ESP32-S3 开发板、2.8 寸 ST7789 屏幕、转接板、电源模块全部到位。
✅ 硬件连接：完成 8 线杜邦线接线，屏幕与 ESP32-S3 正确对接。
✅ 开发环境搭建：配置 PlatformIO 工程，定义引脚宏、库依赖和编译参数。
✅ 第一个 Demo 跑通：屏幕成功点亮并显示完整的状态面板界面，验证了 SPI 通信、屏幕驱动、UI 渲染全链路正常工作。

从"快递到了"到"屏幕亮了"，这看起来只是简单的几步，但每一步都承载着前期大量的规划和设计。硬件的跑通意味着项目从"纸上谈兵"正式进入了"实战阶段"。

6.2 遇到的问题与解决思路

整个过程中并非一帆风顺，主要遇到的问题包括：

问题	原因	解决方案
屏幕白屏无显示	DC 引脚接错	对照引脚表重新核对接线
屏幕有背光但无内容	SPI 频率过高导致通信不稳定	降低 SPI 频率至 20MHz 后恢复正常
显示方向不正确	`setRotation()` 参数值不对	调整旋转参数（0-3）直到方向正确
串口无输出	波特率不匹配	统一使用 115200 波特率

这些问题虽然看似基础，但却是每个嵌入式项目初期都会遇到的典型障碍。记录下来，既能帮助自己复盘，也能为后来者提供参考。

6.3 下期预告

本篇解决了"屏幕能不能亮"的问题，下一篇文章将深入解决"屏幕应该显示什么"的问题。

下期内容规划：

ESP32-S3 固件项目工程详解：完整的项目目录结构、模块划分与构建配置
核心代码讲解：从屏幕初始化、UI 框架搭建到数据渲染的完整代码走读
状态面板 UI 设计：如何在 240×320 的小屏幕上合理布局，展示尽可能多的有效信息
数据通路打通：ESP32-S3 如何获取状态数据并驱动屏幕刷新

本篇文章所有的项目工程代码已在 GitHub 上开源：

欢迎 Star 和 Fork，也欢迎在 Issue 区交流讨论。如果觉得本系列文章对你有帮助，别忘了关注后续更新 👋