HowTo: MQTT 直连自有服务器

设备不经过商为云，直接连你自有 MQTT 服务器。打印内容全程不上商为云——满足金融 / 医疗 / 政务对数据自主的硬要求。协议规范 MQTT v2025-11-10（计划 2026-10 以 Apache 2.0 开放）。该方案已有国内与海外用户商用运行。本指南适用于合规要求严苛的银行、证券、保险、医院、政府、企业。

1支持的 MQTT 服务器类型

云打印设备支持接入以下类型的 MQTT 服务器：

服务器类型	说明
阿里云 MQTT	公共实例 / 企业实例
腾讯云 MQTT	托管，免运维
自建 MQTT	客户自行部署的 Broker
电信云	—

适用设备：热敏打印机、标签打印机、打印云盒。如有定制需求，请联系商务人员。

2写入设备 MQTT 参数

使用 PC 端《云打印设备配置工具》，通过 USB 数据线连接设备写入参数：

准备好 MQTT 服务器参数（地址、端口、认证信息）
打印机开机，用 USB 数据线连接 PC
在配置工具中选择服务器类型（阿里云 / 腾讯云 / 自建 MQTT 等），填入参数并写入

💡 Clean Session：设备默认在连接时清除会话。如需设备继续接收离线期间的消息，请在配置工具写入参数时选择「不清除 Session」。

3主题与消息流

协议约定两类主题，QoS 均为 1：

方向	用途	QoS
订阅	接收打印任务、语音播报消息、命令消息	1
发布	上报设备状态及打印结果	1

📌 关于主题名：具体主题字符串随所选 MQTT 服务器类型与设备参数而定，不属公开规范内容。完整主题定义见官方《云打印机对接 MQTT 服务器通信协议》，可向商务索取。

设备上报数据中的 devicename 为设备 SN（机器码），与应用侧三元组的 DeviceName 或 ClientID 保持一致。

4下行：打印与语音消息字段

MQTT 服务器推送到云打印设备的消息为 UTF-8 编码的 JSON：

字段	类型	必填	说明
`id`	uint32	是	打印任务 id，范围 0-4294967295。服务端须确保不重复；设备具备防重打能力——同一 id 在不断电情况下只打印一次，重复推送会上报状态 209
`type`	int	是	打印数据排版类型（打印语言）：1 ESC（BASE64 编码）｜2 CPCL｜3 TSPL｜4 XML｜5 JSON｜6 PNG｜99 设备配置管理
`contents`	String / Array / Object	是	打印内容，数据格式与 type 保持一致。ESC / CPCL / TSPL / XML 为字符串；JSON 排版为 Array（小票）或 Object（标签）；PNG 为 URL 链接字符串或 base64 内容
`pWidth`	int	否	打印纸张宽度（mm）：58 / 80 / 110，默认 58
`pCopy`	int	否	打印份数，默认 1
`pType`	int	否	纸张类型（默认 1）：1 连续纸｜2 标签纸｜3 黑标纸｜4 穿孔纸｜8 连续纸（标签指令打印小票）。纸类型为标签时必传
`vType`	int	否	播报类型：-1 无播报｜0 定制语音｜1「你有新的订单」｜10000 指定语音链接下载播报
`vMessage`	string	否	语音播报内容文本（TTS 合成，UTF-8）；vType 为 10000 时为下载链接 URL
`vMode`	int	否	0 按队列顺序播报（默认）｜1 立即播报｜2 立即播报并清空待播报队列
`message`	string	否	预留 HTTP 下载类型的打印内容，与 contents 二选一（优先 contents）
`gateway`	string	否	仅打印云盒：`usb` 表示发送到本机 USB 打印机；填入 IP（如 192.168.2.11）表示发送到指定局域网网络打印机

示例一：XML 排版（票据，type=4）

{"id":100001,"type":4,"pType":1,"pWidth":58,"pCopy":1,"vType":0,"vMessage":"测试语音", "contents":"<CB>收款小票</CB> 商户存根请妥善保管 -------------------------------- 商户名称示例水果店 交易金额 126.50 元 <QR>10058001200047217</QR> -------------------------------- 打印时间 2026-09-16 11:02:36 "}

示例二：JSON 排版（票据，type=5）

{"id":100002,"type":5,"pType":1,"pWidth":58,"pCopy":1, "contents":[ {"cont":"云打印 JSON 排版","type":"title"}, {"thead":{"名称":"40%","单价":"25%","数量":"15%","金额":"20%"}, "tbody":[["云打印机（4G/WiFi）",100,1,100],["打印云盒",189,1,189]]}, {"cont":"合计:289 元","size":"11","align":"left"}, {"both_sides":["收款金额","289.00"]}, {"both_sides":["支付方式","微信支付"]}, {"cont":"https://www.sw-aiot.com","type":"qrcode","align":"center","size":"60"}, {"cont":"1","type":"cut"}]}

JSON 排版的完整属性定义（票据 / 标签两种）见官网JSON 排版文档。

5上行：设备状态与打印结果

云打印设备上报的数据以 JSON 格式组装：

字段	类型	说明
`devicename`	string	云打印设备 SN（机器码），与三元组的 DeviceName 或 ClientID 一致
`id`	uint32	打印任务 id，与服务器推送的任务 id 一致。上报设备状态时不包含本项
`code`	int	状态码，见下表

状态码一览

code	含义
0	打印成功 / 打印机正常
100	未知错误，通讯异常
101	打印机缺纸
102	打印机开盖
103	打印机过热
201	没有 id
202	没有 type
203	无效 type 参数（未在定义范围）
204	没有 msg
205	无效 msg（例如链接非标准 HTTP）
206	下载错误（重复下载 6 次）
207	任务长度超出设备缓冲区
208	内容格式错误
209	重复任务，不执行打印（按 id 判断）

上报样例

// 4G 机型开机连上服务器后上报一次（imei 为 15 位数字，iccid 为 20 位卡号） {"devicename":"dev1","imei":"123456789012345","iccid":"12345678901234567890"} // 设备状态上报：缺纸 {"devicename":"dev1","code":101} // 打印结果上报：任务 123456789 打印成功 {"devicename":"dev1","id":123456789,"code":0}

6远程配置管理（type=99）

云打印设备支持通过云端远程设置音量、重启打印机、设置默认指令模式等：

命令	参数	说明
`volume`	value：0-4	音量设置：0 静音｜1 低音量｜2 中音量｜3 大音量
`reboot`	—	系统重启
`label_cmd`	print：tspl / cpcl / zpl	默认标签指令（针对图片或 JSON 打印），默认 tspl
`print_cmd`	cmd：tspl / cpcl / esc	设置打印机默认语言

{"id":12345678,"type":99,"contents":{"cmd":"volume", "value":1}}

带扫码功能的产品还可上报扫码内容：

{"devicename":"dev1","scan_content":"abcd1234"}

7合规建议与验收

⚠️ 建议的安全加固项（由客户在自有 Broker 侧实施）：

TLS 加密传输（mqtts / 8883）
Broker ACL：按设备 SN 限定可读写的主题
通信与任务审计日志留存
每设备独立凭证，杜绝 SN 仿冒
数据落在客户自有数据中心

商为可协助：

完整协议文档与字段说明（含主题定义）
PC 配置工具与参数写入指导
Broker 部署与联调支持
原厂对接工程师支持

⚡ 评估 MQTT 直连方案？联系商务 sw@sw-aiot.com 或拨打 0755-23003730