WebUSB용 기기 빌드

WebUSB API를 최대한 활용할 수 있도록 기기를 빌드합니다.

이 도움말에서는 Google Workspace의 이점을 최대한 활용할 수 있도록 기기를 빌드하는 방법을 설명합니다. WebUSB API. API 자체에 대한 간단한 소개는 USB 기기 액세스 검색을 참조하세요.

배경

USB (Universal Serial Bus)는 주변 장치를 데스크탑 및 모바일 컴퓨팅 장치에 연결하는 것입니다. 또한 버스의 전기적 특성과 데이터 레이크를 위한 일반적인 모델을 장치와 통신하며, USB 사양에는 장치 클래스 집합이 포함되어 있습니다. 지정할 수도 있습니다 이들은 특정 유형의 장치를 위한 일반적인 모델입니다. 스토리지, 오디오, 비디오, 네트워킹 등과 같은 데이터 애널리스트가 있습니다. 이러한 기기 클래스 사양의 장점은 운영체제 공급업체는 클래스에 따라 단일 드라이버를 구현할 수 있음 사양('클래스 드라이버')과 해당 클래스를 구현하는 모든 기기는 지원됩니다. 이는 모든 제조업체의 IT 지원 전문가로서 대단한 발전이었죠. 자체 장치 드라이버가 있습니다.

그러나 일부 기기는 이러한 표준화된 기기 클래스 중 하나에 적합하지 않습니다. 가 대신 제조업체에서 해당 기기에 이러한 기술을 구현한다는 라벨을 공급업체별 클래스를 제공합니다. 이 경우 운영체제는 사용자가 애플리케이션을 공급업체의 드라이버 패키지에 제공된 정보에 따라 로드할 수 있지만 일반적으로 API를 구현할 수 있는 공급업체 및 제품 ID 특정 공급업체별 프로토콜이 있습니다.

USB의 또 다른 기능은 장치가 컴퓨터 장치에 여러 인터페이스를 제공할 수 있다는 것입니다. 외부 IP 주소가 있습니다 각 인터페이스는 표준화된 클래스이거나 공급업체별로 다를 수 있습니다. 운영 체제가 각 인터페이스는 다른 공급업체에서 요구할 수 있는 드라이버입니다. 예를 들어, USB 웹캠은 일반적으로 두 개의 인터페이스를 제공합니다. USB 비디오 클래스 구현 (카메라용)과 USB 오디오 클래스 (마이크용)입니다. 운영체제는 단일 포드 또는 '웹캠 드라이버' 대신 독립적인 동영상 및 오디오 클래스 드라이버를 기기의 개별 기능을 담당합니다. 이 인터페이스 클래스의 구성을 사용하면 더 큰 유연성을 얻을 수 있습니다.

API 기본사항

대부분의 표준 USB 클래스에는 이에 상응하는 웹 API가 있습니다. 예를 들어 페이지는 getUserMedia()를 사용하여 동영상 클래스 기기에서 동영상을 캡처할 수 있습니다. 수신 대기하여 인간 인터페이스 (HID) 클래스 기기에서 입력 이벤트를 수신할 수 있습니다. (KeyboardEvents 또는 PointerEvents) 또는 Gamepad 또는 WebHID API를 사용합니다. 모든 기기가 표준화된 클래스 정의를 구현하는 것은 아닌 것처럼 기기는 기존 웹 플랫폼 API에 상응하는 기능을 구현합니다. 날짜 바로 이런 경우에 WebUSB API는 사이트에 데이터를 보낼 방법을 제공하여 을 통해 공급업체별 인터페이스를 요청하여 광고를 게재할 수 있습니다.

WebUSB를 통해 액세스할 수 있는 기기의 구체적인 요구사항은 약간씩 다릅니다. 운영체제에서 USB를 관리하는 방식이 다르기 때문에 플랫폼마다 다릅니다. 기본 요구사항은 페이지가 제어하려는 인터페이스를 주장하는 드라이버입니다. 이는 OS 공급업체가 제공하는 일반 클래스 드라이버 또는 있습니다. USB 장치는 여러 인터페이스를 제공할 수 있기 때문에 각 인터페이스는 자체 드라이버가 있으므로 일부 인터페이스가 인코더와 디바이스를 위한 드라이버가 소유권을 주장하고 나머지는 브라우저에서 액세스할 수 있습니다.

