Unified Printer API MQTT · PRINTDECK

Aktualizacje z drukarek.
Dostarczane przez MQTT.

Wysyłaj status drukarek i zdarzenia wydruku do własnego lokalnego brokera. Twórz panele, powiadomienia i automatyzacje w wybranych przez siebie narzędziach.

Otwórz konfigurację MQTTPoznaj tematy MQTT
Tylko sieć lokalnaZ założenia tylko do odczytuWersjonowany JSON
MQTT

Jedno połączenie.
Wiele możliwości.

PrintDeck wysyła ujednolicone dane drukarek do lokalnego brokera, np. Mosquitto. Aplikacje subskrybują aktualizacje, zamiast cyklicznie odpytywać REST API. HTTP i MQTT mogą działać niezależnie lub jednocześnie.

PrintDeck

Zbiera dane Twoich drukarek

Twój lokalny broker

Dostarcza aktualizacje subskrybentom

Mosquitto

Twoje aplikacje

Panele, światła, powiadomienia

Node-RED · Home Assistant
Instrukcja konfiguracji MQTT

Twoja pierwsza wiadomość MQTT

Zacznij od jednej drukarki i jednej subskrypcji. Home Assistant jest opcjonalny.

  1. 01

    Przygotuj brokera

    Użyj lokalnego brokera MQTT, np. Mosquitto. PrintDeck i Twoja aplikacja łączą się z nim jako klienci; PrintDeck sam nie jest brokerem. Utwórz dane logowania i nadaj PrintDeck uprawnienia do publikowania, a aplikacji do odczytu jego tematów.

  2. 02

    Połącz PrintDeck

    W Web Config otwórz Ustawienia urządzenia > Unified API. Włącz MQTT, podaj adres brokera, port i dane logowania, a następnie zapisz i sprawdź połączenie. Dopasuj ustawienia TLS do brokera. Dla własnej aplikacji pozostaw wykrywanie Home Assistant wyłączone.

  3. 03

    Subskrybuj status drukarek

    Podłącz klienta MQTT do tego samego brokera. Skopiuj główny temat MQTT z Web Config i dopisz /printers/+/status. Znak + pasuje do każdej zapisanej drukarki. Wybierz drukarkę online na PrintDeck i poczekaj około pięciu sekund na świeże dane.

Przykładowa wiadomość statusu
Subskrypcja<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"
}

Skrócony przykład. Postęp odczytasz z status.job.progress_percent, a stan zadania z status.job.phase.

Poznaj tematy MQTT

Wybierz, co
odbiera Twoja aplikacja.

Główny temat ma postać printdeck/<printdeck_id>/v1. Skopiuj swój temat z Web Config i dopisz jeden z tych sufiksów. Użyj ID drukarki z katalogu printers albo + dla wszystkich drukarek.

Przeczytaj pełną dokumentację API
/printers

Znajdź swoje drukarki

Katalog zapisanych drukarek wraz z ID. Zachowywany na brokerze.

/printers/+/status

Aktualizacje statusu

Bieżący stan zadania, postęp, temperatury i dziennik ostatnich zdarzeń. Wiadomości na żywo, mniej więcej co pięć sekund.

/printers/+/events

Zdarzenia wydruku

Poszczególne zaobserwowane zdarzenia, np. started, completed lub milestone. Użyj event_type do wyboru akcji, a event_id do identyfikacji powiadomienia.

/availability

Sprawdź połączenie

Zachowywany stan online lub offline połączenia PrintDeck z brokerem. Każda drukarka ma własne status.connection.state w wiadomości statusu.

Korzystasz z Home Assistant?

Wybierz jedną ścieżkę dla każdego PrintDeck, aby zachować jeden zestaw encji.

Wykrywanie Home Assistant

Encje pojawią się same.

Podłącz wbudowaną integrację MQTT w Home Assistant do tego samego brokera. Włącz wykrywanie Home Assistant MQTT w PrintDeck. Urządzenia, sensory i encje zdarzeń wydruku pojawią się automatycznie; HACS nie jest wymagany.

Home Assistant MQTT
PRINTDECK · HACS

Wybierz integrację PrintDeck.

Zainstaluj PrintDeck przez HACS, wybierz MQTT podczas konfiguracji i pozostaw standardowe wykrywanie wyłączone. Home Assistant używa własnego połączenia z brokerem. Użyj aktualnej integracji w wersji 0.1.7 lub nowszej.

Zainstaluj integrację PrintDeck
Utwórz pierwszą automatyzację
WARTO WIEDZIEĆ

Korzystaj ze
świeżych danych.

Dane tylko do odczytu, wspólne dla obu połączeń

Jak świeże są dane?

MQTT używa tych samych ujednoliconych pól drukarki co REST, z dodatkowymi metadanymi przesyłania. Aktualizacje statusu docierają mniej więcej co pięć sekund; nieaktywne drukarki nadal korzystają z ustawienia odświeżania listy drukarek. Bieżąca telemetria i zdarzenia nie są zachowywane na brokerze.

Przed użyciem odczytu sprawdź status.connection.state, status.connection.stale i status.connection.detail_level. Nieznane wartości to null. Porównuj _mqtt_generation w katalogu i wiadomościach statusu; po jego zmianie usuń stare odczyty.

Czy otrzymam każde zdarzenie wydruku?

Zdarzenia opisują zaobserwowane zmiany; krótkie przejścia mogą zostać pominięte. Pojedyncze zdarzenia używają QoS 0 i nie są zachowywane ani odtwarzane. Dziennik statusu przechowuje osiem ostatnich obserwacji. Śledź stream_id i sequence, aby uniknąć powtórnych akcji, a po ponownym połączeniu ustal punkt odniesienia bez wywoływania akcji. Pełny kontrakt zdarzeń opisuje instrukcja API.

Połączono, ale nie ma wiadomości?

Sprawdź adres brokera, port, TLS i uprawnienia do tematów. Użyj dokładnego głównego tematu z Web Config. Bieżący status nie jest zachowywany, więc poczekaj na kolejną aktualizację. Dane logowania do brokera są niezależne od tokenu REST.

Połączenie i przywracanie

Gdy TLS jest włączone, PrintDeck sprawdza certyfikat i nazwę brokera. W razie potrzeby dodaj własny certyfikat CA. Zapisane sekrety pozostają na PrintDeck. Po restarcie brokera PrintDeck łączy się ponownie i publikuje świeże dane.

Usuń stare wpisy Discovery

Przed zmianą brokera lub przejściem na MQTT przez HACS wyłącz Discovery przy dostępnym starym brokerze i poczekaj na zakończenie porządkowania. Jeśli broker jest nieosiągalny, jego zachowane wpisy Discovery mogą wymagać ręcznego usunięcia. Zmiana nazwy zachowuje tożsamość drukarki; usunięcie profilu usuwa jej konfigurację Discovery.

Unified Printer API

Gotowy na kolejny pomysł?

Pełny opis tematów, pól wiadomości i zasad przesyłania znajdziesz w instrukcji API.

Pobierz dokumentację API