Guía de implementación del lápiz háptico
Este documento detalla la implementación del protocolo de un lápiz háptico que se conecta a un host de Windows 11 compatible. No incluye instrucciones sobre las restricciones mecánicas y eléctricas o la selección de componentes para generar la respuesta háptica dentro del transductor del lápiz. Esta guía de implementación es independiente del protocolo de lápiz que usan el transductor del lápiz y el digitalizador del lápiz, no obstante, una implementación puede decidir usar un protocolo de lápiz con una capacidad de enlace ascendente que le permite al digitalizador del lápiz proporcionar parámetros adicionales al transductor del lápiz para modular la respuesta háptica.
Clase de dispositivo
El lápiz háptico es una extensión de la clase lápiz háptico de Windows. Esta guía de implementación es parte de la Guía de implementación de lápices y se centra en la implementación de tecnología háptica dentro del transductor del lápiz, por tanto, los lápices hápticos deben cumplir los requisitos de la Guía de implementación de lápiz así como los de este tema.
Conectividad de Device Bus
El Lápiz háptico usará los controladores de bandeja de entrada proporcionados por Microsoft para conectarse a un host de Windows mediante HID a través de Bluetooth.
Implementación del protocolo de lápiz háptico
Se requiere una buena comprensión del protocolo de HID para poder comprender la información que se presenta aquí. Consulte los siguientes recursos para obtener información sobre el protocolo de HID:
Windows incluye un controlador de clase HID y el controlador de miniporte HID habilitado para BLUETOOTH HID correspondiente, por lo tanto, no hace falta ningún controlador de minipuerto de terceros. El firmware del dispositivo de lápiz háptico solo necesita informar sobre los usos mostrados en este tema. Windows usará el firmware y sus propios controladores de HID para habilitar el dispositivo y proporcionar acceso a las aplicaciones de Windows al dispositivo.
Se proporciona un descriptor de ejemplo en la sección descriptores de informes de ejemplo de abajo.
Colección HID de nivel superior necesaria
Un dispositivo de lápiz háptico debe usar el protocolo HID en un sistema de Windows 10 de forma que el dispositivo proporcione una colección de nivel superior que se muestre como digitalizador/lápiz óptico (página 0x0D, Uso 0x20).
Informe de entrada del digitalizador de lápiz
La colección del digitalizador de lápiz debe notificar el identificador del lápiz que consta del número de serie del transductor y el identificador del proveedor del transductor en los informes de entrada notificados al SO. El mismo identificador de lápiz debe notificarse a través de la colección de lápiz. Esto permite al SO correlacionar la entrada del lápiz generada por el digitalizador al el lápiz. Puede obtener más información sobre la guía de implementación del lápiz, consulte: Implementación del protocolo de lápiz.
Número de serie del transductor
El número de serie del transductor es un identificador persistente único para el transductor utilizado en el accesorio del lápiz que se comunica con el digitalizador de lápiz. Es necesario que sea de 32 bits y está definido por el proveedor o la entidad identificada por el identificador del proveedor del transductor. En circunstancias en las que el número de serie del transductor es desconocido para el digitalizador, ya sea porque el accesorio del lápiz no admite la transmisión de este valor o que la transmisión no se ha recibido en su totalidad, el digitalizador informará 0 al host. El host no admite la posición nula.
Número de serie del transductor: parte 2
Número de serie del transductor: la parte 2 permite especificar más de 32 bits como parte del identificador persistente único para el transductor utilizado en un accesorio de lápiz. En circunstancias en las que el número de serie del transductor – parte 2 es desconocido para el digitalizador, ya sea porque el accesorio del lápiz no admite la transmisión de este valor o que la transmisión no se ha recibido en su totalidad, el digitalizador informará 0 al host. El host no admite la posición nula.
| Página | ID | Notas |
|---|---|---|
| 0xD | 0x5B | Obligatorio para las características dependientes de la identificación de lápiz única (consulte a continuación) |
| 0xD | 0x6E | Extensión opcional del número de serie por 32 bits adicionales |
ID del proveedor del transductor
El ID del proveedor del transductor es un campo para comunicar al fabricante del transductor usado en el accesorio del lápiz que se comunica con el digitalizador de lápiz. Esto debe ser un ID de proveedor de 2 bytes que la USB-IF asigna, ya sea del fabricante o del IHV/OEM que autoriza el uso del ID de su proveedor para este propósito.
| Página | ID | Notas |
|---|---|---|
| 0xD | 0x91 | Obligatorio para las características dependientes de la identificación de lápiz única (consulte a continuación) |
Características dependientes de la identificación de lápiz única
Informar sobre el PenID es obligatorio para habilitar escenarios como la háptica del lápiz (necesaria para las características hápticas en esta guía).
También es obligatorio para escenarios que usan varios lápices para la entrada manuscrita. Por ejemplo:
- La aplicación de pizarra de Windows soporta el uso de varios lápices en los que a cada lápiz se le puede asignar una herramienta determinada de entrada manuscrita.
- En general, las aplicaciones que quieran asignar atributos o comportamientos a diferentes lápices físicos, aunque el digitalizador solo soporte un lápiz en pantalla en el momento
- Aplicaciones que quieran realizar un seguimiento de varios lápices simultáneos en digitalizadores compatibles
Informe de salida háptica
Si un dispositivo de lápiz admite realimentación háptica, puede permitir que el sistema y las aplicaciones lo aprovechen incluyendo una recopilación de realimentación háptica (página 0x0E, uso 0x01) dentro del TLC del lápiz. Para obtener más información sobre cómo la especificación HID admite realimentación háptica, consulte la página Háptica ratificación de la especificación hid.
El host utiliza los siguientes usos en un informe de salida (a través de la recopilación de realimentación háptica) para permitir que el host emita eventos de realimentación háptica en el dispositivo de lápiz háptico. Si un dispositivo decide exponer una recopilación de realimentación háptica, algunos usos son obligatorios para permitir que se admita la información háptica iniciada por el host.
| Miembro | Descripción | Página | ID | Obligatorio/Opcional |
|---|---|---|---|---|
| Lista de formas de onda | Lista ordenada de formas de onda hápticas admitidas por el dispositivo | 0x0E | 0x10 | Mandatory |
| Lista de duración | Lista ordenada de duraciones para las formas de onda en la lista de formas de onda | 0x0E | 0x11 | Mandatory |
| Desencadenador automático | Forma de onda que se activa automáticamente en la discreción del dispositivo | 0x0E | 0x20 | Mandatory |
| Control asociado del desencadenador automático | Uso de HID del control asociado a realimentación háptica | 0x0E | 0x22 | Mandatory |
| Intensidad | Salida: intensidad de la forma de onda del desencadenador manual en porcentaje | 0x0E | 0x23 | Opcionales |
| Número de repeticiones | Salida: número de veces que se reproduce la forma de onda del desencadenador manual después de la reproducción inicial | 0x0E | 0x24 | Opcionales |
| Período de reintentos de desencadenamiento | Salida: duración del tiempo de espera antes de volver a desencadenar el desencadenador manual al repetir | 0x0E | 0x25 | Opcionales |
| Tiempo de corte de forma de onda | Tiempo máximo que una forma de onda de desencadenador manual puede reproducirse antes de cortarse | 0x0E | 0x28 | Opcionales |
Lista de formas de onda
El uso de la lista de formas de onda muestra una colección de los usos HID de las formas de onda admitidas, ordenadas con ordinales. Las formas de onda de hápticas predefinidas se definen en la especificación HID. En el caso de los dispositivos hápticos de lápiz, estas formas de onda pueden clasificarse como dos segmentos correspondientes a distintos escenarios:
- WAVEFORM_*CONTINOUS: realimentación basada en la entrada de lápiz para simular varias texturas cuando el usuario está insertando activamente con diferentes herramientas, como lápiz, etc.
- WAVEFORM_*: realimentación discreta y no continua basadas en la interacción para cuando un usuario haga alguna tarea controlada por entrada, como mantener el puntero sobre un botón, hacer clic en un botón deshabilitado y un reconocimiento correcto de formas de entrada de lápiz.
A continuación se muestra la lista completa de formas de onda admitidas para dispositivos hápticos de lápiz:
| Forma de onda | Descripción | Página | ID | Obligatorio/Opcional |
|---|---|---|---|---|
| WAVEFORM_NONE | No operativo. No debería afectar al estado de reproducción de las formas de onda en curso | 0x0E | 0x1001 | Mandatory |
| WAVEFORM_STOP | Detiene la reproducción de formas de onda en curso | 0x0E | 0x1002 | Mandatory |
| WAVEFORM_CLICK | Crea una breve realimentación de "clic". Reserva predeterminada cuando la forma de onda de realimentación de interacción seleccionada por la aplicación no es compatible con el lápiz háptico | 0x0E | 0x1003 | Mandatory |
| WAVEFORM_INKCONTINUOUS | Simula la sensación de la entrada manuscrita con un lápiz de punta de bola físico. Reserva predeterminada cuando un lápiz háptico no admite una forma de onda de entrada manuscrita | 0x0E | 0x100B | Mandatory |
| WAVEFORM_SUCCESS | Señal háptica fuerte que avisa al usuario de que una acción se ha realizado correctamente | 0x0E | 0x1009 | Opcionales |
| WAVEFORM_ERROR | Señal háptica fuerte que avisa al usuario que ha producido un error o se ha producido un error | 0x0E | 0x100a | Opcionales |
| WAVEFORM_HOVER | Señal háptica cuando el usuario mantiene el puntero sobre un elemento interactivo de la interfaz de usuario con un lápiz háptico | 0x0E | 0x1008 | Opcionales |
| WAVEFORM_PRESS | Señal háptica para cuando un usuario presiona un elemento interactivo de la interfaz de usuario en una acción incremental (consulte Soltar) | 0x0E | 0x1006 | Opcionales |
| WAVEFORM_RELEASE | Señal háptica para cuando un usuario suelta un elemento interactivo de la interfaz de usuario en una acción incremental (consulte Presionar) | 0x0E | 0x1007 | Opcionales |
| WAVEFORM_PENCILCONTINUOUS | Señal háptica continua cuando el usuario selecciona el lápiz como herramienta de entrada manuscrita | 0x0E | 0x100C | Opcionales |
| WAVEFORM_MARKERCONTINUOUS | Señal háptica continua cuando el usuario selecciona el marcador como herramienta de entrada manuscrita | 0x0E | 0x100D | Opcionales |
| WAVEFORM_CHISELMARKERCONTINUOUS | Señal háptica continua cuando el usuario selecciona el marcador o el resaltador de cincel como herramienta de entrada manuscrita | 0x0E | 0x100E | Opcionales |
| WAVEFORM_BRUSHCONTINUOUS | Señal háptica continua cuando el usuario selecciona el pincel como herramienta de entrada manuscrita | 0x0E | 0x100F | Opcionales |
| WAVEFORM_ERASERCONTINUOUS | Señal háptica continua cuando el usuario selecciona el borrador como herramienta de entrada manuscrita | 0x0E | 0x1010 | Opcionales |
| WAVEFORM_SPARKLECONTINUOUS | Señal háptica continua para herramientas de entrada manuscrita especiales, como un pincel de varios colores | 0x0E | 0x1011 | Opcionales |
Nota
Aunque no es necesario, también se recomienda implementar las otras formas de onda enumeradas para proporcionar una experiencia de usuario más completa. En concreto, WAVEFORM_PRESS y WAVEFORM_RELEASE se recomiendan encarecidamente, ya que proporcionan realimentación de interacción valiosa.
Tanto WAVEFORM_NONE como WAVEFORM_STOP son necesarios para todos los dispositivos hápticos compatibles con HID. Los ordinales 1 y 2 se establecen implícitamente en WAVEFORM_NONE y WAVEFORM_STOP. No es necesario declararlos en la lista de formas de onda o en la lista de duración. La lista de formas de onda declara las formas de onda admitidas por el mínimo y el máximo físico de cada ordinal de la lista.
Lista de duración
El uso de la lista de duración muestra una recopilación de las duraciones de las formas de onda admitidas en la lista de forma de onda, ordenadas con ordinales. El milisegundo es la unidad para la duración de la forma de onda y esta debe ser un valor positivo distinto de cero para cualquier forma de onda no continua. Si una forma de onda es continua (se reproducirá hasta que el host la detenga o se supere el tiempo límite de forma de onda), su duración se define como cero.
Se presupone que WAVEFORM_NONE y WAVEFORM_STOP tienen una duración de cero. No es necesario declararlos en la lista de duración.
Intensidad
El uso de intensidad representa el porcentaje de intensidad máxima que se aplicará a una forma de onda. Este valor debe estar entre 0 y 100 %. El 100 % indica que el dispositivo desencadenará las formas de onda con su máxima fuerza y el 0 % indica que el transductor háptico está deshabilitado.
Número de repeticiones
El uso de recuento de repeticiones muestra el número de veces que una forma de onda se repite. Un recuento de repeticiones con valor cero indica que la forma de onda del desencadenador manual solo debe reproducirse una vez (sin repetición). Si se ha superado el tiempo límite de forma de onda, se espera que se omitan las repeticiones incompletas.
Período de reintentos de desencadenamiento
El uso del período de reintentos de desencadenamiento muestra la cantidad de tiempo que el dispositivo debe esperar antes de repetir una forma de onda del desencadenador manual en un informe de salida, según el valor especificado por el recuento de repeticiones. El milisegundo es la unidad de este valor. Si el período de reintentos de desencadenamiento es menor que la duración de la forma de onda que se reproduce, la forma de onda debe detenerse y reiniciarse en el período de tiempo indicado por el período de reintento de desencadenamiento.
Tiempo de corte de forma de onda
El uso del tiempo de corte de forma de onda muestra el tiempo máximo que el dispositivo permitirá repetir una forma de onda de desencadenador manual antes de finalizar la reproducción. Es un valor constante para el dispositivo e incluye las formas de onda continuas sin duraciones establecidas y las formas de onda con duraciones discretas que se establecen para repetirse muchas veces. El milisegundo es la unidad de este valor.
Informe de salida háptica
El host utiliza los siguientes usos en un informe de salida para emitir eventos de realimentación háptica en el dispositivo de lápiz háptico. Algunos usos son obligatorios para la compatibilidad con la implementación del host de Windows.
| Miembro | Descripción | Página | ID | Obligatorio/Opcional |
|---|---|---|---|---|
| Desencadenador manual | Forma de onda que se activar como comando explícito desde el host | 0x0E | 0x21 | Mandatory |
| Intensidad | Intensidad de la forma de onda del desencadenador manual en porcentaje | 0x0E | 0x23 | Mandatory |
| Número de repeticiones | Número de veces que se reproduce la forma de onda del desencadenador manual después de la reproducción inicial | 0x0E | 0x24 | Opcionales |
| Período de reintentos de desencadenamiento | Duración del tiempo de espera antes de volver a desencadenar el desencadenador manual al repetir | 0x0E | 0x25 | Opcionales |
Desencadenador manual
El uso del desencadenador manual muestra un uso de forma de onda admitido de la lista de formas de onda que el host ha solicitado que lo reproduzca. Cuando se envía un informe de salida que contiene un desencadenador manual distinto a WAVEFORM_NONE al dispositivo, debería empezar a reproducir inmediatamente la forma de onda especificada con las propiedades adicionales incluidas en el informe de salida (intensidad, recuento de repeticiones y período de reintento de desencadenamiento). Cuando un informe de salida contiene un desencadenador manual de WAVEFORM_STOP, se debe detener cualquier reproducción de forma de onda en curso.
Para usos de intensidad, recuento de repeticiones y períodos de reintento de desencadenamiento, consulte la sección anterior con respecto al informe de características de salida.
Inicio y detención de la háptica
El siguiente diagrama de flujo muestra cuándo se deben configurar, borrar, iniciar y detener las señales hápticas del lápiz.
Los distintos estados hápticos que se describen a continuación son:
- En reproducción: el lápiz está reproduciendo activamente la forma de onda háptica
- En pausa: el lápiz está configurado con una forma de onda pero no la reproduce activamente
- Detenido: el lápiz no está configurado con una forma de onda y no reproduce nada activamente
Para el estado del lápiz con respecto al digitalizador, consulte Estados del lápiz de Windows.
Nota:
Cuando el lápiz sale del intervalo, se recomienda, pero no es necesario, para borrar la configuración háptica. Esto se transmite en el diagrama siguiente por las dos rutas alternativas que salen del "Lápiz: En rango; Hápticos: Estado pausado" cuando el lápiz sale del intervalo.
Nota:
El host puede solicitar que se reproduzca una forma de onda no continua en cualquier momento. En ese caso, el lápiz debe reproducirlo y volver a su estado anterior.
Nota:
El host solo debería configurar las formas de onda continuas. Las formas de onda discretas o no continuas solo se desencadenarán manualmente.
Colección del teclado (opcional)
Una característica opcional para habilitar los informes de clics del botón final al host a través de informes de teclado HID.
Un dispositivo compatible notificará 3 combinaciones de teclado distintas correspondientes a 3 acciones de botón distintas a través de un dispositivo de teclado Bluetooth HID expuesto al host. A continuación se describen las acciones y las combinaciones de teclado correspondientes:
| Acciones del botón | Combinación de teclas |
|---|---|
| Un solo clic | WIN+F20 |
| Doble clic | WIN+F19 |
| Mantener presionado | Win+F18 |
Implementación del botón Bluetooth
Para implementar un botón Bluetooth, el dispositivo notificará 3 combinaciones de teclado distintas correspondientes a 3 acciones de botón distintas a través de un dispositivo de teclado HID Bluetooth LE expuesto al host. A continuación se describen las acciones y las combinaciones de teclado correspondientes:
| Acción del botón Bluetooth | Combinación de teclas para notificaciones |
|---|---|
| Haga un solo clic | WIN+F20 |
| Doble clic | WIN+F19 |
| Pulsar y sostener | WIN+F18 |
Almacenamiento de lápiz
Windows admite notificaciones para dispositivos que incorporan el almacenamiento de lápiz compatible a partir de Windows 10 versión 1903. El mecanismo se basa en que el hardware detecta si el lápiz se quita o se reemplaza y genera un informe de teclado HID correspondiente para un par de combinaciones de teclas. Para indicar un acoplamiento (lápiz reemplazado en el almacenamiento), notifique WIN+CTRL+F20. Para indicar un desacoplamiento (lápiz quitado del almacenamiento), notifique WIN+CTRL+F19. Esto se puede implementar con firmware o con un controlador.
Estos eventos de desacoplamiento y acoplamiento muestran o descartan el menú del área de trabajo de entrada de lápiz de Shell. La versión de Office 2004 también reacciona a estos eventos mediante una API de plataforma que permite a cualquier desarrollador ampliar su aplicación para conocer los eventos de almacenamiento a partir de Windows 10. No hay compatibilidad para consultar si el lápiz está presente en el acoplamiento, las aplicaciones solo reciben notificaciones de eventos de eliminación y devolución si están en primer plano.
Descriptor de informe de ejemplo
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 ()