Stampa di etichette con MQTT: ogni messaggio del broker diventa un'etichetta

In un reparto produttivo quasi tutto è già collegato al broker MQTT: bilance, scanner, PLC, sensori. Trasformare tutto questo in etichette di solito significa scrivere un piccolo servizio che si iscrive, compila un layout e invia lo ZPL alla stampante. Puoi fare a meno di quel servizio: zplCloud si iscrive da solo al topic e stampa.

Cosa ti serve

Ingrediente	Esempio
Broker	Mosquitto, HiveMQ, EMQX, AWS IoT Core, Azure IoT Hub
Filtro topic	plant/line1/labels, oppure con wildcard plant/+/labels
Accesso	utente e password, di solito porta 8883 con TLS
Destinazione	una stampante Zebra collegata o una stampante di prova virtuale

Creare la sottoscrizione

In Streaming di dati → Sottoscrizioni → Nuova sottoscrizione scegli il tipo MQTT. La stringa di connessione è un semplice elenco di chiavi e valori:

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

Il campo topic accetta il filtro topic. Le wildcard MQTT sono ammesse: + corrisponde esattamente a un livello, # a tutto ciò che sta sotto. Una sottoscrizione su plant/+/labels riceve quindi contemporaneamente plant/line1/labels e plant/line2/labels.

Due strade verso un'etichetta

Prima strada: entrano i dati, il design si compila da solo. Se nella sottoscrizione scegli un design di etichetta, ogni messaggio JSON diventa un record. Le chiavi del messaggio riempiono i campi collegati del design:

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

Un campo collegato a sku mostra quindi 88-12345. Tutto ciò che non è JSON arriva come message in un unico campo.

Seconda strada: ZPL finito. Se il messaggio contiene già ZPL, lascia vuoto il design nella sottoscrizione e invia una busta:

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

printer indica il numero di serie della stampante, rp:{id} una stampante remota, oppure "*" tutte le stampanti dell'account. Se lo ZPL è grande, punta al file invece di includerlo: "zplRef": { "storage": "archive", "key": "orders/4711.zpl" } recupera il file da S3 o Azure Blob al momento della stampa.

Perché non si perde nulla

Normalmente MQTT conferma un messaggio nel momento in cui arriva. zplCloud fa diversamente: la conferma avviene solo quando lo ZPL ha raggiunto la stampante. Se la stampa fallisce, il messaggio resta non confermato e il broker lo riconsegna con QoS 1 o 2.

Per questo conviene avere Qos=1 nella stringa di connessione. Con QoS 0 il protocollo non prevede alcuna riconsegna: ciò che va perso con un errore di stampa è perso definitivamente.

Prova generale prima di consumare carta

Prima di stampare etichette reali, crea una stampante di prova virtuale in Stampanti → Stampanti sandbox e selezionala nella sottoscrizione. Accetta ZPL come un dispositivo reale, renderizza l'etichetta e la deposita in una cronologia - niente hardware, nessuna quota di rendering. Così vedi cosa producono davvero i tuoi messaggi prima di consumare il primo rotolo.

Una sottoscrizione può anche essere attivata una volta a mano con Test, del tutto senza un messaggio dal broker.

Errori comuni

• Non arriva nulla. Controlla il filtro topic. plant/line1 non riceve i messaggi su plant/line1/labels; ti serve plant/line1/#.
• Errori TLS. La porta 8883 richiede Tls=true; la porta 1883 funziona senza cifratura.
• Etichette duplicate dopo un riavvio. Imposta CleanSession=false e un ClientId fisso, così il broker riconosce la sessione.
• Un campo resta vuoto. Le chiavi del messaggio devono corrispondere ai binding del design. L'area “log” della sottoscrizione mostra ogni messaggio così come è arrivato.