Créer un appareil pour WebUSB

Créez un appareil pour profiter pleinement de l'API WebUSB.

Reilly Grant

Cet article explique comment créer un appareil pour exploiter pleinement l'API WebUSB. Pour une brève présentation de l'API elle-même, consultez Accéder aux appareils USB sur le Web.

Contexte

L'USB (Universal Serial Bus) est devenu l'interface physique la plus courante pour connecter des périphériques à des ordinateurs de bureau et mobiles. En plus de définir les caractéristiques électriques du bus et un modèle général de communication avec un appareil, les spécifications USB incluent un ensemble de spécifications de classe d'appareil. Il s'agit de modèles généraux pour des classes d'appareils spécifiques, tels que le stockage, l'audio, la vidéo, la mise en réseau, etc., que les fabricants d'appareils peuvent implémenter. L'avantage de ces spécifications de classe d'appareils est qu'un fournisseur de système d'exploitation peut implémenter un seul pilote basé sur la spécification de classe (un "pilote de classe"), et que tout appareil implémentant cette classe sera compatible. C'était une grande amélioration par rapport à la situation où chaque fabricant devait écrire ses propres pilotes d'appareil.

Cependant, certains appareils ne correspondent pas à l'une de ces classes d'appareils standardisées. Un fabricant peut choisir d'étiqueter son appareil comme implémentant la classe spécifique au fournisseur. Dans ce cas, le système d'exploitation choisit le pilote d'appareil à charger en fonction des informations fournies dans le package de pilotes du fournisseur, généralement un ensemble d'ID de fournisseur et de produit connus pour implémenter un protocole spécifique au fournisseur.

Autre caractéristique de l'USB : les appareils peuvent fournir plusieurs interfaces à l'hôte auquel ils sont connectés. Chaque interface peut implémenter une classe standardisée ou être spécifique au fournisseur. Lorsqu'un système d'exploitation choisit les pilotes appropriés pour gérer l'appareil, chaque interface peut être revendiquée par un pilote différent. Par exemple, une webcam USB fournit généralement deux interfaces, l'une implémentant la classe vidéo USB (pour la caméra) et l'autre implémentant la classe audio USB (pour le micro). Le système d'exploitation ne charge pas un seul "pilote de webcam", mais des pilotes de classe vidéo et audio indépendants qui sont chargés des fonctions distinctes de l'appareil. Cette composition de classes d'interface offre une plus grande flexibilité.

Principes de base des API

De nombreuses classes USB standards disposent d'API Web correspondantes. Par exemple, une page peut capturer une vidéo à partir d'un appareil de classe vidéo à l'aide de getUserMedia() ou recevoir des événements d'entrée à partir d'un appareil de classe d'interface homme-machine (HID) en écoutant KeyboardEvents ou PointerEvents, ou à l'aide de l'API Gamepad ou WebHID. Tout comme tous les appareils n'implémentent pas une définition de classe standardisée, tous les appareils n'implémentent pas de fonctionnalités correspondant aux API de plates-formes Web existantes. Dans ce cas, l'API WebUSB peut combler cette lacune en permettant aux sites de revendiquer une interface spécifique au fournisseur et de l'implémenter directement sur leur page.

Les exigences spécifiques pour qu'un appareil soit accessible via WebUSB varient légèrement d'une plate-forme à l'autre en raison des différences de gestion des appareils USB par les systèmes d'exploitation. Toutefois, l'exigence de base est qu'un appareil ne doit pas déjà disposer d'un pilote revendiquant l'interface que la page souhaite contrôler. Il peut s'agir d'un pilote de classe générique fourni par le fournisseur de l'OS ou d'un pilote d'appareil fourni par le fournisseur. Étant donné que les appareils USB peuvent fournir plusieurs interfaces, chacune pouvant avoir son propre pilote, il est possible de créer un appareil pour lequel certaines interfaces sont revendiquées par un pilote et d'autres sont laissées accessibles au navigateur.

