跳至內容

Barcode Scanner Emulator

USB HID 與序列埠條碼掃描器

USB HID keyboard wedge 掃描器會把解碼後的條碼打進目前取得焦點的應用程式。USB 序列埠掃描器則提供序列介面,通常呈現為虛擬 COM 埠,應用程式必須自行開啟該埠並讀取位元組。USB 指的是纜線與匯流排。HID 與序列埠是兩種不同的資料呈現方式。

先選應用程式真正讀得到的介面。結帳欄位本來就接受打字,那是 keyboard wedge 要處理的事。服務必須在沒有文字欄取得焦點時收到掃描,或必須把掃描器位元組與鍵盤分開,那就是序列埠要處理的事。許多掃描器只做其中一種模式。有的可以切換。該機型手冊列出的,才是你能測的模式。

HID keyboard wedge 說明把按鍵路徑講清楚。條碼掃描器如何運作?涵蓋擷取與解碼。這一頁比較兩種主機介面,以及各自該做的測試。

什麼是 USB HID keyboard wedge 模式?

在 USB HID 鍵盤模式裡,掃描器會列舉成鍵盤。作業系統載入平常的鍵盤驅動程式。解碼完成後,掃描器把字元當成按鍵,送給目前握有鍵盤焦點的控制項。網頁表單、POS 商品欄或桌面文字方塊都能收下這份輸入,不必寫掃描器專用程式。

目的地由焦點決定。預定欄位沒有焦點時,字元會掉進別的控制項,或是直接消失。掃描器不會點擊,也不會移動指標。

設定好的後綴可能接在承載資料後面。Enter 會送出許多單一欄位表單。Tab 把焦點移到下一個控制項。這兩個鍵都沒有保證。後綴怎麼選,見條碼掃描器的 ENTER 與 TAB 後綴。

一般鍵盤事件不含掃描器的廠商、序號,也沒有旗標說明這些鍵來自掃描器。實作了 WebHID 的瀏覽器仍會拒絕鍵盤介面,所以頁面開不了 wedge 裝置,也讀不到原始 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 這類前綴位元組也有可能。條碼掃描器前綴與後綴:完整說明把這些位元組和 wedge 掃描器送出的 Enter 鍵分開說明。

鮑率、資料位元、同位與停止位元,在真正的 UART 以及許多 USB 轉序列轉接器上有意義。速率設錯得到的是亂碼,不是乾淨的錯誤。有些 USB CDC 虛擬 COM 裝置會不理會主機要求的鮑率,照樣送出位元組。沒有一組設定適用於每一台虛擬序列掃描器。採用該機型手冊裡的速率與框架,再用已知條碼核對。

握著埠不放的處理程序才收得到資料。鍵盤焦點不決定目的地。另一支已經開啟該埠的程式會擋住第二次開啟。拔掉掃描器,埠就消失。插回去可能產生新名稱,應用程式必須再把那個埠打開。

HID 與序列埠

項目 HID keyboard wedge USB 序列埠
資料如何送達 鍵盤式輸入 序列位元組串流
是否需要輸入焦點 需要。按鍵跟著取得焦點的控制項走 不需要。位元組進入開啟該埠的處理程序
瀏覽器整合 一般輸入與鍵盤事件 瀏覽器支援時用 Web Serial,否則用頁面以外的軟體
應用程式能控制什麼 限於鍵盤行為、焦點與後綴 應用程式讀取串流並切割訊框
裝置識別 一般鍵盤事件給不出來 作業系統可以顯示埠名。穩定身分仍看驅動程式
設定 掃描器設定,含後綴與鍵盤配置 掃描器設定,加上裝置實際採用的主機埠設定
常見用途 表單與 POS 商品登錄 獨佔裝置的專用整合

以上是常見情形。機型、作業系統與驅動程式都可能不一樣。處於 HID 鍵盤模式的 Bluetooth 掃描器,在應用程式層走 wedge 這一欄。Bluetooth SPP 走序列埠這一欄。

