Aller au contenu

Barcode Scanner Emulator

Lecteurs de codes-barres USB HID et série

Un lecteur en émulation clavier USB HID tape le code-barres décodé dans l'application qui a le focus. Un lecteur USB série expose une interface série, souvent comme un port COM virtuel, et l'application doit ouvrir ce port et lire les octets. USB est le câble et le bus. HID et série sont deux façons différentes de présenter les données.

Choisissez l'interface que l'application peut vraiment lire. Un champ de caisse qui accepte déjà la frappe est un problème d'émulation clavier. Un service qui doit recevoir des lectures alors qu'aucun champ de texte n'a le focus, ou qui doit garder les octets du lecteur à part du clavier, est un problème série. Beaucoup de lecteurs n'offrent qu'un de ces modes. Certains peuvent basculer. Le manuel de ce modèle est la liste des modes que vous pouvez tester.

Le guide Émulation clavier HID explique en détail le chemin des frappes. Comment fonctionnent les lecteurs de codes-barres ? traite la capture et le décodage. Cette page compare les deux interfaces hôte et les tests qui appartiennent à chacune.

Qu'est-ce que le mode émulation clavier USB HID ?

En mode clavier USB HID, le lecteur s'énumère comme un clavier. Le système d'exploitation charge son pilote clavier habituel. Après un décodage, le lecteur envoie les caractères comme des frappes vers le contrôle qui a le focus clavier. Un formulaire web, un champ article de POS ou une zone de texte de bureau peut accepter cette saisie sans code propre au lecteur.

Le focus décide de la destination. Si le champ prévu n'a pas le focus, les caractères aboutissent dans un autre contrôle ou ils sont perdus. Le lecteur ne clique pas et ne déplace pas le pointeur.

Un suffixe configuré peut suivre la charge utile. Enter envoie de nombreux formulaires à un seul champ. Tab déplace le focus vers le contrôle suivant. Aucune de ces touches n'est garantie. Les choix de suffixe sont traités dans Suffixes ENTER et TAB des lecteurs de codes-barres.

Les événements clavier ordinaires n'incluent ni le fabricant du lecteur, ni le numéro de série, ni un indicateur disant que les touches viennent d'un lecteur. Les navigateurs qui mettent en œuvre WebHID refusent encore les interfaces clavier, donc une page ne peut pas ouvrir l'appareil en émulation et lire les rapports HID bruts.

Qu'est-ce que le mode série USB d'un lecteur de codes-barres ?

En mode USB série, le lecteur ne tape pas. Il expose une interface série sur USB. Le système d'exploitation présente en général cette interface comme un port COM virtuel : un nom COM sous Windows, un périphérique cu ou tty sous macOS, ou un périphérique ttyACM ou ttyUSB sous Linux. Le nom est attribué par le pilote et peut changer une fois le lecteur débranché.

Un port COM virtuel n'est pas un port RS-232 physique. RS-232 est une interface électrique, avec son propre connecteur et ses niveaux de tension, qu'un ordinateur lit à travers une UART. L'USB série utilise un câble USB. L'application ouvre toujours un port série et lit des octets, mais le signal sur le fil est de l'USB. Certains produits sont un vrai lecteur RS-232 plus un adaptateur USB vers série. D'autres mettent en œuvre USB CDC et ne parlent jamais RS-232. Traitez le port que le système d'exploitation vous montre comme le point d'intégration, et ne supposez pas que les détails électriques correspondent.

L'application ouvre le port, lit le flux d'octets et décide où un message commence et finit. Un cadre courant est le texte du code-barres suivi de CR (0x0D), de LF (0x0A), ou de CR puis LF. Ce cadrage est un réglage de l'appareil, pas une règle de l'USB. Un octet de préfixe tel que STX est aussi possible. Le guide Préfixe et suffixe du lecteur de codes-barres : guide complet sépare ces octets de la touche Enter qu'envoie un lecteur en émulation clavier.

