Przewodnik implementacji pióra haptycznego

Ten dokument zawiera szczegółowe informacje na temat implementacji protokołu dla urządzenia haptic Pen łączącego się z zgodnym hostem Windows 11. Nie obejmuje to wskazówek dotyczących ograniczeń mechanicznych, ograniczeń elektrycznych ani wyboru komponentów do generowania odpowiedzi haptycznej w przetworniku pióra. Te wskazówki dotyczące implementacji są niezależne od protokołu pióra używanego między przetwornikiem pióra a cyfryzatorem pióra, jednak implementacja może wybrać użycie protokołu pióra z funkcją łącza w górę, co pozwala cyfryzatorowi pióra przekazać dodatkowe parametry do przetwornika pióra w celu modulacji odpowiedzi haptycznej.

Klasa urządzenia

Haptic Pen to rozszerzenie klasy Pen Device w Windows. Ten przewodnik implementacji uzupełnia przewodnik implementacji pióra i koncentruje się na implementowaniu haptyki w przetworniku pióra, dlatego haptyczne pióra muszą spełniać wymagania określone w przewodniku implementacji pióra oraz zawarte tutaj.

Łączność z magistralą urządzeń

Pióro dotykowe używa wbudowanych sterowników dostarczanych przez Microsoft, aby połączyć się z hostem Windows za pomocą interfejsu HID przez Bluetooth.

Implementacja protokołu haptycznego pióra

Aby zrozumieć przedstawione tutaj informacje, należy dobrze zrozumieć protokół HID. Aby uzyskać informacje o protokole HID, zobacz następujące zasoby:

• Definicja klasy urządzenia dla urządzeń interfejsu człowieka (HID)
• Tabele użycia HID

Windows zawiera sterownik klasy HID i odpowiedni sterownik miniportu z obsługą funkcji Bluetooth HID, dlatego nie ma potrzeby żadnych sterowników mini-portów innych firm. Oprogramowanie układowe pióra haptycznego musi zgłaszać użycia opisane w tym temacie. Windows będzie używać oprogramowania układowego i własnych sterowników HID w celu włączenia urządzenia i udzielenia Windows aplikacjom dostępu do urządzenia.

Przykładowy deskryptor jest udostępniany w poniższej sekcji Deskryptory przykładowych raportów.

Wymagana kolekcja HID najwyższego poziomu

Urządzenie pióro dotykowe powinno używać protokołu HID w systemie Windows 11 w taki sposób, aby urządzenie udostępniało kolekcję najwyższego poziomu, która wygląda jako digitalizator/rysik (Page 0x0D, Usage 0x20).

Raport wejściowy funkcji Pen Digitizer

Kolekcja pen digitizer musi zgłosić identyfikator stylus składający się z numeru seryjnego przetwornika i identyfikatora dostawcy przetwornika w raportach wejściowych zgłoszonych do systemu operacyjnego. Ten sam identyfikator stylus musi być zgłaszany za pośrednictwem kolekcji stylus. Dzięki temu system operacyjny może skorelować dane wejściowe pióra wygenerowane przez digitizatora z rysikami. Szczegółowe informacje na temat przewodnika implementacji protokołu pióra można znaleźć pod tym linkiem: Implementacja protokołu pióra.

Numer seryjny przetwornika

Numer seryjny przetwornika jest unikatowym trwałym identyfikatorem przetwornika używanego w akcesorium do pióra komunikującego się z cyfrowym przetwornikiem. Musi być 32-bitowy i jest definiowany przez dostawcę lub podmiot zidentyfikowany przez identyfikator dostawcy przetwornika. W sytuacjach, gdy numer seryjny przetwornika jest nieznany digitalizerowi, ponieważ akcesorium pióra nie obsługuje przekazywania tej wartości lub transmisja danych nie została w pełni odebrana, digitalizer przesyła 0 do hosta. Pozycja null nie jest obsługiwana przez hosta.

Numer seryjny przetwornika — część 2

Numer seryjny przetwornika — część 2 umożliwia określenie dodatkowych 32-bitowych bitów jako część unikatowego identyfikatora trwałego przetwornika używanego w akcesorium piórowym. W przypadkach, gdy numer seryjny przetwornika – część 2 jest nieznany cyfrowemu przetwornikowi, ponieważ akcesorium pióra nie obsługuje przesyłania tej wartości lub transmisja nie została odebrana w całości, przetwornik przekazuje 0 do hosta. Pozycja null nie jest obsługiwana przez hosta.

