Énumération des périphériques WebHID en frontend : découverte des périphériques connectés avec JavaScript

L'API WebHID libère le potentiel des applications web à communiquer directement avec un large éventail de périphériques d'interface humaine (HID) qui ne sont généralement accessibles qu'aux applications natives. Cela ouvre des possibilités intéressantes pour créer des expériences web innovantes qui interagissent avec du matériel spécialisé comme les contrôleurs de jeux, les périphériques d'entrée personnalisés, les instruments scientifiques, et bien plus encore. Ce guide complet plonge dans le concept central de l'énumération des périphériques, qui est la première étape cruciale pour établir une connexion avec le périphérique HID souhaité.

Qu'est-ce que l'API WebHID ?

L'API WebHID permet aux applications web d'accéder aux périphériques d'interface humaine. Ces périphériques englobent une large catégorie, notamment :

• Contrôleurs de jeux : Joysticks, manettes de jeu, volants de course
• Périphériques d'entrée : Claviers, souris, trackballs
• Commandes industrielles : Panneaux de contrôle spécialisés, interfaces de capteurs
• Instruments scientifiques : Appareils d'acquisition de données, outils de mesure
• Matériel personnalisé : Périphériques d'entrée sur mesure créés à des fins spécifiques

Contrairement aux anciennes API de navigateur qui offraient une prise en charge HID limitée, l'API WebHID fournit un accès direct aux périphériques HID, ce qui permet aux développeurs de créer des applications web plus riches et plus interactives. Imaginez contrôler un bras robotisé dans un laboratoire distant, manipuler un modèle 3D avec un périphérique d'entrée personnalisé ou recevoir des données de capteurs directement dans un tableau de bord web, le tout dans le navigateur.

Comprendre l'énumération des périphériques HID

Avant de pouvoir interagir avec un périphérique HID, votre application web doit découvrir quels périphériques sont connectés au système de l'utilisateur. Ce processus est appelé énumération des périphériques. L'API WebHID fournit un mécanisme pour demander l'accès à des périphériques HID spécifiques en fonction de l'ID du fournisseur (VID) et de l'ID du produit (PID) ou en utilisant un filtre plus large.

Le processus implique généralement les étapes suivantes :

1. Demande d'accès au périphérique : L'application web invite l'utilisateur à sélectionner un périphérique HID à l'aide de navigator.hid.requestDevice().
2. Filtrage des périphériques : Vous pouvez spécifier des filtres pour affiner la liste des périphériques présentés à l'utilisateur. Ces filtres sont basés sur le VID et le PID du périphérique.
3. Gestion de la sélection du périphérique : L'utilisateur sélectionne un périphérique dans la liste.
4. Ouverture du périphérique : L'application ouvre une connexion au périphérique sélectionné.
5. Transfert de données : Une fois la connexion établie, l'application peut envoyer et recevoir des données du périphérique.

Guide étape par étape de l'énumération des périphériques

1. Demande d'accès au périphérique avec des filtres

La méthode navigator.hid.requestDevice() est le point d'entrée pour demander l'accès aux périphériques HID. Elle prend un argument `filters` facultatif, qui est un tableau d'objets qui spécifient le VID et le PID des périphériques que vous souhaitez trouver.

Voici un exemple de la façon de demander l'accès à un périphérique avec un VID et un PID spécifiques :

async function requestHIDDevice() {
  try {
    const devices = await navigator.hid.requestDevice({
      filters: [
        {
          vendorId: 0x1234, // Remplacez par l'ID du fournisseur de votre périphérique
          productId: 0x5678 // Remplacez par l'ID du produit de votre périphérique
        },
        // Ajoutez d'autres filtres pour d'autres périphériques si nécessaire
      ]
    });

    if (devices.length > 0) {
      const device = devices[0]; // Utilisez le premier périphérique sélectionné
      console.log("Périphérique HID trouvé:", device);
      // Ouvrez le périphérique et lancez la communication
      await openHIDDevice(device);
    } else {
      console.log("Aucun périphérique HID sélectionné.");
    }
  } catch (error) {
    console.error("Erreur lors de la demande du périphérique HID:", error);
  }
}

// Exemple d'utilisation (par exemple, déclenché par un clic de bouton) :
document.getElementById('requestButton').addEventListener('click', requestHIDDevice);

Considérations importantes :

• ID du fournisseur (VID) et ID du produit (PID) : Ce sont des identificateurs uniques attribués aux périphériques USB et Bluetooth. Vous devrez obtenir le VID et le PID de votre périphérique cible à partir de la documentation du fabricant ou à l'aide d'outils système (par exemple, Gestionnaire de périphériques sur Windows, Informations système sur macOS ou `lsusb` sur Linux).
• Consentement de l'utilisateur : La méthode requestDevice() affiche une invite d'autorisation contrôlée par le navigateur à l'utilisateur, lui permettant de choisir les périphériques HID auxquels accorder l'accès. Il s'agit d'une mesure de sécurité cruciale pour empêcher les sites web malveillants d'accéder à du matériel sensible sans le consentement de l'utilisateur.
• Filtres multiples : Vous pouvez inclure plusieurs filtres dans le tableau `filters` pour demander l'accès aux périphériques avec différents VIDs et PIDs. Ceci est utile si votre application prend en charge plusieurs configurations matérielles.

