Implementeringsguide för Haptic Pen

Det här dokumentet beskriver protokollimplementeringen för en Haptic Pen-enhet som ansluter till en kompatibel Windows 11 värd. Detta omfattar inte vägledning om mekaniska begränsningar, elektriska begränsningar eller komponentval för att generera haptiska svar i penngivaren. Den här implementeringsvägledningen är oberoende av pennprotokollet som används mellan penngivaren och penndigitaliseraren, men en implementering kan välja att använda ett pennprotokoll med upplänksfunktion, vilket möjliggör för penndigitaliseraren att överföra ytterligare parametrar till penngivaren för att justera de haptiska svaren.

Enhetsklass

Haptic Pen är ett tillägg för klassen Pen Device på Windows. Den här implementeringsguiden kompletterar guiden för pennimplementering och fokuserar på att implementera haptik i penngivaren, därför måste haptiska pennor uppfylla kraven i pennimplementeringsguiden utöver de som finns här.

Enhetsbussanslutning

Haptic Pen ska använda Microsoft tillhandahållna inkorgsdrivrutiner för att ansluta till en Windows värd med HID via Bluetooth.

Implementering av Haptic Pen Protocol

Det krävs en god förståelse för HID-protokollet för att kunna förstå den information som presenteras här. Se följande resurser för information om HID-protokollet:

• Enhetsklassdefinition för humangränssnittsenheter (HID)
• HID-användningstabeller

Windows innehåller en HID-klassdrivrutin och motsvarande HID Bluetooth-aktiverad miniportdrivrutin, så det finns inget behov av några miniportdrivrutiner från tredje part. Haptic pen device firmware behöver bara rapportera de användningar som beskrivs i det här avsnittet. Windows använder den inbyggda programvaran och sina egna HID-drivrutiner för att aktivera enheten och ge Windows program åtkomst till enheten.

En exempelbeskrivning finns i avsnittet Exempelrapportbeskrivningar nedan.

Obligatorisk HID-samling på toppnivå

En Haptic Pen-enhet bör använda HID-protokollet på ett Windows 11 system på ett sådant sätt att enheten tillhandahåller en samling på den översta nivån som visas som en digitaliserare/penna (sida 0x0D, användning 0x20).

Inmatningsrapport för digitaliseringspenna

Pennsiffreringssamlingen måste rapportera pennans identifierare som består av transduktorserienumret och leverantörs-ID:t för givaren i indatarapporterna som rapporteras till operativsystemet. Samma penna-ID måste rapporteras via pennans samling. Detta gör att operativsystemet kan korrelera pennindata som genereras av digitaliseraren till pennan. Mer information om pennimplementeringsguiden finns här: Pen Protocol-implementering.

Serienummer för transduktor

Transducerserienumret är en unik beständig identifierare för den givare som används i penntillbehöret och kommunicerar med penndigitaliseraren. Detta måste vara 32-bitars och definieras av leverantören eller entiteten som identifieras av leverantörs-ID:t för givaren. Om transduktörens serienummer är okänt för digitaliseraren, antingen på grund av att penntillbehöret inte stöder överföring av detta värde eller att överföringen inte har tagits emot i sin helhet, ska digitaliseraren rapportera 0 till värddatorn. Null-position stöds inte av värddatorn.

Serienummer för transduktor – del 2

Transduktorserienummer – Del 2 gör att ytterligare 32 bitar kan anges som en del av den unika beständiga identifieraren för givaren som används i ett penntillbehör. Under omständigheter där transduktörens serienummer – del 2 är okänt för digitaliseraren, antingen därför att penntillbehöret inte stöder att skicka detta värde eller att överföringen inte har tagits emot i sin helhet, ska digitaliseraren rapportera 0 till värddatorn. Null-position stöds inte av värddatorn.

Leverantörs-ID för transducer

Transduktorleverantörs-ID är ett fält för att kommunicera tillverkaren av transduktorn som används i penntillbehöret som kommunicerar med pennigitaliseraren. Detta måste vara ett 2-byte USB-IF-tilldelat leverantörs-ID antingen för tillverkaren eller för den IHV/OEM som tillåter användning av sitt USB-IF-leverantörs-ID för detta ändamål.

Funktioner som är beroende av unik pennidentifiering

Reporting PenID är obligatoriskt för att aktivera scenarier som pennens haptiska feedback (krävs för haptiska funktioner i den här guiden).

Det är också obligatoriskt för scenarier som använder flera pennor för pennanteckning. Till exempel:

• Whiteboard-appen på Windows stöder användning av flera pennor där varje penna kan mappas till ett visst pennanteckningsverktyg
• I allmänhet kan appar som vill tilldela attribut eller beteenden till olika fysiska pennor, även om digitaliseraren endast har stöd för en enda penna på skärmen i taget
• Appar som vill spåra flera samtidiga pennor på stödda digitaliserare