예를 들어 고급 USB 키보드는 운영체제의 입력 하위 시스템과 공급업체별 인터페이스를 제공합니다. 이 제조업체 웹사이트에서 도구를 제공하여 사용자가 기기 동작의 측면(예: 매크로 키 및 조명 효과)의 작동 방식을 플랫폼별 소프트웨어를 설치할 수 없습니다. 이러한 기기의 구성 설명자는 다음과 같이 표시됩니다.

필드 설명
구성 설명자
0x09 bLength 이 설명자의 크기
0x02 bDescriptorType 구성 설명자
0x0039 wTotalLength 이 일련의 설명어의 총 길이
0x02 bNumInterfaces 인터페이스 수
0x01 bConfigurationValue Configuration 1
0x00 iConfiguration 구성 이름 (없음)
0b1010000 bmAttributes 원격 절전 모드 해제 기능이 있는 자체 전원 기기
0x32 bMaxPower 최대 전력은 2mA 단위로 표시됩니다.
인터페이스 설명어
0x09 bLength 이 설명자의 크기
0x04 bDescriptorType 인터페이스 설명어
0x00 bInterfaceNumber 인터페이스 0
0x00 bAlternateSetting 대체 설정 0 (기본값)
0x01 bNumEndpoints 엔드포인트 1개
0x03 bInterfaceClass HID 인터페이스 클래스
0x01 bInterfaceSubClass 부팅 인터페이스 서브클래스
0x01 bInterfaceProtocol 키보드
0x00 iInterface 인터페이스 이름 (없음)
HID 설명자
0x09 bLength 이 설명자의 크기
0x21 bDescriptorType HID 설명자
0x0101 bcdHID HID 버전 1.1
0x00 bCountryCode 하드웨어 대상 국가
0x01 bNumDescriptors 따를 HID 클래스 설명자 수
0x22 bDescriptorType 보고서 설명자 유형
0x003F wDescriptorLength 보고서 설명자의 총 길이
엔드포인트 설명자
0x07 bLength 이 설명자의 크기
0x05 bDescriptorType 엔드포인트 설명자
0b10000001 bEndpointAddress 엔드포인트 1 (IN)
0b00000011 bmAttributes 인터럽트
0x0008 wMaxPacketSize 8바이트 패킷
0x0A bInterval 10밀리초 간격
인터페이스 설명어
0x09 bLength 이 설명자의 크기
0x04 bDescriptorType 인터페이스 설명어
0x01 bInterfaceNumber 인터페이스 1
0x00 bAlternateSetting 대체 설정 0 (기본값)
0x02 bNumEndpoints 엔드포인트 2개
0xFF bInterfaceClass 공급업체별 인터페이스 클래스
0x00 bInterfaceSubClass
0x00 bInterfaceProtocol
0x00 iInterface 인터페이스 이름 (없음)
엔드포인트 설명자
0x07 bLength 이 설명자의 크기
0x05 bDescriptorType 엔드포인트 설명자
0b10000010 bEndpointAddress 엔드포인트 1 (IN)
0b00000010 bmAttributes 대량
0x0040 wMaxPacketSize 64바이트 패킷
0x00 bInterval 대량 엔드포인트는 해당 사항 없음
엔드포인트 설명자
0x07 bLength 이 설명자의 크기
0x05 bDescriptorType 엔드포인트 설명자
0b00000011 bEndpointAddress 엔드포인트 3 (OUT)
0b00000010 bmAttributes 대량
0x0040 wMaxPacketSize 64바이트 패킷
0x00 bInterval 대량 엔드포인트는 해당 사항 없음

구성 설명자는 연결된 여러 설명자로 구성됩니다. 있습니다. 각각 bLengthbDescriptorType 필드로 시작하므로 식별할 수 있습니다 첫 번째 인터페이스는 HID 인터페이스이며 HID 설명자 및 단일 엔드포인트가 실행할 수 있습니다 두 번째 인터페이스는 두 개의 디바이스에 명령을 전송하고 응답을 수신하는 데 사용할 수 있는 엔드포인트 있습니다.

WebUSB 설명자

