Impressão de etiquetas via MQTT: cada mensagem do broker vira uma etiqueta

No chão de fábrica, quase tudo já está ligado ao broker MQTT: balanças, scanners, CLPs, sensores. Transformar isso em etiquetas normalmente significa escrever um pequeno serviço que assina o tópico, preenche um layout e envia ZPL para a impressora. Você pode dispensar esse serviço: o zplCloud assina o tópico por conta própria e imprime.

O que você precisa

Ingrediente	Exemplo
Broker	Mosquitto, HiveMQ, EMQX, AWS IoT Core, Azure IoT Hub
Filtro de tópico	plant/line1/labels ou, com curingas, plant/+/labels
Acesso	usuário e senha, normalmente porta 8883 com TLS
Destino	uma impressora Zebra conectada ou uma impressora de teste virtual

Criando a assinatura

Em Streaming → Assinaturas → Nova assinatura, escolha o tipo MQTT. A string de conexão é uma lista simples de chaves e valores:

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

O campo de tópico recebe o filtro de tópico. Curingas MQTT são permitidos: + corresponde a exatamente um nível, # corresponde a tudo o que está abaixo. Uma assinatura em plant/+/labels captura, portanto, plant/line1/labels e plant/line2/labels ao mesmo tempo.

Dois caminhos até a etiqueta

Primeiro: entram dados, o design se preenche sozinho. Se você escolher um design de etiqueta na assinatura, cada mensagem JSON vira um registro. As chaves da mensagem preenchem os campos vinculados do design:

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

Um campo vinculado a sku mostra então 88-12345. Tudo o que não for JSON chega como message em um único campo.

Segundo: ZPL pronto. Se a mensagem já traz ZPL, deixe o design vazio na assinatura e envie um envelope:

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

printer indica o número de série, rp:{id} uma impressora remota ou "*" todas as impressoras da conta. Se o ZPL for grande, aponte para ele em vez disso: "zplRef": { "storage": "archive", "key": "orders/4711.zpl" } busca o arquivo no S3 ou no Azure Blob no momento da impressão.

Por que nada se perde

Normalmente, o MQTT confirma uma mensagem no instante em que ela chega. O zplCloud faz diferente: a confirmação acontece quando o ZPL chega à impressora. Se a impressão falhar, a mensagem fica sem confirmação e o broker a reentrega com QoS 1 ou 2.

Por isso vale a pena ter Qos=1 na string de conexão. Com QoS 0, o protocolo não oferece nenhuma reentrega: o que se perde em uma falha de impressão se foi de vez.

Ensaie antes de gastar papel

Antes de rodar etiquetas reais, crie uma impressora de teste virtual em Impressoras → Impressoras sandbox e selecione-a na assinatura. Ela aceita ZPL como um dispositivo real, renderiza a etiqueta e a coloca em um histórico - sem hardware, sem consumir cota de renderização. Assim você vê o que suas mensagens realmente produzem antes de usar o primeiro rolo.

Uma assinatura também pode ser disparada uma vez manualmente com Teste, totalmente sem mensagem do broker.

Armadilhas comuns

• Nada chega. Verifique o filtro de tópico. plant/line1 não captura mensagens em plant/line1/labels; para isso você precisa de plant/line1/#.
• Erros de TLS. A porta 8883 exige Tls=true; a porta 1883 funciona sem criptografia.
• Etiquetas duplicadas após reiniciar. Defina CleanSession=false e um ClientId fixo para que o broker reconheça a sessão.
• Um campo fica vazio. As chaves da mensagem precisam corresponder aos bindings do design. A área "Log" da assinatura mostra cada mensagem exatamente como chegou.