Par exemple, un clavier USB haut de gamme peut fournir une interface de classe HID qui sera revendiquée par le sous-système d'entrée du système d'exploitation et une interface spécifique au fournisseur qui reste disponible pour WebUSB et peut être utilisée par un outil de configuration. Cet outil peut être diffusé sur le site Web du fabricant, ce qui permet à l'utilisateur de modifier certains aspects du comportement de l'appareil, tels que les touches de macro et les effets d'éclairage, sans avoir à installer de logiciel spécifique à la plate-forme. Le descripteur de configuration d'un tel appareil se présente comme suit:

Le descripteur de configuration se compose de plusieurs descripteurs concatenatés. Chacun commence par les champs bLength et bDescriptorType afin de pouvoir être identifié. La première interface est une interface HID avec un descripteur HID associé et un seul point de terminaison utilisé pour transmettre des événements d'entrée au système d'exploitation. La deuxième interface est une interface spécifique au fournisseur avec deux points de terminaison qui peuvent être utilisés pour envoyer des commandes à l'appareil et recevoir des réponses en retour.

Descripteurs WebUSB

Bien que WebUSB puisse fonctionner avec de nombreux appareils sans modification du micrologiciel, des fonctionnalités supplémentaires sont activées en marquant l'appareil avec des descripteurs spécifiques indiquant la prise en charge de WebUSB. Par exemple, vous pouvez spécifier une URL de page de destination vers laquelle le navigateur peut rediriger l'utilisateur lorsque votre appareil est branché.

Le BOS (Binary device Object Store) est un concept introduit dans USB 3.0, mais il a également été rétroporté vers les appareils USB 2.0 dans la version 2.1. La déclaration de la prise en charge de WebUSB commence par l'inclusion du descripteur de capacité de plate-forme suivant dans le descripteur BOS:

L'UUID de la capacité de la plate-forme identifie cet élément comme un descripteur de capacité de plate-forme WebUSB, qui fournit des informations de base sur l'appareil. Pour que le navigateur récupère plus d'informations sur l'appareil, il utilise la valeur bVendorCode pour envoyer des requêtes supplémentaires à l'appareil. La seule requête actuellement spécifiée est GET_URL, qui renvoie un descripteur d'URL. Ils sont semblables aux descripteurs de chaîne, mais sont conçus pour encoder les URL dans le moins d'octets possible. Un descripteur d'URL pour "https://google.com" se présente comme suit:

Lorsque vous branchez votre appareil pour la première fois, le navigateur lit le descripteur BOS en émettant ce transfert de contrôle GET_DESCRIPTOR standard:

Cette requête est généralement effectuée deux fois, la première fois avec un wLength suffisamment grand pour que l'hôte détermine la valeur du champ wTotalLength sans s'engager dans un transfert volumineux, puis une nouvelle fois lorsque la longueur complète du descripteur est connue.

Si le champ iLandingPage du descripteur de capacités de la plate-forme WebUSB est défini sur une valeur non nulle, le navigateur effectue une requête GET_URL spécifique à WebUSB en émettant un transfert de contrôle avec bRequest défini sur la valeur bVendorCode du descripteur de capacités de la plate-forme et wValue défini sur la valeur iLandingPage. Le code de requête pour GET_URL (0x02) est placé dans wIndex:

Encore une fois, cette requête peut être émise deux fois afin de vérifier d'abord la longueur du descripteur lu.

Considérations spécifiques à la plate-forme

Bien que l'API WebUSB tente de fournir une interface cohérente pour accéder aux appareils USB, les développeurs doivent tout de même connaître les exigences imposées aux applications, telles que les exigences des navigateurs Web pour accéder aux appareils.

macOS

Aucune configuration particulière n'est requise pour macOS. Un site Web utilisant WebUSB peut se connecter à l'appareil et revendiquer toutes les interfaces qui ne sont pas revendiquées par un pilote de kernel ou une autre application.

Linux

Linux est semblable à macOS, mais par défaut, la plupart des distributions ne configurent pas de comptes utilisateur autorisés à ouvrir des appareils USB. Un démon système appelé udev est chargé d'attribuer l'utilisateur et le groupe autorisés à accéder à un appareil. Une règle de ce type attribue la propriété d'un appareil correspondant au fournisseur et aux ID de produit donnés au groupe plugdev, qui est un groupe commun pour les utilisateurs ayant accès aux périphériques:

