“하드웨어 제어를 위해 더 이상 전용 드라이버 인스톨러나 C++ 로컬 데몬을 배포할 필요가 없습니다.” 브라우저 샌드박스 내부에서 안전하게 물리적 USB 장치와 직접 바이너리 패킷을 주고받는 WebUSB API의 원리부터 실무 프로덕션 구현, 보안 모델, 문제 해결까지 총정리합니다.
과거 웹 애플리케이션에서 물리적인 외장 하드웨어(영수증 프린터, 바코드 라벨러, 임베디드 보드, 계측 장비 등)를 제어하려면 수많은 중간 단계가 강제되었습니다. 사용자는 운영체제별 전용 디바이스 드라이버를 수동으로 설치해야 했고, 로컬 머신에서 백그라운드로 실행되며 WebSocket이나 로컬 HTTP 서버(예: localhost:8080) 역할을 하는 전용 에이전트 프로그램을 깔아야 했습니다.
이러한 아키텍처는 다음과 같은 치명적인 문제를 안고 있었습니다:
WebUSB API는 이러한 비효율을 해결하기 위해 W3C와 웹 표준 그룹에서 제정한 기술입니다. 사용자가 웹 브라우저의 전용 모달 창에서 명시적으로 허용한 특정 하드웨어에 한해, 브라우저가 직접 운영체제의 저수준 USB 서브시스템과 통신할 수 있는 표준 JavaScript 인터페이스를 제공합니다.
WebUSB를 올바르게 다루려면 USB(Universal Serial Bus) 하드웨어의 계층적 구조를 이해해야 합니다. USB는 단순한 시리얼 선이 아니라 고도로 구조화된 트리 구조로 작동합니다.
1)을 가집니다.in은 장치→호스트, out은 호스트→장치)을 가집니다.| 전송 유형 (Transfer Type) | 용도 및 특징 | WebUSB 메서드 |
|---|---|---|
| Control Transfer | 장치 설정, 상태 질의, 짧은 제어 명령 전달 (기본 엔드포인트 0 사용) | controlTransferIn, controlTransferOut |
| Bulk Transfer | 대용량 데이터의 오류 없는 무결성 전송 (프린터 출력, 펌웨어 전송 등) | transferIn, transferOut |
| Interrupt Transfer | 주기적이고 지연 시간에 민감한 소용량 데이터 (센서 데이터, 버튼 클릭 등) | transferIn, transferOut |
| Isochronous Transfer | 실시간 오디오/비디오 스트리밍 (일부 손실 허용) | isochronousTransferIn, isochronousTransferOut |
USB 하드웨어는 임의의 물리적 메모리 조작이나 펌웨어 플래싱이 가능한 강력한 장치이므로, WebUSB API는 매우 엄격한 3중 보안 통제를 받습니다.
navigator.usb 객체 자체가 undefined로 노출되지 않습니다. (단, 로컬 개발용 localhost는 예외적으로 허용)requestDevice)는 반드시 사용자의 클릭이나 키보드 입력 같은 명시적인 제스처 이벤트 핸들러 안에서만 호출되어야 합니다. 페이지 로드 시 자동으로 호출하면 보안 예외(SecurityError)가 발생합니다.allow="usb" 속성을 명시적으로 허용해야 합니다.사용자에게 장치 접근 권한을 얻는 과정은 2가지 API로 나뉩니다.
requestDevice)사용자에게 네이티브 브라우저 장치 선택창을 띄웁니다. 필터(filters)에 Vendor ID와 Product ID를 지정하여 우리 서비스와 호환되는 장치만 목록에 노출되도록 제한하는 것이 표준 패턴입니다.
// 버튼 클릭 이벤트 리스너 내부
async function connectNewDevice() {
try {
// Arduino Uno (VID: 0x2341, PID: 0x0043) 예시
const device = await navigator.usb.requestDevice({
filters: [
{ vendorId: 0x2341 }
]
});
console.log(`선택된 장치: ${device.productName} (제조사: ${device.manufacturerName})`);
return device;
} catch (error) {
if (error.name === 'NotFoundError') {
console.log('사용자가 장치 선택 창을 취소했습니다.');
} else {
console.error('장치 접근 권한 요청 실패:', error);
}
return null;
}
}getDevices)사용자가 과거에 이미 승인했던 장치는 브라우저에 저장됩니다. 서비스 접속 시 사용자 인터랙션 없이도 백그라운드에서 즉시 장치 목록을 조회할 수 있습니다.
async function autoReconnect() {
if (!('usb' in navigator)) {
console.warn('현재 브라우저는 WebUSB API를 지원하지 않습니다.');
return;
}
const pairedDevices = await navigator.usb.getDevices();
for (const device of pairedDevices) {
console.log(`기존 허가 장치 발견: ${device.productName}`);
// 필요한 경우 즉시 open() 및 통신 재개
}
}장치 인스턴스를 얻었다고 해서 바로 데이터를 쏠 수 있는 것은 아닙니다. 운영체제와 USB 스택에 단계적으로 연결을 선언해야 합니다.
async function setupUsbDevice(device) {
// 1. USB 디바이스 세션 열기
await device.open();
console.log('USB 세션 개방 완료');
// 2. Configuration 선택 (현재 구성이 null이거나 다른 경우)
if (device.configuration === null) {
await device.selectConfiguration(1);
}
// 3. 대상 인터페이스 독점 선점 (Interface #0 선점)
const interfaceNumber = 0;
await device.claimInterface(interfaceNumber);
console.log(`인터페이스 #${interfaceNumber} 독점 선점 성공`);
}⚠️
claimInterface의 중요성: 운영체제에게 “지금부터 이 웹 페이지가 이 인터페이스를 독점 제어하겠다”고 알리는 시스템 콜입니다. 만약 OS의 다른 시스템 프로세스가 이미 해당 인터페이스를 점유하고 있다면NetworkError: Unable to claim interface에러가 발생합니다.
인터페이스를 선점했다면, 이제 실제 엔드포인트를 통해 바이너리 데이터를 주고받습니다. WebUSB의 모든 I/O는 ArrayBuffer, Uint8Array, DataView 기반으로 동작합니다.
호스트(브라우저)에서 장치로 명령이나 페이로드를 전송합니다. 첫 번째 파라미터는 대상 엔드포인트 번호(Endpoint Number)입니다.
async function sendCommand(device, endpointNumber, text) {
const encoder = new TextEncoder();
const payload = encoder.encode(text + '\n'); // 바이트 버퍼 생성
const result = await device.transferOut(endpointNumber, payload);
if (result.status === 'ok') {
console.log(`${result.bytesWritten} 바이트 전송 성공`);
} else {
console.error(`전송 실패 상태: ${result.status}`);
}
}장치에서 호스트로 유입되는 데이터를 읽어들입니다. 수신할 최대 바이트 길이(length)를 지정해야 합니다.
async function readLoop(device, endpointNumber) {
const decoder = new TextDecoder();
try {
while (device.opened) {
// 최대 64바이트 버퍼 대기
const result = await device.transferIn(endpointNumber, 64);
if (result.status === 'ok' && result.data.byteLength > 0) {
const receivedString = decoder.decode(result.data);
console.log(`수신된 데이터: ${receivedString}`);
} else if (result.status === 'stall') {
console.warn('엔드포인트 Stall 발생. 파이프를 리셋합니다.');
await device.clearHalt('in', endpointNumber);
}
}
} catch (error) {
console.error('읽기 루프 중단:', error);
}
}다음은 웹 대시보드에서 버튼을 눌러 아두이노 보드의 온보드 LED를 켜고 끄며, 센서 값을 실시간으로 읽어오는 완전한 프로덕션 형태의 클래스 구현체입니다.
class ArduinoWebUsbController {
constructor(vendorId = 0x2341) {
this.vendorId = vendorId;
this.device = null;
this.interfaceNumber = 2; // WebUSB 인터페이스 번호
this.endpointIn = 4; // 수신 엔드포인트
this.endpointOut = 5; // 송신 엔드포인트
this.isReading = false;
}
async connect() {
this.device = await navigator.usb.requestDevice({
filters: [{ vendorId: this.vendorId }]
});
await this.device.open();
await this.device.selectConfiguration(1);
await this.device.claimInterface(this.interfaceNumber);
this.startListening();
return this.device.productName;
}
async setLedState(turnOn) {
if (!this.device || !this.device.opened) throw new Error('장치가 연결되지 않았습니다.');
const command = turnOn ? 'LED:ON' : 'LED:OFF';
const data = new TextEncoder().encode(command);
await this.device.transferOut(this.endpointOut, data);
}
async startListening() {
this.isReading = true;
const decoder = new TextDecoder();
while (this.isReading && this.device && this.device.opened) {
try {
const response = await this.device.transferIn(this.endpointIn, 64);
if (response.data && response.data.byteLength > 0) {
const message = decoder.decode(response.data).trim();
this.onMessageReceived(message);
}
} catch (err) {
if (this.isReading) console.error('센서 수신 에러:', err);
break;
}
}
}
onMessageReceived(msg) {
// UI 업데이트 이벤트 디스패치
window.dispatchEvent(new CustomEvent('sensor-data', { detail: msg }));
}
async disconnect() {
this.isReading = false;
if (this.device) {
try {
await this.device.releaseInterface(this.interfaceNumber);
await this.device.close();
} catch (e) {
console.warn('종료 중 예외:', e);
}
this.device = null;
}
}
}사용자가 하드웨어 케이블을 갑작스럽게 뽑거나 다시 꽂는 상황(핫플러깅, Hot-plugging)은 실무 환경에서 빈번하게 일어납니다. navigator.usb의 이벤트를 통해 이를 매끄럽게 처리할 수 있습니다.
function setupDeviceLifecycleListeners() {
// 장치가 물리적으로 연결되었을 때 (이미 권한이 부여된 장치인 경우)
navigator.usb.addEventListener('connect', (event) => {
console.log('장치 연결 감지:', event.device.productName);
showToastNotification(`장치 연결됨: ${event.device.productName}`);
// 자동 재연결 파이프라인 트리거
});
// 장치 케이블이 분리되었을 때
navigator.usb.addEventListener('disconnect', (event) => {
console.warn('장치 케이블 분리됨:', event.device.productName);
showToastNotification(`장치 연결 끊김`, 'danger');
// 내부 스트림 정리 및 UI를 '연결 대기' 상태로 전환
cleanupActiveSession();
});
}브라우저 하드웨어 접근 표준에는 WebUSB 외에도 Web Serial API와 Web HID API가 존재합니다. 어떤 API를 선택해야 할지 명확한 기준표를 제시합니다.
| 비교 항목 | WebUSB API | Web Serial API | Web HID API |
|---|---|---|---|
| 통신 프로토콜 | 원시 USB 엔드포인트 패킷 (Control, Bulk, Interrupt) | 직렬 스트림 (TX/RX 비동기 바이트 스트림) | HID Report 패킷 (인풋/아웃풋/피처 레포트) |
| 적합한 장비 | 맞춤형 USB 하드웨어, 특수 계측기, 펌웨어 플래셔 | 시리얼 통신 장비, RS-232/485 변환기, 표준 COM 포트 | 게임패드, 특수 키패드, 조이스틱, 바코드 스캐너 |
| 표준 OS 드라이버 점유 | OS 기본 드라이버가 붙으면 브라우저 점유 불가 | OS CDC/ACM 가상 COM 드라이버 위에서 동작 | OS HID 서브시스템과 공존 가능 |
| 데이터 모델 | 바이트 버퍼 기반 명시적 트랜스퍼 | ReadableStream / WritableStream 스트림 파이프 |
정형화된 입력/출력 레포트 구조체 |
| 보안 차단 대상 | 키보드, 마우스, 대용량 저장장치(Mass Storage) 등 | 시스템 콘솔 포트 등 일부 제한 | 시스템 표준 마우스/키보드 필수 필드 차단 |
WebUSB를 실무 프로젝트에 도입할 때 개발자들을 가장 곤혹스럽게 만드는 함정들을 정리합니다.
claimInterface 호출 시 Access Denied 또는 Unable to claim interface 에러를 뿜으며 실패합니다.WinUSB 드라이버를 로드하도록 하드웨어 펌웨어를 빌드해야 합니다.WinUSB로 교체해야 합니다.transferOut을 쏟아부으면 엔드포인트 파이프가 멈추는 Stall 현상이 발생합니다.await)를 확인한 뒤 다음 트랜잭션을 전송해야 하며, Stall 발생 시 device.clearHalt('out', endpointNumber)를 호출하여 파이프의 에러 플래그를 복구해야 합니다.모든 하드웨어 통신을 WebUSB로 해결할 수는 없습니다. 다음 상황에서는 다른 대안을 찾아야 합니다.
requestDevice)를 거쳐야만 장치 핸들을 획득할 수 있습니다.requestDevice → device.open() → selectConfiguration() → claimInterface() 순서로 인터페이스를 선점한 뒤 I/O를 수행합니다.transferOut(송신)과 transferIn(수신)을 통해 Uint8Array 및 ArrayBuffer 형태로 고성능 바이너리 제어를 달성합니다.WinUSB 드라이버로 인식되어야 인터페이스 선점이 가능하므로 하드웨어 펌웨어의 디스크립터 설계가 핵심입니다.✨ 한 줄 요약 WebUSB API는 무거운 드라이버와 로컬 설치 프로그램을 웹 화면 뒤로 숨기고, 브라우저 클릭 한 번으로 하드웨어를 즉각 구동시키는 차세대 웹-물리 인터페이스의 핵심입니다.
