Nota
O acesso a esta página requer autorização. Podes tentar iniciar sessão ou mudar de diretório.
O acesso a esta página requer autorização. Podes tentar mudar de diretório.
Este documento detalha a implementação do protocolo para um dispositivo Haptic Pen que se liga a um host compatível com Windows 11. Isto não inclui orientações sobre restrições mecânicas, restrições elétricas ou seleção de componentes para gerar a resposta háptica dentro do transdutor da caneta. Esta orientação de implementação é agnóstica em relação ao protocolo de caneta usado entre o transdutor de caneta e o digitalizador de canetas, no entanto, uma implementação pode optar por usar um protocolo de caneta com capacidade de ligação ascendente que permite ao digitalizador fornecer parâmetros adicionais ao transdutor para efeitos de modular a resposta háptica.
Classe de dispositivo
Haptic Pen é uma extensão da classe Pen Device no Windows. Este guia de implementação acrescenta ao Guia de Implementação da Caneta e foca-se na implementação da háptica dentro do transdutor da caneta, pelo que as canetas hápticas devem cumprir os requisitos do Guia de Implementação da Caneta além dos aqui contidos.
Conectividade do barramento de dispositivos
A Haptic Pen deve usar os drivers fornecidos pela Microsoft para se ligar a um host Windows através de HID via Bluetooth.
Implementação do Protocolo de Caneta Háptica
É necessária uma boa compreensão do protocolo HID para poder compreender as informações aqui apresentadas. Consulte os seguintes recursos para obter informações sobre o protocolo HID:
O Windows inclui um driver de classe HID e o correspondente driver de miniport HID compatível com Bluetooth, pelo que não há necessidade de drivers de miniport de terceiros. O firmware do dispositivo de caneta háptica só precisa de reportar os usos descritos neste tópico. O Windows usará o firmware e seus próprios drivers HID para habilitar o dispositivo e dar 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 num sistema Windows 10 de modo a que o dispositivo forneça uma coleção de nível superior que apareça como digitalizador/caneta (Página 0x0D, Utilização 0x20).
Relatório de Entrada do Digitalizador de Caneta
A coleção do digitalizador de canetas deve reportar o identificador da caneta que consiste no número de série do transdutor e no ID do Fornecedor do transdutor nos relatórios de entrada reportados ao SO. O mesmo identificador de caneta deve ser comunicado através do conjunto de canetas. Isto permite ao sistema operativo correlacionar a entrada de caneta gerada pelo digitalizador com a caneta. Detalhes relativos ao guia de implementação da caneta podem ser encontrados aqui: Implementação do Protocolo da Caneta.
Número de Série do Transdutor
O Número de Série do Transdutor é um identificador persistente único para o transdutor usado no acessório da caneta que comunica com o digitalizador da caneta. Este deve ser de 32 bits e é definido pelo fornecedor ou entidade identificada pelo ID do fornecedor do transdutor. Em circunstâncias em que o Número de Série do Transdutor é desconhecido para o digitalizador, seja porque o acessório da caneta não suporta a transmissão deste valor ou porque a transmissão não foi recebida na totalidade, o digitalizador deve reportar 0 ao anfitrião. A posição nula não é suportada pelo anfitrião.
Número de Série do Transdutor – Parte 2
Número de Série do Transdutor – Parte 2 permite especificar mais 32 bits como parte do identificador persistente único para o transdutor usado num acessório de caneta. Em circunstâncias em que o Número de Série do Transdutor – Parte 2 é desconhecido para o digitalizador, seja porque o acessório da caneta não suporta a transmissão deste valor ou porque a transmissão não foi recebida na totalidade, o digitalizador deve reportar 0 ao anfitrião. A posição nula não é suportada pelo anfitrião.
| Página | ID | Observações |
|---|---|---|
| 0xD | 0x5B | Obrigatório para características dependentes da identificação única da caneta (ver abaixo) |
| 0xD | 0x6E | Extensão opcional do número de série em mais 32 bits |
ID do Fornecedor do Transdutor
O ID do Fornecedor do Transdutor é um campo para comunicar o fabricante do transdutor usado no acessório da caneta que comunica com o digitalizador da caneta. Deve ser um ID de fornecedor de 2 bytes atribuído pela USB-IF, seja do fabricante ou do IHV/OEM, que autoriza o uso do seu ID de fornecedor USB-IF para este propósito específico.
| Página | ID | Observações |
|---|---|---|
| 0xD | 0x91 | Obrigatório para características dependentes da identificação única da caneta (ver abaixo) |
Características Dependentes da Identificação Única da Caneta
Reportar o PenID é obrigatório para ativar cenários, como a háptica da caneta (necessárias para as funcionalidades hápticas abordadas neste guia).
Também é obrigatório para cenários que usam múltiplas canetas para entintamento. Por exemplo:
- A aplicação Whiteboard no Windows suporta o uso de múltiplas canetas onde cada caneta pode ser mapeada para uma determinada ferramenta de tinta.
- Em geral, aplicações que querem atribuir atributos ou comportamentos a diferentes canetas físicas, mesmo que o digitalizador possa suportar apenas uma caneta no ecrã de cada vez
- Aplicações que querem monitorizar várias canetas em simultâneo em digitalizadores compatíveis
Relatório de Saída Háptica
Se um dispositivo de caneta suportar feedback háptico, ele pode permitir que o sistema e as aplicações o aproveitem ao incluir uma coleção de feedback háptico (Página 0x0E, Utilização 0x01) dentro do TLC da caneta. Para mais informações sobre como a especificação HID suporta feedback háptico, consulte a página de ratificação da Haptics à especificação HID.
O host utiliza as seguintes utilizações num relatório de saída (através da recolha de feedback háptico) para permitir que o host emita eventos de feedback háptico para o dispositivo de caneta háptica. Se um dispositivo optar por expor uma coleção de feedback háptico, alguns usos são obrigatórios para permitir que o feedback háptico iniciado pelo host seja suportado.
| Membro | Description | Página | ID | Obrigatório/Opcional |
|---|---|---|---|---|
| Lista de formas de onda | Lista ordenada de formas de onda hápticas suportadas pelo dispositivo | 0x0E | 0x10 | Mandatory |
| Lista de Duração | Lista ordenada de durações para formas de onda na Lista de Formas de Onda | 0x0E | 0x11 | Mandatory |
| Gatilho automático | A forma de onda disparará automaticamente a critério do dispositivo | 0x0E | 0x20 | Mandatory |
| Controlo Associado ao Gatilho Automático | Utilização HID do controlo associado ao feedback háptico | 0x0E | 0x22 | Mandatory |
| Intensidade | Saída - Intensidade da forma de onda do gatilho manual como percentagem | 0x0E | 0x23 | Opcional |
| Número de repetições | Saída - Número de vezes para executar a forma de onda do gatilho manual após a primeira execução | 0x0E | 0x24 | Opcional |
| Período de regatilho | Resultado - Duração do tempo de espera antes de reativar o Gatilho Manual em caso de repetição. | 0x0E | 0x25 | Opcional |
| Tempo de corte da forma de onda | Tempo máximo que uma forma de onda de gatilho manual pode reproduzir antes de ser cortada | 0x0E | 0x28 | Opcional |
Lista de formas de onda
O uso da Lista de Formas de Onda representa uma coleção dos usos HID das formas de onda suportadas, ordenados por ordinais. As formas de onda hápticas pré-definidas estão definidas na especificação HID. Para dispositivos hápticos com caneta, estas formas de onda podem ser classificadas em dois segmentos que correspondem a diferentes cenários:
- WAVEFORM_*CONTÍNUOS - Retorno baseado em tinta para simular várias texturas enquanto o utilizador está a desenhar ativamente com diferentes ferramentas, como caneta, lápis, etc.
- WAVEFORM_* - Feedback discreto, não contínuo, baseado em interação para quando um utilizador realiza uma tarefa orientada por input, como passar o rato sobre um botão, clicar num botão desativado e reconhecer com sucesso a forma da tinta.
A lista completa de formas de onda suportadas para dispositivos hápticos com caneta está abaixo:
| Forma de onda | Description | Página | ID | Obrigatório/Opcional |
|---|---|---|---|---|
| WAVEFORM_NONE | Não-op. Não deve afetar o estado de jogo das formas de onda em curso | 0x0E | 0x1001 | Mandatory |
| WAVEFORM_STOP | Interrompe a reprodução de formas de onda em curso | 0x0E | 0x1002 | Mandatory |
| WAVEFORM_CLICK | Cria um pequeno feedback de clique. Recurso padrão quando a forma de onda de feedback de interação selecionada pela aplicação não é suportada pela caneta háptica | 0x0E | 0x1003 | Mandatory |
| WAVEFORM_INKCONTINUOUS | Simula a sensação de escrever com uma caneta esferográfica. Fallback predefinido quando uma forma de onda de tinta não é suportada por uma caneta háptica | 0x0E | 0x100B | Mandatory |
| WAVEFORM_SUCCESS | Forte sinal háptico para alertar o usuário de uma ação foi bem-sucedida | 0x0E | 0x1009 | Opcional |
| WAVEFORM_ERROR | Sinal háptico forte para alertar o usuário de que uma ação falhou ou ocorreu um erro | 0x0E | 0x100A | Opcional |
| WAVEFORM_HOVER | Sinal háptico quando o utilizador paira sobre um elemento interativo da interface com uma caneta háptica | 0x0E | 0x1008 | Opcional |
| WAVEFORM_PRESS | Sinal háptico quando um utilizador pressiona um elemento interativo de interface numa ação incremental (ver Release) | 0x0E | 0x1006 | Opcional |
| WAVEFORM_RELEASE | Sinal háptico para quando um utilizador liberta um elemento interativo de UI numa ação incremental (ver Press) | 0x0E | 0x1007 | Opcional |
| WAVEFORM_PENCILCONTINUOUS | Sinal háptico contínuo quando o utilizador seleciona lápis como ferramenta de tinta | 0x0E | 0x100C | Opcional |
| WAVEFORM_MARKERCONTINUOUS | Sinal háptico contínuo quando o utilizador seleciona o marcador como ferramenta de arte-tintagem | 0x0E | 0x100D | Opcional |
| MARCADOR_CINZELONDA_CONTÍNUO | Sinal háptico contínuo quando o utilizador seleciona marcador de cinzel/destaque como ferramenta de marcação | 0x0E | 0x100E | Opcional |
| FORMATO_DE_ONDA_PINCEL_CONTÍNUO | Sinal háptico contínuo quando o utilizador seleciona o pincel como ferramenta de arte-tintagem | 0x0E | 0x100F | Opcional |
| BORRADOR_DE_ONDA_CONTÍNUA | Sinal háptico contínuo ao selecionar a borracha como ferramenta de tinta | 0x0E | 0x1010 | Opcional |
| WAVEFORM_SPARKLECONTINUOUS | Sinal háptico contínuo para ferramentas especiais de tinta, como um pincel multicolorido | 0x0E | 0x1011 | Opcional |
Observação
Embora não seja obrigatório, é incentivado também a implementação das outras formas de onda enumeradas para proporcionar uma experiência de utilizador mais completa. Em particular, WAVEFORM_PRESS e WAVEFORM_RELEASE são altamente recomendados, pois fornecem feedback valioso para a interação.
Tanto WAVEFORM_NONE como WAVEFORM_STOP são necessários para todos os dispositivos hápticos compatíveis com HID. Os ordinais 1 e 2 são implicitamente definidos como WAVEFORM_NONE e WAVEFORM_STOP. Não precisam de ser declarados na Lista de Formas de Onda ou na Lista de Duração. A Lista de Formas de Onda declara as formas de onda suportadas pelo mínimo físico e máximo de cada ordinal na lista.
Lista de Duração
O uso da Lista de Duração representa uma coleção das durações das formas de onda suportadas na lista de Formas de Onda, ordenadas por ordinais. A unidade para a duração da forma de onda é milissegundos, e a duração deve ser um valor positivo não nulo para qualquer forma de onda não contínua. Se uma forma de onda for contínua (reproduzirá até ser interrompida pelo sistema anfitrião ou até que o Tempo de Interrupção da Forma de Onda seja ultrapassado), então a sua duração é definida como zero.
WAVEFORM_NONE e WAVEFORM_STOP assumem-se que têm uma duração zero. Não precisam de ser declarados na Lista de Duração.
Intensidade
A utilização da intensidade representa a percentagem da intensidade máxima aplicada a uma forma de onda. Este valor deve variar entre 0 e 100 por cento. 100 por cento indica que as formas de onda serão ativadas pelo dispositivo na sua força máxima, e 0 por cento indica que o transdutor háptico não está ativado.
Número de repetições
A utilização da Contagem de Repetições representa o número de repetições de uma forma de onda. Uma contagem de repetições de zero indica que a forma de onda do gatilho manual deve ser executada apenas uma vez (sem repetição). Se o Tempo de Corte da Forma de Onda for ultrapassado, espera-se que quaisquer repetições incompletas sejam ignoradas.
Período de regatilho
A utilização do Período de Reativação representa o período de espera que o dispositivo deve cumprir antes de repetir uma forma de onda de gatilho manual num relatório de saída, conforme o valor especificado pela Contagem de Repetição. As unidades para este valor são milissegundos. Se o Período de Retrigger for menor do que a duração da forma de onda que está a ser reproduzida, a forma de onda deve ser interrompida e reiniciada no momento indicado pelo Período de Retrigger.
Tempo de corte da forma de onda
O Tempo de Corte da Forma de Onda representa o tempo máximo em que o dispositivo permitirá repetir uma forma de onda Manual Trigger antes de terminar a reprodução. Este é um valor constante para o dispositivo e inclui tanto formas de onda contínuas sem durações definidas, como formas de onda com durações discretas que são definidas para se repetir muitas vezes. As unidades para este valor são milissegundos.
Relatório de Saída Háptica
O host utiliza as seguintes utilizações num relatório de saída para emitir eventos de feedback háptico ao dispositivo Haptic Pen. Alguns usos são obrigatórios para compatibilidade com a implementação do host do Windows.
| Membro | Description | Página | ID | Obrigatório/Opcional |
|---|---|---|---|---|
| Gatilho manual | Forma de onda para disparar como comando explícito do host | 0x0E | 0x21 | Mandatory |
| Intensidade | Intensidade da forma de onda do gatilho manual em percentagem | 0x0E | 0x23 | Mandatory |
| Número de repetições | Número de vezes para executar a onda Manual Trigger após a reprodução inicial | 0x0E | 0x24 | Opcional |
| Período de regatilho | Duração do tempo de espera antes de disparar novamente o Acionamento Manual ao repetir | 0x0E | 0x25 | Opcional |
Gatilho manual
A utilização do Gatilho Manual representa uma utilização de forma de onda suportada da lista de formas de onda que foi solicitada para ser reproduzida pelo anfitrião. Quando um relatório de saída contendo um Gatilho Manual diferente de WAVEFORM_NONE é enviado para o dispositivo, 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ções, Período de Reativação). Quando um relatório de saída contém um Gatilho Manual de WAVEFORM_STOP, qualquer reprodução contínua da forma de onda deve ser interrompida.
Para usos de Intensidade, Contagem de Repetições e Período de Reativação , consulte a secção anterior relativamente ao relatório de funcionalidades de saída.
Háptica de Arranque e Paragem
O fluxograma abaixo descreve quando os sinais hápticos da caneta devem ser configurados, limpos, iniciados e parados.
Os vários estados hápticos descritos abaixo são:
- A reproduzir: A caneta está a reproduzir ativamente a forma de onda háptica
- Pausada: A caneta está configurada com uma forma de onda, mas não a está a reproduzir ativamente
- Parada: A caneta não está configurada com uma forma de onda e não está a reproduzir nada ativamente
Para o estado da caneta relativamente ao digitalizador, por favor consulte os Estados da Caneta do Windows.
Observação
Quando a caneta sai do alcance, é recomendado, mas não obrigatório, limpar a configuração háptica. Isto é transmitido no diagrama abaixo pelos dois caminhos alternativos que saem do estado "Caneta: Dentro do alcance; Háptica: Pausada" quando a caneta sai do alcance.
Observação
O anfitrião pode, a qualquer momento, solicitar a reprodução de uma forma de onda não contínua. Nesse caso, a caneta deve executá-lo e depois regressar ao seu estado anterior.
Observação
O anfitrião deve configurar apenas formas de onda contínuas. As formas de onda discretas/não contínuas só devem ser acionadas manualmente.
Coleção de Teclados (Opcional)
Uma funcionalidade opcional para permitir o reporte de cliques nos botões finais ao host através de relatórios de teclado HID.
Um dispositivo compatível deverá reportar 3 combinações distintas de teclado correspondentes a 3 ações distintas de botões através de um dispositivo de teclado Bluetooth HID exposto ao anfitrião. As ações e combinações correspondentes de teclado são descritas abaixo:
| Ação de Botão | Combinação de Teclas |
|---|---|
| Clique Único | VITÓRIA+F20 |
| Duplo clique | VITÓRIA+F19 |
| Pressione e Mantenha | Win+F18 |
Implementação do Botão Bluetooth
Para implementar um botão na extremidade final Bluetooth, o dispositivo reportará 3 combinações distintas de teclado correspondentes a 3 ações distintas do botão através de um dispositivo de teclado HID Bluetooth LE exposto ao sistema anfitrião. As ações e combinações correspondentes de teclado são descritas abaixo:
| Ação do Botão Bluetooth | Combinação de Chaves a Reportar |
|---|---|
| Clique único | VITÓRIA+F20 |
| Clique duas vezes em | VITÓRIA+F19 |
| Prima e mantenha pressionado | VITÓRIA+F18 |
Armazenamento de Canetas
A partir do Windows 10, versão 1903, o Windows suporta notificações para dispositivos que incorporam armazenamento de canetas compatível. O mecanismo depende do hardware detetar a caneta a ser removida ou substituída e gerar um relatório de teclado HID correspondente para um par de combinações de atalhos. Para sinalizar um dock (caneta substituída no armazenamento), reportar WIN+CTRL+F20 e para sinalizar um desacoplamento (caneta retirada do armazenamento), reportar WIN+CTRL+F19. Isto pode ser implementado com firmware ou um driver.
Estes eventos de desacoplamento/acoplamento ativam/desativam o menu de trabalho de tinta da Shell. A partir do Windows 10, a versão 2004 do Office também reage a estes eventos utilizando uma API de plataforma que permite a qualquer programador expandir a sua aplicação para dar visibilidade sobre eventos de armazenamento. Não há suporte para questionar se a caneta está presente na doca, as aplicações só são notificadas de eventos de remoção e devolução se estiverem em primeiro plano.
Exemplo de descritor de relatório HID
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 ()