2. Obtention des informations sur le périphérique

Une fois que l'utilisateur a sélectionné un périphérique, la méthode requestDevice() renvoie un tableau d'objets HIDDevice. Chaque objet HIDDevice contient des informations sur le périphérique, telles que son VID, PID, usagePage, usage et collections. Vous pouvez utiliser ces informations pour identifier et configurer davantage le périphérique.

async function openHIDDevice(device) {
  try {
    await device.open();
    console.log("Périphérique HID ouvert:", device.productName);

    // Écouter les rapports d'entrée
    device.addEventListener("inputreport", event => {
      const { data, reportId } = event;
      const uint8Array = new Uint8Array(data.buffer);
      console.log(`Rapport d'entrée reçu ${reportId}:`, uint8Array);
      // Traiter les données du rapport d'entrée
    });

    device.addEventListener("disconnect", event => {
      console.log("Périphérique HID déconnecté:", device.productName);
      // Gérer la déconnexion du périphérique
    });

  } catch (error) {
    console.error("Erreur lors de l'ouverture du périphérique HID:", error);
  }
}

Propriétés du périphérique :

• vendorId : L'ID du fournisseur du périphérique.
• productId : L'ID du produit du périphérique.
• productName : Le nom lisible par l'humain du produit.
• collections : Un tableau d'objets HIDCollectionInfo décrivant les collections HID du périphérique (rapports, fonctionnalités, etc.). Cela peut être très complexe et n'est nécessaire que pour les périphériques complexes.

3. Gestion de la connexion et de la déconnexion des périphériques

L'API WebHID fournit des événements pour informer votre application lorsqu'un périphérique est connecté ou déconnecté. Vous pouvez écouter les événements connect et disconnect sur l'objet navigator.hid.

navigator.hid.addEventListener("connect", event => {
  const device = event.device;
  console.log("Périphérique HID connecté:", device);
  // Gérer la connexion du périphérique (par exemple, rouvrir le périphérique)
});

navigator.hid.addEventListener("disconnect", event => {
  const device = event.device;
  console.log("Périphérique HID déconnecté:", device);
  // Gérer la déconnexion du périphérique (par exemple, nettoyer les ressources)
});

Meilleures pratiques pour la gestion des connexions :

• Ré-énumération lors de la connexion : Lorsqu'un périphérique se connecte, il est souvent judicieux de ré-énumérer les périphériques pour s'assurer que votre application dispose d'une liste à jour.
• Nettoyage des ressources lors de la déconnexion : Lorsqu'un périphérique se déconnecte, libérez toutes les ressources qui lui sont associées (par exemple, fermez la connexion du périphérique, supprimez les écouteurs d'événements).
• Gestion des erreurs : Mettez en œuvre une gestion robuste des erreurs pour gérer en douceur les situations où un périphérique ne parvient pas à se connecter ou se déconnecte de manière inattendue.

Techniques avancées de filtrage des périphériques

Au-delà du filtrage de base VID et PID, l'API WebHID offre des techniques plus avancées pour cibler des périphériques spécifiques. Ceci est particulièrement utile lorsqu'il s'agit de périphériques qui ont plusieurs interfaces ou fonctionnalités.

1. Filtrage par page d'utilisation et utilisation

Les périphériques HID sont organisés en *pages d'utilisation* et *utilisations*, qui définissent le type de fonctionnalité qu'un périphérique fournit. Par exemple, un clavier appartient à la page d'utilisation « Bureau générique » et a une utilisation « Clavier ». Vous pouvez filtrer les périphériques en fonction de leur page d'utilisation et de leur utilisation pour cibler des types de périphériques spécifiques.

async function requestSpecificKeyboard() {
  try {
    const devices = await navigator.hid.requestDevice({
      filters: [
        {
          usagePage: 0x01, // Page de bureau générique
          usage: 0x06      // Utilisation du clavier
        }
      ]
    });

    // ... (reste du code pour gérer le périphérique)
  } catch (error) {
    console.error("Erreur lors de la demande du périphérique HID:", error);
  }
}

Trouver les valeurs de page d'utilisation et d'utilisation :

