Unified Printer API HOME ASSISTANT · INTEGRACIÓN PRINTDECK

Tu impresora pasa a formar
parte de tu hogar inteligente.

Home Assistant puede consultar PrintDeck en tu red local, convertir sus datos normalizados de impresora en entidades y reaccionar cada vez que cambia el estado de una impresión.

Detección mDNS automática Una solicitud, muchos sensores Protegido con un token Bearer Klipper y Bambu Lab
LA IDEA

PrintDeck traduce.
Home Assistant reacciona.

La integración PrintDeck detecta dispositivos compatibles, solicita el token de Unified API en la interfaz de Home Assistant y crea automáticamente las entidades disponibles de las impresoras.

01

Impresión terminada

Enciende una lámpara, envía una notificación al teléfono o anuncia que la pieza está lista.

02

Hitos de progreso

Reacciona cuando el progreso supere el 25 %, 50 % o 75 % para cambiar una luz indicadora o actualizar un panel.

03

Trabajo pausado o detenido

Reacciona ante trabajos pausados, fallidos o cancelados antes de volver al taller.

04

Vista general del taller

Muestra la conexión, las temperaturas, el tiempo restante y la capa actual en un único panel local.

EMPIEZA AQUÍ · NO HACE FALTA YAML

Sin configuration.yaml.
Configúralo desde la interfaz.

HACS instala la integración mantenida de PrintDeck. Después, todo ocurre en la interfaz normal de Home Assistant: detección, introducción del token, dispositivos, sensores y automatizaciones.

La misma red localHome Assistant y PrintDeck deben poder comunicarse entre sí.

Firmware actual de PrintDeckActualiza el monitor antes de conectar la integración.

HACS instaladoSi todavía no tienes HACS, instálalo primero con la guía oficial.

  1. 01

    Activa la API en PrintDeck

    Abre PrintDeck Web Config, elige Ajustes > Unified Printer API, actívala y copia el token generado. Guárdalo en privado; pegarás el token sin modificar en Home Assistant, sin añadir la palabra Bearer.

  2. 02

    Añade PrintDeck a HACS

    Usa el botón de abajo. Abre el repositorio personalizado de PrintDeck directamente en HACS. Si el botón no puede acceder a tu Home Assistant, utiliza la ruta manual indicada debajo.

    Abrir PrintDeck en HACS
    Añadir el repositorio manualmente

    Abre HACS > Integraciones > menú de tres puntos > Repositorios personalizados. Pega https://github.com/PrintDeck/home-assistant, elige Integración como tipo y selecciona Añadir.

    Leer la guía oficial de repositorios personalizados de HACS
  3. 03

    Descarga y reinicia

    En HACS, selecciona PrintDeck, elige Descargar e instala la versión más reciente. Reinicia Home Assistant cuando HACS lo solicite. Actualizar el navegador no es reiniciar.

  4. 04

    Añade la integración

    Abre Ajustes > Dispositivos y servicios > Añadir integración y busca PrintDeck. Elige un monitor detectado o introduce printdeck.local o su IP local. Pega el token de Unified API sin modificar y envía el formulario.

  5. 05

    Nombra y asigna

    Home Assistant muestra el monitor PrintDeck y cada impresora configurada. Cámbiales el nombre o asigna áreas si te resulta útil y elige Finalizar. Usa Añadir concentrador solo si tienes otro monitor PrintDeck físico.

  6. 06

    Comprueba las entidades

    Abre la integración PrintDeck. Deberías ver un concentrador y un dispositivo por impresora. Cada impresora expone el progreso, la fase, la actividad, las temperaturas, las capas, el tiempo, los datos de conexión, la dirección de red y el puerto de red cuando están disponibles.

    Las impresoras se mantienen sincronizadas automáticamente

    Añade una impresora en PrintDeck y Home Assistant creará su dispositivo y sus entidades tras el siguiente ciclo de consulta. Elimina una impresora y la versión 0.1.2 o posterior de la integración eliminará su dispositivo y sus entidades de Home Assistant tras la siguiente actualización completa. Un problema temporal de conexión nunca activa la limpieza. Eliminar una impresora rompe intencionadamente las automatizaciones que hacen referencia a sus entidades; si solo cambió la dirección, edita la impresora guardada.

