Guide d’implémentation du stylet haptique

Ce document détaille l’implémentation du protocole d’un appareil Haptic Pen qui se connecte à un hôte compatible Windows 11. Cela n’inclut pas de conseils sur les contraintes mécaniques, les contraintes électriques ou la sélection de composants pour générer la réponse haptique au sein du transducteur de stylet. Ce guide d’implémentation est indépendant du protocole de stylet utilisé entre le transducteur de stylet et le numériseur de stylet, mais une implémentation peut choisir d’utiliser un protocole de stylet avec une fonctionnalité de liaison montante qui permet au numériseur de stylet de fournir des paramètres supplémentaires au transducteur à des fins de modulation de la réponse haptique.

Classe d’appareil

Haptic Pen est une extension de la classe Pen Device sur Windows. Ce guide d’implémentation ajoute au Guide d’implémentation du stylet et se concentre sur l’implémentation de haptiques au sein du transducteur de stylet, de sorte que les stylos haptiques doivent répondre aux exigences du Guide d’implémentation de stylet en plus de ceux contenus ici.

Connectivité du bus d’appareil

Le stylet Haptic doit utiliser les pilotes de boîte de réception fournis Microsoft pour se connecter à un hôte Windows à l’aide de HID via Bluetooth.

Implémentation du protocole de stylet haptique

Une bonne compréhension du protocole HID est nécessaire pour pouvoir comprendre les informations présentées ici. Pour plus d’informations sur le protocole HID, consultez les ressources suivantes :

• Définition de classe d’appareil pour les appareils d’interface humaine (HID)
• Tables d’utilisation HID

Windows inclut un pilote de classe HID et un pilote miniport compatible HID Bluetooth correspondant, il n’est donc pas nécessaire de disposer de pilotes de mini-port tiers. Le microprogramme du périphérique de stylet haptique doit uniquement signaler les utilisations décrites dans cette rubrique. Windows utilisera le microprogramme et ses propres pilotes HID pour activer l’appareil et donner Windows accès aux applications à l’appareil.

Un exemple descripteur est fourni dans la section Exemples de descripteurs de rapport ci-dessous.

Collection HID de niveau supérieur requise

Un appareil Haptic Pen doit utiliser le protocole HID sur un système de Windows 11 de telle façon que l’appareil fournit une collection de niveau supérieur qui apparaît sous forme de numériseur/stylet (Page 0x0D, Utilisation 0x20).

Rapport d’entrée du numériseur de stylet

La collection du digitiseur de stylet doit signaler l’identificateur de stylet, qui est composé du numéro de série du transducteur et de l’ID du fournisseur de transducteur, dans les rapports d'entrée fournis au système d'exploitation. Le même identificateur de stylet doit être signalé à travers la collection de stylets. Cela permet au système d’exploitation de mettre en corrélation l’entrée du stylet générée par le numériseur. Vous trouverez plus d’informations sur le guide d’implémentation du stylet ici : Implémentation du protocole Pen.

Numéro de série du transducteur

Le numéro de série transducteur est un identificateur persistant unique pour le transducteur utilisé dans l’accessoire de stylet communiquant avec le numériseur de stylet. Cela doit être de 32 bits et est défini par le fournisseur ou l’entité identifiée par l’ID du fournisseur de transducteur. Dans les circonstances où le numéro de série transducteur est inconnu du numériseur, soit parce que l’accessoire de stylet ne prend pas en charge la transmission de cette valeur ou que la transmission n’a pas été reçue en intégralité, le numériseur doit signaler 0 à l’hôte. La position nulle n’est pas supportée par l’hôte.

Numéro de série du transducteur – Partie 2

Numéro de série du transducteur : la partie 2 permet de spécifier un nombre supplémentaire de 32 bits dans le cadre de l’identificateur persistant unique du transducteur utilisé dans un accessoire de stylet. Dans les circonstances où le numéro de série transducteur – La partie 2 est inconnue du numériseur, soit parce que l’accessoire de stylet ne prend pas en charge la transmission de cette valeur ou que la transmission n’a pas été reçue en intégralité, le numériseur doit signaler 0 à l’hôte. La position nulle n’est pas supportée par l’hôte.

