1. 项目概述当ESPHome遇上工业级触摸屏如果你玩过ESPHome大概率是在NodeMCU、D1 Mini这类小巧的开发板上折腾连接几个传感器控制几个继电器通过Home Assistant在手机上看个数据。这很酷但总觉得少了点“实体感”——信息都藏在手机App里想看一眼温湿度还得掏手机解锁。而reTerminal E系列这块带触摸屏的工业级HMI人机界面设备恰好补上了这块拼图。它本质上是一台运行Linux的微型电脑自带一块分辨率不错的电容触摸屏接口丰富。我们的目标就是把ESPHome的逻辑“投射”到这块屏幕上让它成为一个集显示、控制、交互于一体的本地化智能家居中控终端或者任何你需要一个带屏控制器的场景。这不仅仅是“显示几个数字”那么简单。想想看你可以在屏幕上实时滚动显示所有传感器的数据用滑块无级调节灯光的亮度和色温点击按钮执行复杂的自动化场景甚至显示自定义的图表和历史曲线。所有操作都在本地完成响应迅速无需依赖云端隐私和安全也更有保障。这个“菜谱”要解决的就是如何打通ESPHome与reTerminal之间的桥梁从环境搭建、通信配置到UI设计一步步实现一个稳定、美观且功能强大的本地化显示控制方案。无论你是想做一个家庭环境信息面板还是一个车间设备状态监控屏这套基础都能让你快速上手。2. 核心思路与方案选型为什么是MQTT Dashboard要让reTerminal显示和控制ESPHome设备核心是建立一个可靠的双向通信机制。市面上有多种方案我们需要权衡复杂度、可靠性、灵活性和资源消耗。2.1 可选方案对比ESPHome API直连ESPHome设备本身内置了API Server。理论上可以在reTerminal上写一个Python程序直接通过TCP连接ESPHome设备的6053端口进行通信。这听起来很直接但问题不少。首先需要处理TCP连接的重连、保活其次ESPHome的API协议虽然文档化但自己实现订阅、发布逻辑比较繁琐最后当设备数量多时管理多个TCP连接会成为负担。这不是一个“菜谱”该推荐给大众的方案它更偏向定制化开发。Home Assistant前端集成在reTerminal上安装Home Assistant Core然后通过其前端访问。这功能最全但重量级。reTerminal虽然性能不错但运行完整的HA Core加上数据库会占用大量资源启动慢而且我们可能只需要一个简单的控制面板杀鸡用牛刀了。MQTT 自定义前端这是本菜谱选择的方案也是我认为在灵活性、轻量化和可靠性上最平衡的选择。ESPHome原生支持MQTT协议可以轻松地将所有实体的状态发布到MQTT服务器并订阅来自MQTT的控制指令。reTerminal这边我们只需要运行一个MQTT Broker如Mosquitto和一个轻量级的Web服务器来承载我们的控制界面。界面本身可以用任何Web技术HTML/CSS/JS来开发或者使用现成的框架。2.2 最终方案详解MQTT ESPHome Dashboard我们选择的具体实现路径是在reTerminal上部署Mosquitto作为MQTT代理并利用ESPHome本身强大的“仪表盘”功能来生成Web界面。这个方案的巧妙之处在于ESPHome Dashboard 它不是一个运行在ESP设备上的东西而是一个由ESPHome编译系统生成的、描述设备所有实体传感器、开关等的Web界面配置文件一个json文件。我们可以通过ESPHome的命令行工具为我们的设备生成这个dashboard配置文件。轻量级Web服务器 在reTerminal上我们运行一个简单的Web服务器例如Python的http.server或Flask主要做两件事一是托管这个dashboard的静态文件HTML, JS, CSS二是提供WebSocket桥接将前端界面与本地Mosquitto MQTT Broker连接起来。数据流 ESPHome设备 --MQTT-- reTerminal上的Mosquitto --WebSocket-- 浏览器中的Dashboard界面。这样做的好处是巨大的免开发 我们几乎不用写前端UI代码ESPHome Dashboard自动根据你的设备配置生成美观、适配移动端的界面。实时双向 状态更新和控制指令都是实时的。资源占用极低 reTerminal上只需运行Mosquitto和一个轻量Web服务压力很小。高度可定制 生成的Dashboard是开源项目我们可以修改其前端代码来深度定制UI满足工业控制等特殊需求。注意 网络上有些方案会推荐在reTerminal上安装ESPHome Web服务器这通常是为了通过浏览器配置ESPHome设备类似Home Assistant的插件。我们这里讨论的是“显示与控制”而非“配置”所以目的不同方案也不同不要混淆。3. 环境准备与基础配置工欲善其事必先利其器。在开始烹饪这道“大菜”之前我们需要准备好厨房和食材。这一部分将详细说明reTerminal E系列设备的初始化、ESPHome设备的配置以及MQTT环境的搭建。3.1 reTerminal E系列基础设置拿到reTerminal后首先需要为其安装操作系统。官方推荐并提供了适配的Raspberry Pi OS基于Debian镜像。使用Raspberry Pi Imager工具烧录镜像到MicroSD卡是最稳妥的方式。烧录时建议提前在Imager中设置好主机名、开启SSH、配置Wi-Fi和地区设置这样开机后就能直接通过网络访问无需连接键鼠显示器。首次SSH登录后有几项关键操作系统更新sudo apt update sudo apt upgrade -y安装必要工具sudo apt install -y git curl wget vim python3-pip配置静态IP可选但推荐 对于作为家庭网络固定节点的设备配置静态IP能避免IP变化导致的连接问题。修改/etc/dhcpcd.conf文件添加你的网络接口如wlan0和静态IP信息。安装Docker推荐 使用Docker来部署Mosquitto等服务能保持环境干净便于管理和迁移。安装命令可参考Docker官方文档。3.2 ESPHome设备配置要点假设你已经有一个配置好的ESPHome设备例如ESP32。关键是在其YAML配置文件中正确启用并配置MQTT。# 示例 esp32-device.yaml 片段 esphome: name: living-room-sensor platform: ESP32 board: nodemcu-32s wifi: ssid: Your_WiFi_SSID password: Your_WiFi_Password # 建议设置静态IP方便管理 manual_ip: static_ip: 192.168.1.100 gateway: 192.168.1.1 subnet: 255.255.255.0 # 启用MQTT并配置 mqtt: broker: 192.168.1.50 # reTerminal的IP地址 port: 1883 username: mqtt_user # 如果Broker设置了认证 password: mqtt_password discovery: false # 如果你不用HA的自动发现可以关闭 # 以下两个设置对Dashboard生成很重要 topic_prefix: esphome/living-room-sensor # 定义一些传感器和开关 sensor: - platform: dht pin: GPIO4 temperature: name: Living Room Temperature id: temp humidity: name: Living Room Humidity id: hum update_interval: 30s switch: - platform: gpio pin: GPIO5 name: Living Room Light id: light_switch # 启用API可选用于OTA或直接连接 api: encryption: key: your_encryption_key ota: password: your_ota_password logger:关键参数解析broker 这里填reTerminal的IP地址。确保ESP设备能ping通这个地址。topic_prefix 这是生成Dashboard的关键。ESPHome Dashboard会根据这个前缀来构造MQTT主题。建议格式为esphome/设备名清晰且易于管理。discovery: false 因为我们不依赖Home Assistant可以关闭自动发现减少不必要的MQTT流量。配置完成后编译并烧录到你的ESP设备。使用esphome run living-room-sensor.yaml命令可以一站式完成编译、上传和日志监控。3.3 MQTT Broker部署与安全配置在reTerminal上我们使用Docker部署Mosquitto这是最简洁的方式。首先创建一个目录用于存放Mosquitto的配置和数据mkdir -p ~/mqtt/config ~/mqtt/data ~/mqtt/log然后创建Mosquitto的配置文件~/mqtt/config/mosquitto.confpersistence true persistence_location /mosquitto/data/ log_dest file /mosquitto/log/mosquitto.log # 监听端口 listener 1883 0.0.0.0 protocol mqtt # 允许匿名连接初期测试可开启生产环境务必关闭 allow_anonymous true # 生产环境建议设置用户密码 #password_file /mosquitto/config/passwd # 创建密码文件命令 docker exec -it mosquitto mosquitto_passwd -c /mosquitto/config/passwd mqtt_user接着使用Docker命令运行Mosquitto容器docker run -d --name mosquitto \ --restart unless-stopped \ -p 1883:1883 \ -p 9001:9001 \ -v ~/mqtt/config:/mosquitto/config \ -v ~/mqtt/data:/mosquitto/data \ -v ~/mqtt/log:/mosquitto/log \ eclipse-mosquitto:2安全提醒 上述配置中allow_anonymous为true仅用于快速测试。在任何实际部署环境中必须将其改为false并创建密码文件。使用docker exec命令进入容器创建用户或先在本地用mosquitto_passwd命令创建好文件再挂载。运行后你可以使用MQTT客户端工具如MQTT Explorer、MQTTX连接到reTerminal_IP:1883订阅#主题应该能看到你的ESPHome设备上线并发布状态信息了。这是验证通信是否成功的第一步。4. 生成与部署ESPHome Dashboard这是将ESPHome设备实体“可视化”的核心步骤。ESPHome Dashboard本身是一个静态Web应用我们需要生成它并把它放到reTerminal上供浏览器访问。4.1 生成Dashboard配置文件你需要在安装了ESPHome命令行工具的环境下操作可以是你的开发电脑也可以是reTerminal本身。假设你的设备配置文件名是living-room-sensor.yaml。运行以下命令来生成Dashboard的配置包esphome dashboard living-room-sensor.yaml这个命令会做几件事编译设备配置如果之前没编译过。在esphome的配置目录下通常是~/.esphome或项目目录生成一个与设备同名的文件夹例如living-room-sensor/。在该文件夹内生成一个dashboard.json文件以及相关的静态网页资源。关键点 生成的dashboard.json文件包含了设备所有实体的定义、类型、图标以及对应的MQTT主题路径。这个文件是前端界面渲染的依据。4.2 部署Dashboard到reTerminal现在我们需要把这个生成的Dashboard文件夹传输到reTerminal上并用一个Web服务器托管它。方法一简单静态服务器适用于快速测试在reTerminal上将Dashboard文件夹放在某个目录下例如/home/pi/dashboards/living-room-sensor。然后使用Python快速启动一个HTTP服务器cd /home/pi/dashboards python3 -m http.server 8080这样你就可以在reTerminal的浏览器或同一网络下的其他电脑浏览器访问http://reTerminal_IP:8080/living-room-sensor来看到界面了。但这个方法缺少了MQTT WebSocket桥接界面无法显示实时数据和控制设备。方法二使用集成WebSocket桥接的服务器推荐我们需要一个能同时提供静态文件服务和MQTT over WebSocket桥接的服务器。这里提供一个极简的Python Flask应用示例。在reTerminal上创建一个新的Python项目目录并安装依赖pip install flask flask-mqtt flask-socketio eventlet创建一个app.py文件from flask import Flask, send_from_directory from flask_socketio import SocketIO from flask_mqtt import Mqtt import os app Flask(__name__) app.config[SECRET_KEY] your_secret_key app.config[MQTT_BROKER_URL] localhost # Broker运行在本地 app.config[MQTT_BROKER_PORT] 1883 app.config[MQTT_USERNAME] # 如果Broker有认证 app.config[MQTT_PASSWORD] app.config[MQTT_KEEPALIVE] 5 app.config[MQTT_TLS_ENABLED] False socketio SocketIO(app, cors_allowed_origins*) mqtt Mqtt(app) # 假设你的dashboard静态文件放在 static_dashboards 文件夹下 DASHBOARD_DIR static_dashboards mqtt.on_connect() def handle_mqtt_connect(client, userdata, flags, rc): print(MQTT connected) # 连接后可以订阅一些全局主题如果需要 # mqtt.subscribe(esphome/#) mqtt.on_message() def handle_mqtt_message(client, userdata, message): # 收到MQTT消息后通过SocketIO转发给所有连接的Web客户端 data { topic: message.topic, payload: message.payload.decode() } socketio.emit(mqtt_message, data) socketio.on(publish) def handle_publish_event(json): # 接收来自Web客户端的控制指令发布到MQTT mqtt.publish(json[topic], json[payload]) app.route(/dashboard/path:filename) def serve_dashboard(filename): # 提供Dashboard静态文件 return send_from_directory(DASHBOARD_DIR, filename) app.route(/) def index(): # 重定向到你的主Dashboard页面 return send_from_directory(DASHBOARD_DIR, index.html) if __name__ __main__: # 将之前生成的整个dashboard文件夹如living-room-sensor复制到 static_dashboards 目录下 # 访问地址为 http://reTerminal_IP:5000/ socketio.run(app, host0.0.0.0, port5000, debugTrue)这个服务器做了三件事作为MQTT客户端连接到本地的Mosquitto。作为WebSocket服务器与浏览器中的Dashboard页面通信。作为静态文件服务器提供Dashboard的HTML/JS/CSS文件。将之前生成的整个living-room-sensor文件夹复制到static_dashboards目录下并确保其中的index.html是入口文件。运行python app.py现在访问http://reTerminal_IP:5000你应该能看到一个功能完整的ESPHome Dashboard可以实时显示数据并控制开关了。4.3 优化与生产部署上述Flask示例仅用于演示原理。对于生产环境你需要使用生产级服务器 用gunicorn或uWSGI配合eventlet或gevent来运行Flask应用。设置开机自启 使用systemd服务来管理你的Python应用和Mosquitto容器。配置Nginx反向代理 使用Nginx处理静态文件效率更高并将动态请求WebSocket代理给后端应用同时可以配置HTTPS。管理多个设备 你可以为每个ESPHome设备生成一个Dashboard文件夹然后修改Flask应用使其能根据URL动态加载不同的Dashboard。或者探索将多个设备的实体合并到一个自定义的、统一的界面中这需要更多的前端开发工作。5. 界面定制与高级功能实现基础的Dashboard已经可用但你可能觉得界面过于“自动生成”想让它更贴合reTerminal的屏幕尺寸或者增加一些特殊控件。这就涉及到定制。5.1 理解Dashboard的生成机制ESPHome Dashboard的UI是由一个叫做“ESPHome Web Server”的前端项目生成的。当你运行esphome dashboard命令时它使用了这个前端项目的编译后代码。如果你想深度定制有两个方向修改生成模板 这比较困难需要理解ESPHome的内部代码和前端项目的构建流程。在前端注入自定义代码 更实用的方法。部署后你可以直接修改static_dashboards/your_device/目录下的JavaScript和CSS文件。例如修改app.js或相关的样式文件来调整布局、颜色、字体大小使其更适合reTerminal的横屏或竖屏显示。一个简单的例子是修改CSS来适应屏幕/* 在dashboard的css文件中添加 */ media screen and (max-width: 1024px) { /* 针对reTerminal屏幕尺寸 */ .card { margin: 5px; padding: 10px; } .entity { font-size: 1.2em; /* 调大字体 */ } }5.2 集成多个设备与自定义页面一个reTerminal面板通常需要显示多个设备的信息。你不需要为每个设备单独开一个页面。方法A使用MQTT订阅所有设备主题在你的自定义Flask/SocketIO后端中让MQTT客户端订阅一个更广的主题例如esphome/#。当收到任何设备的消息时都通过WebSocket广播给前端。前端则维护一个所有设备实体的状态对象并根据设备ID和实体ID更新对应的UI组件。这需要你完全自己编写前端界面但灵活性最高。方法B利用Home Assistant的前端进阶如果你不排斥在reTerminal上运行更重的服务可以安装Home Assistant Core无Supervisor。然后将ESPHome设备通过MQTT自动发现接入HA。最后在HA中创建一张仪表盘Dashboard专门为reTerminal的屏幕尺寸设计布局。你可以在reTerminal上使用Kiosk模式运行一个全屏浏览器指向这个HA仪表盘地址。这样你就能利用HA强大的UI编辑器如Mushroom卡片创建出非常美观的界面。这相当于把reTerminal变成了一个Home Assistant的专用触摸终端。5.3 添加本地语音与告警功能reTerminal有麦克风和扬声器接口这为本地化交互提供了可能。语音反馈 当某个传感器数值超过阈值如温度过高你可以在reTerminal上运行一个Python脚本使用pyttsx3或gTTS库合成语音并通过扬声器播放告警。本地通知 同样可以编写一个守护进程订阅相关的MQTT主题如esphome/设备名/传感器/状态当状态变化时在reTerminal的屏幕上弹出本地通知可以用tkinter或PyQt做一个简单的通知窗口甚至触发蜂鸣器。这些高级功能将reTerminal从一个单纯的“显示器”升级为一个具有边缘计算能力的交互终端。6. 常见问题与调试技巧实录在实际搭建过程中你肯定会遇到各种问题。这里记录了一些典型坑位和解决方法。6.1 MQTT连接失败症状 ESPHome设备日志显示无法连接到Broker或者reTerminal上的Mosquitto日志显示连接被拒绝。排查网络连通性 在ESP设备上ping一下reTerminal的IP地址。确保它们在同一个子网没有防火墙如ufw阻挡1883端口。在reTerminal上运行sudo ufw allow 1883。Mosquitto配置 检查mosquitto.conf中的listener 1883 0.0.0.0是否正确。确保Docker容器的端口映射-p 1883:1883没错。认证问题 如果你设置了密码确保ESPHome YAML中的username和password与Mosquitto中创建的一致。一个快速测试方法是暂时将allow_anonymous设为true看是否能连接成功。客户端ID冲突 确保你的多个ESP设备没有使用相同的name因为name会作为默认的MQTT客户端ID重复会导致后连接的踢掉先连接的。6.2 Dashboard页面空白或数据不更新症状 能打开网页但看不到实体卡片或者卡片数据一直是“不可用”。排查WebSocket连接 打开浏览器的开发者工具F12查看“网络”(Network)选项卡过滤“WS”WebSocket。应该能看到一个到ws://reTerminal_IP:5000/socket.io/的连接。如果失败检查后端Flask-SocketIO服务是否正常运行以及是否有跨域问题示例代码中已设置cors_allowed_origins*。MQTT主题匹配 这是最常见的原因。Dashboard前端通过topic_prefix来构造订阅主题。打开浏览器开发者工具的“控制台”(Console)查看前端JavaScript的错误或日志。同时用MQTT客户端工具如MQTT Explorer查看ESPHome设备实际发布的主题是什么。确保前后端的主题模式一致。例如设备发布到esphome/living-room-sensor/sensor/temperature/stateDashboard应该订阅类似esphome/living-room-sensor/#的主题。后端消息转发 检查Flask后端是否正确地收到了MQTT消息并将其通过SocketIO转发。可以在handle_mqtt_message函数中添加print语句来调试。6.3 reTerminal性能与优化症状 界面操作卡顿或者系统运行一段时间后变慢。优化关闭不必要的服务 reTerminal默认的Raspberry Pi OS可能包含一些你用不到的服务如蓝牙、Avahi等。使用sudo systemctl disable --now servicename来禁用它们。使用轻量级窗口管理器 如果你不需要完整的桌面环境可以安装如openbox或fluxbox这类轻量级窗口管理器甚至直接以控制台模式运行用Chromium的Kiosk模式显示Dashboard能节省大量内存和CPU。优化Python服务 对于生产环境一定要用gunicorn替代Flask开发服务器并配合eventletworker。可以使用--workers参数根据CPU核心数设置工作进程数。监控资源 使用htop,vmstat命令监控CPU和内存使用情况。MQTT消息频率过高也可能造成压力适当调整ESPHome传感器的update_interval。6.4 触摸屏校准与显示设置reTerminal的触摸屏可能需要在特定系统下校准。官方提供了libinput的校准工具。如果触摸不准可以尝试执行sudo apt install libinput-tools然后使用libinput calibrate-touchscreen命令。对于显示方向横屏/竖屏可以通过修改/boot/config.txt文件中的display_rotate参数来调整。问题速查表问题现象可能原因排查步骤ESPHome设备无法连接Wi-FiSSID/密码错误信号弱检查YAML配置查看设备串口日志MQTT连接时断时续WiFi不稳定Broker负载高检查网络信号查看Mosquitto日志有无错误Dashboard能显示但控制无效MQTT发布主题错误权限问题用MQTT工具监听控制主题查看前端发布的消息格式reTerminal无法访问外网DNS配置问题检查/etc/resolv.conf尝试ping 8.8.8.8自定义界面样式不生效浏览器缓存强制刷新浏览器(CtrlF5)检查CSS文件路径最后分享一个我个人的调试习惯分层验证。先确保ESPHome设备能联网并发布MQTT消息用串口日志和MQTT客户端工具验证。再确保reTerminal上的Mosquitto能收到这些消息。然后确保你的Web后端能连接到Mosquitto并收到消息。最后确保浏览器能连接到Web后端并通过WebSocket收到数据。按照这个顺序任何一环出问题都能快速定位。这个项目最迷人的地方在于当你在reTerminal的屏幕上轻轻一点远处的灯光应声而亮或者环境数据平滑地滚动更新时那种软硬件结合、本地化控制带来的确定性和即时反馈感是纯云端方案难以比拟的。它不仅仅是一个显示终端更是你智能家居系统中的一个坚实、可靠的交互节点。