Identyfikator dostawcy przetwornika

Identyfikator dostawcy przetwornika jest polem służącym do wskazania producenta przetwornika używanego w akcesorium pióra współpracującym z cyfryzatorem pióra. Jest wymagany 2-bajtowy identyfikator dostawcy USB-IF, przypisany albo producentowi, albo przez dostawcę IHV/OEM, którzy autoryzują użycie swojego identyfikatora dostawcy USB-IF do tego celu.

Funkcje wymagające unikatowej identyfikacji długopisu

Raportowanie PenID jest konieczne, aby umożliwić scenariusze, takie jak funkcje haptyczne pióra (związane z haptycznymi funkcjami w tym przewodniku).

Jest to również obowiązkowe w scenariuszach, które używają wielu piór do pisma odręcznego. Przykład:

• Aplikacja do tablicy na systemie Windows obsługuje użycie wielu piór, gdzie każde pióro można przypisać do określonego narzędzia do pisania.
• Ogólnie rzecz biorąc, aplikacje, które chcą przypisać atrybuty lub zachowania do różnych fizycznych długopisów, mimo że cyfryzator może obsługiwać tylko jeden pióro na ekranie jednocześnie
• Aplikacje, które chcą śledzić wiele równoczesnych rysików na obsługiwanych digitalizatorach

Raport funkcji haptycznej

Jeśli urządzenie długopisowe obsługuje informację zwrotną haptyczną, może umożliwić systemowi i aplikacjom korzystanie z tej funkcji, uwzględniając kolekcję informacji zwrotnych haptycznych (strona 0x0E, Usage 0x01) w stylus TLC. Aby uzyskać więcej informacji na temat sposobu, w jaki specyfikacja HID obsługuje opinie haptyczne, zapoznaj się ze stroną Haptics ratyfikacji specyfikacji HID.

Host używa następujących zastosowań w raporcie GET_FEATURE (za pośrednictwem kolekcji opinii haptycznych) w celu wykonywania zapytań dotyczących możliwości haptycznych urządzenia długopisowego, w szczególności obsługiwanych kształtów fal i czasów trwania. Jeśli urządzenie zdecyduje się uwidocznić kolekcję informacji zwrotnej haptycznej, ten raport funkcji jest obowiązkowy, aby host mógł wykryć, które możliwości mogą być używane podczas inicjowania informacji zwrotnej haptycznej za pośrednictwem właściwego raportu wyjściowego.

Lista kształtów falowych

Użycie listy kształtów falowych reprezentuje kolekcję użycia HID obsługiwanych kształtów falowych uporządkowanych przy użyciu reguł porządkowych. Wstępnie zdefiniowane kształty falowe są określone w specyfikacji HID. W przypadku haptycznych urządzeń piórowych kształt fali może być dzielony na dwa segmenty, które odpowiadają różnym scenariuszom.

• Ciągłe — sprzężenie zwrotne oparte na tuszu do symulowania różnych tekstur, podczas gdy użytkownik aktywnie rysuje różnymi narzędziami, np. piórem, ołówkiem itp.
• Dyskretne — dyskretne, nieciągłe informacje zwrotne oparte na interakcjach, gdy użytkownik wykonuje niektóre zadania oparte na danych wejściowych, takie jak umieszczenie wskaźnika myszy na przycisku, kliknięcie zablokowanego przycisku i pomyślne rozpoznawanie kształtu pisma.

Poniżej znajduje się pełna lista kształtów fal obsługiwanych w przypadku urządzeń haptycznych piórem:

Zarówno None, jak i Zatrzymaj są wymagane dla wszystkich urządzeń zgodnych z protokołem HID. Liczebniki porządkowe 1 i 2 są niejawnie ustawione na Brak i Zatrzymaj. Nie muszą być deklarowane na liście kształtów falowych ani na liście czasu trwania. Lista kształtów falowych i lista czasów trwania deklarują obsługiwane kształty falowe za pośrednictwem zakresu użycia porządkowego (Użycie/Wartość minimalna i maksymalna) oraz wartość zwracaną dla każdej porządkowej, przy użyciu opcji Brak dla zwykłych, które nie są obsługiwane.

Kształty fali naciśnięcia i zwolnienia są opcjonalne, ale jeśli jeden jest obsługiwany, drugi również musi być. To samo dotyczy powodzenia i błędu.

Lista czasu trwania

