Cunha de teclado HID explicada

O que é uma cunha de teclado?

O termo vem de leitores antigos de porta serial que ficavam literalmente "encaixados" (wedged) entre o teclado e a porta do computador, interceptando o sinal do teclado e injetando os caracteres lidos. Leitores modernos não precisam mais desse encaixe físico. A expressão passou a designar qualquer leitor que apresenta os dados lidos como se tivessem vindo de um teclado, seja qual for o tipo de conexão.

USB HID e emulação de teclado

O USB define uma classe Human Interface Device (HID) específica para teclados, mouses e dispositivos de entrada parecidos. Quando um leitor se enumera no USB como teclado HID, o sistema operacional carrega o driver genérico de teclado que já vem com ele. Não é preciso driver específico do leitor. O firmware converte cada caractere decodificado no código de tecla HID que um teclado físico enviaria, e os relatórios seguem o mesmo mecanismo de transferência por interrupção de qualquer teclado USB.

Como o aplicativo vê a entrada do leitor

Rajada rápida de teclas em vez de digitação humana: o leitor envia a carga inteira como uma sequência rápida de pares keydown/keyup e normalmente termina em menos de um segundo, qualquer que seja o tamanho do código.

Sem eventos de mouse: leitores em modo teclado HID nunca geram eventos de ponteiro, clique ou foco. Se o campo não estiver com foco no momento da leitura, a entrada se perde ou vai para o elemento que tiver o foco.

Sem eventos de colar: como os dados chegam como pressionamentos individuais e não como operação da área de transferência, os tratadores de paste não veem a entrada do leitor, e máscaras que só escutam paste deixam passar isso em silêncio.

Problemas de layout de teclado

Por que aparecem caracteres errados: o leitor mapeia os caracteres decodificados para códigos de tecla HID usando o próprio layout configurado. Se esse layout não bater com o do sistema operacional, os caracteres podem se trocar. O sintoma clássico é dígito ou pontuação lidos como outro caractere em sistemas QWERTY e AZERTY.

Divergência de localidade: isso é configuração do leitor, não bug de software. A maioria dos leitores troca a localidade por códigos de configuração impressos no manual, e a correção é reprogramar o leitor para coincidir com a localidade do sistema, não alterar o código do aplicativo.

Prefixos e sufixos

Leitores em geral aceitam sequências configuráveis de prefixo e sufixo em volta da carga. Os sufixos mais comuns são ENTER (CR, 0x0D), TAB (0x09) e, às vezes, um par CR+LF completo. Prefixos são menos comuns, mas às vezes servem para encaminhar leituras a campos específicos em aplicativos de terminal antigos.

Limitações para testes no navegador

O navegador não vê pacotes USB HID brutos, não consegue enumerar dispositivos HID conectados especificamente como leitor (fora da API WebHID, pela qual a maioria dos leitores não expõe dados) e não distingue um leitor em modo teclado HID de um teclado de verdade. Só os eventos de teclado visíveis ao navegador (keydown, keyup, keypress) ficam acessíveis ao JavaScript, e é exatamente isso que as ferramentas deste site inspecionam.

Relacionados

Use o testador de eventos de teclado para inspecionar eventos brutos de teclado, ou leia o guia Sufixos ENTER e TAB para detalhes de configuração do sufixo.