Руководство по реализации Haptic Pen

В этом документе описана реализация протокола для устройства Haptic Pen, подключающегося к совместимой Windows 11 узлу. Это не включает в себя рекомендации по механическим ограничениям, электрическим ограничениям или по выбору компонентов для обеспечения тактильного отклика в преобразующем модуле пера. Это руководство по реализации не зависит от протокола, используемого между перо-трансдьюсером и дигитайзером пера. Однако реализация может использовать протокол пера с возможностью восходящей связи, что позволяет дигитайзеру пера предоставлять перо-трансдьюсеру дополнительные параметры для целей модуляции тактильного ответа.

Класс устройства

Haptic Pen — это расширение класса Pen Device на Windows. Это руководство по реализации дополняет Руководство по внедрению пера и фокусируется на реализации тактильных функций в трансдьюсере пера, поэтому тактильные перья должны соответствовать требованиям Руководства по внедрению пера в дополнение к тем, которые содержатся здесь.

Подключение устройств к шине

Haptic Pen должен использовать Майкрософт предоставленные драйверы папки "Входящие" для подключения к узлу Windows с помощью HID по Bluetooth.

Реализация протокола Haptic Pen

Для понимания информации, представленной здесь, требуется хорошее понимание протокола HID. Дополнительные сведения о протоколе HID см. в следующих ресурсах:

• Определение класса устройств для устройств с человеческим интерфейсом (HID)
• Таблицы использования HID

Windows включает драйвер класса HID и соответствующий драйвер минипорта с поддержкой HID Bluetooth, поэтому сторонние драйверы минипортов не требуются. Встроенное ПО хаптического устройства с пером должно сообщать только об использовании, описанном в этом разделе. Windows будет использовать встроенное ПО и собственные драйверы HID, чтобы включить устройство и предоставить Windows приложениям доступ к устройству.

Пример дескриптора представлен в разделе "Примеры дескрипторов отчета" ниже.

Требуемая коллекция HID верхнего уровня

Устройство Haptic Pen должно использовать протокол HID в системе Windows 11 таким образом, чтобы оно предоставляло коллекцию верхнего уровня, которая отображается как дигитайзер/перо (Page 0x0D, Usage 0x20).

Отчет о вводе данных цифрового пера

Коллекция дигитизатора пера должна сообщать идентификатор пера, состоящий из серийного номера трансдуктора и идентификатор поставщика преобразовщика в входных отчетах, сообщаемых ОС. Тот же идентификатор стилуса должен передаваться через коллекцию стилусов. Это позволяет ОС сопоставлять входные данные пера, созданные дигитайзером, с пером. Подробные сведения о руководстве по реализации пера см. здесь: руководство по реализации протокола пера.

Серийный номер преобразователя

Серийный номер преобразователя — это уникальный постоянный идентификатор преобразователя, используемый в аксессуаре пера, взаимодействующего с дигитайзером пера. Это необходимо для 32-разрядных и определяется поставщиком или сущностью, определяемой идентификатором поставщика трансдукатора. В случаях, когда серийный номер трансдуктора неизвестен дигитайзеру либо потому, что аксессуар пера не поддерживает передачу этого значения, либо передача не была получена полностью, дигитайзер должен передать 0 хосту. Позиция NULL не поддерживается хостом.

Серийный номер трансдукатора — часть 2

Серийный номер трансдукатора — часть 2 позволяет указать дополнительные 32-разрядные значения в составе уникального постоянного идентификатора преобразователя, используемого в аксессуаре пера. В случаях, когда серийный номер трансдуктора, часть 2, неизвестен дигитайзеру либо потому, что аксессуар пера не поддерживает передачу этого значения, либо потому, что передача не была получена в полном объеме, дигитайзер должен сообщить 0 хосту. Позиция NULL не поддерживается хостом.

Идентификатор поставщика преобразователя

Идентификатор поставщика датчика — это поле для указания производителя датчика, используемого в аксессуаре для цифрового пера, который взаимодействует с дигитайзером пера. Это должно быть 2-байтовым идентификатором поставщика, назначенным USB-IF, либо для производителя, либо для IHV/OEM, который разрешает использование их идентификатора поставщика USB-IF для данной цели.

Функции, зависящие от уникальной идентификации пера

Сообщение PenID является обязательным для включения таких сценариев, как гаптические эффекты пера, необходимые для активации гаптических функций в этом руководстве.

Это также обязательно для сценариев, использующих несколько перьев для оцифровки рукописного текста. Рассмотрим пример.

