Unified Printer API MQTT · PRINTDECK

Novedades de tus impresoras.
Recibidas por MQTT.

Envía el estado de las impresoras y los eventos de impresión a tu propio servidor local. Crea paneles, notificaciones y automatizaciones con las herramientas que elijas.

Abrir configuración MQTTExplora los temas MQTT
Solo red localSolo lectura por diseñoJSON versionado
MQTT

Una conexión.
Muchas posibilidades.

PrintDeck envía datos normalizados de las impresoras a un servidor local como Mosquitto. Tus aplicaciones se suscriben a las actualizaciones en lugar de consultar repetidamente la API REST. HTTP y MQTT pueden funcionar por separado o juntos.

PrintDeck

Recoge los datos de tus impresoras

Tu servidor local

Entrega actualizaciones a los suscriptores

Mosquitto

Tus aplicaciones

Paneles, luces, notificaciones

Node-RED · Home Assistant
Guía de configuración MQTT

Tu primer mensaje MQTT

Empieza con una impresora y una suscripción. Home Assistant es opcional.

  1. 01

    Prepara tu servidor

    Usa un servidor MQTT local como Mosquitto. PrintDeck y tu aplicación son clientes de ese servidor; PrintDeck no aloja uno. Crea credenciales y permite que PrintDeck publique y tu aplicación lea sus temas.

  2. 02

    Conecta PrintDeck

    En Web Config, abre Ajustes del dispositivo > Unified API. Activa MQTT, introduce dirección, puerto y credenciales del servidor, guarda y comprueba la conexión. Ajusta TLS según el servidor. Para tu propia aplicación, deja desactivada la detección de Home Assistant.

  3. 03

    Suscríbete al estado de las impresoras

    Conecta tu cliente MQTT al mismo servidor. Copia la raíz de temas MQTT desde Web Config y añade /printers/+/status. El signo + incluye todas las impresoras guardadas. Selecciona una impresora en línea en PrintDeck y espera unos cinco segundos para recibir datos actuales.

Ejemplo de mensaje de estado
Suscripción<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"
}

Ejemplo abreviado. Lee status.job.progress_percent para el progreso y status.job.phase para el estado del trabajo.

Explora los temas MQTT

Elige qué
recibe tu aplicación.

La raíz es printdeck/<printdeck_id>/v1. Copia tu raíz real desde Web Config y añade uno de estos sufijos. Usa un ID del catálogo printers o + para todas las impresoras.

Leer la guía completa de la API
/printers

Encuentra tus impresoras

Catálogo de impresoras guardadas con sus ID. Se retiene en el servidor.

/printers/+/status

Actualizaciones de estado

Estado actual, progreso, temperaturas y registro de eventos recientes. Mensajes en directo, aproximadamente cada cinco segundos.

/printers/+/events

Eventos de impresión

Eventos individuales observados, como started, completed o milestone. Usa event_type para elegir una acción y event_id para identificar el aviso.

/availability

Comprueba la conexión

Estado online u offline retenido de la conexión de PrintDeck con el servidor. Cada impresora tiene su propio status.connection.state en su mensaje de estado.

¿Usas Home Assistant?

Elige una ruta por PrintDeck para mantener un único conjunto de entidades.

Detección de Home Assistant

Las entidades aparecen solas.

Conecta la integración MQTT incorporada de Home Assistant al mismo servidor. Activa Home Assistant MQTT Discovery en PrintDeck. Los dispositivos, sensores y entidades de eventos aparecen automáticamente; no necesitas HACS.

Home Assistant MQTT
PRINTDECK · HACS

Usa la integración PrintDeck.

Instala PrintDeck mediante HACS, elige MQTT al configurar y deja desactivada la detección estándar. Home Assistant usa su propia conexión al servidor. Usa la integración actual, versión 0.1.7 o posterior.

Instala la integración PrintDeck
Crea la primera automatización
CONVIENE SABERLO

Trabaja con
datos actuales.

Datos de solo lectura compartidos

¿Están actualizados los datos?

MQTT usa los mismos campos normalizados que REST, con metadatos de entrega adicionales. El estado se actualiza aproximadamente cada cinco segundos; las impresoras inactivas mantienen el intervalo de actualización de la lista. La telemetría y los eventos en directo no se retienen.

Antes de usar una lectura, comprueba status.connection.state, status.connection.stale y status.connection.detail_level. Los valores desconocidos son null. Comprueba que _mqtt_generation coincida en catálogo y estado; borra las lecturas antiguas cuando cambie.

¿Recibiré todos los eventos?

Los eventos describen cambios observados; pueden perderse transiciones breves. Usan QoS 0, sin retención ni repetición. El registro conserva ocho observaciones recientes. Sigue stream_id y sequence para evitar acciones repetidas y establece una referencia sin ejecutar acciones al reconectar. La guía de la API detalla el contrato.

¿Conectado, pero sin mensajes?

Comprueba dirección, puerto, TLS y permisos de los temas. Usa la raíz exacta de Web Config. El estado en directo no se retiene: espera a la siguiente actualización. Las credenciales del servidor son distintas del token REST.

Conexión y recuperación

Con TLS activado, PrintDeck verifica el certificado y el nombre del servidor. Añade tu certificado CA si es necesario. Los secretos guardados permanecen en PrintDeck. Tras reiniciar el servidor, PrintDeck se reconecta y publica datos actuales.

Elimina entradas antiguas de detección

Antes de cambiar de servidor o pasar a HACS MQTT, desactiva la detección con el servidor anterior accesible y espera a que termine la limpieza. Si no está accesible, quizá debas eliminar manualmente sus entradas retenidas. Cambiar el nombre mantiene la identidad; borrar un perfil elimina su configuración de detección.

Unified Printer API

¿Listo para tu próxima idea?

Consulta los temas, campos de los mensajes y reglas de entrega en la guía de la API.

Descargar guía de la API