Ir para o conteúdo

Barcode Scanner Emulator

Leitores de código de barras USB HID e serial

Um leitor em cunha de teclado USB HID digita o código de barras decodificado no aplicativo que está com o foco. Um leitor serial USB expõe uma interface serial, muitas vezes como uma porta COM virtual, e o aplicativo precisa abrir essa porta e ler os bytes. USB é o cabo e o barramento. HID e serial são jeitos diferentes de apresentar os dados.

Escolha a interface que o aplicativo consegue ler de fato. Um campo de caixa que já aceita digitação é um problema de cunha de teclado. Um serviço que precisa receber leituras enquanto nenhum campo de texto está em foco, ou que precisa manter os bytes do leitor separados do teclado, é um problema serial. Muitos leitores oferecem só um desses modos. Alguns podem alternar. O manual desse modelo é a lista dos modos que você pode testar.

O guia Cunha de teclado HID explica o caminho das teclas em detalhe. Como os leitores de código de barras funcionam? cobre a captura e a decodificação. Esta página compara as duas interfaces de host e os testes que cabem a cada uma.

O que é o modo cunha de teclado USB HID?

No modo teclado USB HID o leitor se enumera como um teclado. O sistema operacional carrega o driver de teclado normal. Depois de uma decodificação, o leitor envia os caracteres como pressionamentos para o controle que tem o foco do teclado. Um formulário web, um campo de item do POS ou uma caixa de texto da área de trabalho pode aceitar essa entrada sem código específico de leitor.

O foco decide o destino. Se o campo pretendido não estiver em foco, os caracteres caem em outro controle ou se perdem. O leitor não clica e não move o ponteiro.

Um sufixo configurado pode vir depois da carga. Enter envia muitos formulários de um só campo. Tab move o foco para o controle seguinte. Nenhuma das duas teclas é garantida. As escolhas de sufixo estão em Sufixos ENTER e TAB em leitores de código de barras.

Eventos de teclado comuns não trazem o fabricante do leitor, o número de série nem um sinal de que as teclas vieram de um leitor. Navegadores que implementam WebHID ainda recusam interfaces de teclado, então uma página não pode abrir o aparelho em cunha e ler relatórios HID brutos.

O que é o modo serial USB de um leitor de código de barras?

No modo serial USB o leitor não digita. Ele expõe uma interface serial por USB. O sistema operacional em geral apresenta 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 driver e pode mudar depois que o leitor é desconectado.

Uma porta COM virtual não é uma porta RS-232 física. RS-232 é uma interface elétrica, com o próprio conector e os próprios níveis de tensão, que um computador lê por uma UART. O serial USB usa um cabo USB. O aplicativo ainda abre uma porta serial e lê bytes, mas o sinal no fio é USB. Alguns produtos são um leitor RS-232 de verdade mais um adaptador de USB para serial. Outros implementam USB CDC e nunca falam RS-232. Trate a porta que o sistema operacional mostra como o ponto de integração e não presuma que os detalhes elétricos coincidem.

O aplicativo abre a porta, lê o fluxo de bytes e decide onde uma mensagem começa e termina. Um quadro comum é o texto do código de barras seguido de CR (0x0D), LF (0x0A), ou CR e depois LF. Esse enquadramento é um ajuste do aparelho, não uma regra do USB. Um byte de prefixo como STX também é possível. O guia Prefixo e sufixo no leitor de código de barras: guia completo separa esses bytes da tecla Enter que um leitor em cunha envia.

A taxa de baud, os bits de dados, a paridade e os bits de parada importam numa UART real e em muitos adaptadores de USB para serial. Uma taxa errada produz lixo em vez de um erro claro. Alguns dispositivos COM virtuais USB CDC ignoram a taxa de baud que o host pede e ainda assim entregam os bytes. Não existe um ajuste único que sirva para todo leitor serial virtual. 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. Desconectar o leitor remove a porta. Conectar de novo pode criar um nome novo, e o aplicativo tem de abrir essa porta outra vez.

HID e serial

