Saltar al contenido

Barcode Scanner Emulator

Lectores de códigos de barras USB HID y serie

Un lector en cuña de teclado USB HID escribe el código de barras descodificado en la aplicación que tiene el foco. Un lector serie USB expone una interfaz serie, a menudo como un puerto COM virtual, y la aplicación tiene que abrir ese puerto y leer los octetos. USB es el cable y el bus. HID y serie son formas distintas de presentar los datos.

Elige la interfaz que la aplicación pueda leer de verdad. Un campo de caja que ya acepta la escritura es un problema de cuña de teclado. Un servicio que debe recibir lecturas mientras ningún campo de texto tiene el foco, o que debe mantener los octetos del lector separados del teclado, es un problema de serie. Muchos lectores solo ofrecen uno de esos modos. Algunos pueden cambiar. El manual de ese modelo es la lista de modos que puedes probar.

La guía Cuña de teclado HID explica con detalle la ruta de las pulsaciones. ¿Cómo funcionan los lectores de códigos de barras? trata la captura y la descodificación. Esta página compara las dos interfaces de anfitrión y las pruebas que corresponden a cada una.

¿Qué es el modo de cuña de teclado USB HID?

En modo de teclado USB HID el lector se enumera como un teclado. El sistema operativo carga su controlador de teclado habitual. Tras una descodificación, el lector envía los caracteres como pulsaciones al control que tiene el foco del teclado. Un formulario web, un campo de artículo del POS o un cuadro de texto de escritorio pueden aceptar esa entrada sin código específico del lector.

El foco decide el destino. Si el campo previsto no tiene el foco, los caracteres caen en otro control o se pierden. El lector no hace clic y no mueve el puntero.

Un sufijo configurado puede seguir a la carga útil. Enter envía muchos formularios de un solo campo. Tab mueve el foco al control siguiente. Ninguna de las dos teclas está garantizada. Las opciones de sufijo se tratan en Sufijos ENTER y TAB en los lectores de códigos de barras.

Los eventos de teclado ordinarios no incluyen el fabricante del lector, el número de serie ni un indicador de que las teclas vinieron de un lector. Los navegadores que implementan WebHID siguen rechazando las interfaces de teclado, así que una página no puede abrir el dispositivo en cuña y leer informes HID en bruto.

¿Qué es el modo serie USB de un lector de códigos de barras?

En modo serie USB el lector no escribe. Expone una interfaz serie a través de USB. El sistema operativo suele presentar esa interfaz como un puerto COM virtual: un nombre COM en Windows, un dispositivo cu o tty en macOS, o un dispositivo ttyACM o ttyUSB en Linux. El nombre lo asigna el controlador y puede cambiar después de desconectar el lector.

Un puerto COM virtual no es un puerto RS-232 físico. RS-232 es una interfaz eléctrica, con su propio conector y sus niveles de tensión, que un ordenador lee a través de una UART. El serie USB usa un cable USB. La aplicación sigue abriendo un puerto serie y leyendo octetos, pero la señal en el cable es USB. Algunos productos son un lector RS-232 real más un adaptador de USB a serie. Otros implementan USB CDC y no hablan RS-232 en ningún momento. Trata el puerto que te muestra el sistema operativo como el punto de integración y no des por hecho que los detalles eléctricos coinciden.

La aplicación abre el puerto, lee el flujo de octetos y decide dónde empieza y dónde acaba un mensaje. Un marco habitual es el texto del código de barras seguido de CR (0x0D), LF (0x0A), o CR y después LF. Ese encuadre es un ajuste del dispositivo, no una regla de USB. También es posible un octeto de prefijo como STX. La guía Prefijo y sufijo del lector de códigos de barras: guía completa separa esos octetos de la tecla Enter que envía un lector en cuña.

La velocidad en baudios, los bits de datos, la paridad y los bits de parada importan en una UART real y en muchos adaptadores de USB a serie. Una velocidad incorrecta produce basura en lugar de un error claro. Algunos dispositivos COM virtuales USB CDC ignoran la velocidad en baudios que pide el anfitrión y aun así entregan los octetos. No hay un ajuste único que sirva para cada lector serie virtual. Usa la velocidad y el encuadre del manual de ese modelo y confírmalos con un código de barras conocido.

El proceso que mantiene el puerto abierto recibe los datos. El foco del teclado no elige el destino. Otro programa que ya tenga el puerto abierto bloqueará una segunda apertura. Desconectar el lector elimina el puerto. Volver a conectarlo puede crear un nombre nuevo, y la aplicación tiene que abrir ese puerto otra vez.

