Citizen 标签打印机 USB 连接扫描器直接打印（直接打印+CSV检索打印）

核心原理：Standalone Forms（独立表单），打印机模拟器必须切到 DMI（Datamax 仿真），USB Host 口接 USB HID 键盘模式扫描枪，扫码后自动把扫码数据填入模板变量、出标签；不需要上位机持续运行。 两种模式： 1）直接填入打印（简单场景）：扫码数据直接打印到标签模板变量； 2）CSV 查找打印（数据库场景）：扫码内容作为 KEY，在打印机内部存储的 CSV 检索整行数据回填模板多字段。

一、硬件选型

1. 扫描枪：USB HID Keyboard Wedge 键盘模式（必须，打印机 USB Host 只识别 HID 键盘扫描枪；不要 USB 虚拟串口、不要 COM 口扫描枪）
2. • 扫描枪配置：关闭前缀后缀，或者固定只加回车；不要多余控制码。
3. U 盘（导入模板 + CSV 用）：≤32GB，FAT32；根目录新建文件夹 _CLS，模板、CSV 文件放里面；U 盘仅导入阶段临时使用，导入完成后 U 盘可以拔除。不能用 USB Hub，直接直插打印机前面板 USB Host。
4. 打印机：CL-S700III，CL-S703III，CL-S700IIIR，升级最新固件；在触摸屏设置，模拟器切换为 DMI（Standalone 功能仅 DMI 启用）。

二、开发工具：Label Layout Editor

这是唯一用来制作 Standalone 模板的工具，配套 Layout SDK；不是 BarTender，BarTender 不能输出 Standalone 表单。

• 模板设计要点：
• • 在标签上放置可变字段（变量），变量用于接收扫描枪读入的条码字符串。
  • 模式 A（简单扫码打印）：1 个变量，扫码内容直接映射到此文本 / 条码对象。
  • 模式 B（CSV 检索）：定义查找键变量，模板绑定 CSV 字段映射关系。
• 导出：保存为 Standalone 表单文件，放到 U 盘_CLS目录，CSV 文件一并放在该目录，一起导入打印机闪存。

三、部署流程

1. 电脑端用 Label Layout Editor 设计标签模板，定义接收扫码数据的变量。
2. U 盘建立_CLS文件夹，放入模板文件和对应的_xxx.csv。
3. U 盘插入打印机 USB Host，进入打印机菜单：独立打印 → 导入模板，表单连同 CSV 数据一起存入打印机闪存。导入完成后，可以拔掉 U 盘。
4. 打印机模拟器设置：系统设置 → 模拟器 → DMI（关键，不切 DMI Standalone 不生效）。
5. 扫描枪直插打印机前面 USB Host；打印机屏幕 USB Host 图标亮起，识别成功。
6. 触摸屏选择加载好的 Standalone 表单，进入待机扫码状态。
7. 扫描条码 → 打印机捕获 HID 扫描字符串 → 在本机闪存内的 CSV 检索 KEY，填入模板变量 → 自动打印标签。

四、两种业务模式详细说明

模式 1：扫描数据直接打印（无需 CSV）

• 逻辑：扫描枪输出字符串，直接替换模板内定义的占位变量，扫一次打一张。
• 适用：仅打印条码号、序列号，不需要多字段关联。
• 模板：只需要 1 个输入变量，绑定标签上的条码 / 文本。

模式 2：CSV 文件检索打印（多字段）

• 逻辑：扫描得到_KEY，读取打印机闪存内部预导入的 CSV查找匹配行，把该行多列字段填入模板多个变量。

U 盘仅用于导入，导入完成即可移除，USB Host 端口留给扫描枪。 CSV 文件规范（LayoutSDK）：

• 文件格式为 CSV，编码 UTF-8，可带或不带 BOM，逗号作为分隔符，列内部不能存在换行
• 文件最大 1MB
• 单条记录最大 2048 字节，包含逗号
• 检索依据：每条记录的第一列作为检索关键字 CSV 格式样例（无表头）：

SN001,零件A,20*30,100
SN002,零件B,50*80,20

模板绑定：第一列为扫码检索 KEY；后续列_name/_spec/_qty映射标签其他字段。 扫码_SN001，自动读取闪存内 CSV 对应整行全部字段打印。

五、打印机菜单关键参数

1. 模拟器：DMI
2. Standalone 打印：启用，选择已导入表单
3. USB 主机：启用；不使用集线器
4. 介质传感器（标签间隙 / 黑标）按你的标签类型校准
5. 可选：切刀 / 剥纸器，打印后自动剥离

六、限制 & 坑点（开发重点）

1. 扫描枪必须 HID 键盘模式：虚拟串口 USB 扫描枪不识别；部分工业枪出厂是串口协议，必须扫配置码切 Keyboard Wedge。
2. 模拟器 DMI 强制：ZPL 仿真模式下 Standalone 表单功能不可用。
3. U 盘限制：FAT32、≤32GB；加密 U 盘、NTFS/exFAT 无法识别，仅用于导入。
4. 字符集：CSV 编码使用 UTF-8（可带 BOM 或不带 BOM），不要 GBK 编码。
5. 没有自定义脚本：不能在打印机内写 JS/Python 逻辑；业务逻辑只能是【扫码填入】或【扫码 + CSV 查找】，复杂业务要上位机。
6. 多模板切换：打印机可存储多个 Standalone 表单，触摸屏手动切换。
7. CSV 检索补充限制：CSV 是顺序遍历查找，不是索引查询；数据量越大扫码等待时间越长。文件上限固定为 1MB，单行记录最大 2048 字节（包含逗号），不支持表头，检索固定取每行第一列作为查找 KEY，字段内部不能包含换行。超出限制会导入失败或检索异常。

七、二次开发扩展方案（如果内置 Standalone 不够）

1. Layout SDK：可以程序自动生成 Standalone 表单文件，批量下发到多台打印机（Windows/Android SDK）。
2. 如果需要复杂校验、数据库、网络查询：不使用 USB Host 扫描枪，改用上位机 + TCP/USB 通信，扫描枪接电脑，上位机下发 DMI/ZPL 指令打印。
3. 触发信号：可搭配剥纸 / 切刀信号，做自动流水线联动。

八、快速调试步骤

1. 先确认模拟器切 DMI，导入模板 + CSV 成功，导入后拔掉 U 盘。
2. 扫描枪插电脑记事本扫码，确认输出干净字符串（无多余乱码），确认是 HID 键盘。
3. 扫描枪插到打印机 USB Host，屏幕 USB 图标出现。
4. 进入独立表单，扫码测试；无输出：
5. • 检查扫描枪是否带回车；
   • 确认模板变量绑定正确；
   • 确认打印机固件版本；
   • 确认 CSV 符合 SDK 规范：UTF-8，无表头，每行不超 2048 字节，首列为检索 KEY，字段内无换行。