Recurso Cunha de teclado HID Serial USB
Entrega dos dados Entrada no estilo de teclado Fluxo de bytes serial
Foco de entrada necessário Sim. Os pressionamentos seguem o controle em foco Não. Os bytes vão para o processo que abriu a porta
Integração no navegador Entrada comum e eventos de teclado Web Serial onde o navegador oferece suporte, ou software fora da página
Controle do aplicativo Limitado ao comportamento do teclado, ao foco e aos sufixos O aplicativo lê o fluxo e o enquadra
Identificação do aparelho Indisponível nos eventos de teclado comuns O sistema operacional pode mostrar um nome de porta. Uma identidade estável ainda depende do driver
Configuração Ajustes do leitor, inclusive sufixo e layout de teclado Ajustes do leitor mais os ajustes de porta do host que o aparelho realmente usa
Uso típico Formulários e entrada de itens no POS Integrações dedicadas que são donas do aparelho

Esses são os casos usuais. Um modelo, um sistema operacional e um driver específicos podem diferir. Um leitor Bluetooth em modo teclado HID segue a coluna da cunha na camada do aplicativo. Bluetooth SPP segue a coluna serial.

Como os leitores HID funcionam em aplicativos web

Uma leitura em cunha atualiza o elemento em foco. Caracteres imprimíveis disparam keydown e depois input. Enter e Tab disparam keydown e não inserem um caractere num campo de texto normal. event.key é "Enter" ou "Tab" para essas teclas, e uma cadeia de um caractere para um caractere imprimível. event.code nomeia a tecla física e pode permanecer igual quando um desencontro de layout de teclado muda 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 = ''
})

Foque #barcode antes da leitura. preventDefault() impede que um formulário pai seja enviado uma segunda vez. Se o leitor mandar Tab no lugar, leia o valor nesse keydown e deixe o navegador mover o foco. Se não mandar nenhum dos dois, envie o campo a partir de um botão ou de outra ação explícita. Uma pausa na digitação é só 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 fica na carga. O fluxo no navegador, inclusive Tab e uma entrada vazia, está em Como testar leitores de código de barras em aplicativos web.

Como os leitores seriais funcionam nos aplicativos

Uma integração serial abre uma porta, lê bytes, parte-os em mensagens e trata o desaparecimento da porta. Na área de trabalho, isso é a API serial do sistema operacional ou uma biblioteca do fabricante. Num navegador, a única opção embutida é a Web Serial API, e só nos navegadores que a implementam.

Web Serial está disponível nos navegadores baseados em Chromium. Firefox e Safari não a oferecem. A página precisa ser um contexto seguro, o que significa HTTPS ou localhost. requestPort() tem de rodar a partir de um gesto do usuário, e o usuário precisa escolher a porta no aviso do navegador. Um leitor em cunha de teclado não aparece nessa lista, porque não é um dispositivo serial. Web Serial também não consegue ver uma porta serial que o sistema operacional não tenha exposto.

A taxa de baud do exemplo é um ponto de partida que você troca pelo valor do manual. O laço 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 quadro, essa 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 laço de leitura segue até o fluxo terminar ou a leitura falhar. Desconectar o leitor em geral rejeita a leitura. releaseLock() e close() rodam em finally. Portas já aprovadas para esta origem podem ser listadas com navigator.serial.getPorts() sem mostrar o aviso de novo. A primeira aprovação ainda exige o usuário.

Um aplicativo de área de trabalho segue a mesma ideia com a API serial da plataforma: abrir, ler, enquadrar e reabrir quando o aparelho volta. 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 serial?

Nenhum modo é melhor para todo produto. Use o modo que o leitor oferece de fato e o modo que o aplicativo consegue ler.

Escolha HID quando

  • O aplicativo já aceita entrada de teclado num campo em foco.
  • Você quer que um formulário ou uma tela de POS funcione sem código de aparelho.
  • O fluxo pode garantir o foco antes de cada leitura.
  • Enter ou Tab combina com a forma como esse formulário confirma ou avança.

