Перечисление устройств WebHID на стороне клиента: обнаружение подключенных устройств с помощью JavaScript

API WebHID открывает возможности для веб-приложений по прямому взаимодействию с широким спектром устройств человеко-машинного интерфейса (HID), которые обычно доступны только нативным приложениям. Это открывает захватывающие перспективы для создания инновационных веб-интерфейсов, взаимодействующих со специализированным оборудованием, таким как игровые контроллеры, пользовательские устройства ввода, научные приборы и многое другое. Это исчерпывающее руководство посвящено основной концепции перечисления устройств, которая является важнейшим первым шагом для установления соединения с желаемым HID-устройством.

Что такое API WebHID?

API WebHID позволяет веб-приложениям получать доступ к устройствам человеко-машинного интерфейса. Эти устройства охватывают широкую категорию, включая:

• Игровые контроллеры: Джойстики, геймпады, рули гонок
• Устройства ввода: Клавиатуры, мыши, трекболы
• Промышленное управление: Специализированные панели управления, интерфейсы датчиков
• Научные приборы: Устройства сбора данных, измерительные приборы
• Пользовательское оборудование: Индивидуальные устройства ввода, созданные для конкретных целей

В отличие от старых API браузеров, которые предлагали ограниченную поддержку HID, API WebHID обеспечивает прямой доступ к HID-устройствам, позволяя разработчикам создавать более богатые и интерактивные веб-приложения. Представьте себе управление роботизированной рукой в удаленной лаборатории, манипулирование 3D-моделью с помощью пользовательского устройства ввода или получение данных с датчиков непосредственно в веб-панели управления — все это в браузере.

Понимание перечисления HID-устройств

Прежде чем вы сможете взаимодействовать с HID-устройством, ваше веб-приложение должно обнаружить, какие устройства подключены к системе пользователя. Этот процесс называется перечислением устройств. API WebHID предоставляет механизм для запроса доступа к определенным HID-устройствам на основе идентификатора поставщика (VID) и идентификатора продукта (PID) или с использованием более широкого фильтра.

Процесс обычно включает следующие шаги:

1. Запрос доступа к устройству: Веб-приложение предлагает пользователю выбрать HID-устройство с помощью navigator.hid.requestDevice().
2. Фильтрация устройств: Вы можете указать фильтры для сужения списка устройств, представленных пользователю. Эти фильтры основаны на VID и PID устройства.
3. Обработка выбора устройства: Пользователь выбирает устройство из списка.
4. Открытие устройства: Приложение открывает соединение с выбранным устройством.
5. Передача данных: После установления соединения приложение может отправлять и получать данные от устройства.

Пошаговое руководство по перечислению устройств

1. Запрос доступа к устройству с фильтрами

Метод navigator.hid.requestDevice() является точкой входа для запроса доступа к HID-устройствам. Он принимает необязательный аргумент `filters`, который представляет собой массив объектов, определяющих VID и PID устройств, которые вы хотите найти.

Вот пример запроса доступа к устройству с определенными VID и PID:

async function requestHIDDevice() {
  try {
    const devices = await navigator.hid.requestDevice({
      filters: [
        {
          vendorId: 0x1234, // Замените на Vendor ID вашего устройства
          productId: 0x5678 // Замените на Product ID вашего устройства
        },
        // Добавьте больше фильтров для других устройств при необходимости
      ]
    });

    if (devices.length > 0) {
      const device = devices[0]; // Используем первое выбранное устройство
      console.log("HID Device Found:", device);
      // Открываем устройство и начинаем связь
      await openHIDDevice(device);
    } else {
      console.log("No HID device selected.");
    }
  } catch (error) {
    console.error("Error requesting HID device:", error);
  }
}

// Пример использования (например, срабатывает при нажатии кнопки):
document.getElementById('requestButton').addEventListener('click', requestHIDDevice);

Важные соображения:

• Идентификатор поставщика (VID) и идентификатор продукта (PID): Это уникальные идентификаторы, присвоенные USB и Bluetooth устройствам. Вам потребуется получить VID и PID целевого устройства из документации производителя или с помощью системных инструментов (например, Диспетчера устройств в Windows, Системной информации в macOS или `lsusb` в Linux).
• Согласие пользователя: Метод requestDevice() отображает управляемый браузером запрос на разрешение для пользователя, позволяя ему выбрать, к каким HID-устройствам предоставить доступ. Это важная мера безопасности, предотвращающая доступ вредоносных веб-сайтов к конфиденциальному оборудованию без согласия пользователя.
• Несколько фильтров: Вы можете включить несколько фильтров в массив `filters` для запроса доступа к устройствам с различными VID и PID. Это полезно, если ваше приложение поддерживает несколько аппаратных конфигураций.

