Guia de implementação da caneta háptica

Este documento detalha a implementação do protocolo para um dispositivo Haptic Pen que se conecta a um host compatível com o Windows 11. Isso não inclui diretrizes sobre restrições mecânicas, restrições elétricas ou seleção de componente para gerar a resposta háptica dentro do transdutor de caneta. Essa orientação de implementação é independente do protocolo de caneta usado entre o transdutor de caneta e o digitalizador de caneta, no entanto, uma implementação pode optar por usar um protocolo de caneta com uma funcionalidade de uplink que permite que o digitalizador de caneta forneça parâmetros adicionais ao transdutor de caneta para fins de modulação de resposta háptica.

Classe de dispositivo

A Caneta Haptic é uma extensão da classe Dispositivo de Caneta no Windows. Este guia de implementação complementa o Guia de Implementação de Caneta e se concentra na implementação de hápticos no transdutor da caneta. Portanto, as canetas hápticas devem atender não apenas aos requisitos do Guia de Implementação de Caneta, mas também aos que estão contidos aqui.

Conectividade do barramento de dispositivo

A Caneta Haptic deve usar os drivers de caixa de entrada fornecidos pela Microsoft para se conectar a um host do Windows usando HID via Bluetooth.

Implementação de protocolo haptic pen

Uma boa compreensão do protocolo HID é necessária para entender as informações apresentadas aqui. Consulte os seguintes recursos para obter informações sobre o protocolo HID:

• Definição de classe de dispositivo para dispositivos de interface humana (HID)
• Tabelas de uso hid

O Windows inclui um driver de classe HID e um driver correspondente de miniporta HID com suporte para Bluetooth, portanto, não há necessidade de drivers de miniporta de terceiros. O firmware de dispositivo de caneta háptica só precisa relatar os usos descritos neste tópico. O Windows usará o firmware e seus próprios drivers HID para habilitar o dispositivo e conceder aos aplicativos do Windows acesso ao dispositivo.

Um descritor de exemplo é fornecido na seção Descritores de Relatório de Exemplo abaixo.

Coleção HID de nível superior necessária

Um dispositivo caneta háptica deve usar o protocolo HID em um sistema Windows 10 de modo que forneça uma coleção de nível superior que apareça como um digitalizador/caneta (Página 0x0D, Uso 0x20).

Relatório de entrada do digitalizador de caneta

O conjunto de digitalizadores de caneta deve informar o identificador de caneta que consiste no número de série do transdutor e na ID do fabricante do transdutor nos relatórios de entrada enviados ao sistema operacional. O mesmo identificador de estilete deve ser relatado através da coleção de estiletes. Isso permite que o sistema operacional correlacione a entrada da caneta gerada pelo digitalizador à caneta. Detalhes sobre o guia de implementação de caneta podem ser encontrados aqui: Protocolo de Implementação de Caneta.

Número de série do transdutor

O Número de Série do Transdutor é um identificador persistente exclusivo para o transdutor usado no acessório de caneta que se comunica com o digitalizador de caneta. Isso é necessário para ser de 32 bits e é definido pelo fornecedor ou pela entidade identificada pela ID do fornecedor do transdutor. Em circunstâncias em que o Número de Série do Transdutor é desconhecido para o digitalizador porque o acessório de caneta não dá suporte à transmissão desse valor ou que a transmissão não foi recebida na íntegra, o digitalizador deve relatar 0 para o host. O host não dá suporte para a posição nula.

Número de série do transdutor – Parte 2

O Número de Série do Transdutor – Parte 2 permite que mais 32 bits sejam especificados como parte do identificador persistente exclusivo para o transdutor usado em um acessório de caneta. Em circunstâncias em que o Número de Série do Transdutor – Parte 2 é desconhecido para o digitalizador porque o acessório de caneta não dá suporte à transmissão desse valor ou que a transmissão não foi recebida na íntegra, o digitalizador deve relatar 0 para o host. O host não dá suporte para a posição nula.

ID do fornecedor do Transducer

O ID do Fornecedor do transdutor é um campo para comunicar o fabricante do transdutor utilizado no acessório de caneta que se comunica com o digitalizador. Isso é necessário para que seja uma ID de fornecedor de 2 bytes atribuída pela USB-IF, seja do fabricante ou da IHV/OEM, autorizando o uso de sua ID de fornecedor USB-IF para essa finalidade.

