Implementatiehandleiding voor Haptic Pen

Dit document bevat informatie over de protocol-implementatie voor een Haptic Pen-apparaat dat verbinding maakt met een compatibele Windows 11 host. Dit omvat geen richtlijnen voor mechanische beperkingen, elektrische beperkingen of onderdeelselectie voor het genereren van de haptische reactie binnen de pentransducer. Deze implementatierichtlijnen zijn onafhankelijk van het protocol dat wordt gebruikt tussen de transducer en de pendigitalisator, maar een implementatie kan ervoor kiezen om een penprotocol met uplink-mogelijkheid te gebruiken, waarmee de pendigitalisator aanvullende parameters aan de transducer kan bieden voor het moduleren van haptische respons.

Apparaatklasse

Haptic Pen is een uitbreiding van de klasse Penapparaat op Windows. Deze implementatiehandleiding voegt toe aan de Handleiding voor pen-implementatie en is gericht op het implementeren van haptiek binnen de pentransducer, dus haptische pennen moeten voldoen aan de vereisten in de Pen-implementatiehandleiding , naast die hier.

Apparaatbusconnectiviteit

De Haptic Pen gebruikt de door Microsoft meegeleverde stuurprogramma's om verbinding te maken met een Windows-host via HID over Bluetooth.

Haptic Pen Protocol-implementatie

Een goed begrip van het HID-protocol is nodig om inzicht te krijgen in de informatie die hier wordt gepresenteerd. Zie de volgende bronnen voor informatie over het HID-protocol:

• Apparaatklassedefinitie voor Human Interface Devices (HID)
• HID-gebruikstabellen

Windows bevat een HID-klassestuurprogramma en het bijbehorende HID Bluetooth-minipoortstuurprogramma, daarom is er geen noodzaak voor minipoortstuurprogramma's van derden. Haptic penapparaatfirmware hoeft alleen de gebruiksgegevens te rapporteren die in dit onderwerp worden beschreven. Windows gebruikt de firmware en de eigen HID-stuurprogramma's om het apparaat in te schakelen en Windows toepassingen toegang te geven tot het apparaat.

Hieronder vindt u een voorbeelddescriptor in de sectie Voorbeeldrapportdescriptors.

Vereiste HID-verzameling op topniveau

Een Haptic Pen apparaat moet het HID-protocol op een Windows 11-systeem zodanig gebruiken dat het apparaat een top-level verzameling biedt die wordt weergegeven als een digitizer/stylus (Page 0x0D, Usage 0x20).

Invoerrapport pen-digitizer

De verzameling pendigitaliseerder moet de stylus-id rapporteren die bestaat uit het serienummer van de transducer en de leverancier-id van de transducer in de invoerrapporten die zijn gerapporteerd aan het besturingssysteem. Dezelfde stylus-ID moet worden gerapporteerd via de styluscollectie. Hierdoor kan het besturingssysteem de peninvoer die met de digitalizer wordt gegenereerd, correleren aan de stylus. Meer informatie over de handleiding voor pen-implementatie vindt u hier: Implementatie van penprotocol.

Serienummer van transducer

Het serienummer van de transducer is een unieke permanente identificatiecode voor de transducer die wordt gebruikt in de pen-accessoire die communiceren met de pendigitalisatie. Dit is vereist om 32 bits te zijn en wordt gedefinieerd door de leverancier of entiteit die wordt geïdentificeerd door de leverancier-id van de transducer. In omstandigheden waarin het serienummer van de transducer onbekend is voor de digitalisator, hetzij omdat het penaccessoire geen ondersteuning biedt voor het verzenden van deze waarde of dat de overdracht niet volledig is ontvangen, zal de digitalisator 0 rapporteren aan de host. Null-positie wordt niet ondersteund door de host.

Serienummer van transducer – deel 2

Serienummer van transducer – Deel 2 maakt het mogelijk om nog eens 32 bits op te geven als onderdeel van de unieke permanente id voor de transducer die in een penaccessoire wordt gebruikt. In gevallen waarin het Transducer Serienummer – Deel 2 onbekend is voor de digitalizer, hetzij omdat het penaccessoire deze waarde niet ondersteunt of dat de overdracht niet volledig is ontvangen, meldt de digitalizer 0 aan de host. Null-positie wordt niet ondersteund door de host.