WebUSB는 펌웨어를 수정하지 않고도 많은 기기에서 작동할 수 있지만 추가 기능이 사용 설정됩니다. WebUSB 지원을 나타내는 설명자입니다. 예를 들어 기기가 네트워크에 있을 때 브라우저에서 사용자를 연결할 수 있는 방문 페이지 URL입니다. 전원 공급 장치가 있습니다.

<ph type="x-smartling-placeholder">
</ph> Chrome의 WebUSB 알림 스크린샷
WebUSB 알림.

BOS (Binary Device Object Store)는 USB 3.0에서 도입된 개념이지만 또한 버전 2.1의 일부로 USB 2.0 장치로 백포팅되었습니다. 선언 WebUSB 지원은 다음 플랫폼 기능을 포함하는 것으로 시작됩니다. BOS 설명자의 설명어:

필드 설명
바이너리 기기 객체 저장소 설명어
0x05 bLength 이 설명자의 크기
0x0F bDescriptorType 바이너리 기기 객체 저장소 설명어
0x001D wTotalLength 이 일련의 설명어의 총 길이
0x01 bNumDeviceCaps BOS의 기기 기능 설명어 수
WebUSB 플랫폼 기능 설명어
0x18 bLength 이 설명자의 크기
0x10 bDescriptorType 기기 기능 설명어
0x05 bDevCapabilityType 플랫폼 기능 설명어
0x00 bReserved
{0x38, 0xB6, 0x08, 0x34, 0xA9, 0x09, 0xA0, 0x47, 0x8B, 0xFD, 0xA0, 0x76, 0x88, 0x15, 0xB6, 0x65} PlatformCapablityUUID little-endian 형식의 WebUSB 플랫폼 기능 설명자 GUID입니다.
0x0100 bcdVersion WebUSB 설명자 버전 1.0
0x01 bVendorCode WebUSB의 bRequest 값
0x01 iLandingPage 방문 페이지 URL

플랫폼 기능 UUID는 이를 WebUSB 플랫폼 기능으로 식별합니다. 설명어가 포함되어 있으며, 이는 기기에 관한 기본 정보를 제공합니다. 브라우저의 경우 bVendorCode 값을 사용하여 기기에 관한 추가 정보를 가져옵니다. 기기에 추가 요청을 발행할 수 있습니다. 현재 지정된 유일한 요청은 GET_URL: URL 설명자를 반환합니다. 이는 문자열과 비슷하며 설명어이지만, URL을 가장 적은 바이트로 인코딩하도록 설계되었습니다. URL "https://google.com"의 설명어는 다음과 같습니다.

필드 설명
URL 설명자
0x0D bLength 이 설명자의 크기
0x03 bDescriptorType URL 설명자
0x01 bScheme https://
"google.com" URL UTF-8로 인코딩된 URL 콘텐츠

기기를 처음 연결할 때 브라우저는 BOS 설명자를 이 표준 GET_DESCRIPTOR 제어 전송을 실행하는 경우:

bmRequestType bRequest wValue wIndex wLength 데이터 (응답)
0b10000000 0x06 0x0F00 0x0000 * BOS 설명자

이 요청은 일반적으로 두 번 이루어집니다. 첫 번째에는 충분히 큰 wLength가 포함됩니다. 호스트가 wTotalLength 필드의 값을 전체 설명자 길이가 알 수 있습니다.

WebUSB 플랫폼 기능 설명어의 iLandingPage 필드가 다음과 같이 설정된 경우 0이 아닌 값인 경우 브라우저에서 WebUSB 관련 GET_URL 요청을 실행합니다. bRequestbVendorCode 값으로 설정하여 제어 이전을 실행 플랫폼 기능 설명어와 wValue에서 iLandingPage로 설정됨 값으로 사용됩니다. GET_URL (0x02)의 요청 코드는 wIndex에 들어갑니다.

bmRequestType bRequest wValue wIndex wLength 데이터 (응답)
0b11000000 0x01 0x0001 0x0002 * URL 설명자

다시 말하지만, 이 요청은 먼저 길이를 탐색하기 위해 두 번 발행될 수 있습니다. 읽기 전용입니다

플랫폼별 고려사항