HID y serie

Característica Cuña de teclado HID Serie USB
Entrega de datos Entrada de estilo teclado Flujo de octetos serie
Hace falta foco de entrada Sí. Las pulsaciones siguen al control que tiene el foco No. Los octetos van al proceso que abrió el puerto
Integración en el navegador Entrada ordinaria y eventos de teclado Web Serial donde el navegador lo admite, o software fuera de la página
Control de la aplicación Limitado al comportamiento del teclado, al foco y a los sufijos La aplicación lee el flujo y lo encuadra
Identificación del dispositivo No disponible en los eventos de teclado ordinarios El sistema operativo puede mostrar un nombre de puerto. Una identidad estable sigue dependiendo del controlador
Configuración Ajustes del lector, incluido el sufijo y la distribución de teclado Ajustes del lector más los ajustes de puerto del anfitrión que el dispositivo usa de verdad
Uso habitual Formularios y entrada de artículos en un POS Integraciones dedicadas que poseen el dispositivo

Estos son los casos habituales. Un modelo, un sistema operativo y un controlador concretos pueden diferir. Un lector Bluetooth en modo de teclado HID sigue la columna de la cuña en la capa de aplicación. Bluetooth SPP sigue la columna serie.

Cómo funcionan los lectores HID en las aplicaciones web

Una lectura en cuña actualiza el elemento que tiene el foco. Los caracteres imprimibles disparan keydown y después input. Enter y Tab disparan keydown y no insertan un carácter en un campo de texto normal. event.key es "Enter" o "Tab" para esas teclas, y una cadena de un carácter para un carácter imprimible. event.code nombra la tecla física y puede seguir igual cuando un desajuste de distribución de teclado cambia event.key.

El escuchador de abajo confirma el campo solo cuando llega Enter. Un lector sin sufijo Enter deja el texto en el 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 = ''
})

Pon el foco en #barcode antes de la lectura. preventDefault() evita que un formulario padre se envíe una segunda vez. Si el lector envía Tab en su lugar, lee el valor en ese keydown y deja que el navegador mueva el foco. Si no envía ninguno de los dos, envía el campo desde un botón u otra acción explícita. Una pausa al teclear es solo una heurística del final de una lectura.

Nada en esos eventos identifica el dispositivo USB. Una persona, una macro o el emulador pueden producir la misma secuencia. La validación corresponde a la carga útil. El flujo en el navegador, incluido Tab y una entrada vacía, está en Cómo probar lectores de códigos de barras en aplicaciones web.

Cómo funcionan los lectores serie en las aplicaciones

Una integración serie abre un puerto, lee octetos, los parte en mensajes y gestiona que el puerto desaparezca. En el escritorio, eso es la API serie del sistema operativo o una biblioteca del fabricante. En un navegador, la única opción integrada es la Web Serial API, y solo en los navegadores que la implementan.

Web Serial está disponible en los navegadores basados en Chromium. Firefox y Safari no la ofrecen. La página debe ser un contexto seguro, lo que significa HTTPS o localhost. requestPort() tiene que ejecutarse desde un gesto del usuario, y el usuario debe elegir el puerto en el aviso del navegador. Un lector en cuña de teclado no aparece en esa lista, porque no es un dispositivo serie. Web Serial tampoco puede ver un puerto serie que el sistema operativo no haya expuesto.

La velocidad en baudios del ejemplo es un punto de partida que sustituyes por el valor del manual. El bucle trata CR o LF como el final de un mensaje y consume un par CRLF como un solo terminador. Si tu lector usa otro marco, esta división es incorrecta aunque el puerto esté abierto.

<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>

El bucle de lectura sigue hasta que el flujo termina o la lectura falla. Desconectar el lector suele rechazar la lectura. releaseLock() y close() se ejecutan en finally. Los puertos ya aprobados para este origen se pueden listar con navigator.serial.getPorts() sin volver a mostrar el aviso. La primera aprobación sigue exigiendo al usuario.

Una aplicación de escritorio sigue la misma idea con la API serie de la plataforma: abrir, leer, encuadrar y volver a abrir cuando el dispositivo regresa. Esta página no inventa órdenes del fabricante. Si el lector espera un protocolo propietario, ese protocolo está en la documentación del fabricante.

¿Cuál es mejor: HID o serie?

Ningún modo es mejor para todos los productos. Usa el modo que el lector ofrece de verdad y el modo que la aplicación puede leer.