Użycie listy czasu trwania reprezentuje kolekcję czasów trwania obsługiwanych kształtów falowych na liście Waveform uporządkowane przy użyciu reguł. Jednostka czasu trwania kształtów fali to milisekundy, a czas trwania musi być dodatnią wartością niezerową dla dowolnego nieciągłego kształt fali. Jeśli kształt fali jest ciągły (będzie odtwarzany do momentu, gdy zostanie zatrzymany przez hosta lub przekroczony czas odcięcia fali), to jego czas trwania ustala się na zero.

Zakłada się, że None i Stop mają czas trwania zero. Nie muszą być zadeklarowane na liście czasu trwania.

Raport wyjściowy dotykowy

Gospodarz używa następujących zastosowań w raporcie wyjściowym do generowania zdarzeń haptycznych na urządzeniu Haptic Pen. Niektóre użycia są obowiązkowe w celu zachowania zgodności z implementacją hosta Windows.

Wyzwalacz ręczny

Użycie wyzwalacza ręcznego nie ma bezpośrednio identyfikatora użycia kształtów falowych. Zamiast tego jego wartość to liczba porządkowa w rozszerzonej tabeli fal urządzenia. Porządkowy 1 jest zarezerwowany dla obowiązkowego None (no-op) kształtu fali, porządkowy 2 jest zarezerwowany dla kształtu fali Stop, a porządkowe 3 i wyższe mapują się na wpisy w liście kształtów falowych lub liście czasu trwania urządzenia (zobacz mechanizm Listy kształtów falowych / Listy czasu trwania), gdzie porządkowy 3 odpowiada pierwszemu wpisowi na liście, porządkowy 4 odpowiada drugiemu i tak dalej. Host może wysłać domyślne porządki 1 i 2, a dla porządków 3 i wyższych będzie wysyłać tylko wartości odpowiadające wpisom, które urządzenie zadeklarowało jako obsługiwane.

Gdy raport wyjściowy zawierający wyzwalacz ręczny, którego kolejność odpowiada dyskretnemu kształtowi fali, zostaje wysłany do urządzenia, urządzenie powinno rozpocząć natychmiastowe odtwarzanie określonego kształtu fali z wszelkimi dodatkowymi właściwościami zawartymi w raporcie wyjściowym (intensywność, liczba powtórzeń, okres ponownego wyzwalania). Jeśli ręczny wyzwalacz porządkowy jest rozpoznawany jako ciągły kształt fali, odtwarzanie powinno rozpoczynać się według uznania urządzenia (na przykład, gdy rysik jest w kontakcie z wyświetlaczem).

Gdy raport wyjściowy zawiera wyzwalacz ręczny, którego liczba porządkowa odnosi się do kształtu fali Stop (liczba porządkowa 2), wszelkie trwające odtwarzanie kształtów falowych powinno zostać zatrzymane. Gdy raport wyjściowy zawiera wyzwalacz ręczny, którego numer porządkowy rozpoznawany jest jako obowiązkowy kształt fali None (no-op) (numer 1), urządzenie nie może uruchomić żadnych nowych kształtów fali i nie może zmienić stanu aktualnie odtwarzanego kształtu fali; raport powinien być traktowany jako operacja no-op jeśli chodzi o wyjściowy sygnał haptyczny.

Intensywność

Użycie intensywności reprezentuje wartość procentową maksymalnej intensywności, która ma być stosowana do kształtów fali. Ta wartość powinna się różnić w zakresie od 0 do 100 procent. 100 procent wskazuje, że kształty fal zostaną wyzwolone przez urządzenie przy maksymalnej sile, a 0 procent wskazuje, że transducer haptyczny nie jest włączony.

Liczba powtórzeń

Liczba powtórzeń określa, ile razy należy powtórzyć kształt fali. Liczba powtórzeń zera wskazuje, że kształt fali wyzwalacza ręcznego powinien być odtwarzany tylko raz (bez powtarzania). Jeśli przekroczono czas odcięcia Waveform, oczekuje się, że wszystkie niekompletne powtórzenia będą ignorowane.

Okres ponownego uruchomienia

Użycie okresu ponownego wyzwalania reprezentuje czas, przez jaki urządzenie czeka przed powtórzeniem ręcznie wyzwalanej formy fali w raporcie wyjściowym, zgodnie z wartością określoną przez Liczbę Powtórzeń. Jednostki dla tej wartości to milisekundy. Jeśli okres pobierania jest mniejszy niż czas trwania odtwarzanego kształtu fali, kształt fali powinien zostać zatrzymany i ponownie uruchomiony w okresie wskazanym przez okres pobierania.