WebUSB API가 외부 IP 주소 없이도 로컬에 액세스할 수 있는 USB 기기 개발자는 여전히 USB 장치에 적용되는 요구사항을 브라우저 요구사양과 같은 애플리케이션이 기기에 액세스하려는 경우에 한합니다.

macOS

macOS에는 특별한 것이 필요하지 않습니다. WebUSB를 사용하는 웹사이트는 커널 드라이버 또는 실행할 수 있습니다

Linux

Linux는 macOS와 비슷하지만 기본적으로 대부분의 배포판에서는 사용자를 설정하지 않습니다. USB 기기를 열 수 있는 권한이 있는 계정 udev라는 시스템 데몬은 기기에 액세스할 수 있는 사용자 및 그룹을 할당하는 일을 담당합니다. 규칙 주어진 공급업체와 일치하는 기기의 소유권을 할당하고 액세스 권한이 있는 사용자를 위한 공통 그룹인 plugdev 그룹에 제품 ID를 추가합니다. 외부 장치에 연결:

SUBSYSTEM=="usb", ATTR{idVendor}=="XXXX", ATTR{idProduct}=="XXXX", GROUP="plugdev"

XXXX를 기기의 16진수 공급업체 및 제품 ID로 바꿉니다. 예: ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11"이(가) Nexus One과 일치합니다. 있습니다. 일반적인 '0x' 없이 작성해야 합니다. 접두사 및 모두 소문자 할 수 있습니다. 기기의 ID를 찾으려면 명령줄을 실행합니다. 도구 lsusb.

이 규칙은 /etc/udev/rules.d 디렉터리의 파일에 배치해야 합니다. 기기가 전원에 연결되는 즉시 적용됩니다. 다시 시작할 필요가 없습니다. udev.

Android

Android 플랫폼은 Linux를 기반으로 하지만 다음 작업을 수행하기 위해 수정할 필요가 없습니다. 시스템 구성이 포함됩니다 기본적으로 드라이버가 제작되지 않은 모든 장치 브라우저에서 사용할 수 있습니다. 개발자는 하지만 사용자가 다른 네트워크에 연결할 때 추가 단계가 있다는 것을 알고 있습니다. 있습니다. 사용자가 requestDevice(): Android에 허용할 것인지 묻는 메시지가 표시됩니다. Chrome에서 액세스합니다. 사용자가 웹사이트로 돌아오는 경우에도 이 메시지가 다시 표시됩니다. 이미 기기에 연결할 권한이 있고 웹사이트에서 open()

또한 Android에서 데스크톱 Linux보다 더 많은 기기에 액세스할 수 있습니다. 기본적으로 포함되는 드라이버 수가 더 적기 때문입니다. 주목할 만한 누락은 예를 들면 다음과 같습니다. USB CDC-ACM 클래스는 일반적으로 USB-직렬 어댑터에 의해 구현됩니다. 는 Android SDK에 직렬 기기와 통신하기 위한 API가 없습니다.

ChromeOS

ChromeOS 역시 Linux를 기반으로 하며 수정할 필요가 없습니다. 시스템 구성에 적용됩니다 permission_broker 서비스는 USB 액세스를 제어합니다. 최소 소유권 주장이 제기되지 않은 인터페이스 1개.

Windows

Windows 드라이버 모델에는 추가 요구사항이 있습니다. 좋아요 취소 USB 장치를 열 수 있는 기능보다 높은 플랫폼은 이는 로드된 드라이버가 없는 경우에도 기본값입니다. 대신 인터페이스를 제공하기 위해 로드해야 하는 WinUSB 사용되는 애플리케이션입니다. 이 작업은 커스텀 드라이버 정보 파일 (INF)을 시스템에 설치하거나 이를 수정하여 마이크로소프트 OS 호환성 설명자를 제공하는 펌웨어를 열거형입니다.

드라이버 정보 파일 (INF)

장치를 만날 때 해야 할 일을 Windows에 알려주는 드라이버 정보 파일 처음입니다. 사용자의 시스템에 이미 WinUSB 드라이버가 포함되어 있으므로 INF 파일이 공급업체와 제품 ID를 연결하기만 하면 새 설치 규칙을 적용할 수 있습니다. 아래 파일은 기본 예입니다. 파일을 파일을 .inf 확장자로 변환하려면 'X'로 표시된 섹션을 오른쪽으로 변경한 다음 클릭하고 '설치'를 선택합니다. 선택합니다.