Recursos dependentes da identificação de caneta exclusiva

O relatório de PenID é obrigatório para habilitar cenários como feedback tátil da caneta (necessário para os recursos táteis descritos neste guia).

Também é obrigatório para cenários que usam várias canetas para escrita à tinta. Por exemplo:

• O aplicativo Whiteboard no Windows dá suporte ao uso de várias canetas em que cada caneta pode ser mapeada para uma determinada ferramenta de escrita à tinta
• Em geral, os aplicativos que desejam atribuir atributos ou comportamentos a canetas físicas diferentes, embora o digitalizador possa dar suporte apenas a uma única caneta na tela no momento
• Aplicativos que desejam rastrear várias canetas simultâneas em digitalizadores com suporte

Relatório de saída háptica

Se um dispositivo de caneta der suporte a feedback háptico, ele poderá permitir que o sistema e os aplicativos tirem proveito dele, incluindo uma coleção de feedback háptico (Página 0x0E, Uso 0x01) dentro do TLC de caneta. Para obter mais informações sobre como a especificação HID dá suporte ao feedback háptico, consulte a ratificação da especificação HID na página Haptics.

O host utiliza as seguintes utilizações em um relatório de saída (por meio da coleção de feedback háptico) para permitir que o host envie eventos de feedback háptico para o dispositivo de caneta háptica. Se um dispositivo optar por expor uma coleção de comentários hápticos, alguns usos serão obrigatórios para permitir que comentários hápticos iniciados pelo host sejam suportados.

Lista de forma de onda

O uso da lista de forma de onda representa uma coleção dos usos HID de formas de onda com suporte, ordenados usando ordinais. Os formatos de onda hápticos predefinidos são definidos na especificação HID. Para dispositivos hápticos de caneta, esses formatos de onda podem ser classificados como dois segmentos que correspondem a cenários diferentes:

• WAVEFORM_*CONTINUOUS – Comentários baseados em tinta para simular várias texturas enquanto o usuário está ativamente aplicando tinta com diferentes ferramentas, como caneta, lápis etc.
• WAVEFORM_* – Comentários discretos e não contínuos baseados em interação para quando um usuário executa algumas tarefas orientadas por entrada, como passar o mouse sobre um botão, clicar em um botão desabilitado e o reconhecimento bem-sucedido da forma de tinta.

A lista completa de formas de onda com suporte para dispositivos hápticos de caneta está abaixo:

Tanto WAVEFORM_NONE quanto WAVEFORM_STOP são necessários para todos os dispositivos hápticos compatíveis com HID. Ordinais 1 e 2 são implicitamente definidos como WAVEFORM_NONE e WAVEFORM_STOP. Eles não precisam ser declarados na Lista de Forma de Onda ou na Lista de Duração. A Lista de Formas de Onda declara formas de onda suportadas com base nos mínimos e máximos físicos de cada ordinal na lista.

Lista de Duração

O uso da Lista de Durações representa uma coleção das durações para as formas de onda com suporte na lista de Formas de Onda, ordenadas usando ordinais. A unidade para a duração da forma de onda é de milissegundos e a duração deve ser um valor positivo diferente de zero para qualquer forma de onda não contínua. Se uma forma de onda for contínua, (será reproduzida até que o host ou o Tempo de Corte da Forma de Onda seja excedido), sua duração será definida como zero.

WAVEFORM_NONE e WAVEFORM_STOP devem ter uma duração igual a zero. Eles não precisam ser declarados na Lista de Duração.

Intensidade

O uso de intensidade representa a porcentagem de intensidade máxima a ser aplicada a uma forma de onda. Esse valor deve variar entre 0 e 100%. 100% indica que as formas de onda serão disparadas pelo dispositivo em sua força máxima e 0% indica que o transdutor háptico não está habilitado.

Contagem repetida

O uso de Contagem de Repetição representa o número de vezes que uma forma de onda é repetida. Uma contagem de repetição de zero indica que a forma de onda acionada manualmente deve ser reproduzida somente uma vez (sem repetição). Se o Tempo de Corte de Forma de Onda tiver sido excedido, espera-se que todas as repetições incompletas sejam ignoradas.

Período de repetição