Leverancier-id van transducer

De leverancier-id van Transducer is een veld voor de communicatie van de fabrikant van de transducer die wordt gebruikt in de penaccessoire die communiceert met de pendigitaliseerder. Dit moet een 2-byte USB-IF toegewezen leverancier-id zijn van de fabrikant of die van de IHV/OEM die het gebruik van hun USB-IF leverancier-id voor dit doel toestaat.

Functies die afhankelijk zijn van unieke penidentificatie

Rapportage van PenID is verplicht om scenario's zoals pen-haptiek in te schakelen (vereist voor haptische functies in deze handleiding).

Het is ook verplicht voor scenario's die meerdere pennen gebruiken voor inkt. Voorbeeld:

• Whiteboard-app op Windows ondersteunt meerdere pengebruik, waarbij elke pen kan worden toegewezen aan een bepaald inktprogramma
• Over het algemeen kunnen apps die kenmerken of gedrag willen toewijzen aan verschillende fysieke pennen, ook al kan de digitalisatiefunctie slechts één pen tegelijk op het scherm ondersteunen
• Apps die meerdere gelijktijdige pennen willen bijhouden op ondersteunde digitalisatieprogramma's

Rapport Haptische Functie

Als een penapparaat haptische feedback ondersteunt, kunnen het systeem en de toepassingen hiervan profiteren door een haptische feedbackverzameling (Page 0x0E, Usage 0x01) in de stylus TLC op te nemen. Raadpleeg de Haptics-pagina in de ratificatie bij de HID-specificatie voor meer informatie over hoe de HID-specificatie haptische feedback ondersteunt.

De host gebruikt de volgende gebruiksgegevens in een GET_FEATURE-rapport (via de haptische feedbackverzameling) om een query uit te voeren op de haptische mogelijkheden van het penapparaat, met name de ondersteunde golfvormen en duur. Als een apparaat ervoor kiest om een haptische feedbackverzameling beschikbaar te maken, is dit functierapport verplicht, zodat de host kan detecteren welke mogelijkheden het kan gebruiken bij het initiëren van haptische feedback via het juiste uitvoerrapport.

Lijst met golfvormen

Het gebruik van Waveform List vertegenwoordigt een verzameling van het HID-gebruik van ondersteunde golfvormen, geordend met behulp van ordinals. De vooraf gedefinieerde haptiekgolfvormen worden gedefinieerd in de HID-specificatie. Voor pen haptische apparaten kunnen deze golfvormen worden geclassificeerd als twee segmenten die overeenkomen met verschillende scenario's:

• Doorlopende feedback op basis van inkt voor het simuleren van verschillende patronen terwijl de gebruiker actief inkt gebruikt met verschillende hulpmiddelen zoals pen, potlood, enzovoort.
• Discrete - Niet-continue feedback op basis van interactie voor wanneer een gebruiker een invoergestuurde taak uitvoert, zoals het aanwijzen van een knop, het klikken op een uitgeschakelde knop en geslaagde inktvormherkenning.

Hieronder vindt u de volledige lijst met golfvormen die worden ondersteund voor pen haptische apparaten:

Zowel Geen als Stop zijn vereist voor alle HID-compatibele haptiekapparaten. Ordinals 1 en 2 zijn impliciet ingesteld op None en Stop. Ze hoeven niet te worden gedeclareerd in de waveform-lijst of duurlijst. De Waveform-lijst en Duur-lijst verklaren de ondersteunde golfvormen via hun ordinaal gebruiksbereik (gebruiks-/logische minimum en maximum) en de waarde die wordt geretourneerd voor elke ordinaal, waarbij Geen wordt gebruikt voor ordinaals die niet worden ondersteund.

De druk en release-golfvormen zijn optioneel, maar als de ene wordt ondersteund, moet de andere ook ondersteund zijn. Hetzelfde geldt voor Geslaagd en Fout.

Duurlijst

