MQTT 标签打印：每条 broker 消息都变成一张标签

在工厂车间里，几乎所有设备都早已接在 MQTT broker 上：秤、扫描器、PLC、传感器。要把这些数据变成标签，通常需要编写一个小服务，负责订阅、填充版式并把 ZPL 推送到打印机。这个服务你完全可以省掉：zplCloud 会自己订阅主题并打印。

你需要什么

要素	示例
Broker	Mosquitto、HiveMQ、EMQX、AWS IoT Core、Azure IoT Hub
主题过滤器	plant/line1/labels，或使用通配符 plant/+/labels
访问凭据	用户名和密码，通常使用端口 8883 并启用 TLS
目标	一台已连接的 Zebra 打印机或一台虚拟测试打印机

创建订阅

在 数据流 → 订阅 → 新建订阅 下选择类型 MQTT。连接字符串就是一个简单的键值列表：

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

主题字段填写主题过滤器。允许使用 MQTT 通配符：+ 恰好匹配一个层级，# 匹配其下的所有层级。因此，订阅 plant/+/labels 会同时收到 plant/line1/labels 和 plant/line2/labels 的消息。

生成标签的两种途径

第一种：输入数据，设计自动填充。 如果你在订阅中选择了标签设计，每条 JSON 消息都会成为一条记录。消息中的键会填充设计中已绑定的字段：

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

绑定到 sku 的字段随后会显示 88-12345。任何非 JSON 内容都会作为 message 进入单个字段。

第二种：成品 ZPL。 如果消息本身已携带 ZPL，请在订阅中将设计留空，并发送一个信封：

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

printer 指定打印机序列号，远程打印机用 rp:{id}，账户中的所有打印机则用 "*"。如果 ZPL 很大，可以改为引用它："zplRef": { "storage": "archive", "key": "orders/4711.zpl" } 会在打印时从 S3 或 Azure Blob 获取文件。

为什么不会丢失任何消息

MQTT 通常在消息到达的那一刻就确认。zplCloud 的做法不同：只有在 ZPL 到达打印机后才确认。如果打印失败，消息保持未确认状态，broker 会以 QoS 1 或 2 重新投递。

因此，在连接字符串中设置 Qos=1 很有必要。在 QoS 0 下，协议根本不提供重新投递：打印失败时丢失的内容就彻底没了。

在用纸之前先演练

在正式打印标签之前，先在 打印机 → 沙盒打印机 下创建一台虚拟测试打印机，并在订阅中选择它。它像真实设备一样接收 ZPL，渲染标签并将其存入历史记录——无需硬件，也不占用渲染配额。这样，在用掉第一卷标签纸之前，你就能看到消息实际会生成什么。

你还可以通过 测试 手动触发一次订阅，完全不需要 broker 消息。

常见陷阱

• 什么都收不到。 检查主题过滤器。plant/line1 收不到 plant/line1/labels 上的消息；你需要使用 plant/line1/#。
• TLS 错误。 端口 8883 需要 Tls=true；端口 1883 为未加密连接。
• 重启后出现重复标签。 设置 CleanSession=false 和固定的 ClientId，让 broker 能识别该会话。
• 某个字段一直为空。 消息中的键必须与设计中的绑定一致。订阅的“日志”区域会逐字显示每条消息。