Czas odcięcia kształtów falowych

Użycie czasu odcięcia w formacie Waveform reprezentuje maksymalny czas, przez jaki urządzenie zezwoli na powtórzenie ręcznego przebiegu wyzwalacza przed zakończeniem odtwarzania. Jest to stała wartość urządzenia i zawiera zarówno ciągłe kształty fal bez ustawionych czasów trwania, jak i kształty fal z dyskretnymi czasami trwania, które są ustawione tak, aby powtarzały się wiele razy. Jednostki dla tej wartości to milisekundy.

Uruchamianie i zatrzymywanie haptyki

Poniższy schemat blokowy opisuje, kiedy należy skonfigurować, wyczyścić, uruchomić i zatrzymać sygnały haptyczne pióra.

Różne stany haptyczne opisane poniżej to:

• Odtwarzane: Długopis aktywnie odtwarza falę haptyczną
• Wstrzymano: pióro jest skonfigurowane z przebiegiem falowym, ale nie jest on aktywnie odtwarzany
• Zatrzymano: Długopis nie jest skonfigurowany do odtwarzania fali i nie odtwarza nic.

W przypadku stanu pióra w odniesieniu do digitalizatora należy zapoznać się z Stanów pióra w systemie Windows.

Kolekcja klawiatury (opcjonalnie)

Opcjonalna funkcja umożliwiająca przesyłanie raportów kliknięć końcowych przycisków do hosta za pośrednictwem raportów klawiatury HID.

Aby zaimplementować końcowy przycisk Bluetooth, urządzenie będzie zgłaszać 3 odrębne kombinacje klawiatury odpowiadające 3 odrębnym akcjom przycisku za pośrednictwem urządzenia klawiatury HID Bluetooth LE udostępnionego na hoście. Akcje i odpowiednie kombinacje klawiatury zostały opisane poniżej:

Pióro stowage

Począwszy od Windows 10, wersja 1903, Windows obsługuje powiadomienia dla urządzeń zawierających kompatybilne przechowywanie pióra. Mechanizm polega na tym, że sprzęt wykrywa wyciągnięcie lub włożenie pióra i generuje odpowiedni raport klawiaturowy HID dla pary kombinacji skrótów. Aby zasygnalizować dokowanie (pióro umieszczone w schowku), użyj WIN+CTRL+F20, a aby zasygnalizować oddokowanie (pióro usunięte ze schowka), użyj WIN+CTRL+F19. Można to zaimplementować za pomocą oprogramowania układowego lub sterownika.

Te zdarzenia oddokowania/dokowania otwierają/zamykają menu obszaru roboczego pisma cyfrowego powłoki. Począwszy od Windows 10, pakiet Office w wersji 2004 reaguje również na te zdarzenia przy użyciu interfejsu API platform który umożliwia każdemu deweloperowi rozszerzenie aplikacji na potrzeby rozpoznawania zdarzeń stowage. Nie ma mechanizmu sprawdzania, czy pióro jest w doku; aplikacje są powiadamiane tylko o zdarzeniach usunięcia i powrotu pióra, gdy są w pierwszym planie.

Przykładowy deskryptor raportu HID

Poniższy deskryptor obsługuje wszystkie obowiązkowe i opcjonalne użycie. Deklaruje obsługę siedmiu wpisów listy kształtów falowych (z wyłączeniem niejawnych kształtów fali 1 (Brak) i 2 (Stop), w sumie dziewiętnaście kształtów fali), z najdłuższym dyskretnym kształtem fali o długości 50 ms. Kształty fali ciągłej mają czas trwania zero.

Wszystkie zakresy logiczne powinny być aktualizowane w oparciu o obsługę urządzeń. Aby obsługiwać inną liczbę kształtów fal:

• Należy zaktualizować zakres logiczny użycia wyzwalacza ręcznego
• Należy zaktualizować zakresy użycia i liczbę raportów dla listy kształtów falowych i listy czasu trwania

Aby obsługiwać inną maksymalną długość kształtów fali, należy zaktualizować następujące zakresy logiczne:

• Okres pobierania (dane wyjściowe)
• Czas odcięcia kształtów falowych (dane wyjściowe)
• Lista czasu trwania (funkcja)

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

Tematy pokrewne

• Przewodnik implementacji haptyki urządzenia wejściowego