작동 방식
USB 장치가 연결되자마자 스스로에 대해 선언하는 내용을 보여줍니다. 장치 디스크립터에는 USB-IF가 부여한 Vendor ID, 제조사가 고른 Product ID, 준수한다고 밝힌 USB 사양의 버전, 제품 자체의 버전, 그리고 장치가 제공하는 경우 제조사·제품·일련번호 문자열이 담겨 있습니다.
그 아래에는 전체 트리가 나타납니다. 각 구성과 그 인터페이스, 각 인터페이스의 클래스·서브클래스·프로토콜 세 값을 USB-IF 공식 명칭으로 옮긴 내용, 그리고 각 엔드포인트의 주소, 방향, 전송 유형, 최대 패킷 크기입니다. 대체 설정이 여러 개인 인터페이스 —카메라와 오디오 보드에서 흔합니다— 는 따로 나열됩니다.
이 도구는 디스크립터만 읽습니다. 장치와 세션을 열지도, 인터페이스를 점유하지도, 1바이트도 보내지 않으므로 그 장치를 쓰고 있는 드라이버를 방해하지 않습니다. 전체 트리는 JSON으로 내보내 보고서에 첨부하거나 다른 컴퓨터의 결과와 비교할 수 있습니다.
예시
046D:C52B0x00 / 0x00 / 0x00 → 3 × HID (0x03)키보드와 마우스용 무선 리시버는 장치 수준에서 클래스 0x00을 선언하므로 실제 종류는 인터페이스마다 정해집니다. 여기서는 인터럽트 입력 엔드포인트를 하나씩 가진 HID 인터페이스가 세 개 있습니다.0x08 / 0x06 / 0x50Mass Storage · SCSI transparent command set · Bulk-Only TransportUSB 메모리나 외장 디스크의 전형적인 조합입니다. 입력과 출력 벌크 엔드포인트가 하나씩 있고 그 위로 SCSI 명령이 오갑니다.0x02 / 0x02 / 0x01Communications and CDC Control · Abstract Control Model · AT Commands (ITU-T V.250)개발 보드나 모뎀의 가상 직렬 포트입니다. 인터럽트 엔드포인트가 하나 있는 제어 인터페이스와, 데이터를 나르는 벌크 엔드포인트 두 개를 가진 CDC-Data 인터페이스로 이루어집니다.활용 사례
- 드라이버를 찾거나 Linux에서 udev 규칙을 작성하기 위해 장치의 정확한 Vendor ID와 Product ID를 알아내기.
- 운영체제가 한눈에 보여주지 않는 USB 메모리, 리더, 어댑터의 일련번호 확인하기.
- 펌웨어를 개발하면서 장치가 기대한 인터페이스와 대체 설정, 엔드포인트를 올바른 클래스로 공개하는지 확인하기.
- 장치를 대상으로 코드를 작성하기 전에 어느 엔드포인트에 어떤 전송 유형으로 말을 걸어야 하는지 알아내기.
- 겉보기에 같은 두 장치를 버전, 인터페이스, 패킷 크기로 구분하기.
- 전체 트리를 JSON으로 내보내 컴퓨터의 USB 구성을 문서화하기.
자주 묻는 질문
왜 제 iPhone이나 Firefox에서는 동작하지 않나요?
WebUSB API는 Chromium 기반 브라우저 —Chrome, Edge, Opera— 의 Windows, macOS, Linux, ChromeOS, Android 버전에 구현되어 있습니다. Firefox와 Safari는 구현하지 않으며, iOS에서는 모든 브라우저가 시스템 엔진을 사용하므로 거기서도 쓸 수 없습니다. 또한 HTTPS여야 하고 페이지가 다른 사이트 안에 삽입되어 있지 않아야 합니다.
장치를 연결했는데 선택창에 나타나지 않습니다.
고른 필터가 너무 좁을 수 있습니다. 모든 장치를 보여주는 옵션을 시도해 보세요. 그래도 나타나지 않는다면 브라우저의 차단 목록에 있을 가능성이 큽니다. 이 목록은 어떤 웹 페이지도 건드리지 못하도록 FIDO 보안 키를 비롯한 일부 제품을 보안상의 이유로 제외합니다. Linux에서는 장치 노드에 대한 시스템 권한이 없을 수도 있습니다.
장치가 클래스 0x00이라고 표시되는 이유는 무엇인가요?
장치 디스크립터의 클래스 0x00은 «인터페이스를 보라»는 뜻입니다. 한 케이블에 서로 다른 기능을 묶는 복합 장치 대부분이 이를 사용합니다. 허브가 내장된 키보드, 마이크까지 제공하는 카메라, 복합기 프린터 등이 그렇습니다. 이런 경우 각 기능의 실제 종류는 장치의 클래스가 아니라 각 인터페이스의 클래스에 있습니다.
엔드포인트란 무엇이고 0x81 같은 주소는 무슨 뜻인가요?
엔드포인트는 데이터가 인터페이스로 들어오거나 나가는 우편함 하나하나입니다. 주소의 하위 7비트가 엔드포인트 번호이고 최상위 비트가 방향을 나타냅니다. 그래서 0x81은 입력 엔드포인트 1 —장치에서 컴퓨터로— 이고 0x01이라면 출력 엔드포인트 1이 됩니다. 전송 유형은 처리 방식을 정합니다. 기한이 없는 대용량에는 벌크, 키 입력처럼 작고 잦은 이벤트에는 인터럽트, 늦게 도착하느니 패킷을 버리는 편이 나은 오디오와 비디오에는 등시성 전송을 씁니다.
이 도구가 장치를 바꾸거나 망가뜨릴 수 있나요?
아니요. 브라우저가 장치를 열거할 때 이미 얻어 둔 디스크립터만 읽습니다. 세션을 열지도, 인터페이스를 점유하지도, 쓰지도 않습니다. 그래서 웹 페이지가 통신할 수 없는 키보드나 USB 메모리라도, 운영체제가 그 순간 사용 중인 상태 그대로 검사할 수 있습니다.
제조사나 제품이 비어 있는 이유는 무엇인가요?
그 문자열들은 선택적 디스크립터입니다. 저가 장치는 아예 기록하지 않는 경우가 많고, 일부 운영체제는 브라우저에 넘겨주지 않습니다. 그런 경우 이 도구는 Linux USB 프로젝트의 usb.ids 카탈로그에서 Vendor ID와 Product ID를 찾습니다. 이 카탈로그에는 제조사의 공식 이름이, 많은 경우 제품 이름까지 등록되어 있습니다.
장치 데이터가 제 컴퓨터 밖으로 나가나요?
디스크립터는 브라우저 안에서 읽히며 어떤 서버로도 전송되지 않습니다. 유일한 예외는 usb.ids 카탈로그 조회로, Vendor ID와 Product ID —여러분의 컴퓨터나 개별 제품이 아니라 모델을 가리키는 두 숫자— 만 질의하며 장치를 고르기 전에 끌 수 있습니다. 일련번호는 절대 전송되지 않습니다.
인터페이스의 대체 설정이란 무엇인가요?
같은 인터페이스가 여러 벌의 엔드포인트를 선언하고 그중 하나만 활성으로 둘 수 있습니다. 카메라와 오디오 보드는 해상도나 품질의 조합을 달리 제공하려고 이를 사용합니다. 대체 설정마다 버스에서 확보하는 대역폭이 다르고, 운영체제는 전송을 시작할 때 알맞은 것을 고릅니다. 장치가 쉬는 동안에는 대체 설정 0이 활성 상태로 남습니다.