Considere o serial quando

  • As leituras precisam chegar com o foco num diálogo, num botão ou em lugar nenhum.
  • Os bytes do leitor precisam ficar separados da digitação.
  • O aplicativo pode abrir uma porta, enquadrar mensagens e se recuperar quando o aparelho é desconectado.
  • O host pode conceder permissão a essa porta e nenhum outro processo precisa dela ao mesmo tempo.

Um leitor que só se enumera como teclado não pode ser passado para serial por software no host. Confirme os modos no manual antes de desenhar a integração.

Alternar entre HID e serial

Alguns leitores mudam de modo quando você 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 o que alternar.

Não existe um código de barras de configuração que mude 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 mudança, confira o que o sistema operacional mostra: um teclado, uma porta COM ou os dois. Depois teste o caminho que o seu aplicativo usa. O Guia de configuração do leitor de código de barras descreve os grupos de ajustes usuais. Ele não substitui o manual.

Testar um leitor HID

  1. Conecte o leitor e confirme que ele está em modo cunha de teclado. Um editor de texto deve receber caracteres quando um campo desse editor está em foco.
  2. Abra o testador de entrada de código de barras.
  3. Clique em Start Test ou na área de leitura. Ela fica azul quando está pronta. A página não toma o foco sozinha.
  4. Leia um código de barras cuja carga você já conhece.
  5. Compare o valor capturado e a contagem de caracteres com essa carga.
  6. Leia o sufixo: ENTER, TAB ou None. Enter e Tab não fazem parte da cadeia do código de barras.

O testador registra os eventos de teclado que o navegador consegue ver. Ele não pode ler uma porta serial e não pode identificar o dispositivo USB. Quando o intervalo médio entre caracteres fica abaixo de 100 ms, ele informa esse tempo. O tempo não é uma identificação de hardware. Para cada keydown, inclusive key e code, use o testador de eventos de teclado. Uma passagem de QA mais ampla está em Como testar a entrada do leitor de código de barras.

Testar um leitor serial

O testador de entrada de código de barras não abre uma porta COM. Um teste serial precisa de um programa que consiga abrir a porta que o leitor expõe.

  1. Confirme que o leitor está num modo serial e que o sistema operacional lista uma porta quando ele está conectado. Desconecte-o e confira que a porta some.
  2. Anote o nome da porta. Ele é específico do sistema operacional e pode mudar na próxima conexão.
  3. Abra a porta a partir de um aplicativo compatível: um terminal serial, seu aplicativo de área de trabalho ou o exemplo de Web Serial acima num navegador Chromium em HTTPS ou localhost.
  4. Defina a taxa de baud, os bits de dados, a paridade e os bits de parada quando o manual os especificar. Pule valores inventados.
  5. Leia um código de barras conhecido.
  6. Compare os bytes ou o texto decodificado com essa carga.
  7. Confira o enquadramento. Procure um prefixo e CR, LF ou CRLF depois dos dados, só se foi isso que o manual configurou.

Se a abertura da porta falhar porque ela está ocupada, feche o outro programa que a segura. Se o texto for lixo, os ajustes de linha não batem com o aparelho. Se a porta nunca aparecer, o leitor pode ainda estar em modo teclado, o driver pode faltar ou o usuário do sistema pode não ter permissão para abrir dispositivos seriais.

Problemas comuns

O leitor funciona num editor de texto e não no aplicativo de destino. O aparelho está digitando. O destino não tem foco, ou um ouvinte de keydown descarta as teclas. Comece por Funciona no Notepad, mas não no POS.

O leitor não digita em nenhum campo de texto. Ele pode estar em modo serial, desligado ou sem ler o símbolo. Um leitor em modo serial não digita. Procure uma porta COM antes de depurar o campo. Leitor de código de barras não funciona separa um leitor morto da interface errada.

A porta serial está ausente. O modo teclado não cria uma porta COM. Um driver que falta, um cabo só de carga ou um leitor sem modo serial produzem o mesmo sintoma. Observe a lista de aparelhos do sistema enquanto você conecta o leitor.

A porta serial já está em uso. Só um processo pode lê-la. Feche o terminal ou a outra cópia do aplicativo e abra de novo.