SUBSYSTEM=="usb", ATTR{idVendor}=="XXXX", ATTR{idProduct}=="XXXX", GROUP="plugdev"

Remplacez XXXX par les ID de produit et de fournisseur hexadécimaux de votre appareil. Par exemple, ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11" correspond à un téléphone Nexus One. Pour être correctement reconnues, elles doivent être écrites sans le préfixe "0x" habituel et en minuscules. Pour trouver les ID de votre appareil, exécutez l'outil de ligne de commande lsusb.

Cette règle doit être placée dans un fichier du répertoire /etc/udev/rules.d et prend effet dès que l'appareil est branché. Il n'est pas nécessaire de redémarrer udev.

Android

La plate-forme Android est basée sur Linux, mais ne nécessite aucune modification de la configuration système. Par défaut, tout appareil qui ne dispose pas de pilote intégré au système d'exploitation est disponible pour le navigateur. Les développeurs doivent toutefois savoir que les utilisateurs devront suivre une étape supplémentaire lorsqu'ils se connecteront à l'appareil. Une fois qu'un utilisateur a sélectionné un appareil en réponse à un appel à requestDevice(), Android affiche une invite lui demandant d'autoriser Chrome à y accéder. Cette invite réapparaît également si un utilisateur revient sur un site Web qui est déjà autorisé à se connecter à un appareil et que le site Web appelle open().

De plus, plus d'appareils seront accessibles sur Android que sur Linux pour ordinateur, car moins de pilotes sont inclus par défaut. Par exemple, la classe USB CDC-ACM, couramment implémentée par les adaptateurs USB-série, est une omission notable, car il n'existe aucune API dans le SDK Android pour communiquer avec un appareil série.

ChromeOS

ChromeOS est également basé sur Linux et ne nécessite aucune modification de la configuration système. Le service permission_broker contrôle l'accès aux appareils USB et autorise le navigateur à y accéder tant qu'il existe au moins une interface non revendiquée.

Windows

Le modèle de pilote Windows introduit une exigence supplémentaire. Contrairement aux plates-formes ci-dessus, la possibilité d'ouvrir un appareil USB à partir d'une application utilisateur n'est pas la valeur par défaut, même si aucun pilote n'est chargé. À la place, un pilote spécial, WinUSB, doit être chargé pour fournir l'interface que les applications utilisent pour accéder à l'appareil. Pour ce faire, vous pouvez utiliser un fichier d'informations sur le pilote (INF) personnalisé installé sur le système ou modifier le micrologiciel de l'appareil pour fournir les descripteurs de compatibilité du système d'exploitation Microsoft lors de l'énumération.

Fichier d'informations sur le pilote (INF)

Un fichier d'informations sur le pilote indique à Windows ce qu'il doit faire lorsqu'il rencontre un appareil pour la première fois. Étant donné que le système de l'utilisateur inclut déjà le pilote WinUSB, il suffit que le fichier INF associe votre fournisseur et votre ID de produit à cette nouvelle règle d'installation. Le fichier ci-dessous est un exemple de base. Enregistrez-le dans un fichier avec l'extension .inf, modifiez les sections marquées d'un X, puis effectuez un clic droit dessus et sélectionnez "Installer" dans le menu contextuel.

[Version]
Signature   = "$Windows NT$"
Class       = USBDevice
ClassGUID   = {88BAE032-5A81-49f0-BC3D-A4FF138216D6}
Provider    = %ManufacturerName%
CatalogFile = WinUSBInstallation.cat
DriverVer   = 09/04/2012,13.54.20.543

; ========== Manufacturer/Models sections ===========

[Manufacturer]
%ManufacturerName% = Standard,NTx86,NTia64,NTamd64

[Standard.NTx86]
%USB\MyCustomDevice.DeviceDesc% = USB_Install,USB\VID_XXXX&PID_XXXX

[Standard.NTia64]
%USB\MyCustomDevice.DeviceDesc% = USB_Install,USB\VID_XXXX&PID_XXXX

[Standard.NTamd64]
%USB\MyCustomDevice.DeviceDesc% = USB_Install,USB\VID_XXXX&PID_XXXX

