拓竹打印机监控面板

一个基于 Python Flask 的打印机监控和控制系统，支持在局域网内与拓竹(Bambu Lab)3D 打印机实时交互。

当前实现基于本地网络 MQTT（8883/TLS）通信，使用访问码进行鉴权。

说明：本项目是 LAN MQTT QuickStart，不包含云端模式。

🎯 功能

• ✅ 实时打印机状态监控
• ✅ 打印进度和温度显示
• ✅ 远程打印控制（暂停、继续、取消）
• ✅ WebSocket 推送实时更新
• ✅ 响应式 Web 控制面板
• ✅ 设备配置管理
• ✅ 打印任务监控日志
• ✅ 状态命令中心（低风险命令优先）
• ✅ 命令预览 + 二次确认后下发
• ✅ 完整 MQTT 命令模板离线校验（不连接打印机、不下发）

📋 系统要求

• Python 3.8+
• 拓竹打印机（X1、Pro、Max 等支持局域网 API 的型号）
• 局域网连接

🚀 快速开始

0. 启动前检查（必须）

1. 打印机与电脑在同一网段
2. 打印机已开启 LAN/本地模式
3. 你已获取打印机访问码（Access Code）
4. 防火墙未拦截 8883（打印机 MQTT）

1. 安装依赖

pip install -r requirements.txt

如果你使用 Windows PowerShell，复制环境文件可改用：

Copy-Item .env.example .env

2. 配置打印机

复制 .env.example 为 .env 并编辑：

cp .env.example .env

编辑 .env 文件，填入你的打印机信息：

PRINTER_HOST=192.168.1.100        # 打印机 IP 地址
PRINTER_ACCESS_CODE=your-code     # 打印机访问码
PRINTER_SERIAL=your-serial        # 打印机序列号（建议填写，控制命令需要）

3. （可选）离线校验命令模板

此步骤不会连接打印机，也不会发送任何 MQTT 命令：

python -c "from printer_monitor import BambuPrinterMonitor; m=BambuPrinterMonitor('0.0.0.0','dummy',''); r=m.validate_full_command_catalog(); print('total',r['total'],'valid',r['valid'],'invalid',r['invalid'])"

预期：invalid 为 0

4. 运行应用

python app.py

应用将在 http://localhost:5000 启动

🏠 Web UI 访问

打开浏览器访问：http://localhost:5000

首次使用步骤

1. 在打印机配置部分输入：

   • 打印机 IP 地址（如 192.168.1.100）
   • 打印机访问码
   • 序列号（建议填写）

2. 点击保存配置

3. 控制面板将显示实时状态

4. 在“状态命令中心”里先使用状态类命令（低风险）

5. 执行任意命令时，先在弹窗中确认 payload，再点击确认下发

📡 获取打印机信息

查找打印机 IP 地址

在 Windows 上：

# 方法 1：使用 ping
ping bambulab-<序列号>.local

# 方法 2：查看路由器 DHCP 客户端列表
# 或在拓竹官方 App 中查看打印机详情

获取访问码

1. 在拓竹官方 App 中打开打印机设置
2. 找到"本地访问"或"API 访问码"
3. 复制访问码

📁 项目结构

HowToControlBambu/
├── app.py                    # Flask 应用主程序
├── config.py                 # 配置管理
├── printer_monitor.py        # 打印机通信模块
├── requirements.txt          # Python 依赖
├── .env.example              # 环境变量示例
├── app/
│   ├── templates/
│   │   └── index.html        # Web UI 首页
│   └── static/
│       ├── style.css         # 样式文件
│       └── script.js         # 前端逻辑
└── .github/
    └── copilot-instructions.md

🎮 控制面板功能

打印机状态

• 设备型号、序列号、固件版本
• 当前打印机状态
• 实时连接状态指示

打印控制

• 暂停 - 暂停当前打印
• 继续 - 恢复已暂停的打印
• 取消 - 取消当前打印任务

打印任务

• 当前文件名
• 打印进度百分比
• 剩余打印时间估算

监控日志

• 系统事件日志
• 实时更新记录
• 错误/成功/警告提示

🔧 API 端点

方法	端点	说明
GET	/api/status	获取打印机状态
POST	/api/printer/pause	暂停打印
POST	/api/printer/resume	继续打印
POST	/api/printer/cancel	取消打印
GET/POST	/api/config	获取/设置配置
GET	/api/printer/scan	扫描局域网候选设备
GET	/api/printer/commands	获取状态命令与高风险控制命令预览
GET	/api/printer/commands/full	获取完整 MQTT 命令模板目录
GET	/api/printer/commands/validate	离线校验命令模板（不下发）
POST	/api/printer/command/preview	预览指定命令 payload
POST	/api/printer/command/execute	二次确认后执行命令

🌐 WebSocket 事件

从服务器接收：

• printer_status - 打印机状态更新
• connect_response - 连接确认

客户端发送：

• connect - 客户端连接事件

⚠️ 常见问题

无法连接到打印机

1. 检查 IP 地址是否正确
2. 确认打印机和电脑在同一网络
3. 验证访问码是否正确
4. 查看打印机是否开启了 LAN/本地控制
5. 确认 8883 端口可达

日志反复出现 /api/status

这是前端轮询状态导致。当前版本已在离线时自动降频，不会每 5 秒持续刷错误。

命令格式是否可靠

项目内置白盒检查：

• GET /api/printer/commands/full 查看完整命令模板
• GET /api/printer/commands/validate 查看本地校验报告（不连接打印机、不下发）

可选命令行方式：

python -c "from printer_monitor import BambuPrinterMonitor; m=BambuPrinterMonitor('0.0.0.0','dummy',''); r=m.validate_full_command_catalog(); print('total',r['total'],'valid',r['valid'],'invalid',r['invalid'])"

打印机显示离线

• 检查 Wi-Fi 连接
• 重启打印机
• 检查防火墙设置

控制命令无响应

• 确保打印机连接正常
• 查看监控日志错误信息
• 尝试重新保存配置

📚 更多资源

• 拓竹官方文档
• Flask-SocketIO 文档

📝 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

提示：首次运行时，应用会尝试自动连接到配置的打印机。如果连接失败，请在 Web UI 中重新配置。