Unified Printer API HOME ASSISTANT · PRINTDECK-INTEGRATION

Dein Drucker wird
Teil deines Smart Homes.

Home Assistant kann PrintDeck im lokalen Netzwerk abfragen, die normalisierten Druckerdaten in Entitäten umwandeln und auf jede Statusänderung eines Drucks reagieren.

Automatische mDNS-Erkennung Eine Anfrage, viele Sensoren Durch ein Bearer-Token geschützt Klipper und Bambu Lab
DIE IDEE

PrintDeck übersetzt.
Home Assistant reagiert.

Die PrintDeck-Integration erkennt kompatible Geräte, fragt in der Home-Assistant-Oberfläche nach dem Unified-API-Token und erstellt automatisch die verfügbaren Druckerentitäten.

01

Abgeschlossener Druck

Schalte eine Lampe ein, sende eine Benachrichtigung ans Smartphone oder gib bekannt, dass das Teil fertig ist.

02

Fortschrittsmarken

Reagiere beim Überschreiten von 25 %, 50 % oder 75 %, um eine Signalleuchte zu ändern oder ein Dashboard zu aktualisieren.

03

Auftrag pausiert oder gestoppt

Reagiere auf pausierte, fehlgeschlagene oder abgebrochene Aufträge, bevor du in die Werkstatt zurückkehrst.

04

Werkstattübersicht

Zeige Verbindung, Temperaturen, Restzeit und aktuelle Schicht in einem lokalen Dashboard an.

HIER STARTEN · KEIN YAML NÖTIG

Ohne configuration.yaml.
Richte alles in der Oberfläche ein.

HACS installiert die gepflegte PrintDeck-Integration. Danach erfolgt alles in der normalen Home-Assistant-Oberfläche: Erkennung, Token-Eingabe, Geräte, Sensoren und Automatisierungen.

Dasselbe lokale NetzwerkHome Assistant und PrintDeck müssen sich gegenseitig erreichen können.

Aktuelle PrintDeck-FirmwareAktualisiere den Monitor, bevor du die Integration verbindest.

HACS installiertWenn du HACS noch nicht hast, installiere es zuerst mithilfe der offiziellen Anleitung.

  1. 01

    API in PrintDeck aktivieren

    Öffne PrintDeck Web Config, wähle Einstellungen > Unified Printer API, aktiviere sie und kopiere das erzeugte Token. Behandle es vertraulich; füge das unveränderte Token ohne das Wort Bearer in Home Assistant ein.

  2. 02

    PrintDeck zu HACS hinzufügen

    Verwende die Schaltfläche unten. Sie öffnet das benutzerdefinierte PrintDeck-Repository direkt in HACS. Wenn die Schaltfläche deinen Home Assistant nicht erreicht, nutze den darunter beschriebenen manuellen Weg.

    PrintDeck in HACS öffnen
    Repository manuell hinzufügen

    Öffne HACS > Integrationen > Drei-Punkte-Menü > Benutzerdefinierte Repositories. Füge https://github.com/PrintDeck/home-assistant ein, wähle Integration als Typ und dann Hinzufügen.

    Offizielle HACS-Anleitung zu benutzerdefinierten Repositories lesen
  3. 03

    Herunterladen und neu starten

    Wähle PrintDeck in HACS, dann Herunterladen und installiere die neueste Version. Starte Home Assistant neu, wenn HACS dazu auffordert. Das Aktualisieren des Browsers ist kein Neustart.

  4. 04

    Integration hinzufügen

    Öffne Einstellungen > Geräte & Dienste > Integration hinzufügen und suche nach PrintDeck. Wähle einen erkannten Monitor oder gib printdeck.local beziehungsweise seine lokale IP-Adresse ein. Füge das unveränderte Unified-API-Token ein und bestätige.

  5. 05

    Benennen und zuweisen

    Home Assistant zeigt den PrintDeck-Monitor und jeden konfigurierten Drucker. Benenne sie bei Bedarf um oder weise Bereiche zu und wähle dann Fertigstellen. Verwende Hub hinzufügen nur für einen weiteren physischen PrintDeck-Monitor.

  6. 06

    Entitäten prüfen

    Öffne die PrintDeck-Integration. Du solltest einen Hub und ein Gerät für jeden Drucker sehen. Jeder Drucker stellt, sofern verfügbar, Fortschritt, Phase, Aktivität, Temperaturen, Schichten, Zeit- und Verbindungsdaten, Netzwerkadresse und Netzwerkport bereit.

    Drucker bleiben automatisch synchronisiert

    Füge in PrintDeck einen Drucker hinzu. Home Assistant erstellt dessen Gerät und Entitäten nach dem nächsten Abfragezyklus. Entferne einen Drucker, dann entfernt die Integration ab Version 0.1.2 dessen Gerät und Entitäten nach der nächsten vollständigen Aktualisierung aus Home Assistant. Ein vorübergehendes Verbindungsproblem löst diese Bereinigung niemals aus. Das Löschen eines Druckers unterbricht bewusst Automatisierungen, die auf dessen Entitäten verweisen; hat sich nur die Adresse geändert, bearbeite stattdessen den gespeicherten Drucker.

