MQTT label printing: every broker message becomes a label

On a factory floor almost everything already hangs off the MQTT broker: scales, scanners, PLCs, sensors. Turning that into labels normally means writing a small service that subscribes, fills a layout and pushes ZPL to the printer. You can skip that service: zplCloud subscribes to the topic itself and prints.

What you need

Ingredient	Example
Broker	Mosquitto, HiveMQ, EMQX, AWS IoT Core, Azure IoT Hub
Topic filter	plant/line1/labels, or with wildcards plant/+/labels
Access	user and password, usually port 8883 with TLS
Target	a connected Zebra printer or a virtual test printer

Creating the subscription

Under Streaming → Subscriptions → New subscription pick the type MQTT. The connection string is a plain list of keys and values:

Server=broker.example.com;Port=8883;Tls=true;Username=plant1;Password=…;Qos=1

The topic field takes the topic filter. MQTT wildcards are allowed: + matches exactly one level, # matches everything below. A subscription on plant/+/labels therefore catches plant/line1/labels and plant/line2/labels at the same time.

Two routes to a label

First: data in, the design fills itself. If you pick a label design in the subscription, every JSON message becomes a record. The keys of the message fill the bound fields of the design:

{ "sku": "88-12345", "batch": "LOT-42", "qty": 120, "bestBefore": "2027-03-01" }

A field bound to sku then shows 88-12345. Anything that is not JSON arrives as message in a single field.

Second: finished ZPL. If the message already carries ZPL, leave the design empty in the subscription and send an envelope:

{
  "schemaVersion": 1,
  "printer": "*",
  "zpl": "^XA^FO50,50^A0N,40,40^FDHello^FS^XZ"
}

printer names the serial, rp:{id} for a remote printer, or "*" for every printer on the account. If the ZPL is large, point at it instead: "zplRef": { "storage": "archive", "key": "orders/4711.zpl" } fetches the file from S3 or Azure Blob at print time.

Why nothing gets lost

MQTT normally acknowledges a message the moment it arrives. zplCloud does it differently: acknowledgement happens once the ZPL has reached the printer. If the print fails, the message stays unacknowledged and the broker redelivers it at QoS 1 or 2.

That is why Qos=1 in the connection string is worth having. At QoS 0 the protocol offers no redelivery at all: whatever is lost on a print failure is gone.

Rehearse before any paper moves

Before real labels run, create a virtual test printer under Printers → Sandbox printers and select it in the subscription. It accepts ZPL like a real device, renders the label and drops it into a history - no hardware, no render quota. That way you see what your messages really produce before the first roll is used.

A subscription can also be fired once by hand with Test, entirely without a broker message.

Common pitfalls

• Nothing arrives. Check the topic filter. plant/line1 does not catch messages on plant/line1/labels; you need plant/line1/#.
• TLS errors. Port 8883 requires Tls=true; port 1883 runs unencrypted.
• Duplicate labels after a restart. Set CleanSession=false and a fixed ClientId so the broker recognises the session.
• A field stays empty. The keys of the message have to match the bindings of the design. The "log" area on the subscription shows every message verbatim.