Unified Printer API HOME ASSISTANT · INTÉGRATION PRINTDECK

Votre imprimante devient
un élément de votre maison connectée.

Home Assistant peut interroger PrintDeck sur votre réseau local, convertir ses données d’imprimante normalisées en entités et réagir à chaque changement d’état d’une impression.

Détection mDNS automatique Une requête, de nombreux capteurs Protégé par un jeton Bearer Klipper et Bambu Lab
LE PRINCIPE

PrintDeck traduit.
Home Assistant réagit.

L’intégration PrintDeck détecte les appareils compatibles, demande le jeton Unified API dans l’interface Home Assistant et crée automatiquement les entités d’imprimante disponibles.

01

Impression terminée

Allumez une lampe, envoyez une notification sur un téléphone ou annoncez que la pièce est prête.

02

Jalons de progression

Réagissez lorsque la progression dépasse 25 %, 50 % ou 75 % afin de modifier un voyant ou de mettre à jour un tableau de bord.

03

Tâche en pause ou arrêtée

Réagissez aux tâches en pause, échouées ou annulées avant de retourner à l’atelier.

04

Vue d’ensemble de l’atelier

Affichez la connexion, les températures, le temps restant et la couche actuelle sur un même tableau de bord local.

COMMENCEZ ICI · AUCUN YAML REQUIS

Sans configuration.yaml.
Configurez tout dans l’interface.

HACS installe l’intégration PrintDeck maintenue. Ensuite, tout se passe dans l’interface habituelle de Home Assistant : découverte, saisie du jeton, appareils, capteurs et automatisations.

Le même réseau localHome Assistant et PrintDeck doivent pouvoir communiquer entre eux.

Firmware PrintDeck à jourMettez le moniteur à jour avant de connecter l’intégration.

HACS installéSi vous n’avez pas encore HACS, installez-le d’abord à l’aide du guide officiel.

  1. 01

    Activez l’API dans PrintDeck

    Ouvrez PrintDeck Web Config, choisissez Réglages > Unified Printer API, activez-la et copiez le jeton généré. Gardez-le confidentiel ; vous collerez le jeton brut dans Home Assistant sans ajouter le mot Bearer.

  2. 02

    Ajoutez PrintDeck à HACS

    Utilisez le bouton ci-dessous. Il ouvre directement le dépôt personnalisé PrintDeck dans HACS. Si le bouton ne peut pas accéder à votre Home Assistant, suivez la procédure manuelle indiquée dessous.

    Ouvrir PrintDeck dans HACS
    Ajouter le dépôt manuellement

    Ouvrez HACS > Intégrations > menu à trois points > Dépôts personnalisés. Collez https://github.com/PrintDeck/home-assistant, choisissez Intégration comme type, puis Ajouter.

    Lire le guide officiel des dépôts personnalisés HACS
  3. 03

    Téléchargez et redémarrez

    Dans HACS, sélectionnez PrintDeck, choisissez Télécharger et installez la version la plus récente. Redémarrez Home Assistant lorsque HACS le demande. Actualiser le navigateur ne constitue pas un redémarrage.

  4. 04

    Ajoutez l’intégration

    Ouvrez Réglages > Appareils et services > Ajouter une intégration et recherchez PrintDeck. Choisissez un moniteur découvert ou saisissez printdeck.local ou son adresse IP locale. Collez le jeton Unified API brut et validez.

  5. 05

    Nommez et attribuez

    Home Assistant affiche le moniteur PrintDeck et chaque imprimante configurée. Renommez-les ou attribuez-leur des zones si nécessaire, puis choisissez Terminer. Utilisez Ajouter un hub uniquement si vous possédez un autre moniteur PrintDeck physique.

  6. 06

    Vérifiez les entités

    Ouvrez l’intégration PrintDeck. Vous devez voir un hub et un appareil pour chaque imprimante. Chaque imprimante expose la progression, la phase, l’activité, les températures, les couches, le temps, les données de connexion, l’adresse réseau et le port réseau lorsqu’ils sont disponibles.

    Les imprimantes restent synchronisées automatiquement

    Ajoutez une imprimante dans PrintDeck et Home Assistant créera son appareil et ses entités lors du prochain cycle d’interrogation. Supprimez une imprimante et la version 0.1.2 ou ultérieure de l’intégration supprimera son appareil et ses entités de Home Assistant après la prochaine actualisation complète. Un problème de connexion temporaire ne déclenche jamais ce nettoyage. La suppression d’une imprimante rompt volontairement les automatisations qui référencent ses entités ; si seule son adresse a changé, modifiez l’imprimante enregistrée.

VOTRE PREMIÈRE AUTOMATISATION