O uso do Período de Relançamento representa a quantidade de tempo que o dispositivo deve aguardar antes de repetir uma forma de onda de gatilho manual em um relatório de saída, conforme o valor especificado pela Contagem de Repetição. As unidades para esse valor são milissegundos. Se o Período de Repetição for menor que a duração da forma de onda que está sendo reproduzida, a forma de onda deve ser interrompida e reiniciada no momento indicado pelo período de repetição.

Tempo de corte de forma de onda

O uso do Tempo de Corte da Forma de Onda representa o tempo máximo que o dispositivo permitirá que uma forma de onda com gatilho manual seja repetida antes de encerrar a reprodução. Esse é um valor constante para o dispositivo e inclui formas de onda contínuas sem durações definidas e formas de onda com durações discretas que são definidas para repetir muitas vezes. As unidades para esse valor são milissegundos.

Relatório de saída háptica

O host utiliza os seguintes usos em um relatório de saída para emitir eventos de feedback tátil para o dispositivo Haptic Pen. Alguns usos são obrigatórios para compatibilidade com a implementação do host do Windows.

Gatilho Manual

O uso do Gatilho Manual refere-se a uma forma de onda suportada pela lista de formas de onda, que foi solicitada para reprodução pelo host. Quando um relatório de saída que contém um Gatilho Manual diferente de WAVEFORM_NONE é enviado para o dispositivo, ele deve começar imediatamente a reproduzir a forma de onda especificada com as propriedades adicionais incluídas no relatório de saída (Intensidade, Contagem de Repetição, Período de Repetição). Quando um relatório de saída contém um Gatilho Manual de WAVEFORM_STOP, qualquer reprodução contínua de onda deve ser interrompida.

Para as utilizações de Intensidade, Contagem de Repetição e Período de Reativação, consulte a seção anterior no que diz respeito ao relatório de recursos de saída.

Iniciando e parando hápticos

O fluxograma abaixo descreve quando os sinais hápticos da caneta devem ser configurados, limpos, iniciados e interrompidos.

Os vários estados hápticos descritos abaixo são:

• Jogando: A caneta está ativamente jogando a forma de onda háptica
• Pausada: A caneta está configurada com uma forma de onda, mas não está reproduzindo-a ativamente
• Parado: a caneta não está configurada com uma forma de onda e não está reproduzindo ativamente nada

Para o estado da caneta em relação ao digitalizador, consulte "Windows Pen States".

Coleção de teclados (opcional)

Um recurso opcional para habilitar a notificação de cliques no botão final para o host via relatórios de teclado HID.

Um dispositivo compatível deve relatar três combinações de teclado distintas correspondentes a três ações de botão distintas por meio de um dispositivo de teclado Bluetooth HID exposto ao host. As ações e as combinações de teclado correspondentes são descritas abaixo:

Implementação do botão Bluetooth

Para implementar um botão Bluetooth de extremidade final, o dispositivo relatará três combinações de teclado distintas correspondentes a três ações de botão distintas por meio de um dispositivo de teclado HID Bluetooth LE exposto ao host. As ações e as combinações de teclado correspondentes são descritas abaixo:

Armazenamento de Canetas

A partir do Windows 10, versão 1903, o sistema oferece suporte a notificações para dispositivos que incorporam armazenagem de caneta compatível. O mecanismo depende do hardware detectando a caneta sendo removida ou substituída e gerando um relatório de teclado HID correspondente para um par de combinações de atalho. Para sinalizar um armazenamento (caneta colocada no compartimento), sinalize WIN+CTRL+F20 e para sinalizar um retiro (caneta removida do compartimento), sinalize WIN+CTRL+F19. Isso pode ser implementado com firmware ou driver.

Esses eventos de desencaixar/encaixar abrem/descartam o menu da área de trabalho de tinta do Shell. A partir do Windows 10, a partir da versão 2004 do Office também reage a esses eventos usando uma API de plataforma que permite que qualquer desenvolvedor estenda seu aplicativo para reconhecimento de eventos de stowage. Não há suporte para consultar se a caneta está presente no dock, os aplicativos só são notificados de eventos de remoção e de retorno se estiverem em primeiro plano.

Descritor de relatório HID de exemplo

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

Tópicos relacionados

• Guia de implementação de hápticos de dispositivo de entrada