Unified Printer API MQTT · PRINTDECK

Les nouvelles de vos imprimantes.
Transmises par MQTT.

Envoyez l’état des imprimantes et les événements d’impression à votre propre serveur local. Créez des tableaux de bord, notifications et automatisations avec les outils de votre choix.

Ouvrir la configuration MQTTExplorer les sujets MQTT
Réseau local uniquementLecture seule par conceptionJSON versionné
MQTT

Une connexion.
De nombreuses possibilités.

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.

PrintDeck

Collecte les données de vos imprimantes

Votre serveur local

Transmet les mises à jour aux abonnés

Mosquitto

Vos applications

Tableaux de bord, éclairages, notifications

Node-RED · Home Assistant
Guide de configuration MQTT

Votre premier message MQTT

Commencez avec une imprimante et un abonnement. Home Assistant est facultatif.

  1. 01

    Préparez votre serveur

    Utilisez un serveur MQTT local tel que Mosquitto. PrintDeck et votre application sont ses clients ; PrintDeck n’héberge pas de serveur MQTT. Créez des identifiants et autorisez PrintDeck à publier et votre application à lire ses sujets.

  2. 02

    Connecter PrintDeck

    Dans Web Config, ouvrez Paramètres de l’appareil > Unified API. Activez MQTT, saisissez l’adresse, le port et les identifiants du serveur, puis enregistrez et vérifiez la connexion. Adaptez TLS aux paramètres du serveur. Pour votre application, laissez la découverte Home Assistant désactivée.

  3. 03

    Abonnez-vous à l’état des imprimantes

    Connectez votre client MQTT au même serveur. Copiez la racine des sujets MQTT depuis Web Config et ajoutez /printers/+/status. Le + correspond à chaque imprimante enregistrée. Sélectionnez une imprimante en ligne sur PrintDeck et attendez environ cinq secondes pour recevoir des données fraîches.

Exemple de message d’état
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"
}

Exemple abrégé. Lisez status.job.progress_percent pour la progression et status.job.phase pour l’état du travail.

Explorer les sujets MQTT

Choisissez ce que
votre application reçoit.

La racine est printdeck/<printdeck_id>/v1. Copiez votre racine depuis Web Config et ajoutez l’un de ces suffixes. Utilisez un ID du catalogue printers ou + pour toutes les imprimantes.

Lire le guide API complet
/printers

Retrouvez vos imprimantes

Catalogue des imprimantes enregistrées avec leurs ID. Conservé par le serveur.

/printers/+/status

Mises à jour de l’état

État actuel du travail, progression, températures et journal des événements récents. Messages en direct, environ toutes les cinq secondes.

/printers/+/events

Événements d’impression

Événements individuels observés, comme started, completed ou milestone. Utilisez event_type pour choisir une action et event_id pour identifier l’annonce.

/availability

Vérifiez la connexion

État online ou offline conservé de la connexion de PrintDeck au serveur. Chaque imprimante possède son propre status.connection.state dans son message d’état.

Vous utilisez Home Assistant ?

Choisissez une seule méthode par PrintDeck pour conserver un seul ensemble d’entités.

Découverte Home Assistant

Les entités apparaissent seules.

Connectez l’intégration MQTT native de Home Assistant au même serveur. Activez Home Assistant MQTT Discovery dans PrintDeck. Les appareils, capteurs et entités d’événements apparaissent automatiquement ; HACS n’est pas nécessaire.

Home Assistant MQTT
PRINTDECK · HACS

Utilisez l’intégration PrintDeck.

Installez PrintDeck via HACS, choisissez MQTT pendant la configuration et laissez la découverte standard désactivée. Home Assistant utilise sa propre connexion au serveur. Utilisez l’intégration actuelle, version 0.1.7 ou ultérieure.

Installer l’intégration PrintDeck
Créer la première automatisation
BON À SAVOIR

Appuyez-vous sur
des données fraîches.

Des données en lecture seule communes

Les données sont-elles à jour ?

MQTT utilise les mêmes champs normalisés que REST, avec des métadonnées de transmission supplémentaires. L’état est actualisé environ toutes les cinq secondes ; les imprimantes inactives suivent toujours la fréquence d’actualisation de la liste. La télémétrie et les événements en direct ne sont pas conservés.

Avant d’utiliser une mesure, vérifiez status.connection.state, status.connection.stale et status.connection.detail_level. Les valeurs inconnues sont null. Vérifiez la concordance de _mqtt_generation dans le catalogue et les messages d’état ; effacez les anciennes mesures lorsqu’il change.

Vais-je recevoir tous les événements ?

Les événements décrivent les changements observés ; des transitions brèves peuvent être manquées. Ils utilisent QoS 0, sans conservation ni rejeu. Le journal garde huit observations récentes. Suivez stream_id et sequence pour éviter les actions répétées et établissez une référence sans déclencher d’action après reconnexion. Le guide de l’API détaille le contrat.

Connecté, mais sans messages ?

Vérifiez l’adresse du serveur, le port, TLS et les autorisations des sujets. Utilisez la racine exacte de Web Config. L’état en direct n’est pas conservé : attendez la prochaine mise à jour. Les identifiants du serveur sont distincts du jeton REST.

Connexion et rétablissement

Lorsque TLS est activé, PrintDeck vérifie le certificat et le nom du serveur. Ajoutez votre certificat CA si nécessaire. Les secrets enregistrés restent sur PrintDeck. Après un redémarrage du serveur, PrintDeck se reconnecte et publie des données fraîches.

Supprimer les anciennes entrées de découverte

Avant de changer de serveur ou de passer à HACS MQTT, désactivez la découverte pendant que l’ancien serveur reste accessible et attendez la fin du nettoyage. S’il est inaccessible, ses entrées conservées peuvent nécessiter une suppression manuelle. Renommer conserve l’identité ; supprimer un profil retire sa configuration de découverte.

Unified Printer API

Prêt pour votre prochaine idée ?

Retrouvez tous les sujets, champs des messages et règles de transmission dans le guide de l’API.

Télécharger le guide API