ID du fournisseur de transducteur

L’ID du fournisseur de transducteur est un champ permettant de communiquer avec le fabricant du transducteur utilisé dans l’accessoire de stylet qui communique avec le numériseur de stylet. Il faut qu’il s’agisse d’un ID de fournisseur de 2 octets USB-IF attribué soit du fabricant, soit de celui de l’IHV/OEM autorisant l’utilisation de son ID de fournisseur USB-IF à cet effet.

Fonctionnalités dépendant de l'identification unique du stylet

La création de rapports PenID est obligatoire pour activer des scénarios tels que les haptiques de stylet (requis pour les fonctionnalités haptiques dans ce guide).

Il est également obligatoire dans les scénarios qui utilisent plusieurs stylets pour l'entrée manuscrite. Par exemple:

• L’application Tableau blanc sur Windows prend en charge l’utilisation simultanée de plusieurs stylets où chaque stylet peut être mappé à un certain outil de stylo.
• En général, les applications qui souhaitent attribuer des attributs ou des comportements à différents stylets physiques, même si le numériseur peut uniquement prendre en charge un seul stylet sur l’écran à la fois
• Applications qui souhaitent suivre plusieurs stylets simultanément sur des numériseurs pris en charge

Rapport de fonctionnalités haptique

Si un appareil de stylet prend en charge les commentaires haptiques, il peut permettre au système et aux applications de tirer parti de celui-ci en incluant une collection de commentaires haptique (Page 0x0E, Utilisation 0x01) dans le TLC de stylet. Pour plus d’informations sur la façon dont la spécification HID prend en charge les commentaires haptiques, consultez la page Haptics de ratification de la spécification HID.

L’hôte utilise les utilisations suivantes dans un rapport GET_FEATURE (via la collection de commentaires haptique) pour interroger les fonctionnalités haptiques de l’appareil de stylet, en particulier les formes d’onde et les durées prises en charge. Si un appareil choisit d’exposer un regroupement de commentaires haptiques, ce rapport de fonctionnalités est obligatoire afin que l’hôte puisse découvrir les fonctionnalités qu’il peut utiliser lors du lancement de commentaires haptiques via le rapport de sortie approprié.

Liste de formes d’ondes

La liste des formes d'ondes représente une collection des utilisations HID pour les formes d'ondes prises en charge, classées à l'aide de valeurs ordinales. Les formes d’ondes haptiques prédéfinies sont définies dans la spécification HID. Pour les appareils haptiques de stylet, ces formes d’onde peuvent être classées comme deux segments qui correspondent à différents scénarios :

• Continu - Rétroaction à base d'encre pour simuler différentes textures tandis que l’utilisateur utilise divers outils tels que le stylo, le crayon, etc.
• Discret : commentaires discrets et non continus sur les interactions lorsqu’un utilisateur effectue une tâche pilotée par l’entrée, comme pointer sur un bouton, cliquer sur un bouton désactivé et réussir la reconnaissance de forme manuscrite.

La liste complète des formes d’onde prises en charge pour les appareils haptiques de stylet est ci-dessous :

None et Stop sont obligatoires pour tous les appareils haptiques compatibles HID. Les ordinals 1 et 2 sont implicitement définis sur None et Stop. Ils n’ont pas besoin d’être déclarés dans la Waveform List ou la Duration List. La liste des formes d'onde et la liste des durées déclarent les formes d’onde prises en charge via leur plage d’utilisation ordinale (Utilisation/Minimum logique et Maximum) et la valeur retournée pour chaque ordinal, en utilisant None pour les ordinaux non pris en charge.

Les formes d’onde de pression et relâchement sont facultatives, mais si l’une est prise en charge, l’autre doit l’être également. La même chose s’applique à La réussite et à l’erreur.

Liste de durées