Allumez une lampe
lorsque la progression atteint 75 %.

Cet exemple utilise l’éditeur visuel d’automatisations. Il fonctionne avec n’importe quel pourcentage, notamment 82 % ou 88 %.

  1. QUAND

    Choisissez État numérique, sélectionnez l’entité Progression d’impression de l’imprimante et réglez Supérieur à sur 74,9.

  2. ET SI

    Choisissez État, sélectionnez l’entité Phase d’impression de la même imprimante et définissez l’état sur Printing.

  3. ALORS

    Choisissez Lumière : allumer et sélectionnez une lampe. Utilisez Allumer plutôt que Basculer pour obtenir un résultat prévisible.

  4. ENREGISTRER

    Nommez et enregistrez l’automatisation. Exécuter les actions ne teste que la lampe ; une impression courte teste le déclencheur et la condition.

Pourquoi 74,9 plutôt que 75 ?

Le test Supérieur à de Home Assistant est strict. Un seuil de 74,9 se déclenche lorsque le capteur indique pour la première fois 75 ou plus. La condition Printing empêche une ancienne valeur de progression d’allumer la lampe lorsque l’imprimante est inactive.

BLUEPRINTS PRÊTS À L’EMPLOI

Vous préférez un formulaire guidé ?

Importez un blueprint, puis choisissez le capteur de l’imprimante et la lampe dans les listes de Home Assistant.

DÉPANNAGE RAPIDE

Si quelque chose n’apparaît pas,
vérifiez d’abord ces points.

PrintDeck n’apparaît pas dans Ajouter une intégration

Vérifiez que HACS l’a téléchargée, redémarrez Home Assistant puis actualisez le navigateur.

Home Assistant demande une mise à jour du firmware

Mettez le moniteur PrintDeck à jour, puis réessayez la connexion. Ce message signifie que le moniteur n’annonce pas encore la prise en charge de l’intégration native.

Impossible de se connecter à l’hôte

Conservez Home Assistant et PrintDeck sur le même réseau local. Si printdeck.local n’est pas résolu, saisissez l’adresse IP locale affichée par PrintDeck.

Le jeton est refusé

Copiez un nouveau jeton depuis PrintDeck Web Config et collez-le tel quel. N’ajoutez pas Bearer dans le formulaire de l’intégration native.

La progression n’est pas disponible

Sélectionnez cette imprimante sur PrintDeck afin qu’elle dispose d’une connexion complète en temps réel. Certaines imprimantes inactives ne fournissent que des données résumées.

La lampe ne s’est pas allumée

Ouvrez l’automatisation et choisissez Traces. La trace indique si le déclencheur de progression s’est activé et si la condition Printing a été remplie.

EXEMPLE HOME ASSISTANT

Trouvez PrintDeck dans Ajouter une intégration

Recherche de PrintDeck dans Ajouter une intégration de Home Assistant
Recherchez PrintDeck et sélectionnez le résultat avec l’icône ronde PrintDeck.
EXEMPLE HOME ASSISTANT

Nommez le moniteur et les imprimantes

Écran Nommer et attribuer de Home Assistant pour un moniteur PrintDeck et ses imprimantes
Les zones sont facultatives. Choisissez Ignorer et terminer si vous ne souhaitez pas encore organiser les appareils.
EXEMPLE HOME ASSISTANT

Un hub avec ses imprimantes

Page de l’intégration PrintDeck affichant un hub et quatre imprimantes
Le hub représente le moniteur PrintDeck physique. Les lignes situées en dessous correspondent aux imprimantes configurées sur ce moniteur.
EXEMPLE HOME ASSISTANT

Une automatisation complète de la progression

Automatisation Home Assistant avec déclencheur de progression, condition Printing et action Allumer la lumière
Cet exemple fonctionnel utilise 82 %. Pour 75 %, saisissez Supérieur à 74,9 et conservez la même condition Printing.
EXEMPLE DE DÉPANNAGE

Mise à jour du firmware requise

Formulaire de connexion PrintDeck dans Home Assistant affichant un avertissement de mise à jour du firmware
Il s’agit d’un exemple d’erreur, et non de l’écran de réussite attendu. Mettez PrintDeck à jour, puis validez à nouveau la connexion.
SOLUTION REST MANUELLE

Vous préférez YAML ?
Reliez un état à un éclairage.

L’intégration native ci-dessus est recommandée. N’ouvrez cette solution avancée que si HACS ne peut pas être utilisé ou si vous souhaitez gérer vous-même les capteurs REST.