DEINE ERSTE AUTOMATISIERUNG

Eine Leuchte einschalten
wenn der Fortschritt 75 % erreicht.

Dieses Beispiel verwendet den visuellen Automatisierungseditor. Es funktioniert mit jedem Prozentwert, auch 82 % oder 88 %.

  1. WENN

    Wähle Numerischer Zustand, die Entität Druckfortschritt des Druckers und setze Über auf 74,9.

  2. UND WENN

    Wähle Zustand, die Entität Druckphase desselben Druckers und setze den Zustand auf Printing.

  3. DANN

    Wähle Licht: Einschalten und eine Leuchte. Verwende Einschalten statt Umschalten, damit das Ergebnis vorhersehbar ist.

  4. SPEICHERN

    Benenne und speichere die Automatisierung. Aktionen ausführen testet nur die Leuchte; ein kurzer Druck testet Auslöser und Bedingung.

Warum 74,9 statt 75?

Der Test Über in Home Assistant ist strikt. Ein Schwellenwert von 74,9 löst aus, sobald der Sensor erstmals 75 oder mehr meldet. Die Printing-Bedingung verhindert, dass ein alter Fortschrittswert das Licht bei inaktivem Drucker einschaltet.

FERTIGE BLUEPRINTS

Lieber ein geführtes Formular?

Importiere einen Blueprint und wähle anschließend Druckersensor und Leuchte aus den Listen in Home Assistant.

SCHNELLE FEHLERBEHEBUNG

Wenn etwas nicht erscheint,
prüfe zuerst diese Punkte.

PrintDeck fehlt unter Integration hinzufügen

Prüfe, ob HACS sie heruntergeladen hat, starte Home Assistant neu und aktualisiere danach den Browser.

Home Assistant verlangt eine Firmware-Aktualisierung

Aktualisiere den PrintDeck-Monitor und versuche die Verbindung erneut. Diese Meldung bedeutet, dass der Monitor die Unterstützung der nativen Integration noch nicht ankündigt.

Verbindung zum Host nicht möglich

Home Assistant und PrintDeck müssen sich im selben lokalen Netzwerk befinden. Wenn printdeck.local nicht aufgelöst wird, gib die von PrintDeck angezeigte lokale IP-Adresse ein.

Das Token wird abgelehnt

Kopiere ein neues Token aus PrintDeck Web Config und füge es unverändert ein. Füge im Formular der nativen Integration nicht Bearer hinzu.

Fortschritt ist nicht verfügbar

Wähle diesen Drucker auf PrintDeck aus, damit er eine vollständige Live-Verbindung erhält. Einige inaktive Drucker stellen nur zusammengefasste Daten bereit.

Das Licht wurde nicht eingeschaltet

Öffne die Automatisierung und wähle Ablaufverfolgungen. Dort siehst du, ob der Fortschrittsauslöser ausgelöst und die Printing-Bedingung erfüllt wurde.

HOME-ASSISTANT-BEISPIEL

PrintDeck unter Integration hinzufügen finden

PrintDeck-Suche unter Integration hinzufügen in Home Assistant
Suche nach PrintDeck und wähle das Ergebnis mit dem runden PrintDeck-Symbol.
HOME-ASSISTANT-BEISPIEL

Monitor und Drucker benennen

Home-Assistant-Seite Benennen und zuweisen für einen PrintDeck-Monitor und seine Drucker
Bereiche sind optional. Wähle Überspringen und abschließen, wenn du die Geräte noch nicht zuordnen möchtest.
HOME-ASSISTANT-BEISPIEL

Ein Hub mit seinen Druckergeräten

