Guida all'implementazione della penna aptica
Questo documento illustra in dettaglio l'implementazione del protocollo per un dispositivo Penna aptico che si connette a un host Windows 11 compatibile. Ciò non include indicazioni sui vincoli meccanici, sui vincoli elettrici o sulla selezione dei componenti per generare la risposta aptica all'interno del trasduttore della penna. Questa guida all'implementazione è indipendente dal protocollo penna usato tra il trasducente penna e il digitalizzatore penna, tuttavia un'implementazione può scegliere di usare un protocollo penna con una funzionalità di uplink che consente al digitalizzatore della penna di fornire parametri aggiuntivi al trasducente della penna ai fini della modulare risposta aptica.
Classe Device
Penna aptico è un'estensione della classe Pen Device in Windows. Questa guida all'implementazione aggiunge alla Guida all'implementazione della penna e si concentra sull'implementazione di aptici all'interno del trasduttore penna, quindi le penne aptico devono soddisfare i requisiti della Guida all'implementazione della penna oltre a quelli contenuti qui.
Connessione ivity del bus di dispositivo
La penna aptico userà i driver posta in arrivo forniti da Microsoft per connettersi a un host Windows tramite HID tramite Bluetooth.
Implementazione del protocollo penna aptico
Per comprendere le informazioni presentate qui, è necessaria una buona comprensione del protocollo HID. Per informazioni sul protocollo HID, vedere le risorse seguenti:
- Definizione della classe di dispositivo per dispositivi di interfaccia umana (HID)
- Tabelle di utilizzo HID
Windows include un driver di classe HID e il driver miniport abilitato per HID Bluetooth corrispondente, pertanto non è necessario alcun driver miniport di terze parti. Il firmware del dispositivo penna aptico deve solo segnalare gli utilizzi descritti in questo argomento. Windows userà il firmware e i relativi driver HID per abilitare il dispositivo e concedere alle applicazioni Windows l'accesso al dispositivo.
Un descrittore di esempio viene fornito nella sezione Descrittori di report di esempio seguente.
Raccolta HID di primo livello richiesta
Un dispositivo Penna aptico deve usare il protocollo HID in un sistema Windows 10 in modo che il dispositivo fornisca una raccolta di primo livello visualizzata come digitalizzatore/stilo (Page 0x0D, Usage 0x20).
Report di input del digitalizzatore penna
La raccolta del digitalizzatore penna deve segnalare l'identificatore dello stilo costituito dal numero di serie del trasducente e dall'ID fornitore del trasducente nei report di input segnalati al sistema operativo. Lo stesso identificatore dello stilo deve essere segnalato tramite la raccolta di stilo. Ciò consente al sistema operativo di correlare l'input della penna generato dal digitalizzatore allo stilo. I dettagli sulla guida all'implementazione della penna sono disponibili qui: Implementazione del protocollo penna.
Numero di serie trasducente
Il numero di serie del trasducente è un identificatore permanente univoco per il trasduttorio utilizzato nell'accessorio penna che comunica con il digitalizzatore penna. Questa operazione deve essere a 32 bit ed è definita dal fornitore o dall'entità identificata dall'ID fornitore del trasducente. Nei casi in cui il numero di serie del trasducente è sconosciuto al digitalizzatore perché l'accessorio penna non supporta la trasmissione di questo valore o che la trasmissione non è stata ricevuta completamente, il digitalizzatore deve segnalare 0 all'host. La posizione Null non è supportata dall'host.
Numero di serie trasducente - Parte 2
Numero di serie trasducente: la parte 2 consente di specificare altri 32 bit come parte dell'identificatore permanente univoco per il trasducente utilizzato in un accessorio penna. Nei casi in cui il numero di serie trasducente – Parte 2 è sconosciuto al digitalizzatore perché l'accessorio penna non supporta la trasmissione di questo valore o che la trasmissione non è stata ricevuta completamente, il digitalizzatore deve segnalare 0 all'host. La posizione Null non è supportata dall'host.
| Pagina | ID | Note |
|---|---|---|
| 0xD | 0x5B | Obbligatorio per le funzionalità dipendenti dall'identificazione univoca della penna (vedere di seguito) |
| 0xD | 0x6E | Estensione facoltativa del numero di serie in base a 32 bit aggiuntivi |
ID fornitore trasducente
L'ID fornitore trasducente è un campo per comunicare il produttore del trasducente utilizzato nell'accessorio penna che comunica con il digitalizzatore penna. Questo è necessario per essere un ID fornitore assegnato USB-IF a 2 byte sia del produttore che di quello dell'IHV/OEM che autorizza l'uso del relativo ID fornitore USB-IF a questo scopo.
| Pagina | ID | Note |
|---|---|---|
| 0xD | 0x91 | Obbligatorio per le funzionalità dipendenti dall'identificazione univoca della penna (vedere di seguito) |
Caratteristiche dipendenti dall'identificazione univoca della penna
La funzionalità PenID per la creazione di report è obbligatoria per abilitare scenari come gli aptici della penna (necessari per le funzionalità aptico in questa guida).
È anche obbligatorio per gli scenari che usano più penne per l'input penna. Ad esempio:
- L'app lavagna nelle finestre supporta l'uso di più penna in cui è possibile eseguire il mapping di ogni penna a un determinato strumento di input penna
- In generale, le app che vogliono assegnare attributi o comportamenti a penne fisiche diverse, anche se il digitalizzatore può supportare una sola penna sullo schermo al momento
- App che vogliono tenere traccia di più penne simultanee sui digitalizzatori supportati
Report output aptico
Se un dispositivo penna supporta il feedback aptico, può consentire al sistema e alle applicazioni di sfruttarlo includendo una raccolta di feedback aptico (Page 0x0E, Usage 0x01) all'interno del TLC dello stilo. Per ulteriori informazioni sul modo in cui la specifica HID supporta il feedback aptico, consultare la pagina Haptics ratificare la specifica HID.
L'host usa gli utilizzi seguenti in un report di output (tramite la raccolta di feedback aptico) per consentire all'host di inviare eventi di feedback aptico al dispositivo penna aptico. Se un dispositivo sceglie di esporre una raccolta di feedback aptici, alcuni utilizzi sono obbligatori per consentire il supporto del feedback aptico avviato dall'host.
| Membro | Descrizione | Pagina | ID | Obbligatorio/Facoltativo |
|---|---|---|---|---|
| Elenco waveform | Elenco ordinato di forme d'onda aptice supportate dal dispositivo | 0x0E | 0x10 | Obbligatorio |
| Elenco durata | Elenco ordinato di durate per le forme d'onda nell'elenco waveform | 0x0E | 0x11 | Obbligatorio |
| Trigger automatico | Waveform to fire automatically at device's discretion | 0x0E | 0x20 | Obbligatorio |
| Controllo associato al trigger automatico | Utilizzo HID del controllo associato al feedback aptico | 0x0E | 0x22 | Obbligatorio |
| Intensità | Output - Intensità della forma d'onda trigger manuale come percentuale | 0x0E | 0x23 | Facoltativo |
| Ripeti conteggio | Output : numero di volte in cui riprodurre la forma d'onda trigger manuale dopo la riproduzione iniziale | 0x0E | 0x24 | Facoltativo |
| Periodo di ripetizione | Output- Durata dell'attesa prima di riattivare il trigger manuale durante la ripetizione | 0x0E | 0x25 | Facoltativo |
| Waveform Cutoff Time | Max time a Manual Trigger waveform can play before being cut off | 0x0E | 0x28 | Facoltativo |
Elenco waveform
L'utilizzo dell'elenco waveform rappresenta una raccolta di utilizzi HID delle forme d'onda supportate, ordinate usando ordinali. Le forme d'onda aptice predefinite sono definite nella specifica HID. Per i dispositivi aptici penna, queste forme d'onda possono essere classificate come due segmenti che corrispondono a scenari diversi:
- WAVEFORM_*CONTINOUS - Feedback basato sull'input penna per simulare varie trame mentre l'utente esegue attivamente l'input penna con diversi strumenti, ad esempio penna, matita e così via.
- WAVEFORM_* - Feedback discreto e non continuo basato sull'interazione per quando un utente esegue alcune attività guidate dall'input, ad esempio il passaggio del mouse su un pulsante, il clic su un pulsante disabilitato e il riconoscimento corretto della forma input penna.
Di seguito è riportato l'elenco completo delle forme d'onda supportate per i dispositivi aptici della penna:
| Forma d' onda | Descrizione | Pagina | ID | Obbligatorio/Facoltativo |
|---|---|---|---|---|
| WAVEFORM_NONE | No-op. Non dovrebbe influire sullo stato di riproduzione delle forme d'onda in corso | 0x0E | 0x1001 | Obbligatorio |
| WAVEFORM_STOP | Arresta la riproduzione delle forme d'onda in corso | 0x0E | 0x1002 | Obbligatorio |
| WAVEFORM_CLICK | Crea un breve feedback "click". Fallback predefinito quando la forma d'onda del feedback di interazione selezionata dall'app non è supportata dalla penna aptica | 0x0E | 0x1003 | Obbligatorio |
| WAVEFORM_INKCONTINUOUS | Simula la sensazione dell'utilizzo di input penna con una penna a sfera fisica. Fallback predefinito quando una forma d'onda di input penna non è supportata dalla penna aptica | 0x0E | 0x100B | Obbligatorio |
| WAVEFORM_SUCCESS | Segnale aptico forte per avvisare l'utente che un'azione ha avuto esito positivo | 0x0E | 0x1009 | Facoltativo |
| WAVEFORM_ERROR | Segnale aptico forte per avvisare l'utente che un'azione non è riuscita o si è verificato un errore | 0x0E | 0x100A | Facoltativo |
| WAVEFORM_HOVER | Segnale aptico quando l'utente passa il puntatore su un elemento interattivo dell'interfaccia utente con una penna aptica | 0x0E | 0x1008 | Facoltativo |
| WAVEFORM_PRESS | Segnale aptico per quando un utente preme un elemento interattivo dell'interfaccia utente in un'azione incrementale (vedere Release) | 0x0E | 0x1006 | Facoltativo |
| WAVEFORM_RELEA edizione Standard | Segnale aptico per quando un utente rilascia un elemento interattivo dell'interfaccia utente in un'azione incrementale (vedere Press) | 0x0E | 0x1007 | Facoltativo |
| WAVEFORM_PENCILCONTINUOUS | Segnale aptico continuo quando l'utente seleziona la matita come strumento di input penna | 0x0E | 0x100C | Facoltativo |
| WAVEFORM_MARKERCONTINUOUS | Segnale aptico continuo quando l'utente seleziona l'indicatore come strumento di input penna | 0x0E | 0x100D | Facoltativo |
| WAVEFORM_CHI edizione Standard LMARKERCONTINUOUS | Segnale aptico continuo quando l'utente seleziona l'indicatore/evidenziatore di chisele come strumento di input penna | 0x0E | 0x100E | Facoltativo |
| WAVEFORM_BRUSHCONTINUOUS | Segnale aptico continuo quando l'utente seleziona pennello come strumento di input penna | 0x0E | 0x100F | Facoltativo |
| WAVEFORM_ERA edizione Standard RCONTINUOUS | Segnale aptico continuo quando l'utente seleziona gomma come strumento di input penna | 0x0E | 0x1010 | Facoltativo |
| WAVEFORM_SPARKLECONTINUOUS | Segnale aptico continuo per strumenti di inchiostro speciali, ad esempio un pennello multicolore | 0x0E | 0x1011 | Facoltativo |
Nota
Anche se non richiesto, è consigliabile implementare anche le altre forme d'onda enumerate per offrire un'esperienza utente più completa. In particolare, WAVEFORM_PRESS e WAVEFORM_RELEA edizione Standard sono altamente consigliati in quanto forniscono preziose feedback di interazione.
Sia WAVEFORM_NONE che WAVEFORM_STOP sono necessari per tutti i dispositivi aptici conformi a HID. Gli ordinali 1 e 2 vengono impostati in modo implicito su WAVEFORM_NONE e WAVEFORM_STOP. Non devono essere dichiarati nell'elenco waveform o nell'elenco di durata. L'elenco Waveform dichiara le forme d'onda supportate dal valore minimo fisico e massimo di ogni ordinale nell'elenco.
Elenco durata
L'utilizzo dell'elenco di durata rappresenta una raccolta delle durate per le forme d'onda supportate nell'elenco Waveform, ordinate usando ordinali. L'unità per la durata della forma d'onda è di millisecondi e la durata deve essere un valore diverso da zero positivo per qualsiasi forma d'onda non continua. Se una forma d'onda è continua (verrà riprodotta fino a quando non viene interrotta dall'host o viene superato il time cutoff Waveform), la sua durata viene definita come zero.
si presuppone che WAVEFORM_NONE e WAVEFORM_STOP abbiano una durata pari a zero. Non è necessario dichiarare nell'elenco di durata.
Intensità
L'utilizzo dell'intensità rappresenta la percentuale di intensità massima da applicare a una forma d'onda. Questo valore deve variare tra 0 e 100%. Il 100% indica che le forme d'onda verranno attivate dal dispositivo al massimo livello di forza e il 0% indica che il trasducente aptico non è abilitato.
Ripeti conteggio
L'utilizzo del conteggio ripetizioni rappresenta il numero di volte in cui ripetere una forma d'onda. Un conteggio ripetizione pari a zero indica che la forma d'onda trigger manuale deve essere riprodotta una sola volta (nessuna ripetizione). Se è stato superato il time cutoff waveform, è previsto che tutte le ripetizioni incomplete vengano ignorate.
Periodo di ripetizione
L'utilizzo del periodo di ripetizione rappresenta la quantità di tempo di attesa del dispositivo prima di ripetere una forma d'onda trigger manuale in un report di output, in base al valore specificato da Ripeti conteggio. Le unità per questo valore sono millisecondi. Se il periodo retrigger è inferiore alla durata della forma d'onda riprodotta, la forma d'onda deve essere arrestata e riavviata nel periodo di tempo indicato dal periodo di ripetizione.
Waveform Cutoff Time
L'utilizzo di Waveform Cutoff Time rappresenta la quantità massima di tempo che il dispositivo consentirà di ripetere una forma d'onda trigger manuale prima di terminare la riproduzione. Si tratta di un valore costante per il dispositivo e include sia forme d'onda continue senza durate impostate, sia forme d'onda con durate discrete che vengono impostate per ripetere molte volte. Le unità per questo valore sono millisecondi.
Report output aptico
L'host usa i seguenti utilizzi in un report di output per inviare eventi di feedback aptico al dispositivo Penna aptico. Alcuni utilizzi sono Obbligatori per la compatibilità con l'implementazione dell'host Di Windows.
| Membro | Descrizione | Pagina | ID | Obbligatorio/Facoltativo |
|---|---|---|---|---|
| Trigger manuale | Waveform da attivare come comando esplicito dall'host | 0x0E | 0x21 | Obbligatorio |
| Intensità | Intensità della forma d'onda trigger manuale come percentuale | 0x0E | 0x23 | Obbligatorio |
| Ripeti conteggio | Numero di volte in cui riprodurre la forma d'onda trigger manuale dopo la riproduzione iniziale | 0x0E | 0x24 | Facoltativo |
| Periodo di ripetizione | Durata del tempo di attesa prima di ritentare il trigger manuale durante la ripetizione | 0x0E | 0x25 | Facoltativo |
Trigger manuale
L'utilizzo del trigger manuale rappresenta un utilizzo della forma d'onda supportato dall'elenco di forme d'onda che è stato richiesto di essere riprodotto dall'host. Quando un report di output contenente un trigger manuale diverso da WAVEFORM_NONE viene inviato al dispositivo, deve iniziare immediatamente a riprodurre la forma d'onda specificata con le proprietà aggiuntive incluse nel report di output (Intensità, Conteggio ripetizioni, Periodo di ripetizione). Quando un report di output contiene un trigger manuale di WAVEFORM_STOP, è necessario arrestare qualsiasi riproduzione della forma d'onda in corso.
Per l'utilizzo di Intensità, Conteggio ripetizioni e Periodo di ripetizione, vedere la sezione precedente relativa al report delle funzionalità di output.
Avvio e arresto di aptici
Il diagramma di flusso seguente descrive quando i segnali aptici della penna devono essere configurati, cancellati, avviati e arrestati.
I vari stati aptici descritti di seguito sono:
- Riproduzione: la penna sta giocando attivamente la forma d'onda aptica
- Sospesa: la penna è configurata con una forma d'onda, ma non è attivamente in riproduzione
- Arrestato: la penna non è configurata con una forma d'onda e non sta giocando attivamente nulla
Per lo stato della penna rispetto al digitzer, fare riferimento a Stati penna di Windows.
Nota
Quando la penna esce dall'intervallo, è consigliabile, ma non necessaria, per cancellare la configurazione aptico. Questo viene trasmesso nel diagramma seguente dai due percorsi alternativi che escono dalla "Penna: Nell'intervallo; Aptici: stato sospeso quando la penna esce dall'intervallo.
Nota
L'host in qualsiasi momento può richiedere che venga riprodotta una forma d'onda non continua. In tal caso, la penna dovrebbe riprodurla e quindi tornare allo stato in cui si trovava in precedenza.
Nota
L'host deve configurare solo forme d'onda continue. Le forme d'onda discrete/non continue devono essere attivate solo manualmente.
Insieme Keyboard (facoltativo)
Funzionalità facoltativa per abilitare la creazione di report sui clic del pulsante tail-end sull'host tramite i report della tastiera HID.
Un dispositivo compatibile deve segnalare 3 combinazioni di tastiera distinte corrispondenti a 3 azioni distinte del pulsante tramite un dispositivo tastiera Bluetooth HID esposto all'host. Le azioni e le combinazioni di tastiera corrispondenti sono descritte di seguito:
| Azione pulsante | Combinazione di tasti |
|---|---|
| Clic singolo | WIN+F20 |
| Doppio clic | WIN+F19 |
| Tenere premuto | Win+F18 |
Implementazione del pulsante Bluetooth
Per implementare un pulsante Bluetooth tail-end, il dispositivo segnala 3 combinazioni di tastiera distinte corrispondenti a 3 azioni del pulsante distinte tramite un dispositivo tastiera BLUETOOTH LE HID esposto all'host. Le azioni e le combinazioni di tastiera corrispondenti sono descritte di seguito:
| Azione pulsante Bluetooth | Combinazione di tasti da segnalare |
|---|---|
| Fare clic con un solo clic | WIN+F20 |
| Fare doppio clic su | WIN+F19 |
| Pressione | WIN+F18 |
Penna Stowage
A partire da Windows 10, versione 1903, Windows supporta le notifiche per i dispositivi che incorporano stivaggio penna compatibile. Il meccanismo si basa sull'hardware che rileva la penna da rimuovere o sostituire e genera un report della tastiera HID corrispondente per una coppia di combinazioni di tasti. Per segnalare un ancoraggio (penna sostituita in stowage), segnalare WIN+CTRL+F20 e segnalare un scollegamento (penna rimossa dallo stowage), report WIN+CTRL+F19. Questa operazione può essere implementata con firmware o driver.
Questi eventi di scollegamento/ancoraggio visualizzano/ignorano il menu Area di lavoro input penna della shell. A partire da Windows 10, versione 2004 Office reagisce anche a questi eventi usando un'API della piattaforma che consente a qualsiasi sviluppatore di estendere l'applicazione per la consapevolezza degli eventi di stowage. Non è disponibile alcun supporto per eseguire una query se la penna è presente nel dock, le app ricevono una notifica solo di rimozione e restituiscono eventi se sono in primo piano.
Descrittore di report HID di esempio
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 ()