HID 掃描器在 Web 應用程式裡怎麼運作

一次 wedge 掃描會更新取得焦點的元素。可列印字元先觸發 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 與空白輸入的瀏覽器流程,見如何在 Web 應用程式中測試條碼掃描器。

序列埠掃描器在應用程式裡怎麼運作

序列整合要開啟埠、讀取位元組、把位元組切成訊息,並處理埠消失。在桌面上,這是作業系統的序列 API 或廠商程式庫。在瀏覽器裡,唯一內建的選項是 Web Serial API,而且只有實作它的瀏覽器才有。

Web Serial 可用於以 Chromium 為基礎的瀏覽器。Firefox 與 Safari 不提供。頁面必須位於安全內容,也就是 HTTPS 或 localhost。requestPort() 必須從使用者手勢執行,使用者也必須在瀏覽器提示中選取埠。keyboard wedge 掃描器不會出現在那份清單,因為它不是序列裝置。作業系統沒有暴露的序列埠,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. 接上掃描器,並確認它處在 keyboard wedge 模式。該編輯器裡的欄位取得焦點時,文字編輯器應該收到字元。
  2. 開啟條碼輸入測試器。
  3. 點 Start Test,或點掃描區域。就緒時它會轉成藍色。頁面不會自己取得焦點。
  4. 掃描一張你已經知道承載資料的條碼。
  5. 把擷取到的值與字元數和該承載資料比較。
  6. 讀取後綴:ENTER、TAB 或 None。Enter 與 Tab 不屬於條碼字串。

測試器記錄瀏覽器看得到的鍵盤事件。它讀不了序列埠,也認不出 USB 裝置。字元之間的平均間隔低於 100 ms 時,它會回報該時序。時序不是硬體識別。每一次 keydown,包含 key 與 code,請用鍵盤事件測試器。範圍更廣的 QA 流程見如何測試條碼掃描器輸入。

測試序列埠掃描器

條碼輸入測試器不會開啟 COM 埠。序列測試需要一支能開啟掃描器所暴露之埠的程式。

  1. 確認掃描器處於序列模式,而且接上時作業系統會列出一個埠。拔掉它,檢查埠是否消失。
  2. 記下埠名。它隨作業系統而異,下一次插入時可能改變。
  3. 從相容的應用程式開啟埠:序列終端機、你的桌面應用程式,或在 HTTPS 或 localhost 上的 Chromium 瀏覽器裡使用上面的 Web Serial 範例。
  4. 手冊有指定時,設定鮑率、資料位元、同位與停止位元。略過編造的值。
  5. 掃描一張已知條碼。
  6. 把位元組或解碼文字與該承載資料比較。
  7. 檢查框架。只有手冊如此設定時,才尋找前綴,以及資料之後的 CR、LF 或 CRLF。

若因為埠忙碌而開啟失敗,關掉佔用它的另一支程式。若文字是亂碼,線路設定與裝置不符。若埠始終不出現,掃描器可能仍在鍵盤模式,驅動程式可能缺失,或該 OS 使用者可能不被允許開啟序列裝置。

常見問題

掃描器在文字編輯器裡可用,在目標應用程式裡卻不行。 裝置正在打字。目標沒有焦點,或某個 keydown 聆聽器把按鍵丟掉了。先從掃描器在 Notepad 中可用但在 POS 中不可用著手。

掃描器不打進任何文字欄。 它可能處於序列模式、已經關機,或沒有讀到符號。序列模式的掃描器不會打字。除錯欄位之前先找 COM 埠。條碼掃描器無法運作把壞掉的掃描器與錯誤的介面分開。

序列埠不見了。 鍵盤模式不會建立 COM 埠。缺少驅動程式、只能充電的纜線,或沒有序列模式的掃描器,會出現同樣的現象。插入掃描器時看著作業系統的裝置清單。

