Handbuch für die Implementierung des haptischen Stifts

In diesem Dokument wird die Protokollimplementierung für ein Haptic Pen-Gerät erläutert, das eine Verbindung mit einem kompatiblen Windows 11-Host herstellt. Dies schließt keine Anleitungen zu mechanischen Einschränkungen, elektrischen Einschränkungen oder Komponentenauswahl für die Generierung der haptischen Reaktion innerhalb des Stiftwandlers ein. Dieser Implementierungsleitfaden ist unabhängig vom Stiftprotokoll, das zwischen dem Stiftwandler und dem Stiftdigitierer verwendet wird. Eine Implementierung kann jedoch entscheiden, ein Stiftprotokoll mit einer Uplink-Funktion zu verwenden, mit der der Stiftdigitierer zusätzliche Parameter für den Stifttransduktor für die Modulierung der haptischen Reaktion bereitstellen kann.

Geräteklasse

Haptic Pen ist eine Erweiterung der Stift-Geräteklasse unter Windows. Dieser Implementierungsleitfaden fügt zum Implementierungshandbuch für Stift hinzu und konzentriert sich auf die Implementierung von Haptik innerhalb des Stifttransducers, sodass haptische Stifte zusätzlich zu den hier enthaltenen Anforderungen im Pen-Implementierungshandbuch entsprechen müssen.

Gerätebuskonnektivität

Der Haptic Pen verwendet die von Microsoft bereitgestellten Posteingangstreiber, um über Bluetooth eine Verbindung mit einem Windows-Host herzustellen.

Implementierung des Haptischen Stiftprotokolls

Ein gutes Verständnis des HID-Protokolls ist erforderlich, um die hier dargestellten Informationen verstehen zu können. Informationen zum HID-Protokoll finden Sie in den folgenden Ressourcen:

• Geräteklassendefinition für Human Interface Devices (HID)
• HID-Verwendungstabellen

Windows enthält einen HID-Klassentreiber und den entsprechenden HID Bluetooth-fähigen Miniporttreiber, daher ist es nicht erforderlich, dass Miniporttreiber von Drittanbietern benötigt werden. Haptische Stiftgerätefirmware muss nur die in diesem Thema beschriebenen Verwendungen melden. Windows verwendet die Firmware und seine eigenen HID-Treiber, um das Gerät zu aktivieren und Windows-Anwendungen Zugriff auf das Gerät zu gewähren.

Ein Beispieldeskriptor wird unten im Abschnitt "Beispielberichtdeskriptoren" bereitgestellt.

Erforderliche oberste HID-Sammlung

Ein Haptic Pen-Gerät sollte das HID-Protokoll auf einem Windows 11-System so verwenden, dass das Gerät eine Sammlung auf oberster Ebene bereitstellt, die als Digitalisierungs-/Eingabestift (Page 0x0D, Usage 0x20) angezeigt wird.

Eingabebericht zum Stiftdigisierer

Die Stiftdigitalisierer-Sammlung muss den Stiftidentifikator melden, der aus der Seriennummer des Wandlers und der Hersteller-ID des Wandlers besteht und in den Eingabemeldungen an das Betriebssystem übermittelt wird. Derselbe Eingabestiftbezeichner muss über die Eingabestiftsammlung gemeldet werden. Auf diese Weise kann das Betriebssystem die vom Digitalisierer generierte Stifteingabe mit dem Eingabestift korrelieren. Details zur Stiftimplementierungsanleitung finden Sie hier: Pen-Protokollimplementierung.

Seriennummer des Wandlers

Die Seriennummer des Wandlers ist ein eindeutiger persistenter Bezeichner für den Wandler, der im Stiftzubehör verwendet wird, das mit dem Stiftdigisierer kommuniziert. Dies muss 32 Bit sein und wird von dem Anbieter oder der Entität festgelegt, die durch die Hersteller-ID des Wandlers identifiziert wird. In Fällen, in denen die Seriennummer des Wandlers dem Digitalisierungsgerät nicht bekannt ist, weil das Stiftzubehör diesen Wert nicht unterstützt oder wenn die Übertragung nicht vollständig empfangen wurde, meldet das Digitalisierungsgerät 0 an den Host. Nullposition wird vom Host nicht unterstützt.

Seriennummer des Wandlers – Teil 2