Elige HID cuando

  • La aplicación ya acepta entrada de teclado en un campo con foco.
  • Quieres que un formulario o una pantalla de POS funcione sin código de dispositivo.
  • El flujo de trabajo puede garantizar el foco antes de cada lectura.
  • Enter o Tab coincide con la forma en que ese formulario confirma o avanza.

Plantéate el serie cuando

  • Las lecturas deben llegar mientras el foco está en un cuadro de diálogo, en un botón o en ninguna parte.
  • Los octetos del lector deben quedar separados de lo que se teclea.
  • La aplicación puede abrir un puerto, encuadrar mensajes y recuperarse cuando se desconecta el dispositivo.
  • El anfitrión puede conceder permiso a ese puerto y ningún otro proceso lo necesita al mismo tiempo.

Un lector que solo se enumera como teclado no se puede pasar a serie con software en el anfitrión. Confirma los modos en el manual antes de diseñar la integración.

Cambiar entre HID y serie

Algunos lectores cambian de modo cuando lees un código de barras de configuración del manual de ese fabricante, o cuando escribes un perfil con la utilidad del fabricante. Otros están construidos como una sola interfaz y no tienen nada que cambiar.

No hay un código de barras de configuración que cambie todas las marcas. Una secuencia impresa para otro modelo puede no hacer nada, o dejar el lector en un modo inesperado. Después de cualquier cambio, comprueba qué muestra el sistema operativo: un teclado, un puerto COM o ambos. Luego prueba la ruta que usa tu aplicación. La Guía de configuración del lector de códigos de barras describe los grupos de ajustes habituales. No sustituye al manual.

Probar un lector HID

  1. Conecta el lector y confirma que está en modo de cuña de teclado. Un editor de texto debe recibir caracteres cuando un campo de ese editor tiene el foco.
  2. Abre el Probador de entrada de códigos de barras.
  3. Haz clic en Start Test o en el área de lectura. Se pone azul cuando está listo. La página no toma el foco por sí sola.
  4. Lee un código de barras cuya carga útil ya conoces.
  5. Compara el valor capturado y el número de caracteres con esa carga útil.
  6. Lee el sufijo: ENTER, TAB o None. Enter y Tab no forman parte de la cadena del código de barras.

El probador registra los eventos de teclado que el navegador puede ver. No puede leer un puerto serie y no puede identificar el dispositivo USB. Cuando la separación media entre caracteres es inferior a 100 ms, informa de ese tiempo. El tiempo no es una identificación del hardware. Para cada keydown, incluidos key y code, usa el Probador de eventos de teclado. Un repaso de QA más amplio está en Cómo probar la entrada de un lector de códigos de barras.

Probar un lector serie

El Probador de entrada de códigos de barras no abre un puerto COM. Una prueba serie necesita un programa que pueda abrir el puerto que expone el lector.

  1. Confirma que el lector está en un modo serie y que el sistema operativo lista un puerto cuando está conectado. Desconéctalo y comprueba que el puerto desaparece.
  2. Anota el nombre del puerto. Es específico del sistema operativo y puede cambiar en la siguiente conexión.
  3. Abre el puerto desde una aplicación compatible: un terminal serie, tu aplicación de escritorio o el ejemplo de Web Serial de arriba en un navegador Chromium con HTTPS o localhost.
  4. Ajusta la velocidad en baudios, los bits de datos, la paridad y los bits de parada cuando el manual los especifique. No uses valores inventados.
  5. Lee un código de barras conocido.
  6. Compara los octetos o el texto descodificado con esa carga útil.
  7. Comprueba el encuadre. Busca un prefijo y CR, LF o CRLF después de los datos, solo si eso es lo que configuró el manual.

Si la apertura del puerto falla porque está ocupado, cierra el otro programa que lo retiene. Si el texto es basura, los ajustes de línea no coinciden con el dispositivo. Si el puerto no aparece nunca, el lector puede seguir en modo teclado, puede faltar el controlador o puede que el usuario del sistema no tenga permiso para abrir dispositivos serie.

Problemas habituales

El lector funciona en un editor de texto y no en la aplicación de destino. El dispositivo está escribiendo. El destino no tiene el foco, o un escuchador de keydown descarta las teclas. Empieza por El lector funciona en Notepad pero no en el POS.

El lector no escribe en ningún campo de texto. Puede estar en modo serie, apagado o sin leer el símbolo. Un lector en modo serie no escribe. Busca un puerto COM antes de depurar el campo. El lector de códigos de barras no funciona separa un lector muerto de la interfaz equivocada.

Falta el puerto serie. El modo teclado no crea un puerto COM. Un controlador ausente, un cable solo de carga o un lector sin modo serie producen el mismo síntoma. Observa la lista de dispositivos del sistema mientras conectas el lector.