序列埠已被佔用。 只有一個處理程序能讀它。關掉終端機或應用程式的另一份複本,然後再開啟。

通訊設定錯誤。 鮑率、同位或停止位元不合,看起來像隨機字元。依該機型手冊設定這些值,然後再掃描一次已知碼。

ENTER 或 TAB 始終不到。 這是 wedge 後綴設定。輸入測試器會回報 None。參見條碼掃描器缺少 ENTER以及上文連結的後綴說明。序列埠掃描器不送 Enter 鍵。它可能改送 CR 或 LF 位元組。

wedge 掃描器上的字元不對。 掃描器的鍵盤配置與作業系統配置可能不一致。序列位元組不會被該配置重新對應。參見條碼掃描器鍵盤配置錯誤。

瀏覽器無法存取掃描器。 wedge 掃描器不會出現在 Web Serial 提示裡。Firefox 與 Safari 沒有 Web Serial API。不是 HTTPS 或 localhost 的頁面不能使用它。使用者也可能關掉埠提示。

拔除之後應用程式失去掃描器。 wedge 掃描器會以鍵盤身分回來,下一次掃描仍然需要焦點。序列埠會消失,直到應用程式開啟新埠。名稱可能與上一次不同。

整合情境

Web 應用程式

keyboard wedge 適合取得焦點的輸入與一般 DOM 事件。頁面內部的序列存取,代表支援該能力的瀏覽器裡的 Web Serial、安全內容,以及使用者選取的埠。必須支援 Firefox、Safari 與無人看管自助機的頁面,不能只靠 Web Serial。本機輔助程式可以擁有 COM 埠,並把完整條碼轉給頁面。該輔助程式是獨立軟體。頁面仍不該指望一次 wedge 測試去涵蓋它。

POS 系統

把焦點放在商品欄並在 Enter 時送出的 POS,是 wedge 整合。必須在強制回應視窗開啟時掃描,或必須忽略鍵盤的 POS,是序列埠整合。兩者混用,掃描會進錯欄,或根本送不到。把掃描器模式對上實際值勤的畫面。

桌面應用程式

桌面應用程式可以在取得焦點的控制項接受 wedge 輸入,也可以開啟虛擬 COM 埠,並在處理程序存活期間維持工作階段。埠的所有權、重新連線與訊框切割屬於該工作階段。焦點不屬於。

QA 自動化

Barcode Scanner Emulator把你選定的值打進取得焦點的應用程式,並能送出 ENTER、TAB 或不送後綴。這涵蓋 keyboard wedge 回歸:焦點、驗證與後綴處理。它不建立虛擬 COM 埠,不列舉 USB 裝置,也不重現鮑率與框架。序列測試仍然需要序列埠與讀取程式,或一個寫出與應用程式所剖析相同位元組框架的測試替身。

自助機應用程式

使用 wedge 輸入的自助機,必須在對話方塊、螢幕保護與錯誤訊息之間維持掃描欄的焦點。焦點一失,下一次掃描就會打到快速鍵,或什麼都打不到。使用序列埠的自助機可以不靠該焦點來讀埠,並且必須保有裝置權限,在斷電或纜線被拔掉後重新開啟埠。

Barcode Scanner Emulator 放在哪裡

Barcode Scanner Emulator是給 Windows、macOS 與 Linux 用的桌面應用程式。它重現 wedge 掃描器使用的鍵盤路徑。你輸入文字,選擇打字延遲,並把後綴選成無、ENTER 或 TAB。全域快速鍵把該文字打進取得焦點的應用程式。

掃描器不在桌上時,用它開發並回歸 HID 式表單。搭配條碼輸入測試器,查看瀏覽器收到的值、前綴鍵與後綴。

它不模擬 USB 序列裝置、虛擬 COM 埠、USB 列舉或光學解碼。這些行為仍屬於硬體,或屬於你自己控制的序列測試替身。