Seriennummer des Wandlers – Teil 2 ermöglicht die Angabe zusätzlicher 32 Bits als Teil des eindeutigen und permanenten Bezeichners des in einem Stiftzubehör verwendeten Wandlers. In Fällen, in denen die Seriennummer des Wandlers – Teil 2 – dem Digitalisierer nicht bekannt ist, entweder weil das Stiftzubehör die Übertragung dieses Wertes nicht unterstützt oder weil die Übertragung nicht vollständig empfangen wurde, notiert der Digitalisierer 0 an den Host. Nullposition wird vom Host nicht unterstützt.

Hersteller-ID des Umformers

Die Hersteller-ID des Wandlers ist ein Feld für die Kommunikation des Herstellers des Wandlers, der in der Stiftzubehörkommunikation mit dem Stiftdigisierer verwendet wird. Dies ist erforderlich, um eine 2-Byte-USB-IF-zugewiesene Anbieter-ID entweder von dem Hersteller oder von dem IHV/OEM zu erhalten, das die Nutzung ihrer USB-IF-Anbieter-ID zu diesem Zweck autorisiert.

Features, die von eindeutiger Stiftidentifikation abhängig sind

Die Meldung der PenID ist obligatorisch, um Szenarien wie die Stifthaptik zu ermöglichen (notwendig für die Haptik-Funktionen in diesem Handbuch).

Es ist auch obligatorisch in Szenarien, in denen mehrere Stifte für das Freihandzeichnen verwendet werden. Beispiel:

• Whiteboard-App in Windows unterstützt die Verwendung mehrerer Stifte, wobei jeder Stift einem bestimmten Zeichenwerkzeug zugeordnet werden kann.
• Im Allgemeinen können Apps physischen Stiften verschiedene Attribute oder Verhaltensweisen zuweisen, auch wenn der Digitalisierer auf dem Bildschirm immer nur einen Stift unterstützt.
• Apps, die mehrere gleichzeitige Stifte auf unterstützten Digitalisierungsgebern nachverfolgen möchten

Bericht über haptische Merkmale

Wenn ein Stiftgerät haptisches Feedback unterstützt, kann es dem System und den Anwendungen ermöglichen, diese zu nutzen, indem eine haptische Feedbacksammlung (Page 0x0E, Usage 0x01) innerhalb des Eingabestifts TLC eingeschlossen wird. Weitere Informationen dazu, wie die HID-Spezifikation haptisches Feedback unterstützt, finden Sie auf der Ratifikationsseite zur Haptik der Spezifikation.

Der Host verwendet die folgenden Verwendungsmöglichkeiten in einem GET_FEATURE-Bericht (über die haptische Rückmeldesammlung), um die haptischen Funktionen des Stiftgeräts abzufragen, insbesondere die unterstützten Wellenformen und Dauern. Wenn ein Gerät eine haptische Feedbacksammlung verfügbar macht, ist dieser Featurebericht obligatorisch, sodass der Host ermitteln kann, welche Funktionen beim Initiieren von haptischem Feedback über den entsprechenden Ausgabebericht verwendet werden können.

Wellenformliste

Die Verwendung der Wellenformliste stellt eine Sammlung der HID-Nutzungen der unterstützten Wellenformen dar, geordnet nach Ordnungszahlen. Die vordefinierten Haptikwellenformen werden in der HID-Spezifikation definiert. Bei haptischen Stiftgeräten können diese Wellenformen als zwei Segmente klassifiziert werden, die unterschiedlichen Szenarien entsprechen:

• Kontinuierlich – Tintenbasiertes Feedback zur Simulation verschiedener Texturen, während der Benutzer aktiv mit verschiedenen Werkzeugen wie Stift, Bleistift usw. zeichnet.
• Diskretes , nicht fortlaufendes interaktionsbasiertes Feedback, für das ein Benutzer eine eingabegesteuerte Aufgabe ausführt, z. B. das Daraufzeigen auf eine Schaltfläche, das Klicken auf eine deaktivierte Schaltfläche und eine erfolgreiche Freihandformerkennung.

Die vollständige Liste der für haptischen Stiftgeräte unterstützten Waveforms finden Sie unten:

Sowohl "None " als auch "Stop " sind für alle HID-kompatiblen Haptikgeräte erforderlich. Ordnungszahlen 1 und 2 werden implizit auf "None" und "Stop" festgelegt. Sie müssen nicht in der Waveform-Liste oder Dauerliste deklariert werden. Die Waveform-Liste und die Dauerliste deklarieren unterstützte Wellenformen über ihren ordinalen Verwendungsbereich (Verwendung/Logisches Minimum und Maximum) und den für jedes Ordinal zurückgegebenen Wert, wobei "None" für nicht unterstützte Ordnungszahlen verwendet wird.

Laufzeitliste

