コンテンツへスキップ

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 ポートとして見せます。Windows では COM 名、macOS では cu または tty デバイス、Linux では ttyACM または ttyUSB デバイスです。名前はドライバが割り当て、スキャナーを抜いたあと変わることがあります。

仮想 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-シリアル変換アダプタで意味を持ちます。レートが違うと、きれいなエラーではなく文字化けになります。一部の USB CDC 仮想 COM 機器は、ホストが要求したボーレートを無視して、それでもバイトを届けます。すべての仮想シリアルスキャナーに合う単一の設定はありません。その機種のマニュアルにあるレートと区切りを使い、既知のバーコードで確認します。

ポートを開いたままにしているプロセスがデータを受け取ります。キーボードフォーカスは宛先を選びません。すでにポートを開いている別のプログラムは、二度目のオープンを妨げます。スキャナーを抜くとポートは消えます。差し直すと新しい名前ができることがあり、アプリケーションはそのポートを開き直す必要があります。

HID とシリアル

項目 HID キーボードウェッジ USB シリアル
データの届け方 キーボード型の入力 シリアルのバイト列
入力フォーカスが必要か 必要。キー入力はフォーカスのあるコントロールに従う 不要。バイトはポートを開いたプロセスへ届く
ブラウザ連携 通常の入力とキーボードイベント ブラウザが対応していれば Web Serial。そうでなければページの外のソフトウェア
アプリケーションの制御 キーボードの動作、フォーカス、接尾辞に限られる アプリケーションがストリームを読み、区切る
機器の識別 通常のキーボードイベントからは得られない オペレーティングシステムはポート名を表示できる。安定した識別は依然ドライバに依存する
設定 スキャナーの設定。接尾辞とキーボード配列を含む スキャナーの設定に加え、機器が実際に使うホスト側のポート設定
典型的な用途 フォームと POS の商品入力 機器を専有する専用連携

これらは通常の場合です。機種、オペレーティングシステム、ドライバによって違うことがあります。HID キーボードモードの Bluetooth スキャナーは、アプリケーション層ではウェッジの列に従います。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 で値を読み、フォーカスの移動はブラウザに任せます。どちらも送らないなら、ボタンか別の明示的な操作で欄を送信します。入力の途切れは、スキャンの終わりを推測する目安にすぎません。

これらのイベントのどれにも、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 スキャナーのテスト

  1. スキャナーを接続し、キーボードウェッジモードであることを確認します。そのエディタの欄にフォーカスがあるとき、テキストエディタは文字を受け取るはずです。
  2. バーコード入力テスター を開きます。
  3. Start Test をクリックするか、スキャン領域をクリックします。準備ができると青くなります。ページは自分ではフォーカスを取りません。
  4. ペイロードがすでに分かっているバーコードをスキャンします。
  5. 取得した値と文字数を、そのペイロードと比べます。
  6. 接尾辞を読みます。ENTER、TAB、または None です。Enter と Tab はバーコード文字列の一部ではありません。

テスターが記録するのは、ブラウザから見えるキーボードイベントです。シリアルポートは読めず、USB 機器も識別できません。文字の間隔の平均が 100 ms 未満のとき、そのタイミングを報告します。タイミングはハードウェアの識別ではありません。key と code を含む各 keydown には、キーボードイベントテスター を使います。より広い QA の手順は バーコードスキャナー入力のテスト方法 にあります。

シリアルスキャナーのテスト

バーコード入力テスターは COM ポートを開きません。シリアルのテストには、スキャナーが出すポートを開けるプログラムが必要です。

  1. スキャナーがシリアルモードであり、接続されているときにオペレーティングシステムがポートを一覧することを確認します。抜いて、ポートが消えることを確認します。
  2. ポート名を書き留めます。オペレーティングシステムに固有で、次に差し込んだときに変わることがあります。
  3. 対応するアプリケーションからポートを開きます。シリアル端末、デスクトップアプリ、または HTTPS か localhost 上の Chromium ブラウザで上の Web Serial の例です。
  4. マニュアルが指定するとき、ボーレート、データビット、パリティ、ストップビットを設定します。作り出した値は使いません。
  5. 既知のバーコードをスキャンします。
  6. バイトまたは復号したテキストを、そのペイロードと比べます。
  7. 区切りを確認します。マニュアルがそう設定している場合に限り、接頭辞と、データのあとの CR、LF、または CRLF を探します。

ポートが使用中で開けないなら、それを保持しているほかのプログラムを閉じます。テキストが文字化けするなら、回線設定が機器と一致していません。ポートが一度も現れないなら、スキャナーがまだキーボードモードである、ドライバがない、または OS のユーザーがシリアル機器を開くことを許されていない、のいずれかです。

よくある問題

テキストエディタでは動き、対象のアプリケーションでは動かない。 機器は入力しています。対象にフォーカスがないか、keydown のリスナーがキーを捨てています。まず メモ帳では動くが POS では動かない から始めます。

どのテキスト欄にも入力しない。 シリアルモード、電源オフ、またはシンボルを読んでいない可能性があります。シリアルモードのスキャナーは入力しません。欄を調べる前に COM ポートを確認します。バーコードスキャナーが動作しない は、動かないスキャナーと間違ったインターフェースを分けます。

シリアルポートがない。 キーボードモードは COM ポートを作りません。ドライバがない、充電専用ケーブル、シリアルモードのないスキャナーも、同じ症状になります。スキャナーを差しながら、OS の機器一覧を見ます。

シリアルポートがすでに使用中。 読めるプロセスは一つだけです。端末か、アプリケーションのもう一つのコピーを閉じてから、開き直します。

通信設定が間違っている。 ボー、パリティ、ストップビットの不一致は、でたらめな文字に見えます。その機種のマニュアルの値を設定し、既知のコードを再びスキャンします。

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 システム

商品欄にフォーカスを置き、Enter で確定する POS は、ウェッジ連携です。モーダルが開いているあいだにスキャンしなければならない POS、またはキーボードを無視しなければならない 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 の列挙、光学的な復号はエミュレートしません。それらの動作は、依然としてハードウェア、または自分で制御するシリアルのテストダブルに属します。