Le débit en bauds, les bits de données, la parité et les bits d'arrêt comptent sur une vraie UART et sur beaucoup d'adaptateurs USB vers série. Un mauvais débit produit du charabia plutôt qu'une erreur nette. Certains périphériques COM virtuels USB CDC ignorent le débit demandé par l'hôte et livrent quand même les octets. Il n'existe pas un réglage unique qui convienne à chaque lecteur série virtuel. Utilisez le débit et le cadrage du manuel de ce modèle, puis confirmez-les avec un code-barres connu.

Le processus qui tient le port ouvert reçoit les données. Le focus clavier ne choisit pas la destination. Un autre programme qui a déjà le port ouvert bloque une seconde ouverture. Débrancher le lecteur retire le port. Le rebrancher peut créer un nouveau nom, et l'application doit ouvrir ce port de nouveau.

HID et série

Caractéristique Émulation clavier HID USB série
Remise des données Saisie de type clavier Flux d'octets série
Focus de saisie requis Oui. Les frappes suivent le contrôle qui a le focus Non. Les octets vont au processus qui a ouvert le port
Intégration navigateur Saisie ordinaire et événements clavier Web Serial là où le navigateur le prend en charge, ou un logiciel hors de la page
Contrôle par l'application Limité au comportement clavier, au focus et aux suffixes L'application lit le flux et le cadre
Identification de l'appareil Absente des événements clavier ordinaires Le système d'exploitation peut montrer un nom de port. Une identité stable dépend encore du pilote
Configuration Réglages du lecteur, y compris le suffixe et la disposition de clavier Réglages du lecteur plus les réglages de port de l'hôte que l'appareil utilise vraiment
Usage typique Formulaires et saisie d'articles en POS Intégrations dédiées qui possèdent l'appareil

Ce sont les cas habituels. Un modèle, un système d'exploitation et un pilote donnés peuvent différer. Un lecteur Bluetooth en mode clavier HID suit la colonne émulation clavier au niveau de l'application. Bluetooth SPP suit la colonne série.

Comment les lecteurs HID fonctionnent dans les applications web

Une lecture en émulation clavier met à jour l'élément qui a le focus. Les caractères imprimables déclenchent keydown, puis input. Enter et Tab déclenchent keydown et n'insèrent pas de caractère dans un champ de texte normal. event.key vaut "Enter" ou "Tab" pour ces touches, et une chaîne d'un caractère pour un caractère imprimable. event.code nomme la touche physique et peut rester le même lorsqu'un décalage de disposition de clavier change event.key.

L'écouteur ci-dessous ne valide le champ que lorsque Enter arrive. Un lecteur sans suffixe Enter laisse le texte dans le champ.

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 = ''
})

Donnez le focus à #barcode avant la lecture. preventDefault() empêche un formulaire parent de se soumettre une seconde fois. Si le lecteur envoie Tab à la place, lisez la valeur dans ce keydown et laissez le navigateur déplacer le focus. S'il n'envoie ni l'un ni l'autre, soumettez le champ depuis un bouton ou une autre action explicite. Une pause dans la frappe n'est qu'une heuristique de fin de lecture.

Rien dans ces événements n'identifie le périphérique USB. Une personne, une macro ou l'émulateur peut produire la même séquence. La validation porte sur la charge utile. Le parcours dans le navigateur, y compris Tab et une saisie vide, est dans Comment tester les lecteurs de codes-barres dans les applications web.

Comment les lecteurs série fonctionnent dans les applications

Une intégration série ouvre un port, lit des octets, les découpe en messages et gère la disparition du port. Sur le bureau, c'est l'API série du système d'exploitation ou une bibliothèque du fabricant. Dans un navigateur, la seule option intégrée est la Web Serial API, et seulement dans les navigateurs qui la mettent en œuvre.