2. Получение информации об устройстве

После того как пользователь выбрал устройство, метод requestDevice() возвращает массив объектов HIDDevice. Каждый объект HIDDevice содержит информацию об устройстве, такую как его VID, PID, usagePage, usage и collections. Вы можете использовать эту информацию для дальнейшей идентификации и настройки устройства.

async function openHIDDevice(device) {
  try {
    await device.open();
    console.log("HID Device Opened:", device.productName);

    // Прослушивание отчетов ввода
    device.addEventListener("inputreport", event => {
      const { data, reportId } = event;
      const uint8Array = new Uint8Array(data.buffer);
      console.log(`Received input report ${reportId}:`, uint8Array);
      // Обработка данных отчета ввода
    });

    device.addEventListener("disconnect", event => {
      console.log("HID Device Disconnected:", device.productName);
      // Обработка отключения устройства
    });

  } catch (error) {
    console.error("Error opening HID device:", error);
  }
}

Свойства устройства:

• vendorId: Идентификатор поставщика устройства.
• productId: Идентификатор продукта устройства.
• productName: Человекочитаемое название продукта.
• collections: Массив объектов HIDCollectionInfo, описывающих коллекции HID устройства (отчеты, функции и т. д.). Это может быть очень сложно и требуется только для сложных устройств.

3. Обработка подключения и отключения устройства

API WebHID предоставляет события для уведомления вашего приложения о подключении или отключении устройства. Вы можете прослушивать события connect и disconnect в объекте navigator.hid.

navigator.hid.addEventListener("connect", event => {
  const device = event.device;
  console.log("HID Device Connected:", device);
  // Обработка подключения устройства (например, повторное открытие устройства)
});

avigator.hid.addEventListener("disconnect", event => {
  const device = event.device;
  console.log("HID Device Disconnected:", device);
  // Обработка отключения устройства (например, очистка ресурсов)
});

Лучшие практики управления подключениями:

• Повторное перечисление при подключении: Когда устройство подключается, часто рекомендуется повторно перечислять устройства, чтобы убедиться, что ваше приложение имеет актуальный список.
• Очистка ресурсов при отключении: Когда устройство отключается, освободите все связанные с ним ресурсы (например, закройте соединение с устройством, удалите обработчики событий).
• Обработка ошибок: Реализуйте надежную обработку ошибок для корректной обработки ситуаций, когда устройство не удается подключить или оно неожиданно отключается.

Продвинутые методы фильтрации устройств

Помимо базовой фильтрации VID и PID, API WebHID предлагает более продвинутые методы для нацеливания на конкретные устройства. Это особенно полезно при работе с устройствами, имеющими несколько интерфейсов или функций.

1. Фильтрация по Usage Page и Usage

HID-устройства организованы в *usage pages* (страницы использования) и *usages* (использования), которые определяют тип функциональности, предоставляемой устройством. Например, клавиатура относится к странице использования «Generic Desktop» и имеет использование «Keyboard». Вы можете фильтровать устройства на основе их usage page и usage для нацеливания на определенные типы устройств.

async function requestSpecificKeyboard() {
  try {
    const devices = await navigator.hid.requestDevice({
      filters: [
        {
          usagePage: 0x01, // Generic Desktop Page
          usage: 0x06      // Keyboard Usage
        }
      ]
    });

    // ... (остальной код для обработки устройства)
  } catch (error) {
    console.error("Error requesting HID device:", error);
  }
}

Поиск значений Usage Page и Usage:

• HID Usage Tables: Официальные таблицы использования HID (опубликованные USB Implementers Forum) определяют стандартизированные usage pages и usages для различных типов устройств.
• Документация к устройству: Документация производителя устройства может указывать значения usage page и usage для их устройства.
• Дескрипторы отчетов HID: Для продвинутых сценариев вы можете анализировать дескриптор отчетов HID устройства, чтобы определить поддерживаемые им usage pages и usages.

2. Обработка нескольких интерфейсов

Некоторые HID-устройства предоставляют несколько интерфейсов, каждый из которых имеет свой набор функций. API WebHID рассматривает каждый интерфейс как отдельное HID-устройство. Чтобы получить доступ к определенному интерфейсу, вам может потребоваться объединить фильтрацию VID/PID с фильтрацией usage page/usage для нацеливания на желаемый интерфейс.