Die Verwendung der Dauerliste stellt eine Auflistung der Dauer für die unterstützten Wellenformen in der Waveform-Liste dar, sortiert mithilfe von Ordnungszahlen. Die Einheit für die Wellenformdauer ist Millisekunden, und die Dauer muss ein positiver Wert ungleich Null für jede nicht fortlaufende Wellenform sein. Wenn eine Wellenform kontinuierlich ist (wird abgespielt, bis sie vom Host gestoppt wird oder die Wellenform-Abschaltzeit überschritten wird), wird ihre Dauer als Null definiert.

"None" und "Stop " werden angenommen, dass die Dauer null ist. Sie müssen nicht in der Dauerliste deklariert werden.

Haptischer Ausgabebericht

Der Host verwendet die folgenden Nutzungen in einem Ausgabebericht, um haptische Feedbackereignisse an das Haptic Pen-Gerät auszugeben. Einige Verwendungen sind für die Kompatibilität mit der Windows-Hostimplementierung obligatorisch.

Manueller Auslöser

Die Verwendung des manuellen Triggers trägt keine Waveform-Verwendungs-ID. Stattdessen ist der Wert eine Ordnungszahl in der erweiterten Wellenformtabelle des Geräts. Ordinal 1 ist für die obligatorische None (no-op) Waveform reserviert, Ordinal 2 ist für die Stop Waveform reserviert, und Ordinals 3 und höher werden Einträgen in der Waveform-Liste/Dauerliste des Geräts zugeordnet (siehe Mechanismus der Waveform-Liste/Dauerliste), wobei Ordinal 3 dem ersten Eintrag in der Liste entspricht, Ordinal 4 dem zweiten und so weiter. Der Host sendet möglicherweise die impliziten Ordnungszahlen 1 und 2, und für Ordnungszahlen 3 und höher sendet er nur Werte, die Den Einträgen entsprechen, die das Gerät als unterstützt angekündigt hat.

Wenn ein Ausgabebericht, der einen manuellen Trigger enthält, dessen Ordnungszahl in eine diskrete Wellenform aufgelöst wird, an das Gerät gesendet wird, sollte das Gerät sofort mit der Wiedergabe der angegebenen Wellenform beginnen, mit allen zusätzlichen Eigenschaften, die im Ausgabebericht enthalten sind (Intensität, Wiederholungsanzahl, Wiederholungsperiode). Wenn der manuelle Trigger in eine fortlaufende Wellenform aufgelöst wird, sollte die Wiedergabe nach Ermessen des Geräts beginnen (z. B. wenn festgelegt wird, dass der Stift mit dem Display in Kontakt steht).

Wenn ein Ausgabebericht einen manuellen Trigger enthält, dessen Ordnungszahl zur Wellenform Stop (Ordnungszahl 2) aufgelöst wird, sollte jede laufende Wellenformwiedergabe gestoppt werden. Wenn ein Ausgabebericht einen manuellen Auslöser enthält, dessen Ordnungszahl in die obligatorische None (no-op) Wellenform (Ordnungszahl 1) aufgelöst wird, darf das Gerät keine neue Wellenform starten und darf den Zustand einer aktuell wiedergegebenen Wellenform nicht ändern; der Bericht sollte als keine Operation im Hinblick auf die haptische Ausgabe behandelt werden.

Intensität

Die Intensitätsauslastung stellt den Prozentsatz der maximalen Intensität dar, der auf eine Wellenform angewendet werden soll. Dieser Wert sollte zwischen 0 und 100 Prozent variieren. 100 Prozent deuten darauf hin, dass Wellenformen vom Gerät mit ihrer maximalen Stärke ausgelöst werden, und 0 Prozent gibt an, dass der haptische Wandler nicht aktiviert ist.

Zahl der Wiederholungen

Die Verwendung der Wiederholungsanzahl gibt an, wie oft eine Wellenform wiederholt wird. Eine Wiederholungsanzahl von Null gibt an, dass die manuelle Triggerwellenform nur ein mal wiedergegeben werden soll (keine Wiederholung). Wenn die Wellenform-Abschneidzeit überschritten wurde, wird erwartet, dass unvollständige Wiederholungen ignoriert werden.

Wiederholungszeitraum

Die Verwendung der Retrigger-Periode stellt die Zeitspanne dar, die das Gerät warten muss, bevor eine manuelle Triggerwellenform in einem Ausgabebericht wiederholt wird, entsprechend dem von der Wiederholungsanzahl angegebenen Wert. Die Einheiten für diesen Wert sind Millisekunden. Wenn die Wiederholungsperiode kleiner als die Dauer der abgespielten Wellenform ist, sollte die Wellenform angehalten und neu gestartet werden, zum Zeitpunkt, der durch die Wiederholungsperiode angegeben wird.