; ========== Class definition ===========

[ClassInstall32]
AddReg = ClassInstall_AddReg

[ClassInstall_AddReg]
HKR,,,,%ClassName%
HKR,,NoInstallClass,,1
HKR,,IconPath,%REG_MULTI_SZ%,"%systemroot%\system32\setupapi.dll,-20"
HKR,,LowerLogoVersion,,5.2

; =================== Installation ===================

[USB_Install]
Include = winusb.inf
Needs   = WINUSB.NT

[USB_Install.Services]
Include = winusb.inf
Needs   = WINUSB.NT.Services

[USB_Install.HW]
AddReg = Dev_AddReg

[Dev_AddReg]
HKR,,DeviceInterfaceGUIDs,0x10000,"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}"

; =================== Strings ===================

[Strings]
ManufacturerName              = "Your Company Name Here"
ClassName                     = "Your Company Devices"
USB\MyCustomDevice.DeviceDesc = "Your Device Name Here"

La section [Dev_AddReg] configure l'ensemble des DeviceInterfaceGUIDs pour l'appareil. Chaque interface d'appareil doit disposer d'un GUID pour qu'une application puisse la trouver et s'y connecter via l'API Windows. Utilisez la cmdlet PowerShell New-Guid ou un outil en ligne pour générer un GUID aléatoire.

À des fins de développement, l'outil Zadig fournit une interface simple pour remplacer le pilote chargé pour une interface USB par le pilote WinUSB.

Descripteurs de compatibilité des systèmes d'exploitation Microsoft

L'approche de fichier INF ci-dessus est fastidieuse, car elle nécessite de configurer à l'avance la machine de chaque utilisateur. Windows 8.1 et les versions ultérieures proposent une alternative via l'utilisation de descripteurs USB personnalisés. Ces descripteurs fournissent des informations au système d'exploitation Windows lorsque l'appareil est branché pour la première fois, qui seraient normalement incluses dans le fichier INF.

Une fois les descripteurs WebUSB configurés, il est facile d'ajouter également les descripteurs de compatibilité de l'OS de Microsoft. Commencez par étendre le descripteur BOS avec ce descripteur de capacité de plate-forme supplémentaire. Veillez à mettre à jour wTotalLength et bNumDeviceCaps pour tenir compte de ce changement.

Comme pour les descripteurs WebUSB, vous devez choisir une valeur bRequest à utiliser par les transferts de contrôle associés à ces descripteurs. Dans cet exemple, j'ai choisi 0x02. 0x07, placé dans wIndex, est la commande permettant de récupérer le jeu de descripteurs Microsoft OS 2.0 à partir de l'appareil.

Un appareil USB peut avoir plusieurs fonctions. La première partie de l'ensemble de descripteurs décrit donc la fonction à laquelle les propriétés suivantes sont associées. L'exemple ci-dessous configure l'interface 1 d'un appareil composite. Le descripteur fournit à l'OS deux informations importantes sur cette interface. Le descripteur d'ID compatible indique à Windows que cet appareil est compatible avec le pilote WinUSB. Le descripteur de propriété de Registre fonctionne de manière similaire à la section [Dev_AddReg] de l'exemple INF ci-dessus, en définissant une propriété de Registre pour attribuer à cette fonction un GUID d'interface d'appareil.

Windows ne demande ces informations à l'appareil qu'une seule fois. Si l'appareil ne répond pas avec des descripteurs valides, il ne posera pas de nouvelle question la prochaine fois qu'il sera connecté. Microsoft a fourni une liste des entrées de registre d'appareils USB décrivant les entrées de registre créées lors de l'énumération d'un appareil. Lors des tests, supprimez les entrées créées pour un appareil pour forcer Windows à réessayer de lire les descripteurs.

Pour en savoir plus, consultez l'article de blog de Microsoft sur l'utilisation de ces descripteurs.

Exemples

Vous trouverez des exemples de code implémentant des appareils compatibles avec WebUSB qui incluent à la fois des descripteurs WebUSB et des descripteurs de système d'exploitation Microsoft dans ces projets:

• WebLight
• Bibliothèque Arduino WebUSB