L’utilisation de la liste de durées représente une collection de durées pour les formes d’onde prises en charge dans la liste des formes d'onde, classée par ordre ordinal. L’unité pour la durée de la forme d’onde est en millisecondes, et la durée doit être une valeur positive non nulle pour toute forme d’onde non continue. Si une forme d’onde est continue (joue jusqu’à ce qu’elle soit arrêtée par l’hôte ou le temps de coupure de forme d’onde est dépassée), sa durée est définie comme zéro.

Aucun et Stop sont supposés avoir une durée de zéro. Ils n’ont pas besoin d’être déclarés dans la liste de durées.

Rapport de sortie haptique

L’hôte utilise les usages suivants dans un rapport de sortie pour émettre des événements de retour haptique au dispositif Haptic Pen. Certaines utilisations sont obligatoires pour la compatibilité avec l’implémentation de l’hôte Windows.

Déclencheur manuel

L'utilisation du déclencheur manuel ne comprend pas directement un ID d'utilisation d'onde. Au lieu de cela, sa valeur est un ordinal dans la table de forme d’onde étendue de l’appareil. Ordinal 1 est réservé pour la forme d'onde obligatoire None (no-op), ordinal 2 est réservé pour la forme d'onde Stop, et les ordinaux supérieurs ou égaux à 3 mappent aux entrées dans la Liste de formes d'ondes/Liste de durée de l'appareil (voir le mécanisme Liste de formes d'ondes/Liste de durée), où l'ordinal 3 correspond à la première entrée de la liste, ordinal 4 à la seconde, et ainsi de suite. L’hôte peut envoyer les ordinals implicites 1 et 2, et pour les ordinals 3 et versions ultérieures, il envoie uniquement des valeurs qui correspondent aux entrées publiées par l’appareil comme étant prises en charge.

