Вичерпний посібник із виявлення та взаємодії з пристроями людського інтерфейсу (HID) за допомогою WebHID API в JavaScript. Дізнайтеся про перелік пристроїв, фільтрацію та найкращі практики підключення.
Перелік пристроїв WebHID на фронтенді: виявлення підключених пристроїв за допомогою JavaScript
WebHID API розблоковує потенціал веб-додатків для прямої взаємодії з широким спектром пристроїв людського інтерфейсу (HID), які зазвичай доступні лише для нативних додатків. Це відкриває захоплюючі можливості для створення інноваційних веб-інтерфейсів, які взаємодіють зі спеціалізованим обладнанням, таким як ігрові контролери, користувацькі пристрої введення, наукові інструменти та багато іншого. Цей вичерпний посібник заглиблюється в основну концепцію переліку пристроїв, що є першим і вирішальним кроком у встановленні з'єднання з потрібним HID-пристроєм.
Що таке WebHID API?
WebHID API дозволяє веб-додаткам отримувати доступ до пристроїв людського інтерфейсу (Human Interface Devices). Ці пристрої охоплюють широку категорію, включаючи:
- Ігрові контролери: джойстики, геймпади, гоночні керма
- Пристрої введення: клавіатури, миші, трекболи
- Промислові контролери: спеціалізовані панелі керування, сенсорні інтерфейси
- Наукові інструменти: пристрої збору даних, вимірювальні прилади
- Спеціальне обладнання: унікальні пристрої введення, створені для конкретних цілей
На відміну від старих браузерних API, які пропонували обмежену підтримку HID, WebHID API надає прямий доступ до HID-пристроїв, дозволяючи розробникам створювати більш насичені та інтерактивні веб-додатки. Уявіть, що ви керуєте роботизованою рукою у віддаленій лабораторії, маніпулюєте 3D-моделлю за допомогою спеціального пристрою введення або отримуєте дані з датчиків безпосередньо на веб-панелі — і все це в межах браузера.
Розуміння переліку HID-пристроїв
Перш ніж ви зможете взаємодіяти з HID-пристроєм, ваш веб-додаток повинен виявити, які пристрої підключені до системи користувача. Цей процес називається переліком пристроїв. WebHID API надає механізм для запиту доступу до конкретних HID-пристроїв на основі ідентифікатора постачальника (VID) та ідентифікатора продукту (PID) або за допомогою більш широкого фільтра.
Процес зазвичай включає наступні кроки:
- Запит доступу до пристрою: веб-додаток пропонує користувачеві вибрати HID-пристрій за допомогою
navigator.hid.requestDevice(). - Фільтрація пристроїв: ви можете вказати фільтри, щоб звузити список пристроїв, представлених користувачеві. Ці фільтри базуються на VID та PID пристрою.
- Обробка вибору пристрою: користувач вибирає пристрій зі списку.
- Відкриття пристрою: додаток відкриває з'єднання з обраним пристроєм.
- Передача даних: після встановлення з'єднання додаток може надсилати та отримувати дані з пристрою.
Покрокове керівництво з переліку пристроїв
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);
Важливі зауваження:
- Vendor ID (VID) та Product ID (PID): це унікальні ідентифікатори, що присвоюються USB та Bluetooth-пристроям. Вам потрібно отримати VID та PID вашого цільового пристрою з документації виробника або за допомогою системних утиліт (наприклад, Device Manager у Windows, System Information у 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: ID постачальника пристрою.productId: ID продукту пристрою.productName: Зрозуміла для людини назва продукту.collections: Масив об'єктів HIDCollectionInfo, що описують HID-колекції пристрою (звіти, функції тощо). Це може бути дуже складним і потрібно лише для комплексних пристроїв.
3. Обробка підключення та відключення пристрою
WebHID API надає події для сповіщення вашого додатка про підключення або відключення пристрою. Ви можете прослуховувати події connect та disconnect на об'єкті navigator.hid.
navigator.hid.addEventListener("connect", event => {
const device = event.device;
console.log("HID Device Connected:", device);
// Обробити підключення пристрою (наприклад, повторно відкрити пристрій)
});
navigator.hid.addEventListener("disconnect", event => {
const device = event.device;
console.log("HID Device Disconnected:", device);
// Обробити відключення пристрою (наприклад, очистити ресурси)
});
Найкращі практики управління підключеннями:
- Повторний перелік при підключенні: коли пристрій підключається, часто є хорошою практикою повторно виконати перелік пристроїв, щоб переконатися, що ваш додаток має актуальний список.
- Очищення ресурсів при відключенні: коли пристрій відключається, звільніть будь-які пов'язані з ним ресурси (наприклад, закрийте з'єднання з пристроєм, видаліть слухачів подій).
- Обробка помилок: реалізуйте надійну обробку помилок для коректної обробки ситуацій, коли пристрій не може підключитися або несподівано відключається.
Розширені методи фільтрації пристроїв
Окрім базової фільтрації за VID та PID, WebHID API пропонує більш просунуті методи для націлювання на конкретні пристрої. Це особливо корисно при роботі з пристроями, які мають кілька інтерфейсів або функціональностей.
1. Фільтрація за сторінкою використання (Usage Page) та використанням (Usage)
HID-пристрої організовані у *сторінки використання* та *використання*, які визначають тип функціональності, що надає пристрій. Наприклад, клавіатура належить до сторінки використання "Generic Desktop" і має використання "Keyboard". Ви можете фільтрувати пристрої на основі їхньої сторінки використання та використання, щоб націлюватися на конкретні типи пристроїв.
async function requestSpecificKeyboard() {
try {
const devices = await navigator.hid.requestDevice({
filters: [
{
usagePage: 0x01, // Сторінка Generic Desktop
usage: 0x06 // Використання Keyboard
}
]
});
// ... (решта коду для обробки пристрою)
} catch (error) {
console.error("Error requesting HID device:", error);
}
}
Пошук значень сторінки використання та використання:
- Таблиці використання HID: офіційні таблиці використання HID (опубліковані USB Implementers Forum) визначають стандартизовані сторінки використання та використання для різних типів пристроїв.
- Документація пристрою: документація виробника пристрою може вказувати значення сторінки використання та використання для їхнього пристрою.
- Дескриптори звітів HID: для просунутих сценаріїв ви можете проаналізувати дескриптор звіту HID пристрою, щоб визначити підтримувані ним сторінки використання та використання.
2. Робота з кількома інтерфейсами
Деякі HID-пристрої надають кілька інтерфейсів, кожен зі своїм набором функціональностей. WebHID API розглядає кожен інтерфейс як окремий HID-пристрій. Щоб отримати доступ до конкретного інтерфейсу, вам може знадобитися поєднати фільтрацію за VID/PID з фільтрацією за сторінкою використання/використанням, щоб націлитися на потрібний інтерфейс.
Практичні приклади та сценарії використання
1. Створення власного інтерфейсу ігрового контролера
Уявіть, що ви створюєте веб-гру і хочете підтримувати власний ігровий контролер. Ви можете використовувати WebHID API для прямого зчитування вводу з кнопок, джойстиків та інших елементів керування контролера. Це дозволяє створювати надзвичайно чутливий та захоплюючий ігровий досвід.
2. Створення веб-контролера MIDI
Музиканти та звукорежисери можуть отримати користь від веб-контролерів MIDI, які взаємодіють з цифровими аудіо робочими станціями (DAW) або синтезаторами. WebHID API дозволяє створювати власні MIDI-контролери, які надсилають та отримують MIDI-повідомлення безпосередньо в браузері.
3. Взаємодія з науковими приладами
Дослідники та вчені можуть використовувати WebHID API для взаємодії з науковими приладами, такими як пристрої збору даних, датчики та вимірювальні інструменти. Це дозволяє їм збирати та аналізувати дані безпосередньо у веб-панелі або інструменті аналізу.
4. Додатки для доступності
WebHID надає можливості для створення допоміжних технологій. Наприклад, спеціалізовані пристрої введення для користувачів з порушеннями рухового апарату можуть бути інтегровані безпосередньо у веб-додатки, забезпечуючи більш налаштований та доступний досвід. Глобальні приклади можуть включати інтеграцію спеціалізованих пристроїв для відстеження погляду для навігації без рук або налаштовуваних масивів кнопок для доступу одним перемикачем для різних мов та методів введення.
Сумісність з браузерами та питання безпеки
1. Підтримка браузерами
WebHID API наразі підтримується в браузерах на основі Chromium (Chrome, Edge, Opera) і перебуває в розробці для інших браузерів. Перед впровадженням WebHID API у ваш додаток важливо перевірити сумісність з браузерами та надати резервні механізми для браузерів, які не підтримують API.
2. Питання безпеки
WebHID API розроблено з урахуванням безпеки. Браузер запитує дозвіл користувача перед тим, як дозволити веб-додатку отримати доступ до HID-пристрою. Це запобігає доступу шкідливих веб-сайтів до чутливого обладнання без згоди користувача. Крім того, WebHID API працює в межах "пісочниці" безпеки браузера, обмежуючи доступ додатка до системних ресурсів.
- Лише HTTPS: WebHID, як і інші потужні веб-API, для роботи вимагає безпечного контексту (HTTPS).
- Дії користувача: запит на доступ до пристрою зазвичай вимагає дії користувача (наприклад, кліку на кнопку), щоб запобігти небажаним запитам на доступ.
- Permissions API: Permissions API можна використовувати для запиту та керування дозволами WebHID.
Вирішення поширених проблем
1. Пристрій не знайдено
Якщо ваш додаток не може знайти HID-пристрій, перевірте ще раз VID та PID. Переконайтеся, що вони відповідають фактичним ідентифікаторам пристрою. Також перевірте, чи пристрій правильно підключений та розпізнаний операційною системою.
2. У доступі відмовлено
Якщо користувач відмовляє у дозволі на доступ до HID-пристрою, ваш додаток не зможе з ним взаємодіяти. Обробляйте цей сценарій коректно, відображаючи повідомлення користувачеві та пояснюючи, чому потрібен доступ. Розгляньте можливість надання альтернативних способів взаємодії користувача з вашим додатком.
3. Проблеми з форматом даних
HID-пристрої часто використовують власні формати даних для надсилання та отримання інформації. Вам потрібно буде зрозуміти формат даних пристрою та реалізувати відповідну логіку розбору та серіалізації у вашому додатку. Зверніться до документації виробника пристрою для отримання інформації про формат даних.
Висновок
WebHID API надає веб-розробникам можливість створювати інноваційні та інтерактивні веб-додатки, які безпосередньо взаємодіють з пристроями людського інтерфейсу. Розуміючи принципи переліку пристроїв, фільтрації та управління підключеннями, ви можете розкрити весь потенціал WebHID API та створити захоплюючі користувацькі досвіди. Використовуйте потужність WebHID, щоб з'єднати веб із фізичним світом, відкриваючи нові можливості для творчості, продуктивності та доступності в усьому світі.