跳到内容

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 扫描器

  1. 连接扫描器,并确认它处于 keyboard wedge 模式。当该编辑器中的字段拥有焦点时,文本编辑器应当收到字符。
  2. 打开条码输入测试器。
  3. 点击 Start Test,或点击扫描区域。就绪时它会变成蓝色。页面不会自己取得焦点。
  4. 扫描一条你已经知道有效载荷的条码。
  5. 把捕获到的值和字符数与该有效载荷比较。
  6. 读取后缀:ENTER、TAB 或 None。Enter 和 Tab 不属于条码字符串。

测试器记录浏览器能看到的键盘事件。它不能读取串口,也不能识别 USB 设备。当字符之间的平均间隔低于 100 ms 时,它报告该时序。时序不是硬件识别。对每一次 keydown,包括 key 和 code,使用键盘事件测试器。更广的 QA 流程见如何测试条码扫描器输入。

测试串口扫描器

条码输入测试器不会打开 COM 端口。串口测试需要一个能够打开扫描器所暴露端口的程序。

  1. 确认扫描器处于串口模式,并且连接时操作系统会列出一个端口。拔掉它,检查端口是否消失。
  2. 记下端口名。它依操作系统而异,下次插入时可能改变。
  3. 从兼容的应用打开端口:串口终端、你的桌面应用,或在 HTTPS 或 localhost 上的 Chromium 浏览器中使用上面的 Web Serial 示例。
  4. 手册指定时,设置波特率、数据位、奇偶校验和停止位。跳过编造的值。
  5. 扫描一条已知条码。
  6. 把字节或解码文本与该有效载荷比较。
  7. 检查分帧。仅当手册如此配置时,才查找前缀,以及数据之后的 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 枚举或光学解码。这些行为仍然属于硬件,或属于你自己控制的串口测试替身。