프론트엔드 WebHID 기능 탐지: 장치 기능 발견 마스터하기

WebHID API는 웹 애플리케이션이 다양한 휴먼 인터페이스 장치(HID)와 직접 상호작용할 수 있는 흥미로운 가능성을 열어줍니다. 기본적인 통신은 간단하지만, 잠재력을 진정으로 발휘하려면 장치 기능을 효과적으로 탐지하는 것이 중요합니다. 이 글은 WebHID를 사용한 기능 탐지에 대한 종합 가이드를 제공하여, 더 풍부하고 반응성이 뛰어나며 맞춤화된 웹 경험을 구축할 수 있도록 돕습니다.

WebHID란 무엇이며 기능 탐지가 왜 중요한가?

WebHID는 웹사이트가 키보드, 마우스부터 게임 컨트롤러, 센서, 맞춤형 하드웨어에 이르기까지 모든 HID 장치에 접근할 수 있게 해주는 웹 API입니다. 표준화된 인터페이스에 의존하는 기존 웹 API와 달리, WebHID는 장치의 원시 데이터 및 제어 메커니즘에 직접 접근할 수 있는 기능을 제공합니다.

하지만 문제는 HID 장치가 매우 다양하다는 점입니다. 한 제조업체의 게임패드는 다른 제조업체의 것과 다른 버튼, 축 또는 센서를 노출할 수 있습니다. 맞춤형 산업용 센서는 고유한 데이터 형식이나 구성 옵션을 가질 수 있습니다. 기능 탐지를 위한 견고한 방법이 없다면, 웹 애플리케이션은 가정에 의존할 수밖에 없으며, 이는 호환성 문제, 제한된 기능, 그리고 좋지 않은 사용자 경험으로 이어질 수 있습니다.

기능 탐지는 연결된 HID 장치의 기능과 특징을 프로그래밍 방식으로 식별하는 과정입니다. 이를 통해 웹 애플리케이션은 사용 중인 특정 장치에 따라 동작과 사용자 인터페이스를 동적으로 조정할 수 있습니다. 이는 최적의 성능, 호환성, 그리고 각 사용자를 위한 맞춤형 경험을 보장합니다.

HID 보고서 및 디스크립터 이해하기

코드를 살펴보기 전에, HID 보고서와 디스크립터의 기본 개념을 이해하는 것이 중요합니다. 이것들은 장치가 호스트 시스템과 통신하는 방식을 정의하는 핵심 요소입니다.

HID 보고서

HID 보고서는 장치가 호스트로 보내거나 호스트로부터 받는 데이터 패킷입니다. 세 가지 주요 보고서 유형이 있습니다:

• 입력 보고서: 장치에서 호스트로 전송되는 데이터 (예: 버튼 누름, 센서 판독 값).
• 출력 보고서: 호스트에서 장치로 전송되는 데이터 (예: LED 색상 설정, 모터 속도 제어).
• 기능 보고서: 장치 기능 조회 및 구성에 사용 (예: 펌웨어 버전 검색, 감도 수준 설정).

HID 디스크립터

HID 디스크립터는 장치의 기능을 설명하는 이진 구조로, 다음을 포함합니다:

• 지원하는 보고서 유형 (입력, 출력, 기능).
• 각 보고서 내 데이터의 형식 (예: 크기, 데이터 유형, 비트 필드).
• 각 데이터 요소의 의미 (예: 버튼 1, X축, 온도 센서).

디스크립터는 본질적으로 운영 체제(그리고 확장하여 웹 애플리케이션)에게 장치가 보낸 데이터를 어떻게 해석해야 하는지 알려주는 청사진입니다. 이 디스크립터에 접근하고 파싱하는 것이 WebHID에서 기능 탐지의 기초입니다.

WebHID를 사용한 기능 탐지 방법

WebHID로 기능 탐지를 하는 데에는 여러 접근 방식이 있으며, 각각 장단점이 있습니다:

1. 수동 디스크립터 파싱: 가장 직접적이지만 가장 복잡한 방법입니다. 원시 HID 디스크립터를 가져와 HID 사양에 따라 수동으로 구조를 해석해야 합니다.
2. HID 보고서 ID 사용: 많은 장치가 보고서 ID를 사용하여 다른 유형의 보고서를 구별합니다. 특정 ID로 기능 보고서 요청을 보내면 해당 장치가 그 기능을 지원하는지 확인할 수 있습니다.
3. 공급업체 정의 사용 페이지 및 사용: HID 장치는 공급업체별 기능을 나타내기 위해 맞춤형 사용 페이지 및 사용을 정의할 수 있습니다. 이러한 값을 쿼리하면 특정 기능의 존재 여부를 식별할 수 있습니다.
4. 사전 정의된 기능 세트 또는 데이터베이스: 공급업체 ID, 제품 ID 또는 기타 식별자를 기반으로 알려진 장치 기능의 데이터베이스를 유지 관리합니다. 이를 통해 일반적인 장치에 대한 기능 탐지를 빠르고 쉽게 할 수 있습니다.