Het gebruik van de Duration List vertegenwoordigt een verzameling van de duren voor de ondersteunde golfvormen in de Waveform-lijst, geordend met behulp van rangtelwoorden. De eenheid voor de duur van de golfvorm is milliseconden en de duur moet een positieve niet-nulwaarde zijn voor elke niet-doorlopende golfvorm. Als een golfvorm continu is (wordt afgespeeld totdat deze wordt gestopt door de host of de Cutoff-tijd van Waveform wordt overschreden), wordt de duur ervan gedefinieerd als nul.

Geen en Stop worden verondersteld een duur van nul te hebben. Ze hoeven niet te worden gedeclareerd in de duurlijst.

Haptisch Uitvoerrapport

De host gebruikt de volgende gebruiksgegevens in een uitvoerrapport om haptische feedbackgebeurtenissen uit te voeren op het Haptic Pen-apparaat. Sommige gebruiksrechten zijn verplicht voor compatibiliteit met de Windows host-implementatie.

Handmatige trigger

Het gebruik van handmatige triggers draagt niet rechtstreeks een golfvormgebruiks-id. In plaats daarvan is de waarde een ordinaal in de uitgebreide golfvormtabel van het apparaat. Ordinaal 1 is gereserveerd voor de verplichte None (no-op) golfvorm, ordinaal 2 is gereserveerd voor de stopgolfvorm, en ordinaals 3 en hoger worden toegewezen aan vermeldingen in de Waveform List/Duration List van het apparaat (zie het mechanisme Waveform List/Duration List), waarbij ordinaal 3 overeenkomt met de eerste vermelding in de lijst, ordinaal 4 met de tweede, enzovoort. De host kan de impliciete rangtelwoorden 1 en 2 verzenden, en voor rangtelwoorden 3 en hoger worden alleen waarden verzonden die overeenkomen met vermeldingen die het apparaat heeft aangekondigd als ondersteund.

Wanneer een uitvoerrapport met een handmatige trigger waarvan de rangschikker wordt omgezet in een discrete golfvorm naar het apparaat wordt verzonden, moet het apparaat onmiddellijk beginnen met het afspelen van de opgegeven golfvorm met eventuele extra eigenschappen die zijn opgenomen in het uitvoerrapport (Intensiteit, Aantal herhalingen, Retriggerperiode). Als de manuele triggerrangorde wordt omgezet in een doorlopende golfvorm, moet het afspelen beginnen op basis van het oordeel van het apparaat (bijvoorbeeld wanneer het bepaalt dat de stylus in contact is met het beeldscherm).

Wanneer een uitvoerrapport een handmatige trigger bevat waarvan het ordinaal overeenkomt met de Stop golfvorm (ordinaal 2), moet het huidige afspelen van golfvormen stoppen. Wanneer een uitvoerrapport een handmatige trigger bevat waarvan de ordinalen worden vertaald naar de verplichte Geen (no-op) golfvorm (ordinaal 1), mag het apparaat geen nieuwe golfvorm activeren en mag het de status van een huidige golfvorm niet wijzigen; het rapport moet worden behandeld als een no-operation met betrekking tot haptische uitvoer.

Intensiteit

Het intensiteitsgebruik vertegenwoordigt het percentage van de maximale intensiteit dat moet worden toegepast op een golfvorm. Deze waarde moet variëren tussen 0 en 100 procent. 100 procent geeft aan dat golfvormen worden geactiveerd door het apparaat met hun maximale sterkte en 0 procent geeft aan dat de haptische transducer niet is ingeschakeld.

Aantal herhalingen

Het gebruik van het aantal herhalingen geeft aan hoeveel keer een golfvorm moet worden herhaald. Een aantal herhalingen van nul geeft aan dat de handmatige triggergolfvorm slechts één keer mag worden afgespeeld (geen herhaling). Als de Cutoff-tijd van Waveform is overschreden, wordt verwacht dat onvolledige herhalingen worden genegeerd.

Hertriggerperiode

Het gebruik van de Retrigger Periode vertegenwoordigt de hoeveelheid tijd die het apparaat moet wachten voordat een handmatige triggergolfvorm in een uitvoerrapport wordt herhaald, conform de waarde die is gespecificeerd door het aantal herhalingen. De eenheden voor deze waarde zijn milliseconden. Als de retriggerperiode kleiner is dan de duur van de golfvorm die wordt afgespeeld, moet de golfvorm worden gestopt en opnieuw worden gestart op de periode die wordt aangegeven door de retriggerperiode.