Haptic-funktionsrapport

Om en pennenhet stöder haptisk feedback kan det göra det möjligt för systemet och programmen att dra nytta av den genom att inkludera en haptisk feedbacksamling (sida 0x0E, användning 0x01) i pennans TLC. Mer information om hur HID-specifikationen stöder haptisk feedback finns i Haptics-sidans ratificering till HID-specifikationen.

Värdenheten använder följande användningar i en GET_FEATURE rapport, genom att använda samlingen för haptisk feedback, för att specifikt interrogéra pennenhetens haptiska möjligheter, särskilt de vågformer och varaktigheter som stöds. Om en enhet väljer att exponera en haptisk feedback-kollektion är den här funktionsrapporten obligatorisk så att värdenheten kan identifiera vilka funktioner den kan använda när den initierar haptisk feedback via korrekt utdatarapport.

Vågformslista

Användningen av vågformslistan representerar en samling av HID-användningar för de vågformer som stöds, ordnade med hjälp av ordningstal. De fördefinierade haptiska vågformerna definieras i HID-specifikationen. För haptiska pennenheter kan dessa vågformer klassificeras som två segment som motsvarar olika scenarier:

• Kontinuerlig - Bläckbaserad feedback för att simulera olika texturer medan användaren aktivt inkar med olika verktyg såsom penna, blyertspenna osv.
• Diskret – Diskret, icke-kontinuerlig interaktionsbaserad feedback för när en användare utför vissa indatadrivna uppgifter som att hovra över en knapp, klicka på en inaktiverad knapp och lyckad pennanteckningsformigenkänning.

Den fullständiga listan över vågformer som stöds för haptiska pennenheter finns nedan:

Både None och Stop krävs för alla HID-kompatibla haptics-enheter. Ordningstalen 1 och 2 är implicit inställda på None och Stop. De behöver inte deklareras i vågformslistan eller varaktighetslistan. Vågformslistan och varaktighetslistan deklarerar vågformer som stöds via deras ordningstalsanvändningsintervall (användning/logisk lägsta och högsta) och värdet som returneras för varje ordningstal, med ingen för ordningstal som inte stöds.

Tryck- och Frisläppningsvågformerna är valfria, men om den ena stöds måste även den andra vara det. Samma sak gäller för lyckade och fel.

Varaktighetslista

Användning av varaktighetslista representerar en samling varaktigheter för vågformerna som stöds i Waveform-listan, ordnade med hjälp av ordningstal. Enheten för vågformens varaktighet är millisekunder och varaktigheten måste vara ett positivt värde som inte är noll för alla icke-kontinuerliga vågformer. Om en vågform är kontinuerlig (spelas upp tills den stoppas av värdenheten eller vågformens stopp-tid överskrids) definieras dess varaktighet som noll.

Ingen och Stopp antas ha en varaktighet på noll. De behöver inte deklareras i varaktighetslistan.

Haptisk utdatarapport

Värden använder följande tillämpningar i en utdatarapport för att generera haptiska återkopplingshändelser till Haptic Pen-enheten. Vissa användningar är obligatoriska för kompatibilitet med Windows värdimplementering.

Manuell utlösare

Användningen av den manuella utlösaren bär inte direkt med sig ett vågforms-ID. I stället är dess värde ett ordinaltal i den utökade vågformstabellen för enheten. Ordningstal 1 är reserverad för den obligatoriska None (no-op) vågformen, ordningstal 2 är reserverad för Stoppvågformen och ordningstal från 3 och högre motsvarar poster i enhetens vågformslista/varaktighetslista (se mekanismen Vågformslista/Varaktighetslista), där ordningstal 3 motsvarar den första posten i listan, ordningstal 4 till den andra och så vidare. Värdenheten kan skicka de implicita ordningstalen 1 och 2, och för ordningstal 3 och högre skickas endast värden som motsvarar poster som enheten har annonserat som stödjer.

När en utdatarapport som innehåller en manuell utlösare vars ordningstal matchar en diskret vågform skickas till enheten, bör enheten omedelbart börja spela upp den angivna vågformen med eventuella ytterligare egenskaper som ingår i utdatarapporten (Intensitet, Upprepa antal, Retrigger-period). Om den manuella utlösarordningen matchar en kontinuerlig vågform bör uppspelningen börja efter enhetens gottfinnande (till exempel när den fastställer att pennan är i kontakt med displayen).

När en utdatarapport innehåller en manuell utlösare vars ordningstal matchar stoppvågformen (ordningstal 2) bör all pågående vågformsuppspelning stoppas. När en utdatarapport innehåller en manuell utlösare vars ordningstal matchar den obligatoriska vågformen Ingen (no-op) (ordningstal 1) får enheten inte starta någon ny vågform och får inte ändra tillståndet för någon vågform som för närvarande spelas. rapporten ska behandlas som en icke-åtgärd när det gäller haptiska utdata.