Wellenformgrenzzeit

Die Nutzung der Waveform-Abschneidezeit stellt die maximale Zeitspanne dar, die das Gerät ermöglicht, dass eine manuelle Trigger-Wellenform wiederholt wird, bevor die Wiedergabe beendet wird. Dies ist ein konstanter Wert für das Gerät und enthält sowohl fortlaufende Wellenformen ohne festgelegte Dauer als auch Wellenformen mit diskreten Daueren, die so eingestellt sind, dass sie viele Male wiederholt werden. Die Einheiten für diesen Wert sind Millisekunden.

Starten und Stoppen des haptischen Feedbacks

Das flussdiagramm unten beschreibt, wann die haptischen Signale des Stifts konfiguriert, gelöscht, gestartet und angehalten werden sollen.

Die unten aufgeführten haptischen Zustände sind:

• Spielen: Der Stift spielt aktiv die haptische Wellenform
• Angehalten: Der Stift ist mit einer Wellenform konfiguriert, spielt sie jedoch nicht aktiv ab.
• Beendet: Der Stift ist nicht mit einer Wellenform konfiguriert und es wird derzeit nichts abgespielt.

Informationen zum Stiftstatus in Bezug auf den Digitizer finden Sie unter Windows Pen States.

Tastatursammlung (optional)

Eine optionale Funktion, um die Berichterstellung über letzte Schaltflächenklicks an den Host über HID-Tastaturberichte zu aktivieren.

Um eine End-Bluetooth-Taste zu implementieren, meldet das Gerät 3 verschiedene Tastaturkombinationen, die 3 verschiedenen Tastenaktionen über ein HID Bluetooth LE-Tastaturgerät entsprechen, das dem Host verfügbar gemacht wird. Die Aktionen und die entsprechenden Tastaturkombinationen werden unten beschrieben:

Stiftaufbewahrung

Ab Windows 10, Version 1903, unterstützt Windows Benachrichtigungen für Geräte mit kompatiblem Stiftstau. Der Mechanismus basiert auf der Hardware, die den entfernten oder ersetzten Stift erkennt und einen entsprechenden HID-Tastaturbericht für ein Paar Tastenkombinationen generiert. Melden Sie WIN+STRG+F20, um eine Andockung zu signalisieren (Stift in der Verstauung), melden Sie WIN+STRG+F19, um eine Entdocking zu signalisieren (Stift aus der Verstauung entfernt). Dies kann mit Firmware oder treiber implementiert werden.

Diese Andocken-/Abdocken-Ereignisse rufen das Shell-Freihandbereichsmenü auf oder blenden es aus. Ab Windows 10, Version 2004, reagiert Office auch auf diese Ereignisse mithilfe einer Plattform-API , mit der entwickler ihre Anwendung erweitern können, um das Bewusstsein für Stowageereignisse zu erhöhen. Es gibt keine Unterstützung, um abzufragen, ob der Stift im Dock vorhanden ist, Apps werden nur über das Entfernen und Zurückgeben von Ereignissen benachrichtigt, wenn sie sich im Vordergrund befinden.

HiD-Berichtsdeskriptorbeispiel

Der folgende Deskriptor unterstützt alle obligatorischen und optionalen Verwendungen. Er deklariert unterstützung für siebzehn Wellenformlisteneinträge (mit Ausnahme der impliziten Wellenformen 1 (Keine) und 2 (Stop), für insgesamt neunzehn Wellenformen), wobei die längste diskrete Wellenform eine Dauer von 50 ms aufweist. Fortlaufende Wellenformen haben eine Dauer von Null.

Alle logischen Bereiche sollten basierend auf der Geräteunterstützung aktualisiert werden. Zur Unterstützung einer anderen Anzahl von Wellenformen:

• Der logische Bereich der Manuellen Triggerverwendung muss aktualisiert werden.
• Die Nutzungsbereiche und die Berichtsanzahl für Waveform-Liste und Dauerliste müssen aktualisiert werden.

Um eine andere maximale Wellenformlänge zu unterstützen, müssen die folgenden logischen Bereiche aktualisiert werden:

• Rückstellperiode (Ausgang)
• Wellenform-Schnittzeit (Ausgabe)
• Dauerliste (Feature)

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 ()

Verwandte Themen

• Implementierungshandbuch für Eingabegeräte-Haptik