Barcode Scanner Emulator
USB HID и последовательные сканеры штрихкодов
Сканер USB HID в режиме клавиатурного клина вводит декодированный штрихкод в приложение с фокусом. Последовательный сканер USB открывает последовательный интерфейс, часто как виртуальный порт COM, и приложение должно открыть этот порт и прочитать байты. USB — это кабель и шина. HID и последовательный режим — разные способы представить данные.
Выбирайте интерфейс, который приложение действительно умеет читать. Поле на кассе, которое уже принимает набор, — задача клавиатурного клина. Служба, которая должна получать сканирования, когда ни одно текстовое поле не в фокусе, или которая должна держать байты сканера отдельно от клавиатуры, — последовательная задача. Многие сканеры предлагают только один из этих режимов. Некоторые умеют переключаться. Руководство к этой модели — список режимов, которые можно проверить.
Руководство Клавиатурный клин HID подробно объясняет путь нажатий. Как работают сканеры штрихкодов? разбирает захват и декодирование. Эта страница сравнивает два интерфейса на стороне компьютера и проверки, которые относятся к каждому.
Что такое режим клавиатурного клина USB HID?
В режиме клавиатуры USB HID сканер перечисляется как клавиатура. Операционная система загружает свой обычный драйвер клавиатуры. После декодирования сканер отправляет символы нажатиями клавиш в тот элемент, у которого фокус клавиатуры. Веб-форма, поле позиции в POS или текстовое поле на рабочем столе принимают этот ввод без кода, написанного специально для сканера.
Фокус решает, куда попадут символы. Если нужное поле не в фокусе, символы попадают в другой элемент или теряются. Сканер не щёлкает и не двигает указатель.
За полезной нагрузкой может идти настроенный суффикс. Enter отправляет многие формы с одним полем. Tab переносит фокус на следующий элемент. Ни одна из этих клавиш не гарантирована. Выбор суффикса разобран в руководстве Суффиксы ENTER и TAB в сканерах штрихкодов.
Обычные события клавиатуры не содержат производителя сканера, серийный номер и признак того, что клавиши пришли от сканера. Браузеры с WebHID всё равно отказывают интерфейсам клавиатуры, поэтому страница не может открыть устройство клина и прочитать сырые отчёты HID.
Что такое последовательный режим сканера штрихкодов USB?
В последовательном режиме USB сканер не набирает текст. Он открывает последовательный интерфейс поверх USB. Операционная система обычно показывает этот интерфейс как виртуальный порт COM: имя COM в Windows, устройство cu или tty в macOS либо устройство ttyACM или ttyUSB в Linux. Имя назначает драйвер, и оно может смениться после отключения сканера.
Виртуальный порт COM — это не физический порт RS-232. RS-232 — электрический интерфейс со своим разъёмом и уровнями напряжения, который компьютер читает через UART. Последовательный USB использует кабель USB. Приложение по-прежнему открывает последовательный порт и читает байты, но сигнал на проводе — это USB. Одни изделия — настоящий сканер RS-232 плюс переходник с USB на последовательный порт. Другие реализуют USB CDC и вообще не говорят на RS-232. Считайте портом интеграции тот порт, который показывает операционная система, и не предполагайте, что электрические подробности совпадают.
Приложение открывает порт, читает поток байтов и решает, где сообщение начинается и заканчивается. Обычная рамка — текст штрихкода, за которым идёт CR (0x0D), LF (0x0A) или CR, а затем LF. Эта рамка — настройка устройства, а не правило USB. Возможен и префиксный байт, например STX. Руководство Префикс и суффикс сканера штрихкодов: полное руководство отделяет эти байты от клавиши Enter, которую отправляет сканер-клин.
Скорость, биты данных, чётность и стоповые биты важны на настоящем UART и на многих переходниках с USB на последовательный порт. Неверная скорость даёт мусор, а не чистую ошибку. Некоторые виртуальные устройства COM с USB CDC игнорируют скорость, которую запрашивает хост, и всё равно отдают байты. Нет одной настройки на каждый виртуальный последовательный сканер. Возьмите скорость и рамку из руководства к этой модели, затем подтвердите их известным штрихкодом.
Данные получает процесс, который держит порт открытым. Фокус клавиатуры получателя не выбирает. Другая программа, которая уже открыла порт, заблокирует второе открытие. Отключение сканера убирает порт. Повторное подключение может создать новое имя, и приложению придётся открыть этот порт снова.
HID и последовательный режим
| Возможность | Клавиатурный клин HID | Последовательный USB |
|---|---|---|
| Доставка данных | Ввод в стиле клавиатуры | Последовательный поток байтов |
| Нужен фокус ввода | Да. Нажатия следуют за элементом с фокусом | Нет. Байты идут в процесс, который открыл порт |
| Встраивание в браузер | Обычный ввод и события клавиатуры | Web Serial там, где браузер его поддерживает, или программа вне страницы |
| Управление в приложении | Ограничено поведением клавиатуры, фокусом и суффиксами | Приложение читает поток и собирает из него сообщения |
| Опознание устройства | Недоступно из обычных событий клавиатуры | Операционная система может показать имя порта. Устойчивое опознание по-прежнему зависит от драйвера |
| Настройка | Настройки сканера, включая суффикс и раскладку клавиатуры | Настройки сканера плюс те настройки порта на хосте, которые устройство действительно использует |
| Обычное применение | Формы и ввод позиций в POS | Отдельные интеграции, которым принадлежит устройство |
Это обычные случаи. Конкретная модель, операционная система и драйвер могут отличаться. Сканер Bluetooth в режиме клавиатуры HID на уровне приложения идёт по столбцу клина. Bluetooth SPP идёт по последовательному столбцу.
Как сканеры HID работают в веб-приложениях
Сканирование клином обновляет элемент с фокусом. Печатаемые символы вызывают 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 и дайте браузеру перенести фокус. Если он не отправляет ни Enter, ни Tab, отправьте поле кнопкой или другим явным действием. Пауза в наборе — только эвристика конца сканирования.
В этих событиях нет ничего, что опознаёт устройство USB. Тот же ряд может создать человек, макрос или эмулятор. Проверка относится к полезной нагрузке. Браузерный сценарий, включая Tab и пустой ввод, есть в руководстве Как тестировать сканеры штрихкодов в веб-приложениях.
Как последовательные сканеры работают в приложениях
Последовательная интеграция открывает порт, читает байты, режет их на сообщения и обрабатывает исчезновение порта. На рабочем столе это последовательный API операционной системы или библиотека производителя. В браузере единственный встроенный вариант — Web Serial API, и только в браузерах, которые его реализуют.
Web Serial есть в браузерах на основе Chromium. Firefox и Safari его не дают. Страница должна быть в безопасном контексте, то есть HTTPS или localhost. requestPort() должен вызываться из жеста пользователя, и пользователь должен выбрать порт в запросе браузера. Сканер в режиме клавиатурного клина в этом списке не появляется, потому что это не последовательное устройство. 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
- Подключите сканер и убедитесь, что он в режиме клавиатурного клина. Текстовый редактор должен получать символы, когда поле в этом редакторе в фокусе.
- Откройте тестер ввода штрихкода.
- Нажмите Начать тест или щёлкните область сканирования. Она становится синей, когда готова. Страница сама фокус не забирает.
- Отсканируйте штрихкод, полезную нагрузку которого вы уже знаете.
- Сравните захваченное значение и число символов с этой полезной нагрузкой.
- Прочитайте суффикс: ENTER, TAB или None. Enter и Tab не входят в строку штрихкода.
Тестер записывает события клавиатуры, которые видит браузер. Он не может читать последовательный порт и не может опознать устройство USB. Когда средний промежуток между символами меньше 100 ms, он сообщает это время. Время — не опознание оборудования. Для каждого keydown, включая key и code, используйте тестер событий клавиатуры. Более широкий проход есть в руководстве Как тестировать ввод со сканера штрихкодов.
Проверка последовательного сканера
Тестер ввода штрихкода не открывает порт COM. Последовательной проверке нужна программа, которая может открыть порт, показанный сканером.
- Убедитесь, что сканер в последовательном режиме и что операционная система показывает порт, когда сканер подключён. Отключите его и проверьте, что порт исчез.
- Запишите имя порта. Оно зависит от операционной системы и может смениться при следующем подключении.
- Откройте порт из совместимого приложения: последовательного терминала, вашего настольного приложения или примера Web Serial выше в браузере на основе Chromium по HTTPS или localhost.
- Задайте скорость, биты данных, чётность и стоповые биты, когда руководство их указывает. Пропущенные в руководстве значения не выдумывайте.
- Отсканируйте известный штрихкод.
- Сравните байты или декодированный текст с этой полезной нагрузкой.
- Проверьте рамку. Ищите префикс и CR, LF или CRLF после данных, только если именно это задано в руководстве.
Если открытие порта не удаётся, потому что он занят, закройте другую программу, которая его держит. Если текст — мусор, параметры линии не совпадают с устройством. Если порт так и не появляется, сканер может всё ещё быть в режиме клавиатуры, драйвер может отсутствовать, или пользователю ОС может быть запрещено открывать последовательные устройства.
Частые проблемы
Сканер работает в текстовом редакторе и не работает в целевом приложении. Устройство набирает текст. У цели нет фокуса, или слушатель keydown отбрасывает клавиши. Начните со статьи Работает в Notepad, но не в POS.
Сканер не набирает текст ни в одно текстовое поле. Он может быть в последовательном режиме, выключен или не читает символ. Сканер в последовательном режиме набирать не будет. Проверьте порт COM, прежде чем отлаживать поле. Статья Сканер штрихкодов не работает отделяет неработающий сканер от неверного интерфейса.
Последовательный порт отсутствует. Режим клавиатуры не создаёт порт COM. Отсутствующий драйвер, кабель только для зарядки или сканер без последовательного режима дают тот же симптом. Смотрите список устройств ОС, пока подключаете сканер.
Последовательный порт уже занят. Читать его может только один процесс. Закройте терминал или другую копию приложения, затем откройте порт снова.
Параметры связи неверны. Несовпадение скорости, чётности или стоповых битов выглядит как случайные символы. Задайте значения из руководства к этой модели, затем снова отсканируйте известный код.
ENTER или TAB так и не приходят. Это настройка суффикса клина. Тестер ввода сообщает None. См. У сканера штрихкодов нет ENTER и руководство по суффиксам выше. Последовательный сканер не отправляет клавишу Enter. Он может отправить байты CR или LF.
На сканере-клине неверные символы. Раскладка клавиатуры сканера и раскладка операционной системы могут не совпадать. Последовательные байты эта раскладка не переназначает. См. Неверная раскладка клавиатуры сканера штрихкодов.
Браузер не может обратиться к сканеру. Сканер-клин не появится в запросе Web Serial. У Firefox и Safari нет Web Serial API. Страница не на HTTPS и не на localhost воспользоваться им не может. Пользователь также может закрыть запрос порта.
Приложение теряет сканер после отключения. Сканер-клин возвращается как клавиатура, и следующему сканированию по-прежнему нужен фокус. Последовательный порт отсутствует, пока приложение не откроет новый порт. Имя может не совпасть с прежним.
Сценарии интеграции
Веб-приложения
Клавиатурный клин подходит полю с фокусом и обычным событиям DOM. Последовательный доступ внутри страницы означает Web Serial в поддерживающем браузере, безопасный контекст и порт, выбранный пользователем. Страница, которая должна поддерживать Firefox, Safari и киоски без оператора, не может опираться только на Web Serial. Локальный помощник может владеть портом COM и пересылать готовые штрихкоды на страницу. Этот помощник — отдельная программа. Проверка клина эту программу не упражняет.
Системы POS
POS, который ставит фокус в поле позиции и фиксирует значение по Enter, — интеграция клина. POS, который должен сканировать, пока открыто модальное окно, или который должен игнорировать клавиатуру, — последовательная интеграция. Смешение даёт сканирования не в то поле или сканирования, которые не приходят. Согласуйте режим сканера с экраном, который действительно на смене.
Настольные приложения
Настольное приложение может принимать ввод клина в том элементе, который в фокусе, или открыть виртуальный порт COM и держать сеанс на время жизни процесса. Владение портом, повторное подключение и рамка — часть этого сеанса. Фокус к нему не относится.
Автоматизация QA
Barcode Scanner Emulator набирает выбранное вами значение в приложение с фокусом и может отправить ENTER, TAB или обойтись без суффикса. Это покрывает регрессии клавиатурного клина: фокус, проверку и обработку суффикса. Он не создаёт виртуальный порт COM, не перечисляет устройства USB и не воспроизводит скорость и рамку. Последовательным проверкам по-прежнему нужны последовательный порт и программа чтения либо тестовый двойник, который пишет ту же байтовую рамку, которую разбирает приложение.
Киоски
Киоск с вводом клина должен удерживать поле сканирования в фокусе сквозь диалоги, заставки и сообщения об ошибках. Один потерянный фокус — и следующее сканирование попадает в сочетание клавиш или в никуда. Киоск с последовательным режимом может читать порт без этого фокуса, и он должен держать разрешение на устройство и заново открывать порт после потери питания или выдёргивания кабеля.
Где подходит Barcode Scanner Emulator
Barcode Scanner Emulator — настольное приложение для Windows, macOS и Linux. Оно воспроизводит клавиатурный путь, которым пользуется сканер-клин. Вы вводите текст, выбираете задержку набора и выбираете суффикс: нет, ENTER или TAB. Глобальное сочетание набирает этот текст в приложение с фокусом.
Используйте его, чтобы разрабатывать формы в стиле HID и ловить их регрессии, когда сканера нет на столе. Соедините его с тестером ввода штрихкода, чтобы увидеть значение, клавиши префикса и суффикс, которые получил браузер.
Он не эмулирует последовательное устройство USB, виртуальный порт COM, перечисление USB или оптическое декодирование. Это поведение по-прежнему принадлежит оборудованию или последовательному тестовому двойнику, которым вы управляете.