Web Serial est disponible dans les navigateurs fondés sur Chromium. Firefox et Safari ne le fournissent pas. La page doit être un contexte sécurisé, ce qui veut dire HTTPS ou localhost. requestPort() doit s'exécuter depuis un geste de l'utilisateur, et l'utilisateur doit choisir le port dans l'invite du navigateur. Un lecteur en émulation clavier n'apparaît pas dans cette liste, parce que ce n'est pas un périphérique série. Web Serial ne peut pas non plus voir un port série que le système d'exploitation n'a pas exposé.

Le débit en bauds de l'exemple est un point de départ que vous remplacez par la valeur du manuel. La boucle traite CR ou LF comme la fin d'un message et consomme une paire CRLF comme un seul terminateur. Si votre lecteur utilise un autre cadre, ce découpage est faux même lorsque le port est ouvert.

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

La boucle de lecture tourne jusqu'à ce que le flux se termine ou que la lecture échoue. Débrancher le lecteur rejette en général la lecture. releaseLock() et close() s'exécutent dans finally. Les ports déjà approuvés pour cette origine peuvent être listés avec navigator.serial.getPorts() sans montrer de nouveau l'invite. La première approbation exige encore l'utilisateur.

Une application de bureau suit la même idée avec l'API série de la plateforme : ouvrir, lire, cadrer et rouvrir après le retour de l'appareil. Cette page n'invente pas de commandes de fabricant. Si le lecteur attend un protocole propriétaire, ce protocole est dans la documentation du fabricant.

Lequel est le meilleur : HID ou série ?

Aucun mode n'est meilleur pour chaque produit. Utilisez le mode que le lecteur offre vraiment et le mode que l'application peut lire.

Choisissez HID lorsque

  • L'application accepte déjà la saisie clavier dans un champ qui a le focus.
  • Vous voulez qu'un formulaire ou un écran de POS fonctionne sans code d'appareil.
  • Le flux de travail peut garantir le focus avant chaque lecture.
  • Enter ou Tab correspond à la façon dont ce formulaire valide ou avance.

Envisagez le série lorsque

  • Les lectures doivent arriver alors que le focus est dans une boîte de dialogue, sur un bouton, ou nulle part.
  • Les octets du lecteur doivent rester séparés de la frappe.
  • L'application peut ouvrir un port, cadrer les messages et se rétablir lorsque l'appareil est débranché.
  • L'hôte peut accorder l'autorisation sur ce port et aucun autre processus n'en a besoin en même temps.

Un lecteur qui ne s'énumère que comme un clavier ne peut pas passer en série par un logiciel sur l'hôte. Confirmez les modes dans le manuel avant de concevoir l'intégration.

Basculer entre HID et série

Certains lecteurs changent de mode lorsque vous lisez un code-barres de configuration tiré du manuel de ce fabricant, ou lorsque vous écrivez un profil avec l'utilitaire du fabricant. D'autres sont construits comme une seule interface et n'ont rien à basculer.

Il n'existe pas de code-barres de configuration qui change toutes les marques. Une séquence imprimée pour un autre modèle peut ne rien faire, ou laisser le lecteur dans un mode inattendu. Après tout changement, vérifiez ce que montre le système d'exploitation : un clavier, un port COM, ou les deux. Testez ensuite le chemin que votre application utilise. Le Guide de configuration du lecteur de codes-barres décrit les groupes de réglages habituels. Il ne remplace pas le manuel.

Tester un lecteur HID

  1. Branchez le lecteur et confirmez qu'il est en mode émulation clavier. Un éditeur de texte doit recevoir des caractères lorsqu'un champ de cet éditeur a le focus.
  2. Ouvrez le testeur de saisie de codes-barres.
  3. Cliquez sur Start Test, ou cliquez sur la zone de lecture. Elle devient bleue lorsqu'elle est prête. La page ne prend pas le focus d'elle-même.
  4. Lisez un code-barres dont vous connaissez déjà la charge utile.
  5. Comparez la valeur capturée et le nombre de caractères à cette charge utile.
  6. Lisez le suffixe : ENTER, TAB ou None. Enter et Tab ne font pas partie de la chaîne du code-barres.

