brother_ql 故障排查指南：LED 闪灯诊断、analyze 反编译与 USB 逐条指令调试

brother_ql 故障排查指南：LED 闪灯诊断、analyze 反编译与 USB 逐条指令调试

【免费下载链接】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

本文围绕开源 Python 项目brother_ql展开，带你排查 Brother QL 系列标签打印机的故障：看懂 LED 指示灯、用 analyze 命令"反编译"标签指令文件、再用 USB 逐条指令调试抓出真正的问题所在。无需打印驱动，一套流程即可定位绝大多数打印失败的原因。

brother_ql 是一个直接实现 Brother QL 打印机**光栅语言（Raster Language）**的 Python 包，支持 QL-500、QL-550、QL-710W、QL-820NWB、QL-1100 等型号。它绕开系统打印驱动直接与打印机通信，因此一旦出问题，排查思路也要"绕开驱动"——直接看协议层面的数据。

1️⃣ 第一步：看懂 Brother QL 的 LED 指示灯

在动任何命令之前，先观察打印机的指示灯，这是最快的"免费诊断"。

• Editor Lite 灯常亮：如果你的机型带 "Editor Lite" 模式，该 LED 亮起时USB 打印会被打印机自身占用，任何软件都无法通过 USB 发送指令。解决方法很简单：长按打印机按键直到该灯熄灭。这是很多"突然不能打印"案例的第一原因。
• 打印中闪灯 / 蜂鸣：通常对应卡纸、缺带、切刀故障等硬件状态。QL 打印机支持自动状态回传，它会把具体错误通过 USB 发回主机，brother_ql可以直接解读（见下文第 4 节），不需要靠猜。

💡 小建议：每次故障复现时，先记下 LED 的状态（常亮/闪烁/熄灭）和出带情况，再进入下一步。

2️⃣ 第二步：确认软件能否"看见"打印机

排查顺序应该是：先确认连接层没问题，再怀疑数据层。

用 discover 探测设备（跨平台，基于 pyusb）：

brother_ql -b pyusb discover

输出中会列出打印机标识符，形如usb://0x04f9:0x2015/000M6Z401370。这个标识符要记住，后面调试会用到。设备枚举逻辑位于 brother_ql/backends/pyusb.py。

用 info env 导出环境信息：

brother_ql info env

它会打印操作系统、Python 版本、brother_ql 版本以及各依赖包的安装情况（实现见 brother_ql/cli.py）。遇到问题时，这份输出是定位"环境类故障"的关键证据。

常见"看不见打印机"的原因：

现象	可能原因	检查点
discover 无输出	Editor Lite 灯亮	长按按键关灯
discover 无输出	libusb 未安装	Linux 安装libusb-1.0-0，macOS 用 Homebrew 安装 libusb
只有部分指令卡住	内核驱动抢占	Linux 下/dev/usb/lp0属主不对，见 brother_ql/backends/linux_kernel.py
完全无响应	型号未指定	用-m指定如QL-710W

⚠️ 注意：network 后端（TCP）不支持读取打印机状态回传，"缺带""标签类型错误"等故障在网络模式下感知不到。要做状态级排查，请使用 USB 连接。

3️⃣ 第三步：用 analyze 命令"反编译"标签文件

打印失败有两种可能：发出去的内容本身是错的，或者传输过程出了问题。analyze命令解决前者——它把一个二进制光栅指令文件（.bin/指令文件）还原成 PNG 图片，让你直观看到打印机"将会打印什么"。

brother_ql analyze mylabel.bin

执行后会在当前目录生成label0001.png、label0002.png……（双色的 QL-8xx 机型会叠加红色通道）。它的核心是 brother_ql/reader.py 中的BrotherQLReader类：逐条解析指令流，还原 raster 行数据、反压缩、再转成位图。

排查价值：

• 图片尺寸/内容与预期不符 → 创建阶段的问题（图片缩放、型号/标签参数配错）；
• analyze 报unknown opcode警告 → 指令文件可能损坏或版本不匹配；
• analyze 完全正常，但打出来是空白 → 问题在传输/打印端，进入第 4 节。

你也可以用-f选项自定义输出文件名格式，例如-f page_{counter:02d}.png。

4️⃣ 第四步：USB 逐条指令调试（杀手锏）

当传输层出问题（中途卡住、只打出一半、状态码报错）时，brother_ql/brother_ql_debug.py 提供的调试器是终极手段。它会把指令文件切成一条条光栅指令，逐条发送、逐条读取并解读打印机响应，日志长这样：

INFO: CMD init FOUND. Instruction: 1B 40 INFO: Response from the device: 80 20 42 01 00 ... INFO: Interpretation of the response: 'Error occurred' (phase: 'Printing state')

基本用法（以 Linux 为例，设备为/dev/usb/lp0）：

python -m brother_ql.brother_ql_debug mylabel.bin /dev/usb/lp0 --debug

推荐组合的"排查参数"：

参数	作用	何时用
--interactive	每条指令发送前暂停，等待你回车	想精确定位"哪一条开始出错"
--sleep-time 0.5	两条指令之间插入 0.5 秒延时	疑似打印机来不及响应（缓冲区溢出）
--sleep-before-read 0.2	读取响应前等待	响应偶发读不到时
--split-raster	不合并 preamble/raster 大指令，逐条发送	怀疑某类长指令导致卡死
--continue-reading-for 5	最后一条指令后继续监听 5 秒	打印完成后观察延迟状态包

响应解读逻辑在 brother_ql/reader.py 的interpret_response函数中：它把 29 字节的回传包逐字节拆成状态类型、阶段、介质宽度和错误位图，直接把十六进制变成人话。

5️⃣ 常见错误码速查表

brother_ql对打印机回传的错误位做了完整映射（来源：brother_ql/reader.py 中的RESP_ERROR_INFORMATION_1_DEF/RESP_ERROR_INFORMATION_2_DEF）：

错误信息	含义	典型处理
No media when printing	打印时无介质	装带 / 检查带座
End of media (die-cut size only)	预裁标签用尽	更换标签卷
Tape cutter jam	切刀卡住	断电后清理切刀区域
Replace media error	需要更换介质	重新装带
Transmission / Communication error	传输/通信错误	换 USB 口、缩短线缆、加大--sleep-time
Cover opened while printing	打印时开了盖	重新合盖
Media cannot be fed	介质无法走带（含带尾检测）	检查是否装反/打滑
System error	系统错误	断电重启打印机

如果调试日志里出现Errors occured: ['...']，直接对照上表即可，无需再猜。

6️⃣ 故障排查总流程（30 秒版）

1. 看灯：Editor Lite 灯亮？长按按键熄灭它；
2. 探设备：brother_ql -b pyusb discover能否列出打印机？
3. 验内容：brother_ql analyze mylabel.bin生成的图片是否符合预期？
4. 逐条调试：brother_ql_debug+--interactive定位出错指令与错误码；
5. 对表处理：按第 5 节错误码表解决硬件/通信问题。

整个过程中用到的代码模块集中在 brother_ql/reader.py（协议解读）、brother_ql/brother_ql_debug.py（调试器）、brother_ql/backends/（pyusb / network / linux_kernel 三种后端）以及 brother_ql/cli.py（命令行入口）。遇到包层面的异常，可参考 brother_ql/exceptions.py 中定义的BrotherQLError等异常类。

🎯 掌握"看灯 → 探设备 → analyze 验内容 → 逐条指令调试"这条链路后，绝大多数 Brother QL 打印故障都能在不重装驱动、不盲目重启的情况下被精准定位。

【免费下载链接】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