KlipperScreen-esp¶
KlipperScreen-esp 是一款紧凑的跨平台 3D 打印机显示与控制软件，可运行在低成本 ESP32 开发板以及 Windows/macOS 桌面端。它通过 Moonraker 完整控制 Klipper 打印机，并在 ESP32 与桌面端提供只读的拓竹云端状态监视；共享 LVGL 界面支持触摸、旋转编码器、鼠标、键盘或混合输入，EC11 参考板则展示了完全不使用触摸屏的纯旋钮设备。
单独命名的 SDL2 模拟器使用 mock 数据，无需连接打印机即可用于布局开发、输入实验和界面截图。
功能特性¶
- 主界面 — 喷嘴/热床/腔体温度卡片、打印进度、一键操作
- G-code 文件 — 缩略图、元数据、历史记录，打印/删除
- 控制 — 轴点动与回零、冷挤出保护的挤进/回抽、温度预设（PLA/PETG/ABS/冷却）、带确认的紧急停止与固件重启
- 打印微调 — 打印中或暂停时，从打印状态页右上角进入；Z 单独选择 0.01/0.05mm，速度和流量共用 1%/5%/10%/25% 步长，支持恢复 0mm/100%。Wio Terminal 因程序 Flash 限制暂不开放。
- 手动调平 — 菜单中的
bed_level面板从[bed_screws]或[screws_tilt_adjust]读取三点/四点螺丝坐标，点选位置安全移头；探针方案支持计算和显示螺丝调整结果。未配置时只显示配置提示，打印中/暂停时禁用操作。Wio Terminal 因程序 Flash 限制暂不开放。 - 稳健连接 — WebSocket 自动重连、应用层心跳与 RTT 显示、僵尸连接检测、Klipper 错误 toast（如限位未触发）
- 拓竹状态监视 — ESP32 与桌面端均支持登录、验证码、账号设备选择和云端 MQTT 状态同步；云端模式只读，局域网 Developer Mode 控制路径预留给后续后端。
- 杂项 — "Umeko" 开机动画、5 种语言（EN / 简中 / 繁中 / FR / IT，切换时淡黑重启）、亮度滑条、自动息屏触摸唤醒、标题栏时钟从当前后端的标准 HTTP 时间同步
- 输入路线 — 无触摸旋钮板无需触摸层；电阻屏走板型专属校准流程；电容屏通常直接提供屏幕坐标；触摸和旋钮可以共存
支持的板子¶
| 板型 | 屏幕 | 触摸 | 主控 | 状态 |
|---|---|---|---|---|
| CYD 2432S028R | 2.8" 320×240 ILI9341 SPI | XPT2046 电阻 | ESP32 | ✅ 稳定 |
| CYD 2432S028R-PLUS | 2.8" 320×240 ST7789 SPI | XPT2046 电阻 | ESP32-WROOM-32E | 🆕 新机型，CYD 引脚 |
| E32R35T（ESP32-32E 3.5"） | 3.5" 480×320 ST7796 SPI | XPT2046 电阻（共总线） | ESP32-32E | ✅ 稳定 |
| esp32s3-st7789-320_240-ec11 | 240×320 ST7789 SPI | 无，纯旋钮 | ESP32-S3 N16R8 | ✅ 官方参考，贡献者实机验证 |
| esp32-st7735s-128_160-ec11 | 1.8" 128×160 ST7735S SPI | 无，纯旋钮 | ESP32 | 🆕 新机型，引脚兼容 CYD |
| esp32-st7789-320_240-ec11 | 240×320 ST7789 SPI | 无，纯旋钮 | ESP32 | 🆕 新机型，引脚兼容 CYD |
| esp32-ILI9341-320_240-ec11 | 240×320 ILI9341 SPI | 无，纯旋钮 | ESP32 | 🆕 新机型，引脚兼容 CYD |
| esp32-ST7796-320_240-ec11 | 240×320 ST7796 SPI | 无，纯旋钮 | ESP32 | 🆕 新机型，引脚兼容 CYD |
| esp32s3-st7796-480_320-xpt2046-ec11 | 480×320 ST7796S SPI | XPT2046 电阻（共总线）+ EC11 | ESP32-S3 N16R8 | 🆕 新机型 |
| esp32s3-ILI9488-480_320-xpt2046-ec11 | 3.5" 480×320 ILI9488 SPI | XPT2046 电阻（共总线）+ EC11 | ESP32-S3 N16R8 | 🆕 新机型，MKS PI-TS35 |
| esp32s3-ILI9341-320_240-xpt2046-ec11 | 320×240 ILI9341 SPI | XPT2046 电阻（共总线）+ EC11 | ESP32-S3 N16R8 | 🆕 新机型 |
| JC8048W550 | 5" 800×480 ST7262 RGB 并口 | GT911 电容 | ESP32-S3 | ✅ 稳定 |
| esp32c3-st7789-320_240-ec11 | 240×320 ST7789 SPI | 无，纯旋钮 | ESP32-C3 | 🆕 新机型，合宙 CORE/Super Mini 通用 |
详细引脚与硬件参数见支持的板子。
快速开始¶
- 从 Releases 下载对应板型的 zip，解压后
flash.bat COMx（Windows）或./flash.sh /dev/ttyUSB0 - 设置 → 无线网络：扫描 → 选 AP → 输密码
- 设置 → 打印机连接设置：选打印机槽位和 Klipper/拓竹模式；Klipper 再填写主机 IP + 端口（默认 7125），拓竹继续进入局域网或云端设置
自行编译见仓库 README；把固件移植到自己的板子见移植指南。移植指南第 5 步先选择“无触摸”或“有触摸”，有触摸时再区分电阻屏和电容屏。
触摸校准（电阻屏板型）¶
电阻触摸板型（XPT2046：CYD 2432S028R / 2432S028R-PLUS、E32R35T、ESP32-S3 480×320 XPT2046 系列）支持两点校准。无校准数据的板子首次开机会自动进入校准界面；出厂固件已内置默认参数的板子，点击若有偏移可随时重校：
- 刷机时：release 刷机包脚本（
flash.bat/flash.sh）刷完会询问是否需要校准，输入y即自动通过串口把机器送入校准界面；开发路径tools/build-esp32.sh <board> flash COMx同样会询问。 - 任意时刻：串口 115200 8N1 连接，发送
caltouch，设备立即重启进入校准界面。
依次精准点按两个校准点即可，结果保存到 flash，每次开机自动加载。
文档导航¶
- 支持的板子 — 现有板型的硬件信息与引脚定义
- 移植到自己的开发板 — BSP 接口契约与实现要点
- 界面展示 — 当前桌面模拟器英文界面截图
- 架构说明 — 共享 UI、BSP、桌面控制端与模拟器结构
- 拓竹接入说明 — 当前只读云端边界与后续局域网路线