1. 수동 디스크립터 파싱: 심층 분석

수동 디스크립터 파싱은 기능 탐지에 대해 가장 세분화된 제어를 제공합니다. 다음 단계를 포함합니다:

1. 장치 접근 요청: navigator.hid.requestDevice()를 사용하여 사용자에게 HID 장치를 선택하라는 메시지를 표시합니다.
2. 장치 열기: device.open()을 호출하여 연결을 설정합니다.
3. HID 디스크립터 가져오기: 안타깝게도 WebHID API는 원시 HID 디스크립터를 직접 노출하지 않습니다. 이는 중대한 제한 사항입니다. 일반적인 해결 방법은 장치가 지원하는 경우 device.controlTransferIn()을 통해 "Get Descriptor" 제어 전송 요청을 보내는 것입니다. 그러나 이는 보편적으로 지원되지는 않습니다. 따라서 다른 방법이 일반적으로 더 신뢰할 수 있습니다.
4. 디스크립터 파싱: 디스크립터를 얻었다면(얻을 수 있다면!), HID 사양에 따라 파싱해야 합니다. 이는 이진 데이터를 디코딩하고 보고서 유형, 데이터 크기, 사용 및 기타 관련 세부 정보에 대한 정보를 추출하는 것을 포함합니다.

예시 (설명을 위한 것으로, 직접적인 디스크립터 접근은 제한적입니다):

이 예시는 디스크립터를 얻을 수 있는 방법이 있다고 가정합니다. 아마도 해결 방법이나 외부 라이브러리를 통해서일 것입니다. 이 부분이 까다로운 부분입니다.

async function getDeviceDescriptor(device) {
  // 바로 이 부분이 디스크립터를 얻는 데 있어 어려운 점입니다.
  // 실제로는 이 부분이 생략되거나 다른 방법으로 대체되는 경우가 많습니다.
  // 이 예시는 설명을 위한 목적으로만 사용됩니다.
  // 라이브러리나 다른 방법을 사용하여 디스크립터를 얻는 것을 고려해 보세요.
  
  // 디스크립터 수신 시뮬레이션 (실제 수신 코드로 대체)
  const descriptor = new Uint8Array([0x05, 0x01, 0x09, 0x02, 0xA1, 0x01, 0x09, 0x01, 0xA1, 0x00, 0x05, 0x09, 0x19, 0x01, 0x29, 0x03, 0x15, 0x00, 0x25, 0x01, 0x95, 0x03, 0x75, 0x01, 0x81, 0x02, 0x95, 0x01, 0x75, 0x05, 0x81, 0x03, 0x05, 0x01, 0x09, 0x30, 0x09, 0x31, 0x15, 0x81, 0x25, 0x7F, 0x75, 0x08, 0x95, 0x02, 0x81, 0x06, 0xC0, 0xC0]);
  return descriptor;
}

async function analyzeDescriptor(device) {
  const descriptor = await getDeviceDescriptor(device);

  // 이것은 파싱의 단순화된 예시입니다. 실제 파싱은 더 복잡합니다.
  let offset = 0;

  while (offset < descriptor.length) {
    const byte = descriptor[offset];

    switch (byte) {
      case 0x05: // 사용 페이지 (Usage Page)
        const usagePage = descriptor[offset + 1];
        console.log("Usage Page:", usagePage.toString(16));
        offset += 2;
        break;
      case 0x09: // 사용 (Usage)
        const usage = descriptor[offset + 1];
        console.log("Usage:", usage.toString(16));
        offset += 2;
        break;
      case 0xA1: // 컬렉션 (Collection)
        const collectionType = descriptor[offset + 1];
        console.log("Collection Type:", collectionType.toString(16));
        offset += 2;
        break;
      // ... 다른 아이템 타입을 위한 케이스들 ...
      default:
        console.log("Unknown Item:", byte.toString(16));
        offset++;
    }
  }
}

어려운 점:

• 복잡성: HID 디스크립터를 파싱하려면 HID 사양에 대한 깊은 이해가 필요합니다.
• 제한된 직접 접근: WebHID는 HID 디스크립터를 직접 제공하지 않으므로 이 방법을 안정적으로 구현하기 어렵습니다.
• 오류 발생 가능성: 수동 파싱은 디스크립터의 복잡한 구조로 인해 오류가 발생하기 쉽습니다.

