콘텐츠로 건너뛰기

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는 시리얼 연동입니다. 섞으면 스캔이 잘못된 필드에 들어가거나 한 번도 도착하지 않습니다. 실제로 근무 중인 화면에 스캐너 모드를 맞춥니다.

데스크톱 애플리케이션

데스크톱 앱은 포커스가 있는 컨트롤에서 웨지 입력을 받거나, 가상 COM 포트를 열어 프로세스 수명 동안 세션을 유지할 수 있습니다. 포트 소유, 재연결, 프레이밍은 그 세션의 일부입니다. 포커스는 아닙니다.

QA 자동화

Barcode Scanner Emulator는 고른 값을 포커스가 있는 애플리케이션에 입력하고 ENTER, TAB 또는 접미사 없음을 보낼 수 있습니다. 이것은 키보드 웨지 회귀를 덮습니다. 포커스, 검증, 접미사 처리입니다. 가상 COM 포트를 만들지 않고, USB 장치를 열거하지 않으며, 전송 속도와 프레이밍을 재현하지 않습니다. 시리얼 테스트에는 여전히 시리얼 포트와 리더, 또는 애플리케이션이 파싱하는 것과 같은 바이트 프레이밍을 쓰는 테스트 더블이 필요합니다.

키오스크 애플리케이션

웨지 입력을 쓰는 키오스크는 대화 상자, 화면 보호기, 오류 메시지를 가로질러 스캔 필드의 포커스를 유지해야 합니다. 포커스를 한 번 잃으면 다음 스캔은 단축키에 닿거나 아무것에도 닿지 않습니다. 시리얼을 쓰는 키오스크는 그 포커스 없이 포트를 읽을 수 있고, 장치에 대한 권한을 유지하며 전원 손실이나 케이블이 뽑힌 뒤 포트를 다시 열어야 합니다.

Barcode Scanner Emulator가 맞는 곳

Barcode Scanner Emulator는 Windows, macOS, Linux용 데스크톱 앱입니다. 웨지 스캐너가 쓰는 키보드 경로를 재현합니다. 텍스트를 입력하고, 입력 지연을 고르고, 접미사를 없음, ENTER, TAB 중에서 고릅니다. 전역 단축키가 그 텍스트를 포커스가 있는 애플리케이션에 입력합니다.

스캐너가 책상 위에 없을 때 HID 방식 양식을 개발하고 회귀 테스트하는 데 사용합니다. 바코드 입력 테스터와 함께 써서 브라우저가 받은 값, 접두 키, 접미사를 봅니다.

USB 시리얼 장치, 가상 COM 포트, USB 열거, 광학 디코딩은 에뮬레이트하지 않습니다. 그 동작은 여전히 하드웨어, 또는 직접 제어하는 시리얼 테스트 더블에 속합니다.