PrintDeck-Integrationsseite mit einem Hub und vier Druckergeräten
Der Hub steht für den physischen PrintDeck-Monitor. Die Zeilen darunter sind die auf diesem Monitor konfigurierten Drucker.
HOME-ASSISTANT-BEISPIEL

Eine vollständige Fortschrittsautomatisierung

Home-Assistant-Automatisierung mit Fortschrittsauslöser, Printing-Bedingung und Aktion Licht einschalten
Dieses funktionierende Beispiel verwendet 82 %. Gib für 75 % bei Über den Wert 74,9 ein und behalte dieselbe Printing-Bedingung bei.
BEISPIEL ZUR FEHLERBEHEBUNG

Firmware-Aktualisierung erforderlich

PrintDeck-Verbindungsformular in Home Assistant mit Firmware-Aktualisierungswarnung
Dies ist ein Fehlerbeispiel und nicht die erwartete Erfolgsansicht. Aktualisiere PrintDeck und bestätige die Verbindung erneut.
MANUELLE REST-ALTERNATIVE

Lieber YAML?
Verbinde einen Status mit einem Licht.

Die oben beschriebene native Integration wird empfohlen. Öffne diese erweiterte Alternative nur, wenn HACS nicht verwendet werden kann oder du die REST-Sensoren bewusst selbst pflegen möchtest.

Manuelle REST-Anleitung anzeigen
  1. 01

    API aktivieren

    Öffne Web Config auf PrintDeck, wähle Unified Printer API, aktiviere sie und kopiere das erzeugte Zugriffstoken.

  2. 02

    Drucker-ID ermitteln

    Rufe die Druckerliste ab und notiere die ID des Druckers, den du überwachen möchtest.

    Terminal
    curl http://PRINTDECK-IP/v1/printers \
      -H 'Authorization: Bearer pd_your_token_here'
  3. 03

    Token in secrets.yaml aufbewahren

    Nimm das Wort Bearer in den Wert des Secrets auf.

    secrets.yaml
    printdeck_api_bearer: "Bearer pd_your_token_here"
  4. 04

    Phasensensor hinzufügen

    Damit wird alle 10 Sekunden eine Anfrage gesendet. Ändere PRINTDECK-IP und die Drucker-ID 1 in der URL.

    configuration.yaml
    rest:
      - resource: "http://PRINTDECK-IP/v1/printers/1/status"
        method: GET
        headers:
          Authorization: !secret printdeck_api_bearer
        scan_interval: 10
        timeout: 5
        sensor:
          - name: "PrintDeck Phase"
            unique_id: printdeck_printer_1_phase
            value_template: "{{ value_json.status.job.phase }}"
  5. 05

    Home Assistant prüfen und neu starten

    Validiere das YAML in den Entwicklerwerkzeugen, starte Home Assistant neu und prüfe anschließend, ob die Entität PrintDeck Phase einen Wert besitzt.

  6. 06

    Automatisierung hinzufügen

    Ersetze light.living_room durch die Entitäts-ID deiner Lampe.

    automations.yaml
    - alias: "PrintDeck - light on when print completes"
      id: printdeck_light_on_when_print_completes
      triggers:
        - trigger: state
          entity_id: sensor.printdeck_phase
          to: "completed"
      conditions:
        - condition: template
          value_template: >-
            {{ trigger.from_state is not none and
               trigger.from_state.state in ['preparing', 'printing', 'paused'] }}
      actions:
        - action: light.turn_on
          target:
            entity_id: light.living_room
      mode: single
  7. 07

    Kurzen Testdruck starten

    Beobachte, wie die Phasenentität zu completed wechselt. Wenn sich die Lampe nicht einschaltet, öffne die Ablaufverfolgung der Automatisierung, um die Ergebnisse von Auslöser und Bedingung zu sehen.

ALLE NORMALISIERTEN ZUSTÄNDE

Nutze übergeordnete Phasen
oder detaillierte Aktivitäten.

Die Auftragsphase eignet sich für die meisten Automatisierungen. Die Auftragsaktivität stellt die detaillierten Aktivitäten bereit, die PrintDeck-Reaktionen auslösen, sofern der Drucker sie meldet.

Auftragsphasen

Alle unterstützten Werte für die Auftragsphase:

unknownidlepreparingprintingpausedcompletedfailedcancelled

Detaillierte Aktivitäten

Alle unterstützten Werte für die Auftragsaktivität:

unknownstandbypreparingnozzle_heatingbed_heatinghomingbed_levelingnozzle_cleaningcalibratingfilament_changingfilament_unloadingfilament_loadingfilament_purgingprintingpausedcompletedfailedcancelled

Du benötigst nicht für jeden Wert eine eigene Entität. Der unten gezeigte Sensor PrintDeck Activity wechselt zwischen allen aufgeführten Aktivitäten, und eine Automatisierung kann auf den gewählten Wert reagieren.

Verbindungs- und Statuswerte

connection.state
stopped waiting_for_network connecting online offline
connection.reachability
unknown online offline
connection.detail_level
summary full
job.kind
print calibration

Welche detaillierten Aktivitäten verfügbar sind, hängt von den Meldungen des verbundenen Druckers ab. Der API-Wert unknown verwendet die PrintDeck-Reaktion unavailable als Rückfallwert. Der ausgewählte Drucker liefert vollständige Live-Daten; andere gespeicherte Drucker können zusammengefasste Daten im konfigurierten Aktualisierungsintervall der Druckerliste bereitstellen.

VOLLSTÄNDIGES STATUSSENSOR-PAKET

Eine API-Anfrage.
Jedes Feld des detaillierten Status.

Die native Integration erstellt diese Entitäten automatisch. Dieses YAML-Paket bleibt für fortgeschrittene manuelle REST-Installationen verfügbar.

Vollständiges manuelles Sensor-YAML anzeigen
configuration.yaml
rest:
  - resource: "http://PRINTDECK-IP/v1/printers/1/status"
    method: GET
    headers:
      Authorization: !secret printdeck_api_bearer
    scan_interval: 10
    timeout: 5
    sensor:
      - name: "PrintDeck Printer ID"
        unique_id: printdeck_printer_1_id
        value_template: "{{ value_json.status.printer_id }}"

      - name: "PrintDeck Connection"
        unique_id: printdeck_printer_1_connection
        value_template: "{{ value_json.status.connection.state }}"

      - name: "PrintDeck Reachability"
        unique_id: printdeck_printer_1_reachability
        value_template: "{{ value_json.status.connection.reachability }}"

      - name: "PrintDeck Detail Level"
        unique_id: printdeck_printer_1_detail_level
        value_template: "{{ value_json.status.connection.detail_level }}"

      - name: "PrintDeck Update Marker"
        unique_id: printdeck_printer_1_updated_at_ms
        value_template: "{{ value_json.status.connection.updated_at_ms }}"
        unit_of_measurement: "ms"

      - name: "PrintDeck Phase"
        unique_id: printdeck_printer_1_phase
        value_template: "{{ value_json.status.job.phase }}"

      - name: "PrintDeck Job Kind"
        unique_id: printdeck_printer_1_job_kind
        value_template: "{{ value_json.status.job.kind }}"

      - name: "PrintDeck Activity"
        unique_id: printdeck_printer_1_activity
        value_template: "{{ value_json.status.job.activity }}"

      - name: "PrintDeck Job Name"
        unique_id: printdeck_printer_1_job_name
        value_template: "{{ value_json.status.job.name | default('none', true) }}"

      - name: "PrintDeck Progress"
        unique_id: printdeck_printer_1_progress
        value_template: "{{ value_json.status.job.progress_percent }}"
        availability: >-
          {{ value_json.status.connection.detail_level == 'full' and
             not value_json.status.connection.stale }}
        unit_of_measurement: "%"

      - name: "PrintDeck Elapsed"
        unique_id: printdeck_printer_1_elapsed
        value_template: "{{ value_json.status.job.elapsed_seconds }}"
        availability: >-
          {{ value_json.status.connection.detail_level == 'full' and
             not value_json.status.connection.stale }}
        device_class: duration
        unit_of_measurement: "s"

      - name: "PrintDeck Remaining"
        unique_id: printdeck_printer_1_remaining
        value_template: "{{ value_json.status.job.remaining_seconds }}"
        availability: "{{ not value_json.status.connection.stale }}"
        device_class: duration
        unit_of_measurement: "s"

      - name: "PrintDeck Current Layer"
        unique_id: printdeck_printer_1_current_layer
        value_template: "{{ value_json.status.job.current_layer }}"
        availability: >-
          {{ value_json.status.connection.detail_level == 'full' and
             not value_json.status.connection.stale }}

      - name: "PrintDeck Total Layers"
        unique_id: printdeck_printer_1_total_layers
        value_template: "{{ value_json.status.job.total_layers }}"
        availability: >-
          {{ value_json.status.connection.detail_level == 'full' and
             not value_json.status.connection.stale }}

      - name: "PrintDeck Nozzle Temperature"
        unique_id: printdeck_printer_1_nozzle_temperature
        value_template: "{{ value_json.status.temperatures.nozzle_current_c }}"
        availability: >-
          {{ value_json.status.temperatures.nozzle_current_c is not none and
             not value_json.status.connection.stale }}
        device_class: temperature
        state_class: measurement
        unit_of_measurement: "°C"

      - name: "PrintDeck Nozzle Target"
        unique_id: printdeck_printer_1_nozzle_target
        value_template: "{{ value_json.status.temperatures.nozzle_target_c }}"
        availability: >-
          {{ value_json.status.temperatures.nozzle_target_c is not none and
             not value_json.status.connection.stale }}
        device_class: temperature
        unit_of_measurement: "°C"

      - name: "PrintDeck Bed Temperature"
        unique_id: printdeck_printer_1_bed_temperature
        value_template: "{{ value_json.status.temperatures.bed_current_c }}"
        availability: >-
          {{ value_json.status.temperatures.bed_current_c is not none and
             not value_json.status.connection.stale }}
        device_class: temperature
        state_class: measurement
        unit_of_measurement: "°C"

      - name: "PrintDeck Bed Target"
        unique_id: printdeck_printer_1_bed_target
        value_template: "{{ value_json.status.temperatures.bed_target_c }}"
        availability: >-
          {{ value_json.status.temperatures.bed_target_c is not none and
             not value_json.status.connection.stale }}
        device_class: temperature
        unit_of_measurement: "°C"

      - name: "PrintDeck Chamber Temperature"
        unique_id: printdeck_printer_1_chamber_temperature
        value_template: "{{ value_json.status.temperatures.chamber_current_c }}"
        availability: >-
          {{ value_json.status.temperatures.chamber_current_c is not none and
             not value_json.status.connection.stale }}
        device_class: temperature
        state_class: measurement
        unit_of_measurement: "°C"

    binary_sensor:
      - name: "PrintDeck Data Stale"
        unique_id: printdeck_printer_1_data_stale
        value_template: "{{ value_json.status.connection.stale }}"
        device_class: problem

      - name: "PrintDeck Online"
        unique_id: printdeck_printer_1_online
        value_template: "{{ value_json.status.connection.state == 'online' }}"
        device_class: connectivity