사용 시기:

• 기능 탐지에 대해 가장 세분화된 제어가 필요하고 HID 사양을 이해하는 데 상당한 노력을 기울일 의향이 있을 때.
• 다른 방법으로는 필요한 특정 기능을 식별하기에 충분하지 않을 때.

2. HID 보고서 ID 사용: 특정 기능 쿼리

많은 HID 장치가 보고서 ID를 사용하여 여러 유형의 보고서를 구별합니다. 특정 ID로 기능 보고서 요청을 보내면 장치가 특정 기능을 지원하는지 확인할 수 있습니다. 이 방법은 기능이 존재할 경우 장치 펌웨어가 특정 값으로 응답하는 것에 의존합니다.

예시:

async function checkFeatureSupport(device, reportId, expectedResponse) {
  try {
    const data = new Uint8Array([reportId]); // 보고서 ID로 요청 준비
    await device.sendFeatureReport(reportId, data);

    //장치로부터 성공을 나타내는 입력 보고서를 수신 대기합니다.
    device.addEventListener("inputreport", (event) => {
        const { data, reportId } = event;
        const value = data.getUint8(0);  //단일 바이트 응답을 가정

        if(value === expectedResponse){
            console.log(`보고서 ID ${reportId}를 가진 기능이 지원됩니다.`);
            return true;
        } else {
            console.log(`보고서 ID ${reportId}를 가진 기능이 예상치 못한 값을 반환했습니다.`);
            return false;
        }
    });

    
    //또는, 장치가 getFeatureReport에 즉시 응답하는 경우
    // const data = await device.receiveFeatureReport(reportId);
    // if (data[0] === expectedResponse) {
    //   console.log(`보고서 ID ${reportId}를 가진 기능이 지원됩니다.`);
    //   return true;
    // } else {
    //   console.log(`보고서 ID ${reportId}를 가진 기능이 지원되지 않습니다.`);
    //   return false;
    // }

  } catch (error) {
    console.error(`보고서 ID ${reportId}를 가진 기능 확인 중 오류 발생:`, error);
    return false; // 오류가 발생하면 기능이 지원되지 않는 것으로 간주
  }

  return false;
}


async function detectDeviceFeatures(device) {
  // 예시 1: 특정 LED 제어 기능 확인 (가상의 보고서 ID)
  const ledControlReportId = 0x01;
  const ledControlResponseValue = 0x01; //LED 지원을 나타내는 예상 값.
  const hasLedControl = await checkFeatureSupport(device, ledControlReportId, ledControlResponseValue);

  if (hasLedControl) {
    console.log("장치가 LED 제어를 지원합니다!");
  } else {
    console.log("장치가 LED 제어를 지원하지 않습니다.");
  }

  // 예시 2: 특정 센서 기능 확인 (가상의 보고서 ID)
  const sensorReportId = 0x02;
  const sensorResponseValue = 0x01; //센서 지원을 나타내는 예상 값.
  const hasSensor = await checkFeatureSupport(device, sensorReportId, sensorResponseValue);

  if (hasSensor) {
    console.log("장치에 센서가 있습니다!");
  } else {
    console.log("장치에 센서가 없습니다.");
  }
}

어려운 점:

• 장치별 지식 필요: 탐지하려는 기능에 대한 특정 보고서 ID와 예상 응답을 알아야 합니다. 이 정보는 일반적으로 장치의 문서나 사양에서 찾을 수 있습니다.
• 오류 처리: 장치가 응답하지 않거나 예상치 못한 값을 반환하는 등의 잠재적 오류를 처리해야 합니다.
• 장치 일관성 가정: 특정 보고서 ID가 동일한 유형의 다른 장치에서도 항상 동일한 기능에 해당한다는 가정에 의존합니다.

사용 시기:

• 필요한 보고서 ID와 예상 응답을 제공하는 장치 문서나 사양에 접근할 수 있을 때.
• 표준 HID 사용으로 다루어지지 않는 특정 기능을 탐지해야 할 때.

3. 공급업체 정의 사용 페이지 및 사용: 맞춤 기능 식별

HID 사양은 공급업체가 공급업체별 기능을 나타내기 위해 맞춤형 사용 페이지 및 사용을 정의할 수 있도록 허용합니다. 사용 페이지는 관련 사용에 대한 네임스페이스이며, 사용은 해당 페이지 내의 특정 기능이나 속성을 정의합니다. 이러한 공급업체 정의 값을 쿼리하여 맞춤형 기능의 존재를 식별할 수 있습니다.