Практические примеры и варианты использования

1. Создание интерфейса пользовательского игрового контроллера

Представьте, что вы создаете веб-игру и хотите поддерживать пользовательский игровой контроллер. Вы можете использовать API WebHID для прямого считывания ввода с кнопок, джойстиков и других элементов управления контроллера. Это позволяет создать высокоотзывчивый и захватывающий игровой процесс.

2. Создание веб-MIDI-контроллера

Музыканты и инженеры звукозаписи могут извлечь выгоду из веб-MIDI-контроллеров, которые взаимодействуют с цифровыми звуковыми рабочими станциями (DAW) или синтезаторами. API WebHID позволяет создавать пользовательские MIDI-контроллеры, которые отправляют и получают MIDI-сообщения непосредственно в браузере.

3. Взаимодействие с научными приборами

Исследователи и ученые могут использовать API WebHID для подключения к научным приборам, таким как устройства сбора данных, датчики и измерительные инструменты. Это позволяет им собирать и анализировать данные непосредственно в веб-панели управления или инструменте анализа.

4. Приложения для доступности

WebHID предоставляет возможности для создания вспомогательных технологий. Например, специализированные устройства ввода для пользователей с нарушениями моторики могут быть интегрированы непосредственно в веб-приложения, предоставляя более индивидуальный и доступный опыт. Глобальные примеры могут включать интеграцию специализированных устройств отслеживания взгляда для навигации без рук или настраиваемые массивы кнопок для доступа одной кнопкой в различных языках и методах ввода.

Кросс-браузерная совместимость и соображения безопасности

1. Поддержка браузеров

API WebHID в настоящее время поддерживается в браузерах на базе Chromium (Chrome, Edge, Opera) и находится в стадии разработки для других браузеров. Прежде чем внедрять API WebHID в свое приложение, важно проверить совместимость браузеров и предоставить механизмы резервного копирования для браузеров, которые не поддерживают API.

2. Соображения безопасности

API WebHID разработан с учетом безопасности. Браузер запрашивает у пользователя разрешение, прежде чем разрешить веб-приложению доступ к HID-устройству. Это предотвращает доступ вредоносных веб-сайтов к конфиденциальному оборудованию без согласия пользователя. Кроме того, API WebHID работает в песочнице безопасности браузера, ограничивая доступ приложения к системным ресурсам.

• Только HTTPS: WebHID, как и другие мощные веб-API, требует безопасного контекста (HTTPS) для работы.
• Жесты пользователя: Запрос доступа к устройству обычно требует жеста пользователя (например, нажатия кнопки), чтобы предотвратить нежелательные запросы доступа.
• API разрешений: API разрешений может использоваться для запроса и управления разрешениями WebHID.

Устранение распространенных проблем

1. Устройство не найдено

Если ваше приложение не может найти HID-устройство, дважды проверьте VID и PID. Убедитесь, что они совпадают с фактическими идентификаторами устройства. Также убедитесь, что устройство правильно подключено и распознано операционной системой.

2. Отказано в разрешении

Если пользователь отказывает в разрешении на доступ к HID-устройству, ваше приложение не сможет с ним взаимодействовать. Обработайте этот сценарий корректно, отобразив сообщение пользователю и объяснив, почему требуется доступ. Рассмотрите возможность предоставления пользователю альтернативных способов взаимодействия с вашим приложением.

3. Проблемы с форматом данных

HID-устройства часто используют пользовательские форматы данных для отправки и получения данных. Вам потребуется понять формат данных устройства и реализовать соответствующую логику разбора и сериализации в вашем приложении. Обратитесь к документации производителя устройства для получения информации о формате данных.

Заключение

API WebHID дает веб-разработчикам возможность создавать инновационные и интерактивные веб-приложения, которые напрямую взаимодействуют с устройствами человеко-машинного интерфейса. Понимая принципы перечисления устройств, фильтрации и управления соединениями, вы можете раскрыть весь потенциал API WebHID и создать убедительные пользовательские интерфейсы. Используйте мощь WebHID для подключения веба к физическому миру, способствуя появлению новых возможностей для творчества, продуктивности и доступности во всем мире.

Дополнительные ресурсы

• Спецификация API WebHID
• API WebHID на Chrome Developers
• USB Implementers Forum (Информация о HID)