Afficher les instructions REST manuelles
  1. 01

    Activez l’API

    Ouvrez Web Config sur PrintDeck, choisissez Unified Printer API, activez-la et copiez le jeton d’accès généré.

  2. 02

    Trouvez l’identifiant de l’imprimante

    Demandez la liste des imprimantes et notez l’identifiant de celle que vous souhaitez surveiller.

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

    Conservez le jeton dans secrets.yaml

    Incluez le mot Bearer dans la valeur du secret.

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

    Ajoutez le capteur de phase

    Cette configuration envoie une requête toutes les 10 secondes. Modifiez PRINTDECK-IP et l’identifiant d’imprimante 1 dans l’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

    Vérifiez et redémarrez Home Assistant

    Validez le YAML dans les Outils de développement, redémarrez Home Assistant, puis vérifiez que l’entité PrintDeck Phase possède une valeur.

  6. 06

    Ajoutez l’automatisation

    Remplacez light.living_room par l’identifiant d’entité de votre 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

    Lancez une courte impression de test

    Observez l’entité de phase passer à completed. Si la lampe ne s’allume pas, ouvrez la trace de l’automatisation pour consulter les résultats du déclencheur et de la condition.

TOUS LES ÉTATS NORMALISÉS

Utilisez des phases générales
ou des activités détaillées.

La phase de la tâche convient à la plupart des automatisations. L’activité de la tâche expose les activités détaillées qui déclenchent les réactions de PrintDeck lorsque l’imprimante les transmet.

Phases de la tâche

Toutes les valeurs de phase de tâche prises en charge :

unknownidlepreparingprintingpausedcompletedfailedcancelled

Activités détaillées

Toutes les valeurs d’activité de tâche prises en charge :

unknownstandbypreparingnozzle_heatingbed_heatinghomingbed_levelingnozzle_cleaningcalibratingfilament_changingfilament_unloadingfilament_loadingfilament_purgingprintingpausedcompletedfailedcancelled

Vous n’avez pas besoin d’une entité par valeur. Le capteur PrintDeck Activity ci-dessous passe d’une activité répertoriée à l’autre et une automatisation peut réagir à la valeur choisie.

Valeurs de connexion et d’état

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

La disponibilité des activités détaillées dépend des informations transmises par l’imprimante connectée. La valeur API unknown utilise la réaction unavailable de PrintDeck comme solution de repli. L’imprimante sélectionnée fournit des données complètes en temps réel ; les autres imprimantes enregistrées peuvent fournir des données résumées selon l’intervalle configuré d’actualisation de la liste des imprimantes.

ENSEMBLE COMPLET DE CAPTEURS D’ÉTAT

Une requête API.
Chaque champ d’état détaillé.

L’intégration native crée automatiquement ces entités. Ce bloc YAML reste disponible pour les installations REST manuelles avancées.

Afficher le YAML manuel complet des capteurs
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
Avant de redémarrer

Conservez le jeton correspondant dans secrets.yaml, puis remplacez PRINTDECK-IP et l’identifiant d’imprimante 1. Si configuration.yaml contient déjà une section rest de premier niveau, ajoutez cette ressource dessous au lieu de créer une seconde clé rest.

BON À SAVOIR

Local par conception.
En lecture seule par conception.

Home Assistant interroge PrintDeck ; PrintDeck n’envoie pas de webhooks. Conservez les deux appareils sur un réseau local de confiance et n’exposez pas le port de l’API à Internet. L’intégration stocke le jeton dans l’entrée de configuration Home Assistant ; pour une configuration REST manuelle, conservez-le dans secrets.yaml.

La progression, les températures et les activités détaillées utilisées par les réactions sont les plus complètes pour l’imprimante actuellement sélectionnée dans PrintDeck. La connexion et l’état résumé de la tâche restent disponibles pour les autres imprimantes enregistrées.

Revenir à Unified Printer API

MQTT pour vos outils locaux

PrintDeck envoie les données normalisées des imprimantes à un serveur local tel que Mosquitto. Vos applications s’abonnent aux mises à jour au lieu d’interroger régulièrement l’API REST. HTTP et MQTT peuvent fonctionner séparément ou ensemble.

01

Mises à jour de l’état

Recevez l’état du travail, la progression, les températures et la disponibilité dans vos tableaux de bord ou flux Node-RED.

02

Événements d’impression

Réagissez aux débuts d’impression observés, aux étapes de progression et aux événements nécessitant votre attention. Les événements en direct ne sont ni conservés ni rejoués après reconnexion.

03

Découverte Home Assistant

Laissez Home Assistant créer automatiquement les appareils et entités avec son intégration MQTT native. Vous pouvez aussi choisir PrintDeck via HACS avec MQTT et laisser la découverte standard désactivée.