Waveshare ESP32-S3 4 英寸触控屏案例
案例概述
本例使用 Waveshare ESP32-S3-Touch-LCD-4 Rev4，将 FastBee 的本地数据和控制入口集中到一块 4 英寸触控屏上。浏览器负责编辑布局和绑定数据，ESP32-S3 负责显示、触摸处理、采集和执行。日常查看与本地控制不要求一直打开浏览器；天气等网络数据仍需要联网。
图 1：连接设备后取得的 Web 编辑器示例截图。下文配图均为 Web 页面，展示布局和配置入口，不是实体屏拍照，也不代表当前版本已通过实物或长期稳定性验收。页面名称、数值和日期随实际配置变化。
| 页面示例 | 内容 | 数据或动作来源 |
|---|---|---|
| 首页 | 时间、温湿度、天气 | 系统时间、传感器采集、心知天气服务 |
| 最近记录 | 温度、湿度等趋势 | 已开启记录的数据源 |
| 设备控制 | 继电器开关动作、电机控制 | 已配置设备与获准执行的规则 |
| 系统操作 | 亮度、自动息屏、触摸提示音 | 显示外设能力与屏幕全局设置 |
这些页面可以增删和重新排列。系统不固定电机型号、从站地址或传感器，其他已支持的外设也可通过配置接入。
当前运行配置入口已合并到固件仓库docs/device-test-configs/com8-com9-esp32s3-touch/；旧板卡目录保留说明，不再假设其下仍有完整JSON。导入须先核对实际目录及目标设备，不复制历史网络凭据。
硬件准备
| 项目 | 本例配置 |
|---|---|
| 主控板 | Waveshare ESP32-S3-Touch-LCD-4，Rev4 / CH32 扩展控制版本 |
| 构建环境 | esp32s3-F16R8，16MB Flash、8MB PSRAM |
| 显示 | 4 英寸、480 × 480、RGB 接口，ST7701 初始化配置 |
| 触摸 | GT911，I2C 接口；本例按单点触摸使用 |
| 板载控制 | CH32V003，处理显示复位、背光及蜂鸣器等信号 |
| 可选传感器 | SHT30，用于首页温湿度和历史曲线 |
| 可选控制设备 | GPIO 继电器、Modbus 继电器、步进电机驱动器等 |
本例不是 Waveshare 6 路继电器板。同名系列不同板本的显示、扩展 IO 和引脚可能不同，先核对丝印及厂商硬件资料。触控屏自身通过 RGB/I2C 工作，不是 Modbus 从站，没有供触摸使用的 A/B 接口。
本例接口配置
| 用途 | 参数 | 说明 |
|---|---|---|
| 共享 I2C | SDA GPIO15、SCL GPIO7，100kHz | 触摸、CH32 和 SHT30 使用同一组总线配置 |
| CH32 | 地址 0x24 | 使用板级配置中的控制掩码，不套用其他扩展芯片的配置 |
| GT911 | 初始化探测 0x5D / 0x14 | 地址受复位/INT 时序影响，由触摸后端初始化 |
| SHT30 | 地址 0x44 | 示例采样周期 10 秒；未连接时不添加其数据组件 |
| 外部 RS485 | UART TX GPIO43、RX GPIO44；示例为 9600、8-N-1 | 按实际收发器和从站说明书接线、配置；不是触摸总线 |
完整 RGB 数据引脚及控制参数使用本板的配置文件，不建议逐项手工猜填。上述引脚属于此板例子，不是通用 ESP32-S3 接线约定。
配置步骤
1. 准备固件和本板配置
使用包含 RGB、GT911 支持并匹配本板的 esp32s3-F16R8 固件。硬件说明在 FastBee-Arduino 源码仓库的 docs/waveshare-esp32s3-touch-lcd4/ 中。
| 文件 | 用途 |
|---|---|
peripherals.json | 显示、触摸、共享 I2C、传感器和 UART 参数 |
screen_panel.json | 屏幕全局设置、页面及组件绑定 |
periph_exec.json | 采集和受限控制规则 |
protocol.json | 可选 Modbus 设备及寄存器映射 |
rgb-build-contract.json | RGB 编译缓冲与配置的一致性要求 |
此样例目录未附带 features.json；屏幕和传感器的运行时开关在 Web“功能配置”中设置并保存。
本例 RGB 为 12MHz，bufferLines=16，需要与固件的 16 行双 bounce 缓冲合同匹配。通用固件的环境名称相同，不意味着已使用同一 RGB 构建参数；按样例目录中的构建说明准备镜像。烧录方式见烧录与测试。
已有设备先备份配置，保留自己的网络、登录和平台连接参数。公开样例不含现场凭据，也不应覆盖另一台设备的配置。布局通过“设备屏幕”的导入及保存入口应用；外设和协议分别通过对应配置页面核对。
2. 联网并启用屏幕
- 按快速开始完成首次配网，使用串口日志或路由器中显示的本机地址访问 Web。
- 在“功能配置”中确认设备屏幕已编译并启用；添加 SHT30 时同时启用相应 I2C 传感器能力。按页面提示保存并重启。
- 在“外设配置”核对本板显示外设：RGB / ST7701、GT911、480 × 480、CH32 控制及 I2C 参数。示例显示外设 ID 为
panel_display。 - 进入“设备屏幕”，在全局属性中选择该显示外设，确认设备运行状态；需要重启才能应用的修改，重启后再次检查。
本板样例的 backlightActiveHigh=false。若改用其他屏幕，应按实际背光电路设置，不能把此值当作所有屏幕的默认极性。
3. 编辑首页、页面顺序和组件
- 在左侧新增页面，选择模板或空白布局，将首页设为默认页面。
- 从组件库添加“时钟”和两个“数值”组件，分别绑定温度、湿度来源。未配置采集时先完成采集规则，不用固定数字代替实时数据。
- 选中组件，在属性区填写标题、单位和尺寸；自由布局下可拖动位置、拖动角点改变大小。
- 页面列表可拖动排序，也可用上移、下移按钮调整。组件在画布内拖动改变位置；“重新排版”会按模板重新安排本页组件。
- 单击“保存并应用”，确认保存版本与设备应用状态。重新载入后核对布局，未保存草稿不会直接出现在实体屏上。
Web“设备屏幕”是编辑实体面板的入口；“设备大屏”是浏览器中的另一种展示界面。编辑画布上的控制预览不发送真实电机或继电器动作。
4. 添加天气与趋势
天气组件使用共享的心知天气配置。在天气属性中填写自己的 API Key、城市和更新周期，保存后按需更新；不要把 Key 放入公开截图。离线或服务失败时保留最近有效值并显示过期状态，不将缺失值当成 0。
图 2：为不同来源配置独立趋势组件。没有采样记录时不应期待曲线，只有一条记录时显示单点。
趋势组件需绑定真实数值来源，并在“最近记录”中开启相应来源的记录；执行规则产生的数据还应开启该规则的记录选项。每个来源最多显示十条有效记录，断档不会用伪造数据补齐。
5. 设置亮度与自动息屏
图 3：系统操作页示例。具体控件由布局和显示外设能力决定，可删去不需要的组件。
在“全局属性”中设置默认亮度、自动息屏和触摸提示音，再“保存并应用”。自动息屏关闭或选择“永不”时，闲置不会自动熄灭；开启后按设定时间处理。实体页也可添加亮度、息屏等系统组件。
逻辑亮度 0% 保持最低可见亮度，明确的息屏操作才关闭背光。息屏后的第一次触摸只用于唤醒，不同时执行该位置的控制按钮。触摸未就绪时不会自动息屏，以免留下无法触摸唤醒的黑屏。
接入继电器、电机等设备
屏幕复用外设、协议和规则层，不在界面中写死某种设备。先让设备通信和动作映射成立，再绑定屏幕组件。
| 设备 | 配置顺序 | 面板组件 |
|---|---|---|
| GPIO 继电器 | 配置引脚和有效电平，建立明确的开启、关闭规则 | 两个“执行一次”按钮 |
| Modbus 继电器 | 按手册配置从站、功能码及线圈/寄存器，建立固定开、关规则 | 两个“执行一次”按钮 |
| 可调数值设备 | 建立受支持的接收值规则，设置最小值、最大值、步长和精度 | 数值控件或滑块 |
| 步进电机 | 配置驱动器命令、速度/脉冲读回、动作许可和行程参数 | 专用电机组件 |
控制规则需启用并允许设备屏幕控制，再从编辑器中选择对应控制来源。修改规则目标或动作后，应重新核对绑定。普通继电器动作规则不自动等于布尔开关；按实际支持的控制类型选择组件。
电机组件提供一排正转、停止、反转按钮及参数控件。停止无需重新确认，启动仍受通信、参数和行程状态检查。滑台软限位应使用已核对的脉冲/毫米、原点和安全余量；标称 30cm 不能直接当作脉冲边界。命令应答也不等于已完成物理运动。
详细配置可继续阅读 Modbus 继电器、Modbus 步进电机和外设执行管理。
首次启动与检查
首次烧录、重启恢复和断电再上电要分别检查。仅能看到画面，不能说明 GT911 已经输出触摸坐标；Web 预览可操作也不能替代实体触控检查。
| 检查项 | 操作与预期 |
|---|---|
| 冷启动 | 断电再上电，等待显示运行；检查运行状态中的 touchReady 和 touchError |
| 点击 | 点击首页及其他底栏页面，确认只跳转一次、命中位置正确 |
| 滑动 | 在只读卡片区域左右滑动，确认换页；亮度滑块拖动应调整亮度 |
| 息屏唤醒 | 到达设置的闲置时间后息屏；首次触摸唤醒，抬手后再次触摸可操作 |
| 配置恢复 | 保存布局后重启，核对首页、页面顺序和亮度/息屏设置 |
| 数据更新 | 检查采样时间和趋势记录推进，不只看某一时刻的数值 |
若首次上电时画面正常、点击和滑动都无反应，先记录 touchReady、touchError、固件版本及启动日志，区分触摸初始化失败和无坐标上报；同时核对 GT911 与 CH32 的共享 I2C、复位/INT 配置。不要将触摸故障归因于 Modbus A/B 接线。
触摸后端初始化失败时，当前实现保留显示并周期重试；初始化成功仍须用真实点击、滑动验证。修复固件应在多次断电启动、网络连接及页面刷新场景下复测，不能仅用一次软件重启或短时观察宣布长期稳定。