Guia de implementação da caneta tátil
Este documento detalha a implementação do protocolo para um dispositivo com caneta tátil que está se conectando a um host Windows 11 compatível. Não estão incluídas diretrizes sobre restrições mecânicas, restrições elétricas ou seleção de componentes para gerar a resposta tátil dentro do transdutor da caneta. Essa orientação de implementação é independente do protocolo de caneta usado entre o transdutor e o digitalizador de caneta, no entanto, uma implementação pode optar por usar um protocolo de caneta com uma funcionalidade de uplink que permita que o digitalizador de caneta forneça parâmetros adicionais para o transdutor de caneta para fins de modulação da resposta tátil.
Classe de dispositivo
A caneta tátil é uma extensão da classe Caneta dispositivo no Windows. Este guia de implementação complementa o Guia de implementação da caneta e se concentra na implementação de táteis dentro do transdutor de caneta, portanto, as canetas táteis devem atender também aos requisitos no Guia de implementação da caneta, além daqueles contidos aqui.
Conectividade do barramento de dispositivo
A caneta tátil deve usar os drivers de caixa de entrada fornecidos pela Microsoft para se conectar a um host do Windows usando o HID via Bluetooth.
Implementação do protocolo de caneta tátil
É necessária uma boa compreensão do protocolo HID para entender as informações apresentadas aqui. Confira os seguintes recursos para obter informações sobre o protocolo HID:
- Definição da classe de dispositivo para dispositivos de interface humana (HID)
- Tabelas de uso de HID
O Windows inclui um driver de classe HID e um driver de miniporta habilitado para Bluetooth de HID correspondente, portanto, não são necessários drivers de miniporta de terceiros. O firmware do dispositivo com caneta tátil 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 a seguir chamada Descritores de relatório de exemplo.
Necessária uma coleção HID de nível superior
Um dispositivo de caneta tátil deve usar o protocolo HID em um sistema Windows 10 de modo que o dispositivo 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
A coleção de digitalizadores de caneta deve relatar o identificador de caneta composto pelo número de série do transdutor e pela ID do fornecedor do transdutor nos relatórios de entrada relatados ao sistema operacional. O mesmo identificador de caneta deve ser relatado por meio da coleção de caneta. Isso permite que o sistema operacional correlacione, à caneta, a entrada de caneta gerada pelo digitalizador. Detalhes sobre o guia de implementação da caneta podem ser encontrados aqui: Implementação de protocolo 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 está se comunicando com o digitalizador de caneta. Ele precisa 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, 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 íntegra, o digitalizador deve relatar 0 ao host. A posição nula não é suportada pelo host.
Número de série do transdutor – Parte 2
Número de série do transdutor – Parte 2 permite que um adicional de 32 bits seja especificado 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, 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 íntegra, o digitalizador deve relatar 0 ao host. A posição nula não é suportada pelo host.
| ? | ID | Observações |
|---|---|---|
| 0xD | 0x5B | Obrigatório para recursos que dependem da identificação de caneta exclusiva (veja abaixo) |
| 0xD | 0x6E | Extensão opcional do número de série por mais 32 bits |
ID do fornecedor do transdutor
A ID do fornecedor do transdutor é um campo para indicar o fabricante do transdutor usado no acessório da caneta que se comunica com o digitalizador de caneta. Deve ser uma ID de fornecedor atribuída por USB-IF de 2 bytes do fabricante ou da IHV/OEM que autoriza o uso de sua ID de fornecedor USB-IF para essa finalidade.
| ? | ID | Observações |
|---|---|---|
| 0xD | 0x91 | Obrigatório para recursos que dependem da identificação de caneta exclusiva (veja abaixo) |
Recursos dependentes da identificação de caneta exclusiva
É obrigatório informar a PenID para habilitar cenários como táteis de caneta (necessários para recursos táteis neste guia).
É obrigatório também 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, aplicativos que desejam designar atributos ou comportamentos a canetas físicas diferentes, ainda que 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 tátil
Se um dispositivo de caneta der suporte a comentários táteis, ele poderá permitir que o sistema e os aplicativos aproveitem isso com a inclusão de uma coleção de comentários táteis (Página 0x0E, Uso 0x01) no TLC da caneta. Para obter mais informações sobre como a especificação HID dá suporte a comentários táteis, confira a ratificação da página Táteis para a especificação de HID.
O host faz os usos a seguir em um relatório de saída (por meio da coleção de comentários táteis) para permitir que o host emita eventos de comentários táteis ao dispositivo de caneta tátil. Se um dispositivo optar por expor uma coleção de comentários táteis, alguns usos serão obrigatórios para permitir o suporte a comentários táteis iniciados por host.
| Membro | Descrição | ? | ID | Obrigatório/opcional |
|---|---|---|---|---|
| Lista de formas de onda | Lista ordenada de formas de onda táteis com suporte do dispositivo | 0x0E | 0x10 | Obrigatório |
| Lista de durações | Lista ordenada de durações para formas de onda na Lista de formas de onda | 0x0E | 0x11 | Obrigatório |
| Disparador automático | Forma de onda a ser disparada automaticamente a critério do dispositivo | 0x0E | 0x20 | Obrigatório |
| Controle associado ao Disparador automático | Uso de HID do controle associado a comentários táteis | 0x0E | 0x22 | Obrigatório |
| Intensidade | Saída – intensidade da forma de onda do Disparador manual como porcentagem | 0x0E | 0x23 | Opcional |
| Contagem repetida | Saída – número de vezes para reproduzir a forma de onda do Disparador manual após a reprodução inicial | 0x0E | 0x24 | Opcional |
| Tempo até novo disparo | Saída – tempo de espera antes de disparar novamente o Disparador manual ao repetir | 0x0E | 0x25 | Opcional |
| Tempo de corte de formas de onda | Tempo máximo em que uma forma de onda do Disparador manual pode ser reproduzida 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 de HID de formas de onda com suporte, ordenadas usando ordinais. As formas de onda táteis predefinidas são definidas na especificação de HID. Para dispositivos táteis de caneta, essas formas de onda podem ser classificadas como dois segmentos que correspondem a cenários diferentes:
- WAVEFORM_*CONTINOUS – Comentários baseados em tinta para simular várias texturas enquanto o usuário estiver escrevendo ativamente à 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 controladas por entrada, como passar o cursor 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 táteis de caneta é mostrada abaixo:
| Forma de onda | Description | ? | ID | Obrigatório/opcional |
|---|---|---|---|---|
| WAVEFORM_NONE | Não operacional. Não deve afetar o estado da execução das formas de onda em andamento | 0x0E | 0x1001 | Obrigatório |
| WAVEFORM_STOP | Interrompe a reprodução das formas de onda em andamento | 0x0E | 0x1002 | Obrigatório |
| WAVEFORM_CLICK | Cria um breve comentário de "clique". Fallback padrão quando a forma de onda do comentário de interação selecionada pelo aplicativo não tem suporte da caneta tátil | 0x0E | 0x1003 | Obrigatório |
| WAVEFORM_INKCONTINUOUS | Simula a sensação de escrita à tinta com uma caneta esferográfica real. Fallback padrão quando não houver suporte para uma forma de onda de escrita à tinta por caneta tátil | 0x0E | 0x100B | Obrigatório |
| WAVEFORM_SUCCESS | Sinal tátil forte para alertar o usuário que uma ação foi bem-sucedida | 0x0E | 0x1009 | Opcional |
| WAVEFORM_ERROR | Sinal tátil forte para alertar o usuário que uma ação falhou ou que ocorreu um erro | 0x0E | 0x100A | Opcional |
| WAVEFORM_HOVER | Sinal tátil quando o usuário passa uma caneta tátil sobre um elemento interativo da interface do usuário | 0x0E | 0x1008 | Opcional |
| WAVEFORM_PRESS | Sinal tátil para quando um usuário pressiona um elemento interativo de interface do usuário em uma ação incremental (confira Liberar) | 0x0E | 0x1006 | Opcional |
| WAVEFORM_RELEASE | Sinal tátil para quando um usuário libera um elemento interativo de interface do usuário em uma ação incremental (confira Pressionar) | 0x0E | 0x1007 | Opcional |
| WAVEFORM_PENCILCONTINUOUS | Sinal tátil contínuo quando o usuário seleciona o lápis como ferramenta de escrita à tinta | 0x0E | 0x100C | Opcional |
| WAVEFORM_MARKERCONTINUOUS | Sinal tátil contínuo quando o usuário seleciona o marcador como ferramenta de escrita à tinta | 0x0E | 0x100D | Opcional |
| WAVEFORM_CHISELMARKERCONTINUOUS | Sinal tátil contínuo quando o usuário seleciona o marcador/realce de cinzel como ferramenta de escrita à tinta | 0x0E | 0x100E | Opcional |
| WAVEFORM_BRUSHCONTINUOUS | Sinal tátil contínuo quando o usuário seleciona o pincel como ferramenta de escrita à tinta | 0x0E | 0x100F | Opcional |
| WAVEFORM_ERASERCONTINUOUS | Sinal tátil contínuo quando o usuário seleciona a borracha como ferramenta de escrita à tinta | 0x0E | 0x1010 | Opcional |
| WAVEFORM_SPARKLECONTINUOUS | Sinal tátil contínuo para ferramentas à tinta especiais, como um pincel multicolorido | 0x0E | 0x1011 | Opcional |
Observação
Embora não seja necessário, também é recomendável implementar as outras formas de onda enumeradas para fornecer uma experiência de usuário mais completa. Em particular, recomenda-se altamente o uso do WAVEFORM_PRESS e WAVEFORM_RELEASE, pois eles fornecem comentários de interação valiosos.
Tanto o WAVEFORM_NONE quanto o WAVEFORM_STOP são necessários para todos os dispositivos táteis compatíveis com HID. Os Ordinais 1 e 2 são definidos implicitamente como WAVEFORM_NONE e WAVEFORM_STOP. Eles não precisam estar declarados na Lista de formas de onda ou na Lista de durações. A Lista de formas de onda declara formas de onda com suporte pelos físicos mínimo e máximo de cada ordinal na lista.
Lista de durações
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, ordenada usando ordinais. A unidade para a duração de formas de onda é de milissegundos, sendo que 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é ser interrompida pelo host ou o Tempo de corte de formas de onda ser excedido), sua duração será definida como zero.
O WAVEFORM_NONE e o WAVEFORM_STOP têm uma duração igual a zero. Eles não precisam estar 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%. Cem por cento (100%) indica que as formas de onda serão disparadas pelo dispositivo em sua força máxima, e zero por cento (0%) indica que o transdutor tátil não está habilitado.
Contagem repetida
O uso de Contagem de repetição representa o número de vezes a repetir uma forma de onda. Uma Contagem de repetição de zero indica que a forma de onda do Disparador manual deve ser executada uma única vez (sem repetição). Se o Tempo de corte de formas de onda tiver sido excedido, espera-se que todas as repetições incompletas sejam ignoradas.
Tempo até novo disparo
O uso do Tempo até novo disparo representa a quantidade de tempo que o dispositivo deve aguardar antes de repetir uma forma de onda do Disparador manual em um relatório de saída, de acordo com o valor especificado pela Contagem de repetições. As unidades para esse valor são milissegundos. Se o Tempo até novo disparo for menor que a duração da forma de onda que está sendo reproduzida, a forma de onda deverá ser interrompida e reiniciada no período de tempo indicado pelo tempo até novo disparo.
Tempo de corte de formas de onda
O uso do Tempo de corte de formas de onda representa a quantidade máxima de tempo que o dispositivo permitirá que uma forma de onda do Disparador 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 serem repetidas muitas vezes. As unidades para esse valor são milissegundos.
Relatório de saída tátil
O host faz os usos a seguir em um relatório de saída para emitir eventos de comentários táteis para o dispositivo caneta tátil. Alguns usos são obrigatórios para a compatibilidade com a implementação do host do Windows.
| Membro | Descrição | ? | ID | Obrigatório/opcional |
|---|---|---|---|---|
| Gatilho manual | Forma de onda para disparar como comando explícito do host | 0x0E | 0x21 | Obrigatório |
| Intensidade | Intensidade da forma de onda do Gatilho manual como uma porcentagem | 0x0E | 0x23 | Obrigatório |
| Contagem repetida | Número de vezes para reproduzir a forma de onda Gatilho manual após a reprodução inicial | 0x0E | 0x24 | Opcional |
| Tempo até novo disparo | Duração do tempo restante antes de repetir o Gatilho manual quando houver repetição | 0x0E | 0x25 | Opcional |
Gatilho manual
O uso do Gatilho manual representa um uso de forma de onda com suporte da lista de forma de onda que foi solicitada a ser reproduzida 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 a reproduzir imediatamente 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 de forma de onda contínua deve ser interrompida.
Para usos de Intensidade, Contagem de repetição e Período de repetição, confira a seção anterior em relação ao relatório do recurso de saída.
Iniciar e parar táteis
O fluxograma abaixo descreve quando os sinais táteis da caneta devem ser configurados, limpos, iniciados e interrompidos.
Os vários estados táteis descritos abaixo são:
- Executando: a caneta está executando ativamente a forma de onda tátil
- Em pausa: a caneta é configurada com uma forma de onda, mas não a está executando ativamente
- Parado: a caneta não está configurada com uma forma de onda e não está executando nada ativamente
Para o estado da caneta em relação ao digitalizador, confira 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. Isso é transmitido no diagrama abaixo pelos dois caminhos alternativos que saem da "Caneta: No intervalo; Hápticos: estado pausado" quando a caneta sai do alcance.
Observação
A qualquer momento, o host pode solicitar que uma forma de onda não contínua seja reproduzida. Nesse caso, a caneta deve reproduzi-la e, em seguida, retornar ao estado em que estava anteriormente.
Observação
O host só deve configurar formas de onda contínuas. Formas de onda discretas/não contínuas só devem ser disparadas manualmente.
Coleção Teclado (opcional)
Um recurso opcional para habilitar o relatório de cliques de botão final para o host por meio de 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 de HID exposto ao host. As ações e as combinações de teclado correspondentes são descritas abaixo:
| Ação do botão | Combinação de teclas |
|---|---|
| Clique único | WIN+F20 |
| Clique duplo | WIN+F19 |
| Pressionar e segurar | Win+F18 |
Implementação do botão Bluetooth
Para implementar um botão Bluetooth na extremidade traseira, 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 Bluetooth LE de HID exposto ao host. As ações e as combinações de teclado correspondentes são descritas abaixo:
| Ação do botão Bluetooth | Combinação de teclas para relatar |
|---|---|
| Clique uma vez em | WIN+F20 |
| Clicar duas vezes | WIN+F19 |
| Pressionar e segurar | WIN+F18 |
Acondicionamento da caneta
A partir do Windows 10 versão 1903, o Windows dá suporte a notificações para dispositivos que incorporam acondicionamento de caneta compatível. O mecanismo depende do hardware que detecta que a caneta está sendo removida ou guardada e gera um relatório de teclado HID correspondente para um par de combinações de atalho. Para sinalizar o armazenamento (caneta colocada no acondicionamento), relate WIN+CTRL+F20 e para sinalizar a remoção do armazenamento (caneta removida do acondicionamento), relate WIN+CTRL+F19. Isso pode ser implementado com firmware ou driver.
Esses eventos de armazenar/remover do armazenamento trazem/descartam o menu do espaço de trabalho de tinta do Shell. A partir do Windows 10, a versão 2004 do Office também reage a esses eventos usando uma API de plataforma que permite que qualquer desenvolvedor amplie o aplicativo para reconhecimento de eventos de acondicionamento. Não há suporte para consultar se a caneta está presente no armazenamento, os aplicativos só são notificados sobre eventos de remoção e armazenamento se estiverem em primeiro plano.
Descritor de relatório de 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 ()