El puerto serie ya está en uso. Solo un proceso puede leerlo. Cierra el terminal o la otra copia de la aplicación y ábrelo de nuevo.

Los ajustes de comunicación son incorrectos. Una velocidad en baudios, una paridad o unos bits de parada que no coinciden parecen caracteres al azar. Pon los valores del manual de ese modelo y vuelve a leer un código conocido.

ENTER o TAB no llegan nunca. Es un ajuste de sufijo de la cuña. El probador de entrada informa None. Consulta Al lector de códigos de barras le falta ENTER y la guía de sufijos enlazada arriba. Un lector serie no envía la tecla Enter. Puede enviar octetos CR o LF en su lugar.

Los caracteres son incorrectos en un lector en cuña. La distribución de teclado del lector y la del sistema operativo pueden no coincidir. Los octetos serie no se reasignan con esa distribución. Consulta Distribución de teclado incorrecta en el lector de códigos de barras.

El navegador no puede acceder al lector. Un lector en cuña no aparecerá en el aviso de Web Serial. Firefox y Safari no tienen Web Serial API. Una página que no sea HTTPS o localhost no puede usarla. El usuario también puede cerrar el aviso del puerto.

La aplicación pierde el lector después de desconectarlo. Un lector en cuña vuelve como teclado, y la siguiente lectura sigue exigiendo el foco. Un puerto serie desaparece hasta que la aplicación abre el puerto nuevo. El nombre puede no coincidir con el anterior.

Escenarios de integración

Aplicaciones web

La cuña de teclado encaja con una entrada enfocada y con los eventos DOM ordinarios. El acceso serie dentro de la página significa Web Serial en un navegador compatible, un contexto seguro y un puerto elegido por el usuario. Una página que deba admitir Firefox, Safari y quioscos desatendidos no puede depender solo de Web Serial. Un ayudante local puede poseer el puerto COM y reenviar los códigos de barras completos a la página. Ese ayudante es software aparte. La página no debería esperar que una prueba en cuña lo ejercite.

Sistemas POS

Un POS que pone el foco en el campo de artículo y confirma con Enter es una integración en cuña. Un POS que debe leer mientras hay un cuadro modal abierto, o que debe ignorar el teclado, es una integración serie. Mezclarlos produce lecturas en el campo equivocado o lecturas que no llegan nunca. Haz coincidir el modo del lector con la pantalla que está de verdad en servicio.

Aplicaciones de escritorio

Una aplicación de escritorio puede aceptar la entrada en cuña en el control que tenga el foco, o abrir el puerto COM virtual y mantener una sesión durante la vida del proceso. La propiedad del puerto, la reconexión y el encuadre forman parte de esa sesión. El foco no.

Automatización de QA

El Barcode Scanner Emulator escribe un valor que eliges en la aplicación con el foco y puede enviar ENTER, TAB o ningún sufijo. Eso cubre las regresiones de la cuña de teclado: foco, validación y tratamiento del sufijo. No crea un puerto COM virtual, no enumera dispositivos USB ni reproduce la velocidad en baudios ni el encuadre. Las pruebas serie siguen necesitando un puerto serie y un lector, o un doble de prueba que escriba el mismo encuadre de octetos que analiza tu aplicación.

Aplicaciones de quiosco

Un quiosco que usa entrada en cuña tiene que mantener el campo de lectura enfocado a través de cuadros de diálogo, protectores de pantalla y mensajes de error. Un foco perdido y la siguiente lectura cae en un atajo o en nada. Un quiosco que usa serie puede leer el puerto sin ese foco, y debe conservar el permiso sobre el dispositivo y volver a abrir el puerto tras un corte de alimentación o un tirón del cable.

Dónde encaja Barcode Scanner Emulator

El Barcode Scanner Emulator es una aplicación de escritorio para Windows, macOS y Linux. Reproduce la ruta de teclado que usa un lector en cuña. Introduces el texto, eliges un retraso de escritura y eliges un sufijo entre ninguno, ENTER o TAB. Un atajo global escribe ese texto en la aplicación con el foco.

Úsalo para desarrollar formularios de estilo HID y comprobar sus regresiones cuando el lector no está sobre la mesa. Combínalo con el Probador de entrada de códigos de barras para ver el valor, las teclas de prefijo y el sufijo que recibió el navegador.

No emula un dispositivo serie USB, un puerto COM virtual, una enumeración USB ni una descodificación óptica. Esos comportamientos siguen perteneciendo al hardware, o a un doble de prueba serie que tú controlas.