Le testeur enregistre les événements clavier que le navigateur peut voir. Il ne peut pas lire un port série, et il ne peut pas identifier le périphérique USB. Lorsque l'écart moyen entre les caractères est inférieur à 100 ms, il signale ce minutage. Le minutage n'est pas une identification du matériel. Pour chaque keydown, y compris key et code, utilisez le testeur d'événements clavier. Un passage d'assurance qualité plus large est dans Comment tester la saisie d'un lecteur de codes-barres.

Tester un lecteur série

Le testeur de saisie de codes-barres n'ouvre pas de port COM. Un test série exige un programme capable d'ouvrir le port que le lecteur expose.

  1. Confirmez que le lecteur est dans un mode série et que le système d'exploitation liste un port lorsqu'il est branché. Débranchez-le et vérifiez que le port disparaît.
  2. Notez le nom du port. Il est propre au système d'exploitation et peut changer au branchement suivant.
  3. Ouvrez le port depuis une application compatible : un terminal série, votre application de bureau, ou l'exemple Web Serial ci-dessus dans un navigateur Chromium en HTTPS ou localhost.
  4. Réglez le débit en bauds, les bits de données, la parité et les bits d'arrêt lorsque le manuel les précise. Écartez les valeurs inventées.
  5. Lisez un code-barres connu.
  6. Comparez les octets ou le texte décodé à cette charge utile.
  7. Vérifiez le cadrage. Cherchez un préfixe, et CR, LF ou CRLF après les données, seulement si c'est ce que le manuel a configuré.

Si l'ouverture du port échoue parce qu'il est occupé, fermez l'autre programme qui le détient. Si le texte est du charabia, les réglages de ligne ne correspondent pas à l'appareil. Si le port n'apparaît jamais, le lecteur est peut-être encore en mode clavier, le pilote peut manquer, ou l'utilisateur du système n'a peut-être pas le droit d'ouvrir les périphériques série.

Problèmes courants

Le lecteur fonctionne dans un éditeur de texte et pas dans l'application cible. L'appareil tape. La cible n'a pas le focus, ou un écouteur keydown écarte les touches. Commencez par Le lecteur fonctionne dans Notepad mais pas dans le POS.

Le lecteur ne tape dans aucun champ de texte. Il est peut-être en mode série, éteint, ou il ne lit pas le symbole. Un lecteur en mode série ne tape pas. Cherchez un port COM avant de diagnostiquer le champ. Le lecteur de codes-barres ne fonctionne pas sépare un lecteur mort de la mauvaise interface.

Le port série est absent. Le mode clavier ne crée pas de port COM. Un pilote manquant, un câble de charge seule ou un lecteur sans mode série produisent le même symptôme. Surveillez la liste des appareils du système pendant que vous branchez le lecteur.

Le port série est déjà utilisé. Un seul processus peut le lire. Fermez le terminal ou l'autre copie de l'application, puis ouvrez-le de nouveau.

Les réglages de communication sont faux. Un débit, une parité ou des bits d'arrêt qui ne correspondent pas ressemblent à des caractères au hasard. Posez les valeurs du manuel de ce modèle, puis relisez un code connu.

ENTER ou TAB n'arrive jamais. C'est un réglage de suffixe d'émulation clavier. Le testeur de saisie signale None. Voir Le lecteur de codes-barres n'envoie pas ENTER et le guide des suffixes lié plus haut. Un lecteur série n'envoie pas la touche Enter. Il peut envoyer des octets CR ou LF à la place.

Les caractères sont faux sur un lecteur en émulation clavier. La disposition de clavier du lecteur et celle du système d'exploitation peuvent diverger. Les octets série ne sont pas réassociés par cette disposition. Voir Mauvaise disposition de clavier du lecteur de codes-barres.