예시:

이 예시는 개념을 보여줍니다. 실제 구현은 사용 가능한 사용을 결정하기 위해 보고서 디스크립터를 읽어야 할 수 있습니다.

// 이것은 개념적인 설명입니다. WebHID는 직접적으로
// 추가적인 디스크립터 분석 없이는 사용 페이지/사용을 쿼리하는 메서드를 노출하지 않습니다.

async function checkVendorDefinedFeature(device, vendorId, featureUsagePage, featureUsage) {
  // 단순화된 로직 - 향후 WebHID 버전에 사용 가능한 실제 메서드로 대체하세요
  if (device.vendorId === vendorId) {
    // 내부적으로 사용 확인이 가능하다고 가정
    // if (device.hasUsage(featureUsagePage, featureUsage)) { // 가상의 함수
    //   console.log("장치가 공급업체 정의 기능을 지원합니다!");
    //   return true;
    // }

    console.log("공급업체 정의 기능을 직접 확인할 수 없습니다. 다른 방법을 고려하세요.");

  } else {
    console.log("장치가 예상 공급업체 ID와 일치하지 않습니다.");
  }

  return false;
}


async function detectVendorFeatures(device) {
  // 예시: 공급업체 XYZ가 정의한 맞춤 기능 확인 (가상)
  const vendorId = 0x1234; // 가상의 공급업체 ID
  const featureUsagePage = 0xF001; // 가상의 공급업체 정의 사용 페이지
  const featureUsage = 0x0001; // 해당 기능을 위한 가상의 사용

  const hasVendorFeature = await checkVendorDefinedFeature(device, vendorId, featureUsagePage, featureUsage);

  // 기능 보고서를 사용하는 대안적인 접근법의 예시. 실제 사용을 위해서는 보고서 디스크립터 분석이 필요합니다.
  if (hasVendorFeature) {
    console.log("장치가 공급업체 XYZ의 맞춤 기능을 지원합니다!");
  } else {
    console.log("장치가 공급업체 XYZ의 맞춤 기능을 지원하지 않습니다.");
  }
}

어려운 점:

• 공급업체 문서 필요: 맞춤형 사용 페이지 및 사용의 의미를 이해하려면 공급업체 문서에 접근해야 합니다.
• 표준화 부족: 공급업체 정의 기능은 표준화되어 있지 않아 일반적인 기능 탐지 코드를 작성하기 어렵습니다.
• 제한된 WebHID 지원: 현재 WebHID 구현은 더 고급 보고서 디스크립터 분석 없이는 사용 페이지 및 사용을 쿼리하는 메서드를 직접 노출하지 않을 수 있습니다.

사용 시기:

• 특정 공급업체의 하드웨어로 작업하고 해당 문서에 접근할 수 있을 때.
• 표준 HID 사용으로 다루어지지 않는 맞춤형 기능을 탐지해야 할 때.

4. 사전 정의된 기능 세트 또는 데이터베이스: 장치 인식 단순화

기능 탐지에 대한 실용적인 접근 방식 중 하나는 공급업체 ID, 제품 ID 또는 기타 식별 특성을 기반으로 알려진 장치 기능의 데이터베이스를 유지하는 것입니다. 이를 통해 웹 애플리케이션은 일반적인 장치를 신속하게 식별하고 사전 정의된 구성 또는 기능 세트를 적용할 수 있습니다.

예시:

const deviceDatabase = {
  "046d:c52b": { // 로지텍 G502 게이밍 마우스 (공급업체 ID:제품 ID)
    features: {
      dpiAdjustment: true,
      programmableButtons: 11,
      rgbLighting: true
    }
  },
  "04f3:0c4b": { // 엘가토 스트림 덱 (공급업체 ID:제품 ID)
    features: {
      lcdButtons: true,
      customIcons: true,
      hotkeys: true
    }
  }
  // ... 더 많은 장치 정의 ...
};


async function detectDeviceFeaturesFromDatabase(device) {
  const deviceId = `${device.vendorId.toString(16)}:${device.productId.toString(16)}`;

  if (deviceDatabase[deviceId]) {
    const features = deviceDatabase[deviceId].features;
    console.log("데이터베이스에서 장치를 찾았습니다!");
    console.log("기능:", features);
    return features;
  } else {
    console.log("데이터베이스에서 장치를 찾을 수 없습니다.");
    return null; // 인식되지 않은 장치
  }
}

어려운 점:

• 데이터베이스 유지 관리: 새로운 장치와 기능으로 데이터베이스를 최신 상태로 유지하려면 지속적인 노력이 필요합니다.
• 제한된 적용 범위: 데이터베이스에 모든 가능한 HID 장치, 특히 덜 일반적이거나 맞춤형 하드웨어에 대한 정보가 포함되어 있지 않을 수 있습니다.
• 부정확성 가능성: 데이터베이스의 장치 정보가 불완전하거나 부정확하여 잘못된 기능 탐지로 이어질 수 있습니다.

사용 시기:

• 다양한 일반 HID 장치를 지원해야 할 때.
• 사용자가 수동으로 기능을 설정할 필요 없이 장치를 빠르고 쉽게 구성하는 방법을 제공하고 싶을 때.
• 다른 기능 탐지 방법이 실패했을 때의 대체 메커니즘으로.

WebHID 기능 탐지를 위한 모범 사례

• 사용자 개인정보 보호 우선: 항상 사용자에게 명시적으로 장치 접근을 요청하고 HID 장치에 접근해야 하는 이유를 명확하게 설명하세요.
• 대체 메커니즘 제공: 기능 탐지에 실패할 경우 사용자가 수동으로 장치를 구성하거나 지원되는 기능 목록에서 선택할 수 있는 방법을 제공하세요.
• 오류를 정상적으로 처리: 예기치 않은 동작이나 충돌을 방지하기 위해 강력한 오류 처리 기능을 구현하세요.
• 비동기 작업 사용: WebHID 작업은 비동기적이므로 async와 await를 사용하여 메인 스레드를 차단하지 않도록 하세요.
• 성능 최적화: 성능을 개선하고 배터리 소모를 줄이기 위해 기능 탐지 요청 수를 최소화하세요.
• 외부 라이브러리 고려: WebHID 기능 탐지를 위한 고수준 추상화를 제공하는 외부 라이브러리나 모듈 사용을 고려해 보세요.
• 철저한 테스트: 호환성과 정확성을 보장하기 위해 다양한 HID 장치로 코드를 테스트하세요. 테스트 프로세스를 간소화하기 위해 자동화된 테스트 프레임워크 사용을 고려하세요.

실제 예시 및 사용 사례

• 게임: 탐지된 버튼, 축, 센서를 기반으로 게임패드 레이아웃을 동적으로 조정합니다.
• 접근성: 대체 키보드나 포인팅 장치와 같은 보조 장치를 위해 사용자 인터페이스를 조정합니다.
• 산업 제어: 제조, 로봇 공학 및 기타 산업 응용 분야에서 사용되는 맞춤형 센서 및 액추에이터와 상호 작용합니다. 예를 들어, 웹 애플리케이션은 USB-HID를 통해 연결된 특정 온도 센서나 압력계의 존재를 감지할 수 있습니다.
• 교육: 전자 현미경이나 데이터 수집 시스템과 같은 특수 하드웨어를 활용하는 대화형 학습 도구를 구축합니다.
• 의료: 원격 환자 모니터링을 위해 맥박 산소 측정기나 혈압 모니터와 같은 의료 기기에 연결합니다.
• 디지털 아트: 압력 감도 및 기울기 감지 기능이 있는 다양한 드로잉 태블릿과 스타일러스를 지원합니다. 전 세계 아티스트들이 사용하는 와콤 태블릿을 지원하여 압력 수준과 버튼 구성을 정확하게 해석하는 것이 글로벌한 예시가 될 수 있습니다.

결론

기능 탐지는 WebHID를 사용하여 강력하고 사용자 친화적인 웹 애플리케이션을 구축하는 데 중요한 측면입니다. HID 보고서, 디스크립터 및 다양한 탐지 방법의 개념을 이해함으로써 이 강력한 API의 모든 잠재력을 발휘할 수 있습니다. 특히 직접적인 디스크립터 접근에 어려움이 있지만, 다양한 접근 방식을 결합하고 외부 리소스를 활용하면 더 효과적이고 적응력 있는 솔루션을 만들 수 있습니다. WebHID가 계속 발전함에 따라 기능 탐지 기능이 더욱 향상되어 다양한 하드웨어 장치와 원활하게 상호 작용하는 매력적인 웹 경험을 만드는 것이 훨씬 쉬워질 것으로 기대됩니다.

사용자 개인정보 보호를 우선시하고, 오류를 정상적으로 처리하며, 철저한 테스트를 통해 사용자에게 긍정적이고 신뢰할 수 있는 경험을 보장하는 것을 잊지 마세요. WebHID 기능 탐지 기술을 마스터함으로써 디지털 세계와 물리적 세계 사이의 격차를 해소하는 진정으로 혁신적이고 매력적인 웹 애플리케이션을 구축할 수 있습니다.