[Version]
Signature   = "$Windows NT$"
Class       = USBDevice
ClassGUID   = {88BAE032-5A81-49f0-BC3D-A4FF138216D6}
Provider    = %ManufacturerName%
CatalogFile = WinUSBInstallation.cat
DriverVer   = 09/04/2012,13.54.20.543

; ========== Manufacturer/Models sections ===========

[Manufacturer]
%ManufacturerName% = Standard,NTx86,NTia64,NTamd64

[Standard.NTx86]
%USB\MyCustomDevice.DeviceDesc% = USB_Install,USB\VID_XXXX&PID_XXXX

[Standard.NTia64]
%USB\MyCustomDevice.DeviceDesc% = USB_Install,USB\VID_XXXX&PID_XXXX

[Standard.NTamd64]
%USB\MyCustomDevice.DeviceDesc% = USB_Install,USB\VID_XXXX&PID_XXXX

; ========== Class definition ===========

[ClassInstall32]
AddReg = ClassInstall_AddReg

[ClassInstall_AddReg]
HKR,,,,%ClassName%
HKR,,NoInstallClass,,1
HKR,,IconPath,%REG_MULTI_SZ%,"%systemroot%\system32\setupapi.dll,-20"
HKR,,LowerLogoVersion,,5.2

; =================== Installation ===================

[USB_Install]
Include = winusb.inf
Needs   = WINUSB.NT

[USB_Install.Services]
Include = winusb.inf
Needs   = WINUSB.NT.Services

[USB_Install.HW]
AddReg = Dev_AddReg

[Dev_AddReg]
HKR,,DeviceInterfaceGUIDs,0x10000,"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}"

; =================== Strings ===================

[Strings]
ManufacturerName              = "Your Company Name Here"
ClassName                     = "Your Company Devices"
USB\MyCustomDevice.DeviceDesc = "Your Device Name Here"

[Dev_AddReg] 섹션은 기기의 DeviceInterfaceGUID 집합을 구성합니다. 있습니다. 모든 장치 인터페이스에는 GUID가 있어야 애플리케이션이 찾고 연결하는 데 사용할 수 있습니다. New-Guid PowerShell 사용 임의의 GUID를 생성하는 cmdlet 또는 온라인 도구

개발 목적으로 Zadig 도구는 USB 인터페이스를 위해 로드된 드라이버를 WinUSB 드라이버로 교체하는 간단한 방법을 보여줍니다.

Microsoft OS 호환성 설명자

위의 INF 파일 접근 방식은 사용자의 컴퓨터를 미리 예측할 수 있습니다. Windows 8.1 이상에서는 사용자 지정 USB 설명자를 통해. 이러한 설명어는 윈도우즈 운영 체제로 연결하는 것이 매우 중요합니다. 일반적으로 INF 파일에 포함됩니다

WebUSB 설명자를 설정하고 나면 Microsoft의 OS를 쉽게 추가할 수 있습니다. 호환성 설명어도 포함됩니다. 먼저 추가 플랫폼 기능 설명자입니다. wTotalLength 앱을 업데이트해야 합니다 이를 설명하기 위해 bNumDeviceCaps가 필요합니다.

필드 설명
Microsoft OS 2.0 플랫폼 기능 설명어
0x1C bLength 이 설명자의 크기
0x10 bDescriptorType 기기 기능 설명어
0x05 bDevCapabilityType 플랫폼 기능 설명어
0x00 bReserved
{0xDF, 0x60, 0xDD, 0xD8, 0x89, 0x45, 0xC7, 0x4C, 0x9C, 0xD2, 0x65, 0x9D, 0x9E, 0x64, 0x8A, 0x9F} PlatformCapablityUUID Little Endian 형식의 Microsoft OS 2.0 플랫폼 호환성 설명자 GUID
0x06030000 dwWindowsVersion 호환되는 최소 Windows 버전 (Windows 8.1)
0x00B2 wMSOSDescriptorSetTotalLength 설명어 집합의 총 길이
0x02 bMS_VendorCode 추가 Microsoft 설명자를 검색하기 위한 bRequest 값
0x00 bAltEnumCode 기기가 다른 열거 기능을 지원하지 않습니다.

