Barcode Scanner Emulator
USB HID 与串口条码扫描器
USB HID keyboard wedge 扫描器把解码后的条码键入拥有焦点的应用。USB 串口扫描器暴露一个串行接口,通常显示为虚拟 COM 端口,应用必须打开该端口并读取字节。USB 是线缆和总线。HID 与串口是呈现数据的两种不同方式。
选择应用真正能读到的接口。已经接受键入的结账字段,是 keyboard wedge 问题。必须在没有文本字段获得焦点时收到扫描,或必须把扫描器字节与键盘分开的服务,是串口问题。许多扫描器只提供其中一种模式。有些可以切换。该型号的手册就是你能测试的模式清单。
HID keyboard wedge 说明详细说明按键路径。条码扫描器如何工作?涵盖采集与解码。本页比较两种主机接口,以及各自对应的测试。
什么是 USB HID keyboard wedge 模式?
在 USB HID 键盘模式下,扫描器枚举为键盘。操作系统加载它的普通键盘驱动程序。解码之后,扫描器把字符作为按键发给当前拥有键盘焦点的控件。网页表单、POS 商品字段或桌面文本框都可以接受这份输入,不需要扫描器专用代码。
焦点决定目的地。预定字段没有焦点时,字符会落入另一个控件,或者丢失。扫描器不会点击,也不会移动指针。
配置好的后缀可能跟在有效载荷后面。Enter 会提交许多单字段表单。Tab 把焦点移到下一个控件。这两个键都没有保证。后缀的选择见条码扫描器中的 ENTER 与 TAB 后缀。
普通键盘事件不包含扫描器的厂商、序列号,也不包含说明这些键来自扫描器的标志。实现了 WebHID 的浏览器仍然拒绝键盘接口,因此页面不能打开 wedge 设备并读取原始 HID 报告。
什么是 USB 串口条码扫描器模式?
在 USB 串口模式下,扫描器不键入。它通过 USB 暴露一个串行接口。操作系统通常把该接口显示为虚拟 COM 端口:Windows 上是 COM 名称,macOS 上是 cu 或 tty 设备,Linux 上是 ttyACM 或 ttyUSB 设备。名称由驱动程序分配,扫描器拔出后可能改变。
虚拟 COM 端口不是物理 RS-232 端口。RS-232 是电气接口,有自己的连接器和电平,计算机通过 UART 读取。USB 串口使用 USB 线缆。应用仍然打开串口并读取字节,但线上的信号是 USB。有些产品是真正的 RS-232 扫描器再加上 USB 转串口适配器。另一些实现 USB CDC,完全不说 RS-232。把操作系统显示给你的端口当作集成点,不要假定电气细节一致。
应用打开端口,读取字节流,并决定一条消息从哪里开始、到哪里结束。常见帧是条码文本后面跟着 CR(0x0D)、LF(0x0A),或先 CR 再 LF。这种分帧是设备设置,不是 USB 的规则。STX 这样的前缀字节也有可能。条码扫描器前缀与后缀:完整指南把这些字节与 wedge 扫描器发送的 Enter 键分开说明。
波特率、数据位、奇偶校验和停止位在真实 UART 以及许多 USB 转串口适配器上有意义。速率错误产生的是乱码,而不是干净的错误。有些 USB CDC 虚拟 COM 设备会忽略主机请求的波特率,仍然送出字节。没有一套设置适合每一台虚拟串口扫描器。使用该型号手册中的速率和分帧,再用已知条码确认。
保持端口打开的进程收到数据。键盘焦点不选择目的地。已经打开该端口的另一个程序会挡住第二次打开。拔掉扫描器会移除端口。插回去可能产生新名称,应用必须再次打开那个端口。
HID 与串口
| 特性 | HID keyboard wedge | USB 串口 |
|---|---|---|
| 数据送达 | 键盘式输入 | 串口字节流 |
| 是否需要输入焦点 | 需要。按键跟随拥有焦点的控件 | 不需要。字节进入打开了端口的进程 |
| 浏览器集成 | 普通输入和键盘事件 | 浏览器支持时用 Web Serial,否则用页面之外的软件 |
| 应用控制 | 限于键盘行为、焦点和后缀 | 应用读取并分帧该数据流 |
| 设备识别 | 普通键盘事件提供不了 | 操作系统可以显示端口名。稳定身份仍取决于驱动程序 |
| 配置 | 扫描器设置,包括后缀和键盘布局 | 扫描器设置,加上设备实际使用的主机端口设置 |
| 典型用途 | 表单和 POS 商品录入 | 独占设备的专用集成 |
这些是常见情况。具体型号、操作系统和驱动程序可能不同。处于 HID 键盘模式的 Bluetooth 扫描器,在应用层遵循 wedge 这一列。Bluetooth SPP 遵循串口这一列。
HID 扫描器在 Web 应用中如何工作
一次 wedge 扫描会更新拥有焦点的元素。可打印字符先触发 keydown,再触发 input。Enter 和 Tab 触发 keydown,不会向普通文本输入插入字符。这些键的 event.key 是 "Enter" 或 "Tab",可打印字符则是一个单字符字符串。event.code 命名物理键,键盘布局不匹配改变 event.key 时,它仍可能保持不变。
下面的监听器只在 Enter 到达时提交字段。没有 Enter 后缀的扫描器会把文本留在字段里。
const field = document.querySelector('#barcode')
if (!(field instanceof HTMLInputElement)) {
throw new Error('Barcode field was not found.')
}
field.addEventListener('keydown', (event) => {
if (event.key !== 'Enter') {
return
}
event.preventDefault()
const value = field.value.trim()
if (!value) {
return
}
console.log(value)
field.value = ''
})
扫描前先聚焦 #barcode。preventDefault() 防止父表单再提交一次。如果扫描器改发 Tab,就在那次 keydown 中读取值,并让浏览器移动焦点。如果两者都不发,就用按钮或其他明确操作提交字段。键入中的停顿只是判断扫描结束的启发式方法。
这些事件里没有任何内容能识别 USB 设备。人、宏或模拟器都能产生同样的序列。校验属于有效载荷。包括 Tab 和空输入在内的浏览器流程,见如何在 Web 应用中测试条码扫描器。
串口扫描器在应用中如何工作
串口集成要打开端口、读取字节、把字节拆成消息,并处理端口消失。在桌面上,这是操作系统的串口 API 或厂商库。在浏览器里,唯一的内置选项是 Web Serial API,而且只存在于实现了它的浏览器。
Web Serial 可在基于 Chromium 的浏览器中使用。Firefox 和 Safari 不提供它。页面必须处于安全上下文,也就是 HTTPS 或 localhost。requestPort() 必须从用户手势运行,用户必须在浏览器提示中选择端口。keyboard wedge 扫描器不会出现在该列表中,因为它不是串口设备。操作系统没有暴露的串口,Web Serial 也看不到。
示例中的波特率是起点,应换成手册中的值。循环把 CR 或 LF 当作消息结束,并把一对 CRLF 当作一个终止符消耗。如果扫描器使用不同的帧,即使端口已经打开,这种拆分也是错的。
<button id="open-serial" type="button">Open scanner port</button>
<p id="status" role="status"></p>
<script>
const button = document.querySelector('#open-serial')
const status = document.querySelector('#status')
function takeLine(buffer) {
const cr = buffer.indexOf('\r')
const lf = buffer.indexOf('\n')
const end = cr < 0 ? lf : lf < 0 ? cr : Math.min(cr, lf)
if (end < 0) {
return null
}
const line = buffer.slice(0, end).trim()
let rest = buffer.slice(end + 1)
if (buffer[end] === '\r' && rest.startsWith('\n')) {
rest = rest.slice(1)
}
return { line, rest }
}
button.addEventListener('click', async () => {
if (!('serial' in navigator)) {
status.textContent = 'This browser does not provide Web Serial.'
return
}
let port
try {
port = await navigator.serial.requestPort()
await port.open({ baudRate: 9600 })
} catch (error) {
status.textContent = 'The port was not opened.'
return
}
const reader = port.readable.getReader()
const decoder = new TextDecoder()
let buffer = ''
try {
while (true) {
const { value, done } = await reader.read()
if (done) {
break
}
buffer += decoder.decode(value, { stream: true })
let next = takeLine(buffer)
while (next) {
if (next.line) {
status.textContent = next.line
}
buffer = next.rest
next = takeLine(buffer)
}
}
} catch (error) {
status.textContent = 'The serial read stopped.'
} finally {
reader.releaseLock()
await port.close()
}
})
</script>
读取循环一直运行,直到流结束或读取失败。拔掉扫描器通常会使读取被拒绝。releaseLock() 和 close() 在 finally 中运行。此来源先前批准的端口可以用 navigator.serial.getPorts() 列出,不必再次显示提示。第一次批准仍然需要用户。
桌面应用用平台串口 API 遵循同样的思路:打开、读取、分帧,设备回来后再打开。本页不编造厂商命令。如果扫描器期望专有协议,该协议在制造商的文档里。
HID 和串口哪个更好?
没有一种模式对每个产品都更好。使用扫描器实际提供的模式,以及应用能够读取的模式。
在这些情况下选择 HID
- 应用已经在拥有焦点的字段中接受键盘输入。
- 你希望表单或 POS 画面在没有设备代码的情况下工作。
- 工作流可以在每次扫描前保证焦点。
- Enter 或 Tab 与该表单提交或前进的方式一致。
在这些情况下考虑串口
- 焦点在对话框、按钮上,或根本没有焦点时,扫描也必须到达。
- 扫描器字节必须与键入保持分离。
- 应用能够打开端口、给消息分帧,并在设备被拔出后恢复。
- 主机可以授予该端口的权限,并且没有其他进程同时需要它。
只枚举为键盘的扫描器,不能在主机软件里切换成串口。设计集成之前,先在手册中确认模式。
在 HID 与串口之间切换
有些扫描器在你扫描该制造商手册中的配置条码时改变模式,或者在你用厂商工具写入配置文件时改变模式。另一些只做成一种接口,没有可切换的内容。
没有一条配置条码能改变所有品牌。为另一型号印出的序列可能什么也不做,也可能把扫描器留在意外的模式。任何更改之后,检查操作系统显示的是什么:键盘、COM 端口,或两者都有。然后测试应用实际使用的路径。条码扫描器配置指南描述常见的设置分组。它不能代替手册。
测试 HID 扫描器
- 连接扫描器,并确认它处于 keyboard wedge 模式。当该编辑器中的字段拥有焦点时,文本编辑器应当收到字符。
- 打开条码输入测试器。
- 点击 Start Test,或点击扫描区域。就绪时它会变成蓝色。页面不会自己取得焦点。
- 扫描一条你已经知道有效载荷的条码。
- 把捕获到的值和字符数与该有效载荷比较。
- 读取后缀:ENTER、TAB 或 None。Enter 和 Tab 不属于条码字符串。
测试器记录浏览器能看到的键盘事件。它不能读取串口,也不能识别 USB 设备。当字符之间的平均间隔低于 100 ms 时,它报告该时序。时序不是硬件识别。对每一次 keydown,包括 key 和 code,使用键盘事件测试器。更广的 QA 流程见如何测试条码扫描器输入。
测试串口扫描器
条码输入测试器不会打开 COM 端口。串口测试需要一个能够打开扫描器所暴露端口的程序。
- 确认扫描器处于串口模式,并且连接时操作系统会列出一个端口。拔掉它,检查端口是否消失。
- 记下端口名。它依操作系统而异,下次插入时可能改变。
- 从兼容的应用打开端口:串口终端、你的桌面应用,或在 HTTPS 或 localhost 上的 Chromium 浏览器中使用上面的 Web Serial 示例。
- 手册指定时,设置波特率、数据位、奇偶校验和停止位。跳过编造的值。
- 扫描一条已知条码。
- 把字节或解码文本与该有效载荷比较。
- 检查分帧。仅当手册如此配置时,才查找前缀,以及数据之后的 CR、LF 或 CRLF。
如果因为端口正忙而打开失败,关闭占用它的另一个程序。如果文本是乱码,线路设置与设备不符。如果端口始终不出现,扫描器可能仍处于键盘模式,驱动程序可能缺失,或者该 OS 用户可能不被允许打开串口设备。
常见问题
扫描器在文本编辑器里可用,在目标应用里不可用。 设备正在键入。目标没有焦点,或者某个 keydown 监听器丢掉了这些键。从扫描器在 Notepad 中可用但在 POS 中不可用开始。
扫描器不向任何文本字段键入。 它可能处于串口模式、已关机,或没有读到符号。串口模式的扫描器不会键入。调试字段之前先检查 COM 端口。条码扫描器不工作把坏掉的扫描器与错误的接口分开。
串口缺失。 键盘模式不会创建 COM 端口。缺少驱动程序、仅充电的线缆,或没有串口模式的扫描器,会产生同样的现象。插入扫描器时观察操作系统的设备列表。
串口已被占用。 只有一个进程能读取它。关闭终端或应用的另一份副本,然后再次打开。
通信设置错误。 波特率、奇偶校验或停止位不匹配,看起来像随机字符。按该型号手册设置这些值,然后再次扫描已知码。
ENTER 或 TAB 始终不到达。 这是 wedge 后缀设置。输入测试器会报告 None。参见条码扫描器缺少 ENTER以及上文链接的后缀指南。串口扫描器不发送 Enter 键。它可能改为发送 CR 或 LF 字节。
wedge 扫描器上的字符不对。 扫描器的键盘布局与操作系统布局可能不一致。串口字节不会被该布局重新映射。参见条码扫描器键盘布局错误。
浏览器无法访问扫描器。 wedge 扫描器不会出现在 Web Serial 提示中。Firefox 和 Safari 没有 Web Serial API。不是 HTTPS 或 localhost 的页面不能使用它。用户也可以关掉端口提示。
拔出之后应用丢失扫描器。 wedge 扫描器会作为键盘回来,下一次扫描仍然需要焦点。串口会消失,直到应用打开新端口。名称可能与上一次不同。
集成场景
Web 应用
keyboard wedge 适合拥有焦点的输入和普通 DOM 事件。页面内部的串口访问意味着:支持该能力的浏览器中的 Web Serial、安全上下文,以及用户选择的端口。必须支持 Firefox、Safari 和无人值守自助终端的页面,不能只依赖 Web Serial。本地辅助程序可以拥有 COM 端口,并把完整条码转发给页面。该辅助程序是独立软件。页面仍然不应指望一次 wedge 测试去覆盖它。
POS 系统
把焦点放在商品字段并在 Enter 时提交的 POS,是 wedge 集成。必须在模态框打开时扫描,或必须忽略键盘的 POS,是串口集成。把两者混在一起,扫描会进错字段,或者永远不到达。把扫描器模式与实际值班的画面匹配。
桌面应用
桌面应用可以在拥有焦点的控件中接受 wedge 输入,也可以打开虚拟 COM 端口,并在进程存续期间保持会话。端口所有权、重新连接和分帧属于该会话。焦点不属于。
QA 自动化
Barcode Scanner Emulator把你选择的值键入拥有焦点的应用,并能发送 ENTER、TAB 或不发送后缀。这覆盖 keyboard wedge 回归:焦点、校验和后缀处理。它不创建虚拟 COM 端口,不枚举 USB 设备,也不复现波特率和分帧。串口测试仍然需要串口和读取程序,或者一个写出与应用所解析的相同字节分帧的测试替身。
自助终端应用
使用 wedge 输入的自助终端必须在对话框、屏幕保护和错误消息之间保持扫描字段的焦点。一次失去焦点,下一次扫描就会命中快捷键,或者什么也命不中。使用串口的自助终端可以不依赖该焦点来读取端口,并且必须保有设备权限,在断电或线缆被拔出后重新打开端口。
Barcode Scanner Emulator 适合放在哪里
Barcode Scanner Emulator是面向 Windows、macOS 和 Linux 的桌面应用。它复现 wedge 扫描器使用的键盘路径。你输入文本,选择键入延迟,并选择后缀为无、ENTER 或 TAB。全局快捷键把该文本键入拥有焦点的应用。
扫描器不在桌上时,用它开发和回归 HID 式表单。把它与条码输入测试器配合,查看浏览器收到的值、前缀键和后缀。
它不模拟 USB 串口设备、虚拟 COM 端口、USB 枚举或光学解码。这些行为仍然属于硬件,或属于你自己控制的串口测试替身。