Vor dem Neustart

Bewahre das passende Token in secrets.yaml auf und ersetze PRINTDECK-IP sowie die Drucker-ID 1. Wenn configuration.yaml bereits einen obersten rest-Abschnitt enthält, füge diese Ressource dort hinzu, statt einen zweiten rest-Schlüssel anzulegen.

GUT ZU WISSEN

Von Grund auf lokal.
Von Grund auf schreibgeschützt.

Home Assistant fragt PrintDeck ab; PrintDeck sendet keine Webhooks. Betreibe beide Geräte in einem vertrauenswürdigen lokalen Netzwerk und gib den API-Port nicht für das Internet frei. Die Integration speichert das Token im Home-Assistant-Konfigurationseintrag; bei einer manuellen REST-Einrichtung gehört es in secrets.yaml.

Fortschritt, Temperaturen und die detaillierten Aktivitäten für Reaktionen sind beim aktuell in PrintDeck ausgewählten Drucker am vollständigsten. Verbindung und zusammengefasster Auftragsstatus bleiben für andere gespeicherte Drucker verfügbar.

Zur Unified Printer API zurückkehren

MQTT für deine lokalen Anwendungen

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.

01

Statusaktualisierungen

Empfange Auftragsstatus, Fortschritt, Temperaturen und Verfügbarkeit in deinen Dashboards oder Node-RED-Abläufen.

02

Druckereignisse

Reagiere auf beobachtete Druckstarts, Fortschrittsmarken und Ereignisse, die Aufmerksamkeit erfordern. Live-Ereignisse werden nicht gespeichert und nach einer erneuten Verbindung nicht wiederholt.

03

Home Assistant Discovery

Lass Home Assistant Geräte und Entitäten über die integrierte MQTT-Integration automatisch anlegen. Oder nutze PrintDeck über HACS mit MQTT und lasse die Standard-Discovery ausgeschaltet.