Lorsqu’un rapport de sortie contenant un déclencheur manuel dont l’ordinal se résout en forme d’onde discrète est envoyé à l’appareil, l’appareil doit immédiatement commencer à lire la forme d’onde spécifiée avec toutes les propriétés supplémentaires incluses dans le rapport de sortie (intensité, nombre de répétitions, période de retrigger). Si l’ordinal de déclencheur manuel se résout en une onde continue, la lecture doit commencer à la discrétion de l’appareil (par exemple, lorsque l'appareil détermine que le stylet est en contact avec l’écran).

Lorsqu’un rapport de sortie contient un déclencheur manuel dont l’ordinal se résout en la forme d'onde Arrêt (ordinal 2), toute lecture en cours de forme d’onde doit être arrêtée. Lorsqu’un rapport de sortie contient un déclencheur manuel dont l’ordinal est résolu en forme d’onde obligatoire None (no-op) (ordinal 1), l’appareil ne doit pas démarrer de nouvelle forme d’onde et ne doit pas changer l’état d’une forme d’onde en cours de lecture ; le rapport doit être traité comme une opération sans opération par rapport à la sortie haptique.

Intensité

L’utilisation de l’intensité représente le pourcentage d’intensité maximale à appliquer à une forme d’onde. Cette valeur doit varier entre 0 et 100 %. 100 % indique que les formes d’ondes seront déclenchées par l’appareil à leur force maximale, et 0 % indique que le transducteur haptique n’est pas activé.

Nombre de répétitions

L'utilisation du nombre de répétitions indique combien de fois une forme d'onde doit être répétée. Un nombre de répétitions de zéro indique que la forme d’onde du déclencheur manuel ne doit être lue qu’une seule fois (aucune répétition). Si le délai de coupure de forme d’onde a été dépassé, il est prévu que toutes les répétitions incomplètes soient ignorées.

Période de redéclenchement

L’utilisation de la période de retrigger représente la durée pendant laquelle l’appareil doit attendre avant de répéter une forme d’onde de déclencheur manuel dans un rapport de sortie, conformément à la valeur spécifiée par le nombre de répétitions. Les unités de cette valeur sont des millisecondes. Si la période de retrigger est inférieure à la durée de la forme d’onde jouée, la forme d’onde doit être arrêtée et redémarrée au moment indiqué par la période de retrigger.

Temps de limite de forme d’onde

L'utilisation du temps de coupure de la forme d'onde représente la durée maximale pendant laquelle l'appareil permet de répéter une forme d'onde déclenchée manuellement avant de terminer la lecture. Il s’agit d’une valeur constante pour l’appareil et inclut à la fois des formes d’ondes continues sans durées définies et des formes d’ondes avec des durées discrètes qui sont définies pour se répéter plusieurs fois. Les unités de cette valeur sont des millisecondes.

Démarrage et arrêt des haptics

L’organigramme ci-dessous décrit quand les signaux haptiques du stylet doivent être configurés, effacés, démarrés et arrêtés.

Les différents états haptiques décrits ci-dessous sont les suivants :

• Lecture : Le stylet reproduit activement la forme d’onde haptique
• Suspendu : le stylet est configuré avec une onde, mais ne la diffuse pas activement
• Arrêté : le stylet n’est pas configuré avec une forme d’onde et ne joue pas activement rien

Pour l’état du stylet en ce qui concerne le numériseur, reportez-vous à États du stylet Windows.

Collection de claviers (facultatif)

Fonctionnalité facultative permettant d’activer la communication des clics de boutons finaux à l'hôte par le biais de rapports de clavier HID.

Pour implémenter un bouton Bluetooth de queue, l’appareil signale 3 combinaisons de clavier distinctes correspondant à 3 actions de bouton distinctes via un appareil clavier HID Bluetooth LE exposé à l’hôte. Les actions et les combinaisons de clavier correspondantes sont décrites ci-dessous :

Rangement de stylet

À compter de Windows 10, version 1903, Windows prend en charge les notifications pour les appareils incorporant un stockage de stylet compatible. Le mécanisme s’appuie sur le matériel qui détecte le stylet en cours de suppression ou de remplacement et génère un rapport de clavier HID correspondant pour une paire de combinaisons de raccourcis. Pour signaler un ancrage (stylet rangé dans le rangement), signalez avec WIN+CTRL+F20, et pour signaler un désancrage (stylet retiré du rangement), signalez avec WIN+CTRL+F19. Cela peut être implémenté avec le microprogramme ou un pilote.

Ces événements de désancrage/ancrage affichent/masquent le menu Shell de l'espace de travail d'encre. À compter de Windows 10, la version 2004 d’Office réagit également à ces événements à l’aide d’une API plateforme qui permet aux développeurs d’étendre leur application pour être informés des événements de stockage. Il n’existe aucune fonctionnalité pour vérifier si le stylet est présent dans le dock, les applications ne sont averties que des événements de retrait et de retour s’ils se trouvent au premier plan.

Exemple de descripteur de rapport HID

Le descripteur suivant prend en charge toutes les utilisations obligatoires et facultatives. Il déclare la prise en charge des dix-sept entrées de liste de formes d’ondes (à l’exception des formes d’onde implicites 1 (Aucun) et 2 (Stop), pour un total de dix-neuf formes d’ondes), avec la forme d’onde discrète la plus longue ayant une durée de 50 ms. Les formes d’ondes continues ont une durée de zéro.

Toutes les plages logiques doivent être mises à jour en fonction de la prise en charge des appareils. Pour prendre en charge un nombre différent de formes d’ondes :

• La plage logique de l’utilisation du déclencheur manuel doit être mise à jour
• Les plages d’utilisation et le nombre de rapports pour la liste de formes d’ondes et la liste de durée doivent être mis à jour

Pour prendre en charge une longueur d’onde maximale différente, les plages logiques suivantes doivent être mises à jour :

• Période de retrigger (sortie)
• Délai de coupure de forme d’onde (sortie)
• Liste de durées (fonctionnalité)

05,0D,                      // Usage Page (Digitizers)
09,20,                      // Usage (Stylus)
A1,01,                      // Collection (Application)
85,40,                      //   Report ID (64)
95,01,                      //   Report Count (1)
75,20,                      //   Report Size (32)
17,00,00,00,80,             //   Logical Minimum (-2147483648)
27,FF,FF,FF,7F,             //   Logical Maximum (2147483647)
09,5B,                      //   Transducer Serial Number
81,02,                      //   Input (Data,Var,Abs)
75,10,                      //   Report Size (16)
15,01,                      //   Logical Minimum (1)
27,FF,FF,00,00,             //   Logical Maximum (65535)
09,91,                      //   Transducer Vendor ID
81,02,                      //   Input (Data,Var,Abs)
05,0E,                      //   Usage Page (Haptics)
09,01,                      //   Usage (Simple Haptic Controller)
A1,02,                      //   Collection (Logical)
85,41,                      //     Report ID (65)
09,10,                      //     Usage (Waveform List)
A1,02,                      //     Collection (Logical)
05,0A,                      //       Usage Page (Ordinal)
19,03,                      //       Usage Minimum (0x03)
29,13,                      //       Usage Maximum (0x13)
16,01,10,                   //       Logical Minimum (4097)
26,FF,2F,                   //       Logical Maximum (12287)
95,11,                      //       Report Count (17)
75,10,                      //       Report Size (16)
B1,02,                      //       Feature (Data,Var,Abs)
C0,                         //     End Collection ()
05,0E,                      //     Usage Page (Haptics)
09,11,                      //     Usage (Duration List)
A1,02,                      //     Collection (Logical)
05,0A,                      //       Usage Page (Ordinal)
19,03,                      //       Usage Minimum (0x03)
29,13,                      //       Usage Maximum (0x13)
35,00,                      //       Physical Minimum (0)
45,32,                      //       Physical Maximum (50)
66,01,10,                   //       Unit (SiLinear, Seconds:1)
55,0D,                      //       Unit Exponent (-3)
15,00,                      //       Logical Minimum (0)
25,32,                      //       Logical Maximum (50)
95,11,                      //       Report Count (17)
75,08,                      //       Report Size (8)
B1,02,                      //       Feature (Data,Var,Abs)
C0,                         //     End Collection ()
85,42,                      //     Report ID (66)
95,01,                      //     Report Count (1)
75,08,                      //     Report Size (8)
35,00,                      //     Physical Minimum (0)
45,00,                      //     Physical Maximum (0)
65,00,                      //     Unit (None)
55,00,                      //     Unit Exponent (0)
15,01,                      //     Logical Minimum (1)
25,13,                      //     Logical Maximum (19)
09,21,                      //     Usage (Manual Trigger)
91,02,                      //     Output (Data,Var,Abs)
15,00,                      //     Logical Minimum (0)
26,64,00,                   //     Logical Maximum (100)
09,23,                      //     Usage (Intensity)
91,02,                      //     Output (Data,Var,Abs)
25,05,                      //     Logical Maximum (5)
09,24,                      //     Usage (Repeat Count)
91,02,                      //     Output (Data,Var,Abs)
75,10,                      //     Report Size (16)
46,E8,03,                   //     Physical Maximum (1000)
66,01,10,                   //     Unit (SiLinear, Seconds:1)
55,0D,                      //     Unit Exponent (-3)
15,00,                      //     Logical Minimum (0)
26,E8,03,                   //     Logical Maximum (1000)
09,25,                      //     Usage (Retrigger Period)
91,02,                      //     Output (Data,Var,Abs)
36,E8,03,                   //     Physical Minimum (1000)
46,88,13,                   //     Physical Maximum (5000)
16,E8,03,                   //     Logical Minimum (1000)
26,88,13,                   //     Logical Maximum (5000)
09,28,                      //     Usage (Waveform Cutoff Time)
91,02,                      //     Output (Data,Var,Abs)
C0,                         //   End Collection ()
C0                          // End Collection ()

Rubriques connexes

• Guide d’implémentation des haptics d’entrée