Not
Åtkomst till denna sida kräver auktorisation. Du kan prova att logga in eller byta katalog.
Åtkomst till denna sida kräver auktorisation. Du kan prova att byta katalog.
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 till klassen Pen Device i 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 Microsofts inbox-drivrutiner för att ansluta till en värddator 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:
Windows innehåller en HID-klassdrivrutin och motsvarande HID Bluetooth-aktiverad miniportdrivrutin, därför finns det 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 i Windows 10-systemet på ett sådant sätt att enheten tillhandahåller en samling på högsta nivå som fungerar 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.
| Sida | ID-nummer | Noteringar |
|---|---|---|
| 0xD | 0x5B | Obligatoriskt för funktioner som är beroende av unik pennidentifiering (se nedan) |
| 0xD | 0x6E | Valfritt tillägg av serienumret med ytterligare 32 bitar |
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.
| Sida | ID-nummer | Noteringar |
|---|---|---|
| 0xD | 0x91 | Obligatoriskt för funktioner som är beroende av unik pennidentifiering (se nedan) |
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 i Windows stöder flera pennanvändningar 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 stöder en enda penna på skärmen vid den tidpunkten
- Appar som vill spåra flera samtidiga pennor på stödda digitaliserare
Haptisk utdatarapport
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ärden använder följande funktioner i en utdatarapport (via insamling av haptisk feedback) för att tillåta värden att skicka haptiska feedbackhändelser till den haptiska pennan. Om en enhet väljer att exponera en haptisk feedbacksamling är vissa användningar obligatoriska för att tillåta att värdinitierad haptisk feedback stöds.
| Medlem | Description | Sida | ID-nummer | Obligatoriskt/valfritt |
|---|---|---|---|---|
| Vågformslista | Ordnad lista över haptiska vågformer som stöds av enheten | 0x0E | 0x10 | Mandatory |
| Varaktighetslista | Ordnad lista över varaktigheter för vågformer i vågformslistan | 0x0E | 0x11 | Mandatory |
| Automatisk utlösare | Waveform utlöses automatiskt efter enhetens gottfinnande | 0x0E | 0x20 | Mandatory |
| Automatisk utlösare associerad kontroll | HID-användning av kontrollen som är associerad med haptisk feedback | 0x0E | 0x22 | Mandatory |
| Intensitet | Utdata – Intensitet för manuell utlösarvågform i procent | 0x0E | 0x23 | Valfritt |
| Antal upprepningar | Utdata – Antal gånger du ska spela upp manuell utlösarvågform efter inledande uppspelning | 0x0E | 0x24 | Valfritt |
| Retrigger-period | Utdata – väntetidens varaktighet innan manuell utlösare utlöses igen vid upprepande | 0x0E | 0x25 | Valfritt |
| Tid för vågformsavstängning | Maximal tid som en manuell utlösarvågform kan spelas upp innan den skärs av | 0x0E | 0x28 | Valfritt |
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:
- WAVEFORM_*CONTINUOUS – Bläckbaserad feedback för att simulera olika texturer medan användaren aktivt skriver med olika verktyg som penna, blyertspenna med mera.
- WAVEFORM_* – 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:
| Vågform | Description | Sida | ID-nummer | Obligatoriskt/valfritt |
|---|---|---|---|---|
| WAVEFORM_NONE | No-op. Bör inte påverka uppspelningstillståndet för pågående vågformer | 0x0E | 0x1001 | Mandatory |
| WAVEFORM_STOP | Stoppar uppspelningen av pågående vågformer | 0x0E | 0x1002 | Mandatory |
| WAVEFORM_CLICK | Skapar en kort "klick"-återkoppling. Standardåtergång när den interaktionsfeedbackvågform som valts av appen inte stöds av en haptisk pen | 0x0E | 0x1003 | Mandatory |
| WAVEFORM_INKCONTINUOUS | Simulerar känslan av pennanteckning med en fysisk kulspetspenna. Standardåterställning när en bläckvågform inte stöds av en haptisk penna | 0x0E | 0x100B | Mandatory |
| WAVEFORM_SUCCESS | Stark haptisk signal för att varna användaren om att en åtgärd har slutförts | 0x0E | 0x1009 | Valfritt |
| WAVEFORM_ERROR | Stark haptisk signal för att varna användaren om att en åtgärd har misslyckats, eller så har ett fel inträffat | 0x0E | 0x100A | Valfritt |
| WAVEFORM_HOVER | Haptisk signal när användaren hovrar över ett interaktivt gränssnittselement med en haptisk penna | 0x0E | 0x1008 | Valfritt |
| WAVEFORM_PRESS | Haptisk signal för när en användare trycker på ett interaktivt gränssnittselement i en inkrementell åtgärd (se Release) | 0x0E | 0x1006 | Valfritt |
| WAVEFORM_RELEASE | Haptisk signal för när en användare släpper ett interaktivt UI-element i en stegvis åtgärd (se Tryck) | 0x0E | 0x1007 | Valfritt |
| WAVEFORM_PENCILCONTINUOUS | Kontinuerlig haptisk signal när användaren väljer penna som pennanteckningsverktyg | 0x0E | 0x100C | Valfritt |
| WAVEFORM_MARKERCONTINUOUS | Kontinuerlig haptisk signal när användaren väljer markör som pennanteckningsverktyg | 0x0E | 0x100D | Valfritt |
| WAVEFORM_CHISELMARKERCONTINUOUS | Kontinuerligt haptiskt signal när användaren väljer mejselmarkör eller överstrykningspenna som ritverktyg | 0x0E | 0x100E | Valfritt |
| WAVEFORM_BRUSHCONTINUOUS | Kontinuerlig haptisk signal när användaren väljer pensel som pennanteckningsverktyg | 0x0E | 0x100F | Valfritt |
| VÅGFORM_RADERAREKONTINUERLIG | Kontinuerlig haptisk signal när användaren väljer radergummi som pennanteckningsverktyg | 0x0E | 0x1010 | Valfritt |
| WAVEFORM_SPARKLECONTINUOUS | Kontinuerlig haptisk signal för specialbläckverktyg, till exempel en flerfärgad borste | 0x0E | 0x1011 | Valfritt |
Anmärkning
Även om det inte krävs rekommenderar vi att du även implementerar de andra uppräknade vågformerna för att ge en mer fullständig användarupplevelse. I synnerhet rekommenderas WAVEFORM_PRESS och WAVEFORM_RELEASE starkt eftersom de ger värdefull interaktionsfeedback.
Både WAVEFORM_NONE och WAVEFORM_STOP krävs för alla HID-kompatibla haptics-enheter. Ordningstalen 1 och 2 anges implicit till WAVEFORM_NONE och WAVEFORM_STOP. De behöver inte deklareras i vågformslistan eller varaktighetslistan. Vågformslistan deklarerar vågformer som stöds med det fysiska minimumet och maxvärdet för varje ordningstal i listan.
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.
WAVEFORM_NONE och WAVEFORM_STOP antas ha en varaktighet på noll. De behöver inte deklareras i varaktighetslistan.
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.
Retrigger-period
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ågformsavstängning
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.
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ärdimplementeringen.
| Medlem | Description | Sida | ID-nummer | Obligatoriskt/valfritt |
|---|---|---|---|---|
| Manuell utlösare | Waveform som utlöses som explicit kommando från värden | 0x0E | 0x21 | Mandatory |
| Intensitet | Intensitet för manuell utlösarvågform i procent | 0x0E | 0x23 | Mandatory |
| Antal upprepningar | Antal gånger du ska spela upp manuell utlösarvågform efter inledande uppspelning | 0x0E | 0x24 | Valfritt |
| Retrigger-period | Tidsperioden att vänta innan manuell trigger återutlöses vid upprepningar | 0x0E | 0x25 | Valfritt |
Manuell utlösare
Användning av manuell utlösare representerar en vågformsanvändning som stöds från vågformslistan som har begärts att spelas upp av värden. När en utdatarapport som innehåller en annan manuell utlösare än WAVEFORM_NONE skickas till enheten bör den omedelbart börja spela upp den angivna vågformen med de ytterligare egenskaper som ingår i utdatarapporten (Intensitet, Upprepa antal, Retrigger-period). När en utdatarapport innehåller en manuell utlösare av WAVEFORM_STOP ska pågående vågformsuppspelning stoppas.
För Intensitet, Repetitionsantal och Återutlösningsperiod, se föregående avsnitt i enlighet med rapporten för utdatafunktioner.
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
Information om penntillståndet med avseende på digitalisatorn finns i Windows Pen States.
Anmärkning
När pennan är utom räckhåll rekommenderas, men inte krävs, att rensa den haptiska konfigurationen. Detta förmedlas i diagrammet nedan av de två alternativa vägarna som lämnar "Pen: In range; Haptics: Pausad"-tillståndet när pennan går utom räckhåll.
Anmärkning
Servern kan begära att en icke-kontinuerlig vågform ska spelas upp när som helst. I så fall ska pennan spela upp den och sedan återgå till det tillstånd som den tidigare var i.
Anmärkning
Värden ska endast konfigurera kontinuerliga vågformer. Diskreta/icke-kontinuerliga vågformer ska endast utlösas manuellt.
Tangentbordssamling (valfritt)
En valfri funktion för att aktivera rapportering av knappklick i slutet till värden via rapporter från HID-tangentbord.
En kompatibel enhet ska rapportera tre unika tangentbordskombinationer som motsvarar tre distinkta knappåtgärder via en HID Bluetooth-tangentbordsenhet exponerad för värden. Åtgärderna och motsvarande tangentbordskombinationer beskrivs nedan:
| Knappåverkan | Tangentkombination |
|---|---|
| Enkelt klick | WIN+F20 |
| Dubbelklicka | WIN+F19 |
| Tryck och håll | Win+F18 |
Implementering av Bluetooth-knapp
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:
| Bluetooth-knappåtgärd | Nyckelkombination för att rapportera |
|---|---|
| Enkelklicka | WIN+F20 |
| Dubbelklicka | WIN+F19 |
| Tryck och håll | WIN+F18 |
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 plattforms-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
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 (0x01)
A1,02, // Collection (Logical)
85,41, // Report ID (65)
95,01, // Report Count (1)
75,08, // Report Size (8)
15,01, // Logical Minimum (1)
26,FF,00, // Logical Maximum (255)
09,24, // Usage (0x24)
B1,02, // Feature (Data,Var,Abs)
09,24, // Usage (0x24)
91,02, // Output (Data,Var,Abs)
09,23, // Usage (0x23)
B1,02, // Feature (Data,Var,Abs)
09,23, // Usage (0x23)
91,02, // Output (Data,Var,Abs)
15,01, // Logical Minimum (1)
25,12, // Logical Maximum (18)
09,20, // Usage (0x20)
B1,02, // Feature (Data,Var,Abs)
09,21, // Usage (0x21)
91,02, // Output (Data,Var,Abs)
15,00, // Logical Minimum (0)
26,FE,00, // Logical Maximum (254)
66,01,10, // Unit (SI Linear)
55,FD, // Unit Exponent (253)
35,00, // Physical Minimum (0)
46,EC,09, // Physical Maximum (2540)
09,28, // Usage (0x28)
91,02, // Output (Data,Var,Abs)
75,10, // Report Size (16)
26,D0,07, // Logical Maximum (2000)
46,D0,07, // Physical Maximum (2000)
09,25, // Usage (0x25)
91,02, // Output (Data,Var,Abs)
09,25, // Usage (0x25)
B1,02, // Feature (Data,Var,Abs)
45,00, // Physical Maximum (0)
85,42, // Report ID (66)
75,20, // Report Size (32)
17,42,00,0D,00, // Logical Minimum (852034)
27,42,00,0D,00, // Logical Maximum (852034)
09,22, // Usage (0x22)
B1,02, // Feature (Data,Var,Abs)
09,11, // Usage (0x11)
A1,02, // Collection (Logical)
05,0A, // Usage Page (Ordinal)
75,10, // Report Size (16)
95,10, // Report Count (16)
15,01, // Logical Minimum (1)
27,FF,FF,00,00, // Logical Maximum (65535)
19,03, // Usage Minimum (0x03)
29,12, // Usage Maximum (0x12)
B1,02, // Feature (Data,Var,Abs)
C0, // End Collection ()
05,0E, // Usage Page (Haptics)
09,10, // Usage (0x10)
A1,02, // Collection (Logical)
05,0A, // Usage Page (Ordinal)
16,03,10, // Logical Minimum (4099)
26,FF,2F, // Logical Maximum (12287)
19,03, // Usage Minimum (0x03)
29,12, // Usage Maximum (0x12)
B1,02, // Feature (Data,Var,Abs)
C0, // End Collection ()
C0, // End Collection ()
C0 // End Collection ()