Cutoff-tijd voor golfvorm

Het gebruik van Waveform Cutoff Time vertegenwoordigt de maximale hoeveelheid tijd die het apparaat toestaat dat een handmatige triggergolfvorm wordt herhaald voordat het afspelen wordt beëindigd. Dit is een constante waarde voor het apparaat en bevat zowel continue golfvormen zonder ingestelde duur als golfvormen met discrete duur die vele malen worden herhaald. De eenheden voor deze waarde zijn milliseconden.

Het starten en stoppen van haptics

In het onderstaande stroomdiagram wordt beschreven wanneer de haptische signalen van de pen moeten worden geconfigureerd, gewist, gestart en gestopt.

De verschillende haptische toestanden die hieronder worden beschreven, zijn:

• Spelen: De pen speelt actief de haptische golfvorm af
• Gepauzeerd: De pen is geconfigureerd met een golfvorm, maar het speelt deze niet actief af
• Gestopt: De pen is niet geconfigureerd met een golfvorm en speelt niets actief af

Raadpleeg Windows Pen States voor de penstatus met betrekking tot de digitalisatiefunctie.

Toetsenbordcollectie (optioneel)

Een optionele functie om rapportage van het klikken op de laatste knop aan de host via HID-toetsenbordrapporten mogelijk te maken.

Als u een tail-end Bluetooth-knop wilt implementeren, rapporteert het apparaat drie verschillende toetsenbordcombinaties die overeenkomen met drie afzonderlijke knopacties via een HID Bluetooth LE-toetsenbordapparaat dat beschikbaar is voor de host. De acties en bijbehorende toetsenbordcombinaties worden hieronder beschreven:

Pen Storage

Vanaf Windows 10 versie 1903 ondersteunt Windows meldingen voor apparaten met compatibele penberging. Het mechanisme is afhankelijk van de hardware die detecteert dat de pen wordt verwijderd of vervangen en een bijbehorend HID-toetsenbordrapport genereert voor een paar sneltoetscombinaties. Meldt u WIN+CTRL+F20 om een dock aan te geven (pen teruggeplaatst in opslagruimte) en om een ontkoppeling aan te geven (pen verwijderd uit de opslagruimte), meldt u WIN+CTRL+F19. Dit kan worden geïmplementeerd met firmware of een stuurprogramma.

Deze loskoppelen/dockgebeurtenissen openen/sluiten het menu van de Shell-werkruimte voor inkt. Vanaf Windows 10 reageert Office versie 2004 ook op deze gebeurtenissen met behulp van een platform-API waarmee elke ontwikkelaar de toepassing kan uitbreiden om zich bewust te zijn van opslagevenementen. Er is geen ondersteuning om een query uit te voeren of de pen in het dock aanwezig is, apps ontvangen alleen meldingen van de verwijdering en terugkeer van de pen als zij zich op de voorgrond bevinden.

Voorbeeld van HID-rapportdescriptor

De volgende descriptor ondersteunt alle verplichte en optionele gebruiksgegevens. Het declareert ondersteuning voor zeventien golfvormlijstvermeldingen (met uitzondering van de impliciete golfvormen 1 (Geen) en 2 (Stop), voor een totaal van negentien golfvormen), met de langste discrete golfvorm met een duur van 50 ms. Doorlopende golfvormen hebben een duur van nul.

Alle logische bereiken moeten worden bijgewerkt op basis van de ondersteuning door apparaten. Ter ondersteuning van een ander aantal golfvormen:

• Het logische bereik van het handmatige triggergebruik moet worden bijgewerkt
• De gebruiksbereiken en het aantal rapporten voor Waveform List en Duration List moeten worden bijgewerkt

Als u een andere maximale golfvormlengte wilt instellen, moet het volgende logische bereik worden bijgewerkt:

• Retriggerperiode (uitvoer)
• Cutoff-tijd voor golfvormen (uitvoer)
• Duuuroverzicht (functie)

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

Verwante onderwerpen

• Implementatiehandleiding voor Haptics-invoerapparaten