Unified Printer API MQTT · PRINTDECK

打印机动态。
通过 MQTT 送达。

将打印机状态和打印事件发送到自己的本地代理。使用你选择的工具构建仪表板、通知和自动化。

打开 MQTT 设置了解 MQTT 主题
仅限本地网络设计为只读版本化 JSON
MQTT

一个连接。
多种可能。

PrintDeck 将统一格式的打印机数据发送到 Mosquitto 等本地代理。应用订阅更新，无需反复请求 REST API。HTTP 和 MQTT 可以独立运行，也可以同时使用。

PrintDeck

收集打印机数据

本地代理

向订阅者发送更新

Mosquitto

你的应用

仪表板、灯光、通知

Node-RED · Home Assistant
MQTT 设置指南

第一条 MQTT 消息

从一台打印机和一个订阅开始。Home Assistant 并非必需。

  1. 01

    准备代理

    使用 Mosquitto 等本地 MQTT 代理。PrintDeck 和应用都是代理的客户端；PrintDeck 本身不提供代理服务。创建登录凭据，允许 PrintDeck 发布主题，并允许应用读取这些主题。

  2. 02

    连接 PrintDeck

    在 Web Config 中打开设备设置 > Unified API。开启 MQTT，输入代理地址、端口和凭据，保存并检查连接。TLS 设置应与代理一致。使用自己的应用时，请关闭 Home Assistant 自动发现。

  3. 03

    订阅打印机状态

    将 MQTT 客户端连接到同一代理。从 Web Config 复制 MQTT 主题根路径，追加 /printers/+/status。+ 匹配每台已保存的打印机。在 PrintDeck 上选择一台在线打印机，等待约五秒即可收到新数据。

状态消息示例
订阅<topic-root>/printers/+/status
{
  "api_version": "v1",
  "status": {
    "printer_id": 1,
    "connection": {
      "state": "online",
      "detail_level": "full",
      "stale": false
    },
    "job": {
      "phase": "printing",
      "progress_percent": 42.5
    }
  },
  "_mqtt_generation": "12ab34cd-00000001"
}

精简示例。通过 status.job.progress_percent 读取进度，通过 status.job.phase 读取任务状态。

了解 MQTT 主题

选择
应用接收的数据。

主题根路径为 printdeck/<printdeck_id>/v1。从 Web Config 复制实际路径并追加以下后缀。使用 printers 目录中的打印机 ID，或用 + 匹配所有打印机。

阅读完整 API 指南
/printers

查找打印机

已保存打印机及其 ID 的目录。由代理保留。

/printers/+/status

状态更新

当前任务状态、进度、温度和近期事件日志。约每五秒发送一次实时消息。

/printers/+/events

打印事件

检测到的单个事件，例如 started、completed 或 milestone。使用 event_type 选择操作，使用 event_id 标识通知。

/availability

检查连接

代理保留的 PrintDeck 连接状态：online 或 offline。每台打印机的状态消息中都有独立的 status.connection.state。

使用 Home Assistant？

每台 PrintDeck 选择一种接入方式，以保留一组实体。

Home Assistant 自动发现

让实体自动出现。

将 Home Assistant 内置 MQTT 集成连接到同一代理。在 PrintDeck 中启用 Home Assistant MQTT 自动发现。设备、传感器和打印事件实体会自动出现，无需 HACS。

Home Assistant MQTT
PRINTDECK · HACS

使用 PrintDeck 集成。

通过 HACS 安装 PrintDeck，设置时选择 MQTT，并关闭标准自动发现。Home Assistant 使用自己的代理连接。请使用当前集成，版本为 0.1.7 或更高。

安装 PrintDeck 集成
创建第一个自动化
值得了解

基于
新鲜数据。

共享的只读数据

数据有多新？

MQTT 使用与 REST 相同的统一打印机字段，并附带传输元数据。状态约每五秒更新一次；非活动打印机仍按打印机列表刷新间隔更新。实时遥测和事件不会保留在代理上。

使用读数前，检查 status.connection.state、status.connection.stale 和 status.connection.detail_level。未知值为 null。目录和状态消息中的 _mqtt_generation 必须一致；发生变化时清除旧读数。

会收到每个打印事件吗？

事件描述检测到的变化；短暂变化可能被遗漏。单个事件采用 QoS 0，不保留也不重放。状态日志保留最近八条观察记录。跟踪 stream_id 和 sequence 以避免重复操作，重连后先建立基准，不触发历史事件操作。完整事件约定见 API 指南。

已连接，但没有消息？

检查代理地址、端口、TLS 和主题权限。使用 Web Config 中的准确主题根路径。实时状态不保留，请等待下次更新。代理登录凭据与 REST bearer 令牌不同。

连接与恢复

启用 TLS 时，PrintDeck 会验证代理证书和主机名。如有需要，可添加自己的 CA 证书。已保存的机密信息留在 PrintDeck 上。代理重启后，PrintDeck 会重新连接并发布新数据。

删除旧的自动发现条目

更换服务器或切换到 HACS MQTT 前，请在旧服务器仍可访问时关闭自动发现，并等待清理完成。若无法访问旧服务器，可能需要手动删除其保留的发现条目。重命名保留打印机身份，删除配置会移除其发现配置。

Unified Printer API

准备实现下一个想法？

在 API 指南中查看完整主题参考、消息字段和传输规则。

下载 API 指南