Le navigateur ne peut pas accéder au lecteur. Un lecteur en émulation clavier n'apparaîtra pas dans l'invite Web Serial. Firefox et Safari n'ont pas de Web Serial API. Une page qui n'est pas en HTTPS ou localhost ne peut pas l'utiliser. L'utilisateur peut aussi fermer l'invite de port.

L'application perd le lecteur après qu'il a été débranché. Un lecteur en émulation clavier revient comme un clavier, et la lecture suivante exige encore le focus. Un port série a disparu jusqu'à ce que l'application ouvre le nouveau port. Le nom peut ne pas correspondre au précédent.

Scénarios d'intégration

Applications web

L'émulation clavier convient à une saisie qui a le focus et aux événements DOM ordinaires. L'accès série dans la page veut dire Web Serial dans un navigateur qui le prend en charge, un contexte sécurisé et un port choisi par l'utilisateur. Une page qui doit prendre en charge Firefox, Safari et des bornes sans surveillance ne peut pas dépendre de Web Serial seule. Un assistant local peut posséder le port COM et transmettre les codes-barres complets à la page. Cet assistant est un logiciel distinct. La page ne doit pas s'attendre à ce qu'un test en émulation clavier l'exerce.

Systèmes de POS

Un POS qui place le focus dans le champ article et valide sur Enter est une intégration en émulation clavier. Un POS qui doit lire pendant qu'une fenêtre modale est ouverte, ou qui doit ignorer le clavier, est une intégration série. Les mélanger produit des lectures dans le mauvais champ ou des lectures qui n'arrivent jamais. Faites correspondre le mode du lecteur à l'écran qui est réellement en service.

Applications de bureau

Une application de bureau peut accepter la saisie en émulation clavier dans le contrôle qui a le focus, ou ouvrir le port COM virtuel et tenir une session pendant la vie du processus. La possession du port, la reconnexion et le cadrage font partie de cette session. Le focus n'en fait pas partie.

Automatisation des tests

Barcode Scanner Emulator tape une valeur que vous choisissez dans l'application qui a le focus et peut envoyer ENTER, TAB ou aucun suffixe. Cela couvre les régressions d'émulation clavier : focus, validation et traitement du suffixe. Il ne crée pas de port COM virtuel, n'énumère pas les périphériques USB et ne reproduit ni le débit en bauds ni le cadrage. Les tests série ont encore besoin d'un port série et d'un lecteur, ou d'un double de test qui écrit le même cadrage d'octets que votre application analyse.

Applications de borne

Une borne qui utilise la saisie en émulation clavier doit garder le champ de lecture focalisé à travers les boîtes de dialogue, les économiseurs d'écran et les messages d'erreur. Un focus perdu, et la lecture suivante touche un raccourci ou rien. Une borne qui utilise le série peut lire le port sans ce focus, et elle doit conserver l'autorisation sur l'appareil et rouvrir le port après une coupure d'alimentation ou un câble retiré.

Où se place Barcode Scanner Emulator

Barcode Scanner Emulator est une application de bureau pour Windows, macOS et Linux. Il reproduit le chemin clavier qu'utilise un lecteur en émulation clavier. Vous saisissez le texte, vous choisissez un délai de frappe et vous choisissez un suffixe parmi aucun, ENTER ou TAB. Un raccourci global tape ce texte dans l'application qui a le focus.

Utilisez-le pour développer les formulaires de style HID et en vérifier les régressions lorsque le lecteur n'est pas sur le bureau. Associez-le au testeur de saisie de codes-barres pour voir la valeur, les touches de préfixe et le suffixe que le navigateur a reçus.

Il n'émule pas un périphérique USB série, un port COM virtuel, une énumération USB ni un décodage optique. Ces comportements appartiennent encore au matériel, ou à un double de test série que vous contrôlez.