USBScaner

插件用途

在 Windows 网关主机上监听以键盘方式输入的 USB 扫码器，并把一次完整扫码结果更新为设备变量值。适用于扫码器作为 HID 键盘输入、且 GatewayRuntime 与扫码器位于同一台 Windows 主机的场景。

使用限制

该插件监听当前 Windows 会话中的全局键盘输入，不能区分扫码器和普通键盘。扫码器应连接到运行 GatewayRuntime 的同一台主机，并配置为在条码末尾发送 Enter。启用插件时不要在该会话中输入密码或其它敏感内容。

选择入口

进入“开发配置 → 采集配置”，创建设备并在“采集插件”中选择“USBScaner”。

支持的通道和数据类型

通道类型	配置前检查
Other（无需公共通道）	仅支持 Windows。确认扫码器以键盘方式输入，并连接到运行 GatewayRuntime 的主机。

可选数据类型： 对象。扫码完成后，变量值显示为本次条码文本。

插件参数

该插件没有专属设备参数，不需要配置 TCP、UDP、串口或 USB 设备标识。普通键盘输入也会进入同一监听范围，因此建议在专用 Windows 会话中运行。

地址规则

• 变量地址留空；该插件不读取外部寄存器。
• 扫码器必须在条码末尾发送 Enter，插件收到 Enter 后才把此前连续输入识别为一次完整扫码。
• 插件只接收输入，不支持主动读取、变量写入或特殊方法。
• 同一设备通常只创建一个扫码结果变量，避免多个变量保存相同条码后产生歧义。

设备调试

进入“开发配置 → 采集配置”，切换到“设备显示”，选择当前 USBScaner 设备后打开“调试 → 协议调试 · ScanMonitor”。

功能	作用
最后活动时间	判断是否收到新的扫码输入。
变量表格	查看变量名称、当前值、在线状态、采集时间和最近错误。
消息统计	查看待推送、丢弃、截断和单条消息大小等诊断数据。
消息日志	观察当前调试会话收到的扫码消息。

下图展示 ScanMonitor 中统计、变量和消息日志的位置。现场完成一次扫码后，应在这些区域看到新的活动时间、条码值或消息记录。

验证重点

1. 在 USBScaner 设备下创建并启用一个变量，变量地址留空。
2. 打开“协议调试 · ScanMonitor”，记录当前最后活动时间和变量值。
3. 使用扫码器扫描一个专用测试条码，例如 TG-USB-001。
4. 确认最后活动时间更新，变量当前值变为 TG-USB-001，采集时间同步更新且最近错误为空。
5. 再扫描一个不同条码，确认变量值被新的完整条码替换，而不是与上一次结果拼接。

排障差异

• 设备始终离线：确认 GatewayRuntime 运行在 Windows，且键盘钩子已成功启动；查看设备日志中的钩子启动错误。
• 扫码后没有新记录：确认扫码器连接到 GatewayRuntime 所在主机，并以键盘方式输入；使用文本编辑器验证扫码器会在条码末尾发送 Enter。
• 普通键盘文字被识别为条码：该插件监听全局键盘输入，无法按 USB 设备区分来源；请使用专用会话，避免在插件运行期间进行普通文本输入。
• 作为 Windows 服务运行时收不到扫码：Windows 服务与交互桌面处于不同会话。需要扫码输入时，应让 GatewayRuntime 运行在实际接收扫码键盘事件的 Windows 用户会话中。
• 条码被截断或拆分：检查扫码器字符发送间隔和结束符设置，确保字符连续发送并以 Enter 结束。

相关操作

• 采集配置：查看通道、设备和公共变量配置。
• 插件索引：查找其它采集或数据转发插件。