WebUSB 설명자와 마찬가지로 bRequest 값을 선택하여 제어 전송을 지원하지 않습니다 이 예에서는 0x02 wIndex에 있는 0x07는 Microsoft OS를 검색하는 명령어입니다. 기기에서 설정된 2.0 설명자입니다.

bmRequestType bRequest wValue wIndex wLength 데이터 (응답)
0b11000000 0x02 0x0000 0x0007 * MS OS 2.0 설명자 집합

USB 장치는 여러 기능을 가질 수 있으므로 설명어의 첫 번째 부분은 set는 뒤에 오는 속성이 연결되는 함수를 설명합니다. 이 아래 예에서는 복합 기기의 인터페이스 1을 구성합니다. 설명어는 OS에 이 인터페이스에 관한 두 가지 중요한 정보입니다. 호환되는 ID 설명자는 이 기기가 WinUSB와 호환됨을 Windows에 알립니다. 드라이버입니다. 레지스트리 속성 설명자는 위 INF 예시의 [Dev_AddReg] 섹션에서 레지스트리 속성을 이 함수에 기기 인터페이스 GUID를 할당합니다.

필드 설명
Microsoft OS 2.0 설명자 집합 헤더
0x000A wLength 이 설명자의 크기
0x0000 wDescriptorType 설명자 집합 헤더 설명자
0x06030000 dwWindowsVersion 호환되는 최소 Windows 버전 (Windows 8.1)
0x00B2 wTotalLength 설명어 집합의 총 길이
Microsoft OS 2.0 구성 하위 집합 헤더
0x0008 wLength 이 설명자의 크기
0x0001 wDescriptorType 구성 하위 집합 헤더 내용 입력란
0x00 bConfigurationValue 구성 1에 적용 (구성에도 불구하고 0부터 색인이 생성됨) 일반적으로 1부터 색인이 생성됨)
0x00 bReserved 0으로 설정해야 합니다.
0x00A8 wTotalLength 이 헤더를 포함한 하위 집합의 전체 길이
Microsoft OS 2.0 함수 하위 집합 헤더
0x0008 wLength 이 설명자의 크기
0x0002 wDescriptorType 함수 하위 집합 헤더 설명자
0x01 bFirstInterface 함수의 첫 번째 인터페이스
0x00 bReserved 0으로 설정해야 합니다.
0x00A0 wSubsetLength 이 헤더를 포함한 하위 집합의 전체 길이
Microsoft OS 2.0 호환 ID 설명자
0x0014 wLength 이 설명자의 크기
0x0003 wDescriptorType 호환 ID 설명자
"WINUSB\0\0" CompatibileID 8바이트로 패딩된 ASCII 문자열
"\0\0\0\0\0\0\0\0" SubCompatibleID 8바이트로 패딩된 ASCII 문자열
Microsoft OS 2.0 레지스트리 속성 설명자
0x0084 wLength 이 설명자의 크기
0x0004 wDescriptorType 레지스트리 속성 설명어
0x0007 wPropertyDataType REG_MULTI_SZ
0x002A wPropertyNameLength 속성 이름의 길이
"DeviceInterfaceGUIDs\0" PropertyName UTF-16LE로 인코딩된 null 종결자가 있는 속성 이름
0x0050 wPropertyDataLength 속성 값의 길이
"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}\0\0" PropertyData GUID와 UTF-16LE로 인코딩된 null 종결자 2개

Windows는 기기에 이 정보를 한 번만 쿼리합니다. 기기가 올바른 설명어로 응답하지 않으면 다음 번에 기기가 연결되어 있는지 확인합니다. Microsoft는 USB 기기 레지스트리 목록 항목은 기기를 열거할 때 생성된 레지스트리 항목을 설명합니다. 날짜 기기에 생성된 항목을 삭제하여 Windows가 강제로 읽기를 시도하도록 하는 테스트 다시 설명합니다

자세한 내용은 Microsoft의 블로그 게시물에서 설명어입니다.

두 WebUSB가 모두 포함된 WebUSB 인식 기기를 구현하는 코드의 예 설명자 및 Microsoft OS 설명자는 다음 프로젝트에서 확인할 수 있습니다.