• Приложение доски на Windows поддерживает несколько использования пера, в которых каждое перо можно сопоставить с определенным инструментом рукописного ввода
• Как правило, приложения, которые хотят назначить атрибуты или поведение различным физическим перам, даже если дигитайзер может поддерживать только одно перо на экране одновременно.
• Приложения, способные отслеживать несколько одновременных стилусов на поддерживаемых дигитайзерах.

Тактильная функция отчёт

Если устройство пера поддерживает тактильную обратную связь, это позволяет системе и приложениям воспользоваться ею, включая коллекцию данных о тактильной обратной связи (страница 0x0E, использование 0x01) в TLC стилуса. Дополнительные сведения о том, как спецификация HID поддерживает тактильную обратную связь, обратитесь к странице Haptics, связанной с ратификацией спецификации HID.

Хост использует следующие использования в отчете GET_FEATURE (с помощью коллекции тактильной обратной связи) для запроса тактильных возможностей устройства пера, конкретно поддерживаемых форм волн и длительностей. Если устройство решит предоставить коллекцию тактильной обратной связи, этот отчет о функциях является обязательным, чтобы хост мог обнаружить возможности, которые он может использовать при инициировании тактильной обратной связи с помощью соответствующего выходного отчета.

Список форм сигналов

Использование списка волновых форм представляет собой коллекцию применений волновых форм HID, упорядоченных по порядковым числам. Предварительно определенные хаптиковые волны определяются в спецификации HID. Для тактильных устройств эти волновые формы можно классифицировать на два сегмента, соответствующие различным сценариям.

• Непрерывный — обратная связь на основе чернил для имитации различных текстур при активном использовании пользователем различных инструментов, таких как ручка, карандаш и т. д.
• Дискретная — дискретная, не непрерывная обратная связь на основе взаимодействия, когда пользователь выполняет определенную задачу на основе входных данных, например наведение указателя мыши на кнопку, нажатие на отключенную кнопку и успешное распознавание форм рукописного ввода.

Ниже приведен полный список форм волн, поддерживаемых для хаптических устройств пера.

Для всех устройств, совместимых с HID, требуются None и Stop. Порядковые номера 1 и 2 неявно задаются как None и Stop. Им не нужно быть объявленными в списке форм сигналов или списке продолжительности. Список форм волн и список длительностей объявляют поддерживаемые формы волн через диапазон порядкового использования (минимум и максимум использования / логический минимум и максимум) и значение, возвращаемое для каждого порядкового номера, используя None для порядковых номеров, которые не поддерживаются.

Формы сигналов нажатия и отпускания являются необязательными, но если одна из них поддерживается, другая тоже должна быть поддержана. То же самое относится к успеху и ошибке.

Список длительности

Использование списка длительности представляет коллекцию продолжительности поддерживаемых волновых форм в списке Waveform, упорядоченных по порядковым номерам. Единица для длительности волны составляет миллисекунда, а длительность должна быть положительным ненулевым значением для любой непрерывной волны. Если волновая форма является непрерывной (будет воспроизводиться, пока не остановлена хостом или не превышено время отсечения волны), то её длительность определяется как ноль.

Считается, что None и Stop имеют нулевую продолжительность. Они не должны быть включены в список длительности.

Отчет о тактильной отдаче

Хост использует следующие способы применения в выходном отчете для отправки событий хаптической обратной связи устройству Haptic Pen. Некоторые применения являются обязательными для совместимости с реализацией Windows host.

Ручной триггер

Использование ручного триггера не несет идентификатор использования волновой формы непосредственно. Вместо этого его значение является порядковым числом в таблице расширенных волн устройства. Порядковый номер 1 зарезервирован для обязательной формы волны без операции, порядковый номер 2 зарезервирован для формы волны «Stop», а порядковые номера 3 и выше сопоставляются с записями в списке волновых форм или списком длительности (см. механизм списка волн и длительности), где порядковый номер 3 соответствует первой записи в списке, порядковый номер 4 соответствует второй, и так далее. Хост может отправлять неявные порядковые номера 1 и 2, а для порядковых номеров 3 и выше он будет отправлять только те значения, которые соответствуют записям, объявленным устройством в качестве поддерживаемых.

Когда выходной отчет, содержащий ручной триггер, порядковый номер которого преобразуется в дискретную форму сигнала, отправляется на устройство, устройство должно немедленно начать воспроизведение указанной формы сигнала с учётом любых дополнительных свойств, включённых в выходной отчет (интенсивность, число повторов, период повторного запуска). Если порядковая ручного триггера преобразуется в непрерывную волнообразную форму, воспроизведение должно начинаться по усмотрению устройства (например, когда определяется, что перо соприкасается с дисплеем).

