Unified Printer API MQTT · PRINTDECK

Aktuelles vom Drucker.
Direkt über MQTT.

Sende Druckerstatus und Druckereignisse an deinen eigenen lokalen Broker. Erstelle Dashboards, Benachrichtigungen und Automationen mit den Anwendungen deiner Wahl.

MQTT-Einrichtung öffnenMQTT-Themen ansehen
Nur lokales NetzwerkVon Grund auf schreibgeschütztVersioniertes JSON
MQTT

Eine Verbindung.
Viele Möglichkeiten.

PrintDeck sendet vereinheitlichte Druckerdaten an einen lokalen Broker wie Mosquitto. Deine Apps abonnieren Aktualisierungen, statt sie regelmäßig über die REST-API abzufragen. HTTP und MQTT können unabhängig oder gemeinsam laufen.

PrintDeck

Sammelt deine Druckerdaten

Dein lokaler Broker

Liefert Aktualisierungen an Abonnenten

Mosquitto

Deine Apps

Dashboards, Licht, Benachrichtigungen

Node-RED · Home Assistant
MQTT-Einrichtungsanleitung

Deine erste MQTT-Nachricht

Starte mit einem Drucker und einem Abonnement. Home Assistant ist optional.

  1. 01

    Richte deinen Broker ein

    Verwende einen lokalen MQTT-Broker wie Mosquitto. PrintDeck und deine App verbinden sich als Clients; PrintDeck stellt keinen Broker bereit. Erstelle Zugangsdaten und erlaube PrintDeck das Veröffentlichen sowie deiner App das Lesen seiner Themen.

  2. 02

    PrintDeck verbinden

    Öffne in Web Config Geräteeinstellungen > Unified API. Aktiviere MQTT, gib Brokeradresse, Port und Zugangsdaten ein, speichere und prüfe die Verbindung. Passe TLS an deinen Broker an. Lasse Home Assistant Discovery für deine eigene App ausgeschaltet.

  3. 03

    Abonniere den Druckerstatus

    Verbinde deinen MQTT-Client mit demselben Broker. Kopiere den MQTT-Themenstamm aus Web Config und ergänze /printers/+/status. Das + steht für jeden gespeicherten Drucker. Wähle einen Drucker aus, der online ist, und warte etwa fünf Sekunden auf frische Daten.

Beispiel einer Statusnachricht
Abonnement<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"
}

Gekürztes Beispiel. Lies den Fortschritt aus status.job.progress_percent und den Auftragsstatus aus status.job.phase.

MQTT-Themen ansehen

Wähle, was
deine App empfängt.

Der Themenstamm lautet printdeck/<printdeck_id>/v1. Kopiere deinen tatsächlichen Stamm aus Web Config und ergänze eines dieser Suffixe. Verwende eine Drucker-ID aus dem Katalog printers oder + für alle Drucker.

Vollständigen API-Leitfaden lesen
/printers

Finde deine Drucker

Katalog gespeicherter Drucker mit IDs. Wird vom Broker gespeichert.

/printers/+/status

Statusaktualisierungen

Aktueller Auftragsstatus, Fortschritt, Temperaturen und das jüngste Ereignisprotokoll. Live-Nachrichten etwa alle fünf Sekunden.

/printers/+/events

Druckereignisse

Einzelne beobachtete Ereignisse wie started, completed oder milestone. Nutze event_type zur Auswahl einer Aktion und event_id zur Identifikation der Meldung.

/availability

Prüfe die Verbindung

Gespeicherter Zustand online oder offline der Brokerverbindung von PrintDeck. Jeder Drucker hat seinen eigenen status.connection.state in der Statusnachricht.

Du nutzt Home Assistant?

Wähle einen Weg pro PrintDeck, damit nur ein Satz Entitäten entsteht.

Home Assistant Discovery

Entitäten erscheinen automatisch.

Verbinde die integrierte MQTT-Integration von Home Assistant mit demselben Broker. Aktiviere Home Assistant MQTT Discovery in PrintDeck. Geräte, Sensoren und Druckereignis-Entitäten erscheinen automatisch; HACS ist nicht erforderlich.

Home Assistant MQTT
PRINTDECK · HACS

Nutze die PrintDeck-Integration.

Installiere PrintDeck über HACS, wähle MQTT bei der Einrichtung und lasse die Standard-Discovery ausgeschaltet. Home Assistant nutzt seine eigene Brokerverbindung. Verwende die aktuelle Integration ab Version 0.1.7.

PrintDeck-Integration installieren
Erste Automatisierung erstellen
GUT ZU WISSEN

Nutze
frische Daten.

Gemeinsame Daten mit Lesezugriff

Wie aktuell sind die Daten?

MQTT nutzt dieselben vereinheitlichten Druckerfelder wie REST, ergänzt um Übertragungsmetadaten. Statusaktualisierungen kommen etwa alle fünf Sekunden; inaktive Drucker folgen weiterhin dem Aktualisierungsintervall der Druckerliste. Live-Telemetrie und Ereignisse werden nicht auf dem Broker gespeichert.

Prüfe status.connection.state, status.connection.stale und status.connection.detail_level, bevor du einen Messwert nutzt. Unbekannte Werte sind null. Gleiche _mqtt_generation in Katalog und Statusnachrichten ab; lösche alte Messwerte, wenn sich die Generation ändert.

Erhalte ich jedes Druckereignis?

Ereignisse beschreiben beobachtete Änderungen; kurze Übergänge können fehlen. Sie nutzen QoS 0 ohne Speicherung oder Wiederholung. Das Statusprotokoll enthält acht aktuelle Beobachtungen. Verfolge stream_id und sequence, um doppelte Aktionen zu vermeiden, und setze nach erneuter Verbindung einen Ausgangspunkt ohne Aktionen auszulösen. Der API-Leitfaden beschreibt den Vertrag vollständig.

Verbunden, aber keine Nachrichten?

Prüfe Brokeradresse, Port, TLS und Themenberechtigungen. Verwende den genauen Themenstamm aus Web Config. Live-Status wird nicht gespeichert; warte auf die nächste Aktualisierung. Brokerzugangsdaten sind unabhängig vom REST-Bearer-Token.

Verbindung und Wiederherstellung

Bei aktiviertem TLS prüft PrintDeck das Zertifikat und den Hostnamen des Brokers. Füge bei Bedarf ein eigenes CA-Zertifikat hinzu. Gespeicherte Geheimnisse bleiben auf PrintDeck. Nach einem Brokerneustart verbindet sich PrintDeck erneut und veröffentlicht frische Daten.

Alte Discovery-Einträge entfernen

Deaktiviere Discovery vor einem Brokerwechsel oder dem Wechsel zu HACS MQTT, solange der alte Broker erreichbar ist, und warte auf die Bereinigung. Ist er unerreichbar, müssen gespeicherte Discovery-Einträge gegebenenfalls manuell entfernt werden. Umbenennen behält die Identität; das Löschen eines Profils entfernt seine Discovery-Konfiguration.

Unified Printer API

Bereit für deine nächste Idee?

Alle Themen, Nachrichtenfelder und Übertragungsregeln findest du im API-Leitfaden.

API-Leitfaden herunterladen