MQTT for your local tools

MQTT

One connection.
Many possibilities.

PrintDeck sends normalized printer data to a local broker such as Mosquitto. Your apps subscribe to updates instead of repeatedly requesting them through the REST API. HTTP and MQTT can run independently or together.

PrintDeck

Collects your printer data

Your local broker

Delivers updates to subscribers

Mosquitto

Your apps

Dashboards, lights, notifications

Node-RED · Home Assistant

MQTT setup guide

Your first MQTT message

Start with one printer and one subscription. Home Assistant is optional.

01
Prepare your broker
Use a local MQTT broker such as Mosquitto. PrintDeck and your app are clients of this broker; PrintDeck does not host one. Create broker credentials and allow PrintDeck to publish and your app to read its topics.
02
Connect PrintDeck
In Web Config, open Device Settings > Unified API. Turn MQTT on, enter the broker address, port and credentials, then save and check the connection. Match the broker’s TLS settings. Keep Home Assistant Discovery off for your own app.
03
Subscribe to printer status
Connect your MQTT client to the same broker. Copy MQTT topic root from Web Config and append /printers/+/status. The + matches every saved printer. Select an online printer on PrintDeck and wait about five seconds for fresh data.

Example status message

Subscription<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"
}

Shortened example. Read status.job.progress_percent for progress and status.job.phase for the job state.

Explore MQTT topics

Choose what
your app receives.

The topic root is printdeck/<printdeck_id>/v1. Copy your actual root from Web Config. Add one of these suffixes; use a printer ID from the printers catalog or + for every printer.

Read the complete API guide

/printers

Find your printers

The saved printer catalog, including IDs. Retained by the broker.

/printers/+/status

Status updates

Current job state, progress, temperatures and the recent event journal. Live messages, about every five seconds.

/printers/+/events

Print events

Individual observed events, such as started, completed or milestone. Use event_type to choose an action and event_id to identify the announcement.

/availability

Check the connection

Retained online or offline status for PrintDeck’s broker connection. Each printer has its own status.connection.state in its status message.

Using Home Assistant?

Choose one path for each PrintDeck to keep a single set of entities.

Home Assistant Discovery

Let the entities appear.

Connect Home Assistant’s built-in MQTT integration to the same broker. Enable Home Assistant MQTT Discovery in PrintDeck. Devices, sensors and print-event entities appear automatically; HACS is not required.

Home Assistant MQTT

PRINTDECK · HACS

Use the PrintDeck integration.

Install PrintDeck through HACS, choose MQTT during setup and leave standard Discovery off. Home Assistant uses its own broker connection. Use the current integration, version 0.1.7 or later.

Install the PrintDeck integration

Create the first automation

GOOD TO KNOW

Build on
fresh data.

Read-only data, shared across connections

How fresh is the data?

MQTT uses the same normalized printer fields as REST, with additional delivery metadata. Status updates arrive about every five seconds; inactive printers still follow Printer List Refresh. Live telemetry and events are not retained.

Check status.connection.state, status.connection.stale and status.connection.detail_level before using a reading. Unknown values are null. Match _mqtt_generation in catalog and status messages; clear old readings when it changes.

Will I receive every print event?

Events describe observed changes; brief transitions can be missed. Individual events use QoS 0, with no retention or replay. The status journal keeps eight recent observations. Track stream_id and sequence to avoid repeated actions, and start from a quiet baseline after reconnecting. The API guide explains the full event contract.

Connected, but no messages?

Check the broker address, port, TLS and topic permissions. Use the exact topic root from Web Config. Live status is not retained, so wait for the next update. Broker credentials are separate from the REST bearer token.

Connection and recovery

When TLS is enabled, PrintDeck verifies the broker certificate and hostname. Add your own CA certificate when required. Saved secrets stay on PrintDeck. After a broker restart, PrintDeck reconnects and publishes fresh data.

Remove old Discovery entries

Before changing brokers or switching to HACS MQTT, disable Discovery while the old broker is reachable and allow cleanup to finish. If that broker cannot be reached, its retained Discovery entries may need manual removal. Renaming a printer keeps its identity; deleting a profile removes its Discovery configuration.

Unified Printer API

Ready for your next idea?

Get the full topic reference, payload fields and delivery rules in the API guide.

Download API guide

Printer updates.Delivered over MQTT.