Если выходной отчет содержит ручной триггер, порядковый номер которого разрешается на волну Стоп (порядковый номер 2), следует остановить любое текущее воспроизведение волны. Если выходной отчет содержит триггер вручную, порядковый номер которого разрешается в обязательный формат волны None (no-op) (порядковый номер 1), устройство не должно запускать новую волновую форму и не должно изменять состояние любой текущей волны; Отчет должен рассматриваться как нет операций в отношении храптовых выходных данных.

Интенсивность

Использование интенсивности представляет процент максимальной интенсивности для применения к волнообразной форме. Это значение должно отличаться от 0 до 100 процентов. 100 процентов указывает, что волновые формы будут активированы устройством в их максимальной силе, и 0 процентов указывает, что хаптиковый преобразователь не включен.

Число повторов

Использование счетчика повторений представляет количество раз повторения формы волны. Число повторов, равное нулю, указывает, что форма волны триггера вручную должна воспроизводиться только один раз (без повтора). Если превышено время отреза волны, ожидается, что все неполные повторы будут игнорироваться.

Период повторного активации

Использование периода повторного запуска представляет собой время ожидания устройства перед повтором сигнала ручного запуска в выходном отчете в соответствии со значением, установленным числом повторений. Единицы для этого значения — миллисекунда. Если период повторного срабатывания меньше длительности воспроизводимой волны, эта волна должна быть остановлена и перезапущена в момент времени, указанный периодом повторного срабатывания.

Время отреза волны

Использование времени отсечения формы волны означает наибольшее время, в течение которого устройство позволяет повторять форму волны ручного триггера до завершения воспроизведения. Это константное значение для устройства и включает как непрерывные волны без заданных длительности, так и волны с дискретными длительностью, которые задаются для повторения много раз. Единицы для этого значения — миллисекунда.

Запуск и остановка виброоткликов

Блок-схема ниже описывает, когда тактильные сигналы пера должны быть настроены, очищены, запущены и остановлены.

Ниже описаны различные тактильные состояния:

• Игра: перо активно играет хаптиковую волновую форму
• Приостановлено: перо настроено с формой сигнала, но не активно воспроизводит её
• Остановлено: перо не настроено с волновой формой и не воспроизводит ничего активно

Сведения о состоянии пера относительно дигитайзера см. в разделе Windows Pen States.

Коллекция клавиатур (необязательно)

Необязательная функция для передачи информации о нажатиях концевой кнопки на хост через отчеты клавиатуры HID.

Чтобы реализовать конечную кнопку Bluetooth, устройство сообщит о 3 уникальных сочетаниях клавиатуры, соответствующих 3 отдельным действиям кнопки, через устройство клавиатуры HID Bluetooth LE, предоставляемое хосту. Ниже описаны действия и соответствующие сочетания клавиатуры:

Хранение пера

Начиная с Windows 10, версии 1903, Windows поддерживает уведомления для устройств, которые оснащены совместимым хранилищем для пера. Механизм основан на оборудовании, которое обнаруживает удаление или замену пера и создает соответствующий отчет клавиатуры HID для пары комбинаций клавиш. Чтобы сигнализировать о вставке пера в хранилище, используйте WIN+CTRL+F20, а чтобы сигнализировать об извлечении пера из хранилища, используйте WIN+CTRL+F19. Это можно реализовать с помощью встроенного ПО или драйвера.

Эти события открытия и закрытия вызывают появление и исчезновение меню рукописного ввода оболочки. Начиная с Windows 10, версия 2004, Office также реагирует на эти события с помощью Платформенного API, который позволяет любому разработчику расширить свое приложение для учета событий загрузки. Отсутствует поддержка запроса на наличие пера в док-станции, приложения уведомляются о событиях удаления и возвращения пера только в том случае, если они находятся на переднем плане.

Пример дескриптора отчета HID

Следующий дескриптор поддерживает все обязательные и необязательные использования. Он объявляет поддержку семнадцати записей списка волн (за исключением неявных волновых форм 1 (Нет) и 2 (Стоп), в общей сложности девятнадцати волновых форм), с самой длинной дискретной волнообразной формой с длительностью 50 мс. Непрерывные волны имеют длительность нуля.

Все логические диапазоны должны обновляться на основе уровня поддержки устройств. Для поддержки другого количества волновых форм:

• Логический диапазон использования ручного триггера должен быть обновлен
• Необходимо обновить диапазоны использования и количество отчетов для списка форм волнительных сигналов и длительности.

Чтобы поддерживать другую максимальную длину волн, необходимо обновить следующие логические диапазоны:

• Период извлечения (выходные данные)
• Время среза формы волны (результирующие данные)
• Список длительности (функция)

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

Связанные разделы

• Руководство по реализации входных устройств Haptics