Os ajustes de comunicação estão errados. Taxa de baud, paridade ou bits de parada que não coincidem parecem caracteres aleatórios. Defina os valores do manual desse modelo e leia de novo um código conhecido.

ENTER ou TAB nunca chegam. Isso é um ajuste de sufixo da cunha. O testador de entrada informa None. Veja Leitor de código de barras sem ENTER e o guia de sufixos ligado acima. Um leitor serial não envia a tecla Enter. Ele pode enviar bytes CR ou LF no lugar.

Os caracteres saem errados num leitor em cunha. O layout de teclado do leitor e o do sistema operacional podem discordar. Bytes seriais não são remapeados por esse layout. Veja Layout de teclado errado no leitor de código de barras.

O navegador não consegue acessar o leitor. Um leitor em cunha não vai aparecer no aviso de Web Serial. Firefox e Safari não têm Web Serial API. Uma página que não seja HTTPS ou localhost não pode usá-la. O usuário também pode dispensar o aviso da porta.

O aplicativo perde o leitor depois que ele é desconectado. Um leitor em cunha volta como teclado, e a leitura seguinte ainda exige foco. Uma porta serial some até o aplicativo abrir a porta nova. O nome pode não bater com o anterior.

Cenários de integração

Aplicativos web

A cunha de teclado cabe numa entrada em foco e em eventos DOM comuns. O acesso serial dentro da página significa Web Serial num navegador que ofereça suporte, um contexto seguro e uma porta escolhida pelo usuário. Uma página que precise suportar Firefox, Safari e quiosques sem operador não pode depender só de Web Serial. Um auxiliar local pode ser dono da 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 põe o foco no campo de item e confirma com Enter é uma integração em cunha. Um POS que precisa ler com um modal aberto, ou que precisa ignorar o teclado, é uma integração serial. Misturar os dois manda leituras para o campo errado ou produz leituras que nunca chegam. Combine o modo do leitor com a tela que está de fato em serviço.

Aplicativos de área de trabalho

Um aplicativo de área de trabalho pode aceitar a entrada em cunha no controle que tiver o foco, ou abrir a porta COM virtual e manter uma sessão pela vida do processo. A posse da porta, a reconexão e o enquadramento fazem parte dessa sessão. O foco não.

Automação de QA

O Barcode Scanner Emulator digita um valor que você escolhe no aplicativo em foco e pode enviar ENTER, TAB ou nenhum sufixo. Isso cobre regressões da cunha de teclado: foco, validação e tratamento do sufixo. Ele não cria uma porta COM virtual, não enumera dispositivos USB e não reproduz taxa de baud nem enquadramento. Testes seriais ainda precisam de uma porta serial e de um leitor, ou de um dublê de teste que escreva o mesmo enquadramento de bytes que o seu aplicativo analisa.

Aplicativos de quiosque

Um quiosque que usa entrada em cunha tem de manter o campo de leitura em foco através de diálogos, protetores de tela e mensagens de erro. Um foco perdido e a leitura seguinte cai num atalho ou em nada. Um quiosque que usa serial pode ler a porta sem esse foco, e precisa guardar a permissão do aparelho e reabrir a porta depois de uma queda de energia ou de um puxão no cabo.

Onde o Barcode Scanner Emulator entra

O Barcode Scanner Emulator é um aplicativo de área de trabalho para Windows, macOS e Linux. Ele reproduz o caminho de teclado que um leitor em cunha usa. Você digita o texto, escolhe um atraso de digitação e escolhe um sufixo entre nenhum, ENTER ou TAB. Um atalho global digita esse texto no aplicativo em foco.

Use-o para desenvolver formulários no estilo HID e rodar as regressões quando o leitor não está na mesa. Combine-o com o testador de entrada de código de barras para ver o valor, as teclas de prefixo e o sufixo que o navegador recebeu.

Ele não emula um dispositivo serial USB, uma porta COM virtual, uma enumeração USB nem uma decodificação óptica. Esses comportamentos ainda pertencem ao hardware, ou a um dublê de teste serial que você controla.