Intensitet

Intensitetsanvändningen representerar den procentandel av maximal intensitet som ska tillämpas på en vågform. Det här värdet bör variera mellan 0 och 100 procent. 100 procent anger att vågformerna utlöses av enheten med maximal styrka och 0 procent anger att den haptiska givaren inte är aktiverad.

Antal upprepningar

Användningen av upprepat antal representerar hur många gånger ett vågmönster ska upprepas. Ett upprepningsantal på noll anger att vågformen för manuell avtryckare endast ska spelas upp en gång (ingen upprepning). Om brytningstiden för vågformen har överskridits, förväntas det att eventuella ofullständiga upprepningar ignoreras.

återutlösningsperiod

Användningen av Retrigger-perioden representerar hur lång tid enheten ska vänta innan en manuell utlösarvågform upprepas i en utdatarapport, enligt det värde som anges av Upprepa antal. Enheterna för det här värdet är millisekunder. Om Retrigger-perioden är mindre än varaktigheten för vågformen som spelas upp ska vågformen stoppas och startas om vid den tidsperiod som anges av retriggerperioden.

Tid för vågformsavskärning

Användningen av vågformsavstängningstid representerar den maximala tid som enheten tillåter att en manuell utlösarvågform upprepas innan uppspelningen avslutas. Detta är ett konstant värde för enheten och innehåller både kontinuerliga vågformer utan angivna varaktigheter och vågformer med diskreta varaktigheter som är inställda på att upprepas många gånger. Enheterna för det här värdet är millisekunder.

Starta och stoppa Haptics

I flödesschemat nedan beskrivs när pennans haptiska signaler ska konfigureras, rensas, startas och stoppas.

De olika haptiska tillstånden som beskrivs nedan är:

• Spelar: Pennan spelar aktivt den haptiska vågformen
• Pausad: Pennan är konfigurerad med en vågform, men spelar inte aktivt upp den
• Stoppad: Pennan är inte konfigurerad med en vågform och spelar inte aktivt upp något

För penntillståndet med avseende på digitaliseraren, se Windows Penntillstånd.

Tangentbordssamling (valfritt)

En valfri funktion för att aktivera rapportering av knappklick i slutet till värden via rapporter från HID-tangentbord.

För att implementera en tail-end Bluetooth-knapp rapporterar enheten tre distinkta tangentbordskombinationer som motsvarar tre distinkta knappåtgärder via en HID Bluetooth LE-tangentbordsenhet som exponeras för värdenhet. Åtgärderna och motsvarande tangentbordskombinationer beskrivs nedan:

Pennförvaring

Från och med Windows 10 version 1903 stöder Windows meddelanden för enheter som innehåller kompatibel pennlagring. Mekanismen förlitar sig på att maskinvaran identifierar pennan som tas bort eller ersätts och genererar en motsvarande HID-tangentbordsrapport för ett par genvägskombinationer. Om du vill signalera en dockning (pennan placeras i ställning) rapporterar du WIN+CTRL+F20 och för att signalera en avdockning (pennan har tagits bort från ställning) rapporterar du WIN+CTRL+F19. Detta kan implementeras med inbyggd programvara eller en drivrutin.

De här avdocknings-/dockningshändelserna öppnar/stänger menyn för arbetsytan Shell Ink. Från och med Windows 10 reagerar version 2004 Office också på dessa händelser med hjälp av ett platform-API som gör det möjligt för alla utvecklare att utöka sitt program för att öka medvetenheten om stuvningshändelser. Det finns inget stöd för att fråga om pennan finns i dockan, appar meddelas endast om borttagnings- och returhändelser om de är i förgrunden.

Exempel på HID-rapportbeskrivning

Följande beskrivning stöder alla obligatoriska och valfria användningar. Den deklarerar stöd för sjutton vågformslistposter (exklusive implicita vågformer 1 (Ingen) och 2 (stopp), för totalt nitton vågformer), med den längsta diskreta vågformen som har en varaktighet på 50 ms. Kontinuerliga vågformer har en varaktighet på noll.

Alla logiska intervall bör uppdateras baserat på enhetsstöd. Så här stöder du ett annat antal vågformer:

• Det logiska intervallet för användningen av manuell utlösare måste uppdateras
• Användningsintervallen och rapportantalet för Vågformslista och Varaktighetslista måste uppdateras

För att stödja en annan maximal vågformslängd måste följande logiska intervall uppdateras:

• Retriggerperiod (utdata)
• Bryttid för vågform (utdata)
• Varaktighetslista (funktion)

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

Relaterade ämnen

• Haptik för indataenheter - Implementeringsguide