• Tables d'utilisation HID : Les tables d'utilisation HID officielles (publiées par l'USB Implementers Forum) définissent les pages d'utilisation et les utilisations normalisées pour divers types de périphériques.
• Documentation du périphérique : La documentation du fabricant du périphérique peut spécifier les valeurs de page d'utilisation et d'utilisation pour son périphérique.
• Descripteurs de rapport HID : Pour les scénarios avancés, vous pouvez analyser le descripteur de rapport HID d'un périphérique pour déterminer ses pages d'utilisation et ses utilisations prises en charge.

2. Gestion de plusieurs interfaces

Certains périphériques HID exposent plusieurs interfaces, chacune avec son propre ensemble de fonctionnalités. L'API WebHID traite chaque interface comme un périphérique HID distinct. Pour accéder à une interface spécifique, vous devrez peut-être combiner le filtrage VID/PID avec le filtrage de la page d'utilisation/utilisation pour cibler l'interface souhaitée.

Exemples pratiques et cas d'utilisation

1. Création d'une interface de contrôleur de jeu personnalisée

Imaginez que vous construisez un jeu web et que vous souhaitez prendre en charge un contrôleur de jeu personnalisé. Vous pouvez utiliser l'API WebHID pour lire directement les entrées des boutons, des joysticks et d'autres commandes du contrôleur. Cela vous permet de créer une expérience de jeu très réactive et immersive.

2. Création d'un contrôleur MIDI basé sur le web

Les musiciens et les ingénieurs du son peuvent bénéficier de contrôleurs MIDI basés sur le web qui interagissent avec les stations de travail audio numériques (DAW) ou les synthétiseurs. L'API WebHID vous permet de créer des contrôleurs MIDI personnalisés qui envoient et reçoivent des messages MIDI directement dans le navigateur.

3. Interaction avec des instruments scientifiques

Les chercheurs et les scientifiques peuvent utiliser l'API WebHID pour interagir avec des instruments scientifiques, tels que des appareils d'acquisition de données, des capteurs et des outils de mesure. Cela leur permet de collecter et d'analyser les données directement dans un tableau de bord ou un outil d'analyse basé sur le web.

4. Applications d'accessibilité

WebHID offre des possibilités de création de technologies d'assistance. Par exemple, des périphériques d'entrée spécialisés pour les utilisateurs ayant des déficiences motrices peuvent être intégrés directement dans les applications web, offrant des expériences plus personnalisées et accessibles. Des exemples globaux pourraient inclure l'intégration de périphériques de suivi oculaire spécialisés pour la navigation mains libres ou des matrices de boutons personnalisables pour l'accès à un seul commutateur dans différentes langues et méthodes de saisie.

Compatibilité multi-navigateurs et considérations de sécurité

1. Prise en charge du navigateur

L'API WebHID est actuellement prise en charge dans les navigateurs basés sur Chromium (Chrome, Edge, Opera) et est en cours de développement pour d'autres navigateurs. Avant de mettre en œuvre l'API WebHID dans votre application, il est important de vérifier la compatibilité du navigateur et de fournir des mécanismes de repli pour les navigateurs qui ne prennent pas en charge l'API.

2. Considérations de sécurité

L'API WebHID est conçue avec la sécurité à l'esprit. Le navigateur invite l'utilisateur à donner son autorisation avant d'autoriser une application web à accéder à un périphérique HID. Cela empêche les sites web malveillants d'accéder à du matériel sensible sans le consentement de l'utilisateur. De plus, l'API WebHID fonctionne dans le bac à sable de sécurité du navigateur, ce qui limite l'accès de l'application aux ressources système.

• HTTPS uniquement : WebHID, comme d'autres API web puissantes, nécessite un contexte sécurisé (HTTPS) pour fonctionner.
• Gestes de l'utilisateur : La demande d'accès au périphérique nécessite généralement un geste de l'utilisateur (par exemple, un clic sur un bouton) pour empêcher les demandes d'accès non sollicitées.
• API Permissions : L'API Permissions peut être utilisée pour interroger et gérer les autorisations WebHID.

Dépannage des problèmes courants

1. Périphérique introuvable

Si votre application ne trouve pas le périphérique HID, vérifiez à nouveau le VID et le PID. Assurez-vous qu'ils correspondent aux identificateurs réels du périphérique. Vérifiez également que le périphérique est correctement connecté et reconnu par le système d'exploitation.

2. Autorisation refusée

Si l'utilisateur refuse l'autorisation d'accéder au périphérique HID, votre application ne pourra pas communiquer avec celui-ci. Gérez ce scénario avec élégance en affichant un message à l'utilisateur et en expliquant pourquoi l'accès est nécessaire. Envisagez de proposer d'autres moyens pour l'utilisateur d'interagir avec votre application.

3. Problèmes de format de données

Les périphériques HID utilisent souvent des formats de données personnalisés pour envoyer et recevoir des données. Vous devrez comprendre le format de données du périphérique et mettre en œuvre la logique d'analyse et de sérialisation appropriée dans votre application. Consultez la documentation du fabricant du périphérique pour obtenir des informations sur le format de données.

Conclusion

L'API WebHID permet aux développeurs web de créer des applications web innovantes et interactives qui communiquent directement avec les périphériques d'interface humaine. En comprenant les principes de l'énumération des périphériques, du filtrage et de la gestion des connexions, vous pouvez libérer tout le potentiel de l'API WebHID et créer des expériences utilisateur convaincantes. Adoptez la puissance de WebHID pour connecter le web au monde physique, favorisant de nouvelles possibilités de créativité, de productivité et d'accessibilité dans le monde entier.

Ressources supplémentaires

• Spécification de l'API WebHID
• API WebHID sur Chrome Developers
• USB Implementers Forum (informations HID)