TU PRIMERA AUTOMATIZACIÓN

Enciende una luz
cuando el progreso alcance el 75%.

Este ejemplo utiliza el editor visual de automatizaciones. Funciona con cualquier porcentaje, incluidos 82% u 88%.

  1. CUANDO

    Elige Estado numérico, selecciona la entidad Progreso de impresión de la impresora y establece Por encima de en 74,9.

  2. Y SI

    Elige Estado, selecciona la entidad Fase de impresión de la misma impresora y establece el estado en Printing.

  3. ENTONCES

    Elige Luz: Encender y selecciona una luz. Usa Encender en lugar de Alternar para que el resultado sea predecible.

  4. GUARDAR

    Pon un nombre a la automatización y guárdala. Ejecutar acciones solo prueba la luz; una impresión corta prueba el disparador y la condición.

¿Por qué 74,9 en lugar de 75?

La prueba Por encima de de Home Assistant es estricta. Un umbral de 74,9 se activa cuando el sensor informa por primera vez de 75 o más. La condición Printing evita que un progreso antiguo encienda la luz con la impresora inactiva.

BLUEPRINTS LISTOS PARA USAR

¿Prefieres un formulario guiado?

Importa un blueprint y elige el sensor de la impresora y la luz en las listas de Home Assistant.

SOLUCIÓN RÁPIDA DE PROBLEMAS

Si algo no aparece,
comprueba primero estos puntos.

PrintDeck no aparece en Añadir integración

Confirma que HACS la descargó, reinicia Home Assistant y actualiza el navegador después del reinicio.

Home Assistant solicita una actualización del firmware

Actualiza el monitor PrintDeck y vuelve a intentar la conexión. Este mensaje significa que el monitor todavía no anuncia compatibilidad con la integración nativa.

No se puede conectar con el host

Mantén Home Assistant y PrintDeck en la misma red local. Si printdeck.local no se resuelve, introduce la IP local que muestra PrintDeck.

El token es rechazado

Copia un token nuevo desde PrintDeck Web Config y pégalo exactamente. No añadas Bearer en el formulario de la integración nativa.

El progreso no está disponible

Selecciona esa impresora en PrintDeck para que tenga una conexión completa en tiempo real. Algunas impresoras inactivas solo ofrecen datos resumidos.

La luz no se encendió

Abre la automatización y elige Trazas. La traza muestra si se activó el disparador de progreso y si se cumplió la condición Printing.

EJEMPLO DE HOME ASSISTANT

Busca PrintDeck en Añadir integración

Búsqueda de PrintDeck en Añadir integración de Home Assistant
Busca PrintDeck y selecciona el resultado con el icono redondo de PrintDeck.
EJEMPLO DE HOME ASSISTANT

Nombra el monitor y las impresoras

Pantalla Nombrar y asignar de Home Assistant para un monitor PrintDeck y sus impresoras
Las áreas son opcionales. Elige Omitir y finalizar si todavía no quieres organizar los dispositivos.
EJEMPLO DE HOME ASSISTANT

Un concentrador con sus impresoras

Página de la integración PrintDeck con un concentrador y cuatro impresoras
El concentrador representa el monitor PrintDeck físico. Las filas inferiores son las impresoras configuradas en ese monitor.
EJEMPLO DE HOME ASSISTANT

Una automatización completa del progreso

Automatización de Home Assistant con disparador de progreso, condición Printing y acción Encender luz
Este ejemplo funcional utiliza 82%. Para 75%, introduce Por encima de 74,9 y mantén la misma condición Printing.
EJEMPLO DE SOLUCIÓN DE PROBLEMAS

Se requiere una actualización del firmware

Formulario de conexión de PrintDeck en Home Assistant con un aviso de actualización del firmware
Este es un ejemplo de error, no la pantalla de conexión correcta. Actualiza PrintDeck y vuelve a enviar la conexión.
ALTERNATIVA REST MANUAL

¿Prefieres YAML?
Conecta un estado y una luz.

Se recomienda la integración nativa anterior. Abre esta alternativa avanzada solo si no puedes usar HACS o si quieres mantener los sensores REST manualmente.

