Frontend WebHID-apparaat-enumeratie: Verbonden apparaatdetectie met JavaScript

De WebHID API ontsluit het potentieel voor webapplicaties om rechtstreeks te communiceren met een breed scala aan Human Interface Devices (HIDs) die doorgaans alleen toegankelijk zijn voor native applicaties. Dit opent spannende mogelijkheden voor het creëren van innovatieve webervaringen die interageren met gespecialiseerde hardware zoals gamecontrollers, aangepaste invoerapparaten, wetenschappelijke instrumenten en meer. Deze uitgebreide gids duikt in het kernconcept van apparaat-enumeratie, wat de cruciale eerste stap is bij het tot stand brengen van een verbinding met een gewenst HID-apparaat.

Wat is de WebHID API?

De WebHID API stelt webapplicaties in staat om toegang te krijgen tot Human Interface Devices. Deze apparaten omvatten een brede categorie, waaronder:

• Gamecontrollers: Joysticks, gamepads, racesturen
• Invoerapparaten: Toetsenborden, muizen, trackballs
• Industriële bedieningselementen: Gespecialiseerde bedieningspanelen, sensorinterfaces
• Wetenschappelijke instrumenten: Apparaten voor gegevensverzameling, meetinstrumenten
• Aangepaste hardware: Op maat gemaakte invoerapparaten die voor specifieke doeleinden zijn gemaakt

In tegenstelling tot oudere browser-API's die beperkte HID-ondersteuning boden, biedt de WebHID API directe toegang tot HID-apparaten, waardoor ontwikkelaars rijkere en interactievere webapplicaties kunnen maken. Stel je voor dat je een robotarm in een extern laboratorium bestuurt, een 3D-model manipuleert met een aangepast invoerapparaat, of sensorgegevens rechtstreeks ontvangt in een webgebaseerd dashboard - allemaal binnen de browser.

Inzicht in HID-apparaat-enumeratie

Voordat je kunt interageren met een HID-apparaat, moet je webapplicatie ontdekken welke apparaten op het systeem van de gebruiker zijn aangesloten. Dit proces wordt apparaat-enumeratie genoemd. De WebHID API biedt een mechanisme voor het aanvragen van toegang tot specifieke HID-apparaten op basis van leveranciers-ID (VID) en product-ID (PID) of door een breder filter te gebruiken.

Het proces omvat doorgaans de volgende stappen:

1. Toegang tot het aanvragen van apparaten: De webapplicatie vraagt de gebruiker om een HID-apparaat te selecteren met behulp van navigator.hid.requestDevice().
2. Apparaten filteren: Je kunt filters specificeren om de lijst met apparaten die aan de gebruiker worden gepresenteerd te beperken. Deze filters zijn gebaseerd op de VID en PID van het apparaat.
3. Apparaatselectie afhandelen: De gebruiker selecteert een apparaat uit de lijst.
4. Het apparaat openen: De applicatie opent een verbinding met het geselecteerde apparaat.
5. Gegevensoverdracht: Zodra de verbinding tot stand is gebracht, kan de applicatie gegevens van en naar het apparaat verzenden en ontvangen.

Stapsgewijze handleiding voor apparaat-enumeratie

1. Toegang tot apparaten aanvragen met filters

De methode navigator.hid.requestDevice() is het toegangspunt voor het aanvragen van toegang tot HID-apparaten. Het neemt een optioneel `filters`-argument, dat een reeks objecten is die de VID en PID van de apparaten specificeren die je wilt vinden.

Hier is een voorbeeld van het aanvragen van toegang tot een apparaat met een specifieke VID en PID:

async function requestHIDDevice() {
  try {
    const devices = await navigator.hid.requestDevice({
      filters: [
        {
          vendorId: 0x1234, // Vervang dit door de leveranciers-ID van je apparaat
          productId: 0x5678 // Vervang dit door de product-ID van je apparaat
        },
        // Voeg meer filters toe voor andere apparaten indien nodig
      ]
    });

    if (devices.length > 0) {
      const device = devices[0]; // Gebruik het eerste geselecteerde apparaat
      console.log("HID-apparaat gevonden:", device);
      // Open het apparaat en start de communicatie
      await openHIDDevice(device);
    } else {
      console.log("Geen HID-apparaat geselecteerd.");
    }
  } catch (error) {
    console.error("Fout bij het aanvragen van het HID-apparaat:", error);
  }
}

// Voorbeeldgebruik (bijv. geactiveerd door een klik op een knop):
document.getElementById('requestButton').addEventListener('click', requestHIDDevice);

Belangrijke overwegingen:

• Leveranciers-ID (VID) en Product-ID (PID): Dit zijn unieke identificatiecodes die zijn toegewezen aan USB- en Bluetooth-apparaten. Je moet de VID en PID van je doelapparaat verkrijgen uit de documentatie van de fabrikant of met behulp van systeemtools (bijv. Apparaatbeheer in Windows, Systeeminformatie in macOS of lsusb in Linux).
• Gebruikersconsent: De methode requestDevice() toont de gebruiker een door de browser gecontroleerde toestemmingsprompt, waardoor ze kunnen kiezen welke HID-apparaten ze toegang willen verlenen. Dit is een cruciale beveiligingsmaatregel om te voorkomen dat kwaadaardige websites toegang krijgen tot gevoelige hardware zonder toestemming van de gebruiker.
• Meerdere filters: Je kunt meerdere filters opnemen in de array `filters` om toegang te vragen tot apparaten met verschillende VID's en PID's. Dit is handig als je applicatie meerdere hardwareconfiguraties ondersteunt.

2. Apparaatinformatie verkrijgen

Zodra de gebruiker een apparaat heeft geselecteerd, retourneert de methode requestDevice() een array van HIDDevice-objecten. Elk HIDDevice-object bevat informatie over het apparaat, zoals de VID, PID, usagePage, usage en collections. Je kunt deze informatie gebruiken om het apparaat verder te identificeren en te configureren.

async function openHIDDevice(device) {
  try {
    await device.open();
    console.log("HID-apparaat geopend:", device.productName);

    // Luister naar invoerrapporten
    device.addEventListener("inputreport", event => {
      const { data, reportId } = event;
      const uint8Array = new Uint8Array(data.buffer);
      console.log(`Ontvangen invoerrapport ${reportId}:`, uint8Array);
      // Verwerk de invoerrapportgegevens
    });

    device.addEventListener("disconnect", event => {
      console.log("HID-apparaat verbroken:", device.productName);
      // Apparaatontkoppeling afhandelen
    });

  } catch (error) {
    console.error("Fout bij het openen van het HID-apparaat:", error);
  }
}

Apparaateigenschappen:

• vendorId: De leveranciers-ID van het apparaat.
• productId: De product-ID van het apparaat.
• productName: De voor de mens leesbare naam van het product.
• collections: Een array van HIDCollectionInfo-objecten die de HID-verzamelingen (rapporten, functies, enz.) van het apparaat beschrijven. Dit kan erg complex zijn en is alleen nodig voor complexe apparaten.

3. Apparaatverbinding en -ontkoppeling afhandelen

De WebHID API biedt evenementen om je applicatie op de hoogte te stellen wanneer een apparaat is aangesloten of ontkoppeld. Je kunt luisteren naar de evenementen connect en disconnect op het object navigator.hid.

navigator.hid.addEventListener("connect", event => {
  const device = event.device;
  console.log("HID-apparaat aangesloten:", device);
  // Apparaatverbinding afhandelen (bijv. het apparaat opnieuw openen)
});

navigator.hid.addEventListener("disconnect", event => {
  const device = event.device;
  console.log("HID-apparaat verbroken:", device);
  // Apparaatontkoppeling afhandelen (bijv. bronnen opschonen)
});

Aanbevolen werkwijzen voor verbindingsbeheer:

• Opnieuw enumereren bij verbinding: Wanneer een apparaat verbinding maakt, is het vaak een goede gewoonte om apparaten opnieuw op te sommen om ervoor te zorgen dat je applicatie een actuele lijst heeft.
• Bronopschoning bij ontkoppeling: Wanneer een apparaat wordt ontkoppeld, geeft je alle bronnen vrij die eraan zijn gekoppeld (bijvoorbeeld de apparaatverbinding sluiten, event listeners verwijderen).
• Foutafhandeling: Implementeer robuuste foutafhandeling om situaties waarin een apparaat niet kan verbinden of onverwacht wordt ontkoppeld, op een gracieuze manier af te handelen.

Geavanceerde technieken voor apparaatfiltering

Naast basisfiltering op VID en PID biedt de WebHID API meer geavanceerde technieken om specifieke apparaten te targeten. Dit is met name handig bij het werken met apparaten die meerdere interfaces of functionaliteiten hebben.

1. Filteren op gebruikspagina en gebruik

HID-apparaten zijn georganiseerd in *gebruikspagina's* en *gebruiken*, die het type functionaliteit definiëren dat een apparaat biedt. Een toetsenbord behoort bijvoorbeeld tot de gebruikspagina "Algemene desktop" en heeft een "Toetsenbord"-gebruik. Je kunt apparaten filteren op basis van hun gebruikspagina en gebruik om specifieke typen apparaten te targeten.

async function requestSpecificKeyboard() {
  try {
    const devices = await navigator.hid.requestDevice({
      filters: [
        {
          usagePage: 0x01, // Algemene desktop pagina
          usage: 0x06      // Toetsenbordgebruik
        }
      ]
    });

    // ... (rest van de code om het apparaat af te handelen)
  } catch (error) {
    console.error("Fout bij het aanvragen van het HID-apparaat:", error);
  }
}

Gebruikspagina- en gebruikswaarden vinden:

• HID-gebruikstabellen: De officiële HID-gebruikstabellen (gepubliceerd door het USB Implementers Forum) definiëren de gestandaardiseerde gebruikspagina's en gebruiken voor verschillende apparaattypen.
• Apparaatdocumentatie: De documentatie van de fabrikant van het apparaat kan de gebruikspagina- en gebruikswaarden voor hun apparaat specificeren.
• HID-rapportdescriptoren: Voor geavanceerde scenario's kun je de HID-rapportdescriptor van een apparaat analyseren om de ondersteunde gebruikspagina's en -gebruiken te bepalen.

2. Meerdere interfaces afhandelen

Sommige HID-apparaten stellen meerdere interfaces bloot, elk met zijn eigen set functionaliteiten. De WebHID API behandelt elke interface als een afzonderlijk HID-apparaat. Om toegang te krijgen tot een specifieke interface, moet je mogelijk VID/PID-filtering combineren met filtering op gebruikspagina/gebruik om de gewenste interface te targeten.

Praktische voorbeelden en gebruiksscenario's

1. Een aangepaste gamecontroller-interface bouwen

Stel je voor dat je een webgebaseerd spel bouwt en een aangepaste gamecontroller wilt ondersteunen. Je kunt de WebHID API gebruiken om direct input te lezen van de knoppen, joysticks en andere bedieningselementen van de controller. Hierdoor kun je een zeer responsieve en meeslepende game-ervaring creëren.

2. Een webgebaseerde MIDI-controller maken

