Barcode Scanner Emulator
Leitores de códigos de barras USB HID e série
Um leitor em cunha de teclado USB HID escreve o código de barras descodificado na aplicação que tem o foco. Um leitor série USB expõe uma interface série, muitas vezes como uma porta COM virtual, e a aplicação tem de abrir essa porta e ler os octetos. USB é o cabo e o barramento. HID e série são formas distintas de apresentar os dados.
Escolha a interface que a aplicação consegue mesmo ler. Um campo de caixa que já aceita escrita é um problema de cunha de teclado. Um serviço que tem de receber leituras enquanto nenhum campo de texto tem o foco, ou que tem de manter os octetos do leitor separados do teclado, é um problema de série. Muitos leitores só oferecem um desses modos. Alguns podem mudar. O manual desse modelo é a lista dos modos que pode testar.
O guia Cunha de teclado HID explica em pormenor o caminho das premidas. Como funcionam os leitores de códigos de barras? trata a captura e a descodificação. Esta página compara as duas interfaces de anfitrião e os testes que cabem a cada uma.
O que é o modo de cunha de teclado USB HID?
No modo de teclado USB HID o leitor enumera-se como um teclado. O sistema operativo carrega o controlador de teclado habitual. Depois de uma descodificação, o leitor envia os caracteres como premidas para o controlo que detém o foco do teclado. Um formulário web, um campo de artigo do POS ou uma caixa de texto do ambiente de trabalho pode aceitar essa introdução sem código específico do leitor.
O foco decide o destino. Se o campo pretendido não tiver o foco, os caracteres caem noutro controlo ou perdem-se. O leitor não clica e não desloca o ponteiro.
Um sufixo configurado pode seguir a carga. Enter submete muitos formulários de um só campo. Tab desloca o foco para o controlo seguinte. Nenhuma das duas teclas está garantida. As escolhas de sufixo estão em Sufixos ENTER e TAB nos leitores de códigos de barras.
Os eventos de teclado vulgares não incluem o fabricante do leitor, o número de série nem um indicador de que as teclas vieram de um leitor. Os navegadores que implementam WebHID continuam a recusar interfaces de teclado, pelo que uma página não pode abrir o aparelho em cunha e ler relatórios HID em bruto.
O que é o modo série USB de um leitor de códigos de barras?
No modo série USB o leitor não escreve. Expõe uma interface série por USB. O sistema operativo apresenta, regra geral, essa interface como uma porta COM virtual: um nome COM no Windows, um dispositivo cu ou tty no macOS, ou um dispositivo ttyACM ou ttyUSB no Linux. O nome é atribuído pelo controlador e pode mudar depois de o leitor ser desligado.
Uma porta COM virtual não é uma porta RS-232 física. RS-232 é uma interface eléctrica, com o próprio conector e os próprios níveis de tensão, que um computador lê através de uma UART. A série USB usa um cabo USB. A aplicação continua a abrir uma porta série e a ler octetos, mas o sinal no fio é USB. Alguns produtos são um leitor RS-232 verdadeiro mais um adaptador de USB para série. Outros implementam USB CDC e nunca falam RS-232. Trate a porta que o sistema operativo lhe mostra como o ponto de integração e não presuma que os pormenores eléctricos coincidem.
A aplicação abre a porta, lê o fluxo de octetos e decide onde uma mensagem começa e acaba. Um enquadramento corrente é o texto do código de barras seguido de CR (0x0D), LF (0x0A), ou CR e depois LF. Esse enquadramento é uma definição do aparelho, não uma regra do USB. Um octeto de prefixo como STX também é possível. O guia Prefixo e sufixo no leitor de códigos de barras: guia completo separa esses octetos da tecla Enter que um leitor em cunha envia.
A taxa de baud, os bits de dados, a paridade e os bits de paragem importam numa UART real e em muitos adaptadores de USB para série. Uma taxa errada produz lixo em vez de um erro claro. Alguns dispositivos COM virtuais USB CDC ignoram a taxa de baud pedida pelo anfitrião e entregam na mesma os octetos. Não há uma definição única que sirva a todos os leitores série virtuais. Use a taxa e o enquadramento do manual desse modelo e confirme-os com um código de barras conhecido.
O processo que mantém a porta aberta recebe os dados. O foco do teclado não escolhe o destino. Outro programa que já tenha a porta aberta bloqueia uma segunda abertura. Desligar o leitor remove a porta. Voltar a ligá-lo pode criar um nome novo, e a aplicação tem de abrir essa porta outra vez.
HID e série
| Característica | Cunha de teclado HID | Série USB |
|---|---|---|
| Entrega dos dados | Introdução ao estilo de teclado | Fluxo de octetos série |
| Foco de introdução exigido | Sim. As premidas seguem o controlo com foco | Não. Os octetos vão para o processo que abriu a porta |
| Integração no navegador | Introdução vulgar e eventos de teclado | Web Serial onde o navegador a suporta, ou software fora da página |
| Controlo da aplicação | Limitado ao comportamento do teclado, ao foco e aos sufixos | A aplicação lê o fluxo e enquadra-o |
| Identificação do aparelho | Indisponível nos eventos de teclado vulgares | O sistema operativo pode mostrar um nome de porta. Uma identidade estável continua a depender do controlador |
| Configuração | Definições do leitor, incluindo sufixo e disposição de teclado | Definições do leitor mais as definições de porta do anfitrião que o aparelho usa de facto |
| Utilização típica | Formulários e introdução de artigos no POS | Integrações dedicadas que detêm o aparelho |
Estes são os casos habituais. Um modelo, um sistema operativo e um controlador concretos podem diferir. Um leitor Bluetooth em modo de teclado HID segue a coluna da cunha na camada da aplicação. Bluetooth SPP segue a coluna série.
Como funcionam os leitores HID nas aplicações web
Uma leitura em cunha actualiza o elemento com foco. Os caracteres imprimíveis disparam keydown e depois input. Enter e Tab disparam keydown e não inserem um carácter num campo de texto normal. event.key é "Enter" ou "Tab" para essas teclas, e uma cadeia de um carácter para um carácter imprimível. event.code nomeia a tecla física e pode manter-se igual quando um desajuste da disposição de teclado altera event.key.
O ouvinte abaixo confirma o campo só quando Enter chega. Um leitor sem sufixo Enter deixa o texto no campo.
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 = ''
})
Dê o foco a #barcode antes da leitura. preventDefault() impede que um formulário ascendente seja submetido uma segunda vez. Se o leitor enviar Tab em vez disso, leia o valor nesse keydown e deixe o navegador deslocar o foco. Se não enviar nenhum dos dois, submeta o campo a partir de um botão ou de outra acção explícita. Uma pausa na escrita é apenas uma heurística do fim de uma leitura.
Nada nesses eventos identifica o dispositivo USB. Uma pessoa, uma macro ou o emulador podem produzir a mesma sequência. A validação cabe à carga. O percurso no navegador, incluindo Tab e uma introdução vazia, está em Como testar leitores de códigos de barras em aplicações web.
Como funcionam os leitores série nas aplicações
Uma integração série abre uma porta, lê octetos, parte-os em mensagens e trata o desaparecimento da porta. No ambiente de trabalho, isso é a API série do sistema operativo ou uma biblioteca do fabricante. Num navegador, a única opção integrada é a Web Serial API, e só nos navegadores que a implementam.
Web Serial está disponível nos navegadores baseados em Chromium. O Firefox e o Safari não a fornecem. A página tem de ser um contexto seguro, o que significa HTTPS ou localhost. requestPort() tem de correr a partir de um gesto do utilizador, e o utilizador tem de escolher a porta no pedido do navegador. Um leitor em cunha de teclado não aparece nessa lista, porque não é um dispositivo série. A Web Serial também não consegue ver uma porta série que o sistema operativo não tenha exposto.
A taxa de baud do exemplo é um ponto de partida que substitui pelo valor do manual. O ciclo trata CR ou LF como o fim de uma mensagem e consome um par CRLF como um único terminador. Se o seu leitor usar outro enquadramento, esta divisão está errada mesmo com a porta aberta.
<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>
O ciclo de leitura prossegue até o fluxo terminar ou a leitura falhar. Desligar o leitor rejeita, em regra, a leitura. releaseLock() e close() correm em finally. As portas já aprovadas para esta origem podem ser listadas com navigator.serial.getPorts() sem voltar a mostrar o pedido. A primeira aprovação continua a exigir o utilizador.
Uma aplicação de ambiente de trabalho segue a mesma ideia com a API série da plataforma: abrir, ler, enquadrar e reabrir quando o aparelho regressa. Esta página não inventa comandos do fabricante. Se o leitor espera um protocolo proprietário, esse protocolo está na documentação do fabricante.
Qual é melhor: HID ou série?
Nenhum modo é melhor para todos os produtos. Use o modo que o leitor oferece de facto e o modo que a aplicação consegue ler.
Escolha HID quando
- A aplicação já aceita introdução de teclado num campo com foco.
- Quer que um formulário ou um ecrã de POS funcione sem código de aparelho.
- O fluxo de trabalho pode garantir o foco antes de cada leitura.
- Enter ou Tab corresponde à forma como esse formulário confirma ou avança.
Pondere a série quando
- As leituras têm de chegar com o foco numa caixa de diálogo, num botão ou em lado nenhum.
- Os octetos do leitor têm de ficar separados da escrita.
- A aplicação pode abrir uma porta, enquadrar mensagens e recuperar-se quando o aparelho é desligado.
- O anfitrião pode conceder autorização a essa porta e nenhum outro processo precisa dela ao mesmo tempo.
Um leitor que só se enumera como teclado não pode passar a série por software no anfitrião. Confirme os modos no manual antes de desenhar a integração.
Mudar entre HID e série
Alguns leitores mudam de modo quando lê um código de barras de configuração do manual desse fabricante, ou quando grava um perfil com o utilitário do fabricante. Outros são construídos como uma só interface e não têm nada para mudar.
Não existe um código de barras de configuração que altere todas as marcas. Uma sequência impressa para outro modelo pode não fazer nada, ou deixar o leitor num modo inesperado. Depois de qualquer alteração, verifique o que o sistema operativo mostra: um teclado, uma porta COM ou ambos. Depois teste o caminho que a sua aplicação usa. O Guia de configuração do leitor de códigos de barras descreve os grupos de definições habituais. Não substitui o manual.
Testar um leitor HID
- Ligue o leitor e confirme que está em modo de cunha de teclado. Um editor de texto deve receber caracteres quando um campo desse editor tem o foco.
- Abra o testador de introdução de códigos de barras.
- Clique em Start Test ou na área de leitura. Fica azul quando está pronto. A página não toma o foco por si.
- Leia um código de barras cuja carga já conhece.
- Compare o valor capturado e a contagem de caracteres com essa carga.
- Leia o sufixo: ENTER, TAB ou None. Enter e Tab não fazem parte da cadeia do código de barras.
O testador regista os eventos de teclado que o navegador consegue ver. Não pode ler uma porta série e não pode identificar o dispositivo USB. Quando o intervalo médio entre caracteres fica abaixo de 100 ms, comunica esse tempo. O tempo não é uma identificação de hardware. Para cada keydown, incluindo key e code, utilize o testador de eventos de teclado. Uma passagem de garantia de qualidade mais ampla está em Como testar a introdução do leitor de códigos de barras.
Testar um leitor série
O testador de introdução de códigos de barras não abre uma porta COM. Um teste série precisa de um programa capaz de abrir a porta que o leitor expõe.
- Confirme que o leitor está num modo série e que o sistema operativo lista uma porta quando está ligado. Desligue-o e verifique que a porta desaparece.
- Anote o nome da porta. É específico do sistema operativo e pode mudar na ligação seguinte.
- Abra a porta a partir de uma aplicação compatível: um terminal série, a sua aplicação de ambiente de trabalho ou o exemplo de Web Serial acima num navegador Chromium em HTTPS ou localhost.
- Defina a taxa de baud, os bits de dados, a paridade e os bits de paragem quando o manual os especificar. Ignore valores inventados.
- Leia um código de barras conhecido.
- Compare os octetos ou o texto descodificado com essa carga.
- Verifique o enquadramento. Procure um prefixo e CR, LF ou CRLF a seguir aos dados, só se foi isso que o manual configurou.
Se a abertura da porta falhar porque está ocupada, feche o outro programa que a detém. Se o texto for lixo, as definições de linha não correspondem ao aparelho. Se a porta nunca aparecer, o leitor pode continuar em modo de teclado, o controlador pode faltar ou o utilizador do sistema pode não ter autorização para abrir dispositivos série.
Problemas comuns
O leitor funciona num editor de texto e não na aplicação de destino. O aparelho está a escrever. O destino não tem o foco, ou um ouvinte de keydown descarta as teclas. Comece por Funciona no Notepad mas falha no POS.
O leitor não escreve em nenhum campo de texto. Pode estar em modo série, desligado ou a não ler o símbolo. Um leitor em modo série não escreve. Procure uma porta COM antes de diagnosticar o campo. O leitor de códigos de barras não funciona separa um leitor morto da interface errada.
A porta série está em falta. O modo de teclado não cria uma porta COM. Um controlador em falta, um cabo só de carga ou um leitor sem modo série produzem o mesmo sintoma. Observe a lista de aparelhos do sistema enquanto liga o leitor.
A porta série já está em utilização. Só um processo a pode ler. Feche o terminal ou a outra cópia da aplicação e volte a abri-la.
As definições de comunicação estão erradas. Taxa de baud, paridade ou bits de paragem que não coincidem parecem caracteres ao acaso. Defina os valores do manual desse modelo e leia de novo um código conhecido.
ENTER ou TAB nunca chegam. Isso é uma definição de sufixo da cunha. O testador de introdução indica None. Consulte Leitor de códigos de barras sem ENTER e o guia de sufixos ligado acima. Um leitor série não envia a tecla Enter. Pode enviar octetos CR ou LF em substituição.
Os caracteres estão errados num leitor em cunha. A disposição de teclado do leitor e a do sistema operativo podem discordar. Os octetos série não são reassociados por essa disposição. Consulte Disposição de teclado errada no leitor de códigos de barras.
O navegador não consegue aceder ao leitor. Um leitor em cunha não aparece no pedido de Web Serial. O Firefox e o Safari não têm Web Serial API. Uma página que não seja HTTPS ou localhost não a pode utilizar. O utilizador também pode fechar o pedido da porta.
A aplicação perde o leitor depois de este ser desligado. Um leitor em cunha regressa como teclado, e a leitura seguinte continua a exigir foco. Uma porta série desaparece até a aplicação abrir a porta nova. O nome pode não corresponder ao anterior.
Cenários de integração
Aplicações web
A cunha de teclado serve a uma introdução com foco e a eventos DOM vulgares. O acesso série dentro da página significa Web Serial num navegador que a suporte, um contexto seguro e uma porta escolhida pelo utilizador. Uma página que tenha de suportar Firefox, Safari e quiosques sem vigilância não pode depender só de Web Serial. Um auxiliar local pode deter a porta COM e encaminhar códigos de barras completos para a página. Esse auxiliar é software à parte. A página não deve esperar que um teste de cunha o exercite.
Sistemas POS
Um POS que coloca o foco no campo de artigo e confirma com Enter é uma integração em cunha. Um POS que tem de ler com uma janela modal aberta, ou que tem de ignorar o teclado, é uma integração série. Misturá-los produz leituras no campo errado ou leituras que nunca chegam. Faça corresponder o modo do leitor ao ecrã que está de facto em serviço.
Aplicações de ambiente de trabalho
Uma aplicação de ambiente de trabalho pode aceitar a introdução em cunha no controlo que tiver o foco, ou abrir a porta COM virtual e manter uma sessão durante a vida do processo. A posse da porta, a religação e o enquadramento fazem parte dessa sessão. O foco não.
Automatização da garantia de qualidade
O Barcode Scanner Emulator escreve um valor à sua escolha na aplicação com foco e pode enviar ENTER, TAB ou nenhum sufixo. Isso cobre regressões da cunha de teclado: foco, validação e tratamento do sufixo. Não cria uma porta COM virtual, não enumera dispositivos USB e não reproduz a taxa de baud nem o enquadramento. Os testes série continuam a precisar de uma porta série e de um leitor, ou de um duplo de teste que escreva o mesmo enquadramento de octetos que a sua aplicação analisa.
Aplicações de quiosque
Um quiosque que usa introdução em cunha tem de manter o campo de leitura com foco através de caixas de diálogo, protectores de ecrã e mensagens de erro. Um foco perdido e a leitura seguinte cai num atalho ou em nada. Um quiosque que usa série pode ler a porta sem esse foco, e tem de conservar a autorização sobre o aparelho e reabrir a porta após uma falha de energia ou um puxão no cabo.
Onde entra o Barcode Scanner Emulator
O Barcode Scanner Emulator é uma aplicação de ambiente de trabalho para Windows, macOS e Linux. Reproduz o caminho de teclado que um leitor em cunha utiliza. Introduz o texto, escolhe um atraso de escrita e escolhe um sufixo entre nenhum, ENTER ou TAB. Um atalho global escreve esse texto na aplicação com foco.
Utilize-o para desenvolver formulários ao estilo HID e verificar as regressões quando o leitor não está na secretária. Combine-o com o testador de introdução de códigos de barras para ver o valor, as teclas de prefixo e o sufixo que o navegador recebeu.
Não emula um dispositivo série USB, uma porta COM virtual, uma enumeração USB nem uma descodificação óptica. Esses comportamentos continuam a pertencer ao equipamento, ou a um duplo de teste série que controla.