硬件玩法

如果你想把系统的开放接口做成桌面硬件面板、小屏状态牌、打印状态灯或独立监控终端，可以直接使用现成固件接入。

该玩法的核心思路是：硬件设备通过系统的 开放接口 轮询获取打印机状态，再把 printStatus、printProgress、温度、层数、耗材类型和告警信息展示出来。

开发者提示

硬件底层依赖于系统的开放接口进行数据查询。如果你需要查看接口细节、请求示例或进行自定义接口的对接开发，请参考 开放接口 文档。

设备版本与按键交互

硬件固件根据具体硬件形态，提供以下两种版本/工作模式：

• 单设备版 (SD2 模块)
  • 适合仅监控单台打印机的场景。
  • 无物理交互按键，数据根据设定自动定时轮询刷新。
• 多设备版 (带按键)
  • 支持配置和监控多台打印机，可通过物理按键进行如下交互操作：
    • 单击：手动刷新当前设备的状态数据。
    • 双击：在 时间（时钟） 与 设备状态 展示页面之间进行切换。
    • 长按：循环切换至下一个已绑定的打印机设备。

可以实现什么

基于当前开放接口，硬件端适合做这些只读展示类玩法：

• 显示打印机当前是否在线
• 显示打印状态，例如空闲、打印中、暂停、完成、失败
• 显示打印进度、剩余时间、当前层数和总层数
• 显示热床温度、仓温、喷嘴温度
• 显示当前耗材类型
• 当 hmsErrors 不为空时做本地告警提醒

能力边界

当前开放接口定位是只读查询，适合做状态屏、提示灯、展示终端，不提供通过该页面直接控制打印机的能力。

如何获取硬件

你可以根据自己的动手程度，选择下面三种方式之一：

1. 自行下载固件并手动烧录：下载固件 (单设备)
2. 使用浏览器一键烧录：一键烧录页面
3. 直接购买成品：成品购买链接 (多设备)

如果你选择自己装配或手动烧录（单设备），通常需要准备：

• SD2 模块 购买链接：拼多多购买
• 3D 打印外壳 外壳问题请自行解决
• USB 数据线 (需支持数据传输，而非仅充电)
• 电脑一台 (用于烧录和首次配置)
• 你的 API Key (从本系统获取)
• 目标打印机的 deviceId

手动烧录说明

如果你选择手动烧录，可以使用图形化烧录工具，例如乐鑫官方 Flash Download Tools（适用于 Windows）。

也可以使用命令行工具 esptool.py 直接烧录：

esptool.py --chip esp8266 --port <串口号> --baud 115200 write_flash 0x00000 firmware.bin

其中：

• macOS 常见串口名类似 /dev/cu.usbserial-xxx
• Windows 常见串口名类似 COM3

首次配置

设备首次启动后，会自动开启一个名为 PrinterHubOpenApi 的无密码热点。

连接该热点后：

1. 等待系统自动弹出配置页面
2. 如果没有自动弹出，在浏览器中手动访问 http://192.168.4.1
3. 按页面提示选择 Wi-Fi，输入密码，别的参数可后续配置。
4. 保存后等待设备重启并联网
5. 设备连接同一个Wi-Fi后，直接浏览器访问 http://printerhub-openapi.local

建议的接入顺序

为了减少排查成本，建议按下面顺序操作：

1. 先在电脑上调用 GET /api/open/ping，确认服务可访问。
2. 再调用 GET /api/open/whoami，确认 API Key 有效。
3. 再调用 GET /api/open/device/{deviceId}，确认目标设备能正常返回数据。
4. 最后再把相同的服务地址、API Key 和 deviceId 填进硬件配置页。

常见排查思路

• 连上热点但没有弹出页面：直接访问 http://192.168.4.1。
• 烧录完成但设备没有数据：优先检查 API Key、deviceId 和服务地址是否填写正确。
• 私有部署用户如果一直连接失败：先确认服务地址是否可被局域网设备访问，请求地址为：协议 + ip(域名) + 端口，例如：http://192.168.31.1:5173
• 如果接口本身已返回无权访问或设备不存在：先按开放接口文档进行接口调试排查。