Mostrar las instrucciones REST manuales
  1. 01

    Activa la API

    Abre Web Config en PrintDeck, elige Unified Printer API, actívala y copia el token de acceso generado.

  2. 02

    Busca el ID de la impresora

    Solicita la lista de impresoras y anota el ID de la impresora que quieres supervisar.

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

    Guarda el token en secrets.yaml

    Incluye la palabra Bearer en el valor del secreto.

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

    Añade el sensor de fase

    Esto realiza una solicitud cada 10 segundos. Cambia PRINTDECK-IP y el ID de impresora 1 en la 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

    Comprueba y reinicia Home Assistant

    Valida el YAML en Herramientas para desarrolladores, reinicia Home Assistant y comprueba que la entidad PrintDeck Phase tenga un valor.

  6. 06

    Añade la automatización

    Sustituye light.living_room por el ID de entidad de tu lámpara.

    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

    Inicia una impresión de prueba corta

    Observa cómo la entidad de fase pasa a completed. Si la lámpara no se enciende, abre el seguimiento de la automatización para ver los resultados del disparador y de la condición.

TODOS LOS ESTADOS NORMALIZADOS

Utiliza fases generales
o actividades detalladas.

La fase del trabajo es la mejor opción para la mayoría de las automatizaciones. La actividad del trabajo expone las actividades detalladas que controlan las reacciones de PrintDeck cuando la impresora las comunica.

Fases del trabajo

Todos los valores de fase de trabajo compatibles:

unknownidlepreparingprintingpausedcompletedfailedcancelled

Actividades detalladas

Todos los valores de actividad de trabajo compatibles:

unknownstandbypreparingnozzle_heatingbed_heatinghomingbed_levelingnozzle_cleaningcalibratingfilament_changingfilament_unloadingfilament_loadingfilament_purgingprintingpausedcompletedfailedcancelled

No necesitas una entidad por cada valor. El sensor PrintDeck Activity cambia entre todas las actividades indicadas y una automatización puede reaccionar al valor que elijas.

Valores de conexión y estado

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

La disponibilidad de actividades detalladas depende de los datos que comunique la impresora conectada. El valor unknown de la API utiliza la reacción unavailable de PrintDeck como alternativa. La impresora seleccionada proporciona datos completos en tiempo real; las demás impresoras guardadas pueden proporcionar datos resumidos según el intervalo configurado de actualización de la lista de impresoras.

PAQUETE COMPLETO DE SENSORES DE ESTADO

Una solicitud a la API.
Todos los campos de estado detallado.

La integración nativa crea estas entidades automáticamente. Este paquete YAML se conserva para instalaciones REST manuales avanzadas.

Mostrar el YAML manual completo de sensores
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
Antes de reiniciar

Guarda el token correspondiente en secrets.yaml y sustituye PRINTDECK-IP y el ID de impresora 1. Si configuration.yaml ya contiene una sección rest de nivel superior, añade este recurso debajo en lugar de crear una segunda clave rest.

CONVIENE SABERLO

Local por diseño.
De solo lectura por diseño.

Home Assistant consulta PrintDeck; PrintDeck no envía webhooks. Mantén ambos dispositivos en una red local de confianza y no expongas el puerto de la API a internet. La integración guarda el token en la entrada de configuración de Home Assistant; en una configuración REST manual, guárdalo en secrets.yaml.

El progreso, las temperaturas y las actividades detalladas utilizadas por las reacciones son más completos para la impresora seleccionada actualmente en PrintDeck. La conexión y el estado resumido del trabajo siguen disponibles para las demás impresoras guardadas.

Volver a Unified Printer API

MQTT para tus herramientas locales

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.

01

Actualizaciones de estado

Recibe el estado del trabajo, el progreso, las temperaturas y la disponibilidad en tus paneles o flujos de Node-RED.

02

Eventos de impresión

Reacciona a inicios de impresión observados, hitos de progreso y eventos que requieren atención. Los eventos en directo no se retienen ni se repiten tras reconectar.

03

Detección de Home Assistant

Deja que Home Assistant cree dispositivos y entidades automáticamente con su integración MQTT incorporada. O elige PrintDeck mediante HACS con MQTT y mantén desactivada la detección estándar.