Muzikanten en audio-engineers kunnen profiteren van webgebaseerde MIDI-controllers die interageren met digitale audiowerkstations (DAW's) of synthesizers. De WebHID API stelt je in staat om aangepaste MIDI-controllers te bouwen die rechtstreeks in de browser MIDI-berichten verzenden en ontvangen.

3. Interageren met wetenschappelijke instrumenten

Onderzoekers en wetenschappers kunnen de WebHID API gebruiken om te communiceren met wetenschappelijke instrumenten, zoals apparaten voor gegevensverzameling, sensoren en meetinstrumenten. Hierdoor kunnen ze gegevens rechtstreeks in een webgebaseerd dashboard of analysetool verzamelen en analyseren.

4. Toepassingen voor toegankelijkheid

WebHID biedt mogelijkheden voor het creëren van hulpmiddelen. Zo kunnen gespecialiseerde invoerapparaten voor gebruikers met motorische beperkingen rechtstreeks in webapplicaties worden geïntegreerd, waardoor meer op maat gemaakte en toegankelijke ervaringen mogelijk zijn. Wereldwijde voorbeelden zijn onder meer de integratie van gespecialiseerde eye-tracking apparaten voor handsfree navigatie of aanpasbare knoparrays voor toegang met één schakelaar in verschillende talen en invoermethoden.

Cross-browser compatibiliteit en veiligheidsoverwegingen

1. Browserondersteuning

De WebHID API wordt momenteel ondersteund in Chromium-browsers (Chrome, Edge, Opera) en is in ontwikkeling voor andere browsers. Voordat je de WebHID API in je applicatie implementeert, is het belangrijk om de browsercompatibiliteit te controleren en terugvalmechanismen te bieden voor browsers die de API niet ondersteunen.

2. Veiligheidsoverwegingen

De WebHID API is ontworpen met het oog op veiligheid. De browser vraagt de gebruiker om toestemming voordat een webapplicatie toegang krijgt tot een HID-apparaat. Dit voorkomt dat kwaadaardige websites toegang krijgen tot gevoelige hardware zonder toestemming van de gebruiker. Bovendien werkt de WebHID API binnen de beveiligingssandbox van de browser, waardoor de toegang van de applicatie tot systeemresources wordt beperkt.

• Alleen HTTPS: WebHID vereist, net als andere krachtige web-API's, een veilige context (HTTPS) om te kunnen werken.
• Gebruikersgebaren: Voor het aanvragen van toegang tot apparaten is doorgaans een gebruikersgebaar (bijv. een klik op een knop) vereist om ongevraagde toegangsverzoeken te voorkomen.
• Machtigings-API: De machtigingen-API kan worden gebruikt om WebHID-machtigingen op te vragen en te beheren.

Veelvoorkomende problemen oplossen

1. Apparaat niet gevonden

Als je applicatie het HID-apparaat niet kan vinden, controleer dan de VID en PID nogmaals. Zorg ervoor dat ze overeenkomen met de werkelijke identificatiecodes van het apparaat. Controleer ook of het apparaat correct is aangesloten en door het besturingssysteem wordt herkend.

2. Toestemming geweigerd

Als de gebruiker toestemming weigert om toegang te krijgen tot het HID-apparaat, kan je applicatie er niet mee communiceren. Ga op een gracieuze manier met dit scenario om door een bericht aan de gebruiker weer te geven en uit te leggen waarom toegang nodig is. Overweeg om alternatieve manieren te bieden voor de gebruiker om met je applicatie te interageren.

3. Problemen met gegevensindeling

HID-apparaten gebruiken vaak aangepaste gegevensindelingen voor het verzenden en ontvangen van gegevens. Je moet de gegevensindeling van het apparaat begrijpen en de juiste parser- en serialisatielogica in je applicatie implementeren. Raadpleeg de documentatie van de fabrikant van het apparaat voor informatie over de gegevensindeling.

Conclusie

De WebHID API stelt webontwikkelaars in staat om innovatieve en interactieve webapplicaties te maken die rechtstreeks communiceren met Human Interface Devices. Door de principes van apparaat-enumeratie, filtering en verbindingsbeheer te begrijpen, kun je het volledige potentieel van de WebHID API ontsluiten en aantrekkelijke gebruikerservaringen creëren. Omarm de kracht van WebHID om het web te verbinden met de fysieke wereld, wat nieuwe mogelijkheden bevordert voor creativiteit, productiviteit en toegankelijkheid over de hele wereld.

Verdere bronnen

• WebHID API-specificatie
• WebHID API op Chrome Developers
• USB Implementers Forum (HID-informatie)