brother_ql 打印机状态响应全解读32 字节应答帧的 8 位错误码与 Phase 状态机【免费下载链接】brother_qlPython package for the raster language protocol of the Brother QL series label printers (QL-500, QL-550, QL-560, QL-570, QL-700, QL-710W, QL-720NW, QL-800, QL-810W, QL-820NWB, QL-1050, QL-1060N and more).项目地址: https://gitcode.com/gh_mirrors/br/brother_qlbrother_ql 是一款让 Brother QL 系列标签打印机直连硬件的 Python 工具它绕过系统驱动、直接说打印机的 raster 语言协议。每次发送指令后打印机都会回传一个固定32 字节的状态应答帧——里面的 8 位错误码与 Phase 状态机能精确告诉你打印到底成没成、卡在哪一步。本文逐字节拆解读懂它。1. 为什么值得读懂打印机的回应 ️大多数人只在标签打印机LED 闪红灯时才想起它——闪一下可能是标签类型不对、可能没纸、也可能是切纸刀卡住了。而打印机的应答帧里写着全部答案错误码字节 8、9具体是哪种故障Phase 状态字节 19打印机当前处于等待还是打印阶段介质信息字节 10、11装的是什么规格/类型的标签带⚠️ 一个前提状态读回需要 USB 连接。TCP 网络后端目前只能单向发送、拿不到状态回传后端能力对比见README.md中的后端表格。2. 32 字节应答帧结构速查逐字节含义表 应答帧永远以固定头部80 20 42开头源码称之为 Print head mark后跟 29 字节状态数据。每个字节的位置与含义在源码brother_ql/reader.py第 85-111 行有一张逐字节命名表字节位置名称含义0-2头部固定值80 20 423-4Device dependent依机型而异5-7固定值通常为30 30 008Error information 18 位错误码 ①9Error information 28 位错误码 ②10Media width当前标签带宽度mm11Media type0A连续带 /0B模切标签17Media length标签带长度mm18Status type5 种事件类型19Phase type2 种相位状态20-21Phase number相位编号高/低字节22Notification number通知编号23-31Reserved保留源码brother_ql/reader.py第 159-211 行的interpret_response()函数负责把这 32 个字节翻译成人类可读的状态字典。3. 8 位错误码速查表16 种故障一次看全 字节 8 与字节 9 各是一个 8 位的错误开关每一位对应一种故障允许多位同时置位一次报多个错。完整定义位于brother_ql/reader.py第 44-64 行3.1 Error information 1字节 8介质与硬件状态位含义0打印时无介质No media when printing1介质结束仅模切标签2切纸刀卡住Tape cutter jam3未使用4主机被占用QL-560/650TD/10505打印机已关机6高压适配器未使用7风扇故障QL-1050/1060N3.2 Error information 2字节 9通信与系统状态位含义0请更换介质Replace media error1扩展缓冲区满2传输 / 通信错误3通信缓冲区满未使用4打印中打开了盖板除 QL-5005取消键未使用6介质无法进给含检测到介质末端7系统错误记忆小技巧两字节都是00 完全健康字节 8 的 bit0 亮 没装带字节 9 的 bit6 亮 带子送不动——这是最常见的两种现场故障。4. Phase 状态机打印机如何从等待切到打印 4.1 五种状态类型字节 18Status type值名称何时出现00Reply to status request对主动状态查询的回应01Printing completed打印任务完成02Error occurred发生错误05Notification打印机主动通知06Phase change相位发生切换4.2 两种相位状态字节 19Phase type值名称含义00Waiting to receive空闲等待接收下一条指令01Printing state打印中 / 接收图像数据4.3 一次成功打印的典型应答序列源码LEGACY.md第 120-138 行记录了一次真实打印的完整日志应答顺序是固定的1. Reply to status requestphase: Waiting to receive← 初始状态查询 2. Phase change phase: Printing state ← 图像数据传入开始打印 3. Printing completed phase: Printing state ← 打印完毕 4. Phase change phase: Waiting to receive ← 回到空闲 成功 ✅源码brother_ql/backends/helpers.py第 70-101 行实现了这套验收逻辑必须同时收到Printing completed并回到Waiting to receive才判定打印成功。这就是新版brother_ql send/brother_ql print命令发送后会自动阻塞等待结果的原因。5. 如何启用调试模式brother_ql_debug 分步指令 ⚙️LED 闪烁又查不出原因时用调试工具一条指令一条指令地喂给打印机每发一条打印机就回一帧应答能精确定位是哪条指令触发了报错brother_ql_debug my_label.bin /dev/usb/lp0它随包安装pip install brother_ql即可输出节选自LEGACY.md第 125-131 行INFO: Response from the device: 80 20 42 30 4F 30 00 00 00 00 3E 0A 00 00 15 00 00 00 06 01 00 00 00 00 00 00 00 00 00 00 00 00 INFO: Interpretation of the response: Phase change (phase: Printing state), Continuous length tape 62x0 mm^2, errors: []对照第 2 节的结构表逐字节解读字节 8/9 00 00无错误→ 字节 10 3E即 62mm 带宽 → 字节 11 0A连续带 → 字节 18 06Phase change → 字节 19 01Printing state。加上--interactive参数还可以逐条确认发送详见LEGACY.md的 Debug 章节。6. 排错指南30 秒定位常见故障 ⚠️现象优先检查errors 含No media when printing是否未装带、传感器被遮挡errors 含Tape cutter jam切刀处是否有碎屑卡住errors 含Replace media error标签类型与指令不匹配黑红带漏加--red是典型原因errors 含Transmission / Communication errorUSB 连接不稳可加--sleep-time放慢发送迟迟等不到Printing completed--model选错打印机不认该机型指令README.md中列出的 LED 闪烁三大主因——标签不匹配、用尽、不支持的 opcode——都能在这张错误码表里一一对上号。7. 相关源文件位置一览 文件职责brother_ql/reader.py应答帧解析核心错误码表、状态/相位定义、interpret_response()brother_ql/brother_ql_debug.py逐条调试工具逐指令打印应答解读brother_ql/backends/helpers.py阻塞式发送依据应答帧判定成功/失败brother_ql/cli.py新版命令行入口print / send / analyze / discoverLEGACY.md遗留工具文档含完整调试输出示例读懂这 32 字节应答帧之后打印机的 LED 就不再是黑箱了。下次再遇到打印失败先跑一遍调试工具看错误码——答案往往就明明白白写在第 8、9 字节里。✅【免费下载链接】brother_qlPython package for the raster language protocol of the Brother QL series label printers (QL-500, QL-550, QL-560, QL-570, QL-700, QL-710W, QL-720NW, QL-800, QL-810W, QL-820NWB, QL-1050, QL-1060N and more).项目地址: https://gitcode.com/gh_mirrors/br/brother_ql创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考