Filtro WebHID no Frontend: Explicando a Seleção de Dispositivos de Interface Humana

A API WebHID abre um mundo de possibilidades para aplicações web, permitindo que interajam diretamente com Dispositivos de Interface Humana (HIDs) como gamepads, dispositivos de entrada especializados e muito mais. Uma parte crítica do uso eficaz do WebHID é entender os filtros de dispositivo. Este guia completo irá guiá-lo pelos meandros dos filtros de dispositivo WebHID, capacitando-o a criar experiências web poderosas e envolventes.

O que é WebHID?

WebHID é uma API web que permite que aplicações web se comuniquem com dispositivos HID conectados ao computador ou dispositivo móvel de um utilizador. Ao contrário das APIs web tradicionais que dependem de drivers de dispositivo específicos, o WebHID fornece uma interface genérica para interagir com uma vasta gama de dispositivos, desde que o utilizador conceda permissão. Isso o torna ideal para dispositivos que não têm suporte nativo do navegador ou que requerem um manuseio de entrada personalizado.

Por que usar WebHID?

• Acesso Direto ao Dispositivo: Comunique-se diretamente com dispositivos HID sem depender de drivers específicos do navegador.
• Manuseio de Entrada Personalizado: Implemente mapeamento e processamento de entrada personalizados para dispositivos especializados.
• Amplo Suporte a Dispositivos: Suporte a uma gama mais ampla de dispositivos, incluindo gamepads, instrumentos científicos e controladores industriais.
• Experiência do Utilizador Melhorada: Crie experiências web mais imersivas e interativas.

Entendendo os Filtros de Dispositivo WebHID

Os filtros de dispositivo são cruciais para solicitar acesso a dispositivos HID específicos. Quando a sua aplicação web chama navigator.hid.requestDevice(), o navegador exibe um seletor de dispositivos, permitindo que o utilizador selecione um dispositivo. Os filtros de dispositivo permitem que você restrinja a lista de dispositivos apresentados ao utilizador, facilitando a localização do dispositivo correto.

Um filtro de dispositivo é um objeto JavaScript que especifica critérios para corresponder a dispositivos HID. Você pode especificar vários filtros na chamada requestDevice(), e o navegador mostrará apenas os dispositivos que correspondem a pelo menos um dos filtros.

Propriedades do Filtro de Dispositivo

• vendorId (opcional): O ID de Fornecedor (Vendor ID) USB do dispositivo. Este é um número de 16 bits que identifica o fabricante do dispositivo.
• productId (opcional): O ID de Produto (Product ID) USB do dispositivo. Este é um número de 16 bits que identifica o modelo específico do dispositivo.
• usagePage (opcional): A Página de Uso (Usage Page) HID do dispositivo. Isso identifica a categoria do dispositivo (por exemplo, Controles de Desktop Genéricos, Controles de Jogo).
• usage (opcional): O Uso (Usage) HID do dispositivo. Isso identifica a função específica do dispositivo dentro da página de uso (por exemplo, Joystick, Gamepad).

Você pode usar uma combinação dessas propriedades para criar filtros altamente específicos. Por exemplo, você pode filtrar por dispositivos com um vendorId e productId específicos para visar um modelo particular de gamepad.

Exemplos Práticos de Filtros de Dispositivo

Vejamos alguns exemplos práticos de como usar filtros de dispositivo nas suas aplicações web.

Exemplo 1: Filtrando por um Gamepad Específico

Suponha que você queira visar um gamepad específico com um vendorId e productId conhecidos. Você pode usar o seguinte filtro:

            const filters = [
  {
    vendorId: 0x045e, // Microsoft
    productId: 0x028e, // Controle Xbox 360
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Lidar com o(s) dispositivo(s) selecionado(s)
  })
  .catch((error) => {
    // Lidar com erros
  });

            

              
                Copy
              
            
          

Neste exemplo, o filtro corresponderá apenas a dispositivos com um vendorId de 0x045e (Microsoft) e um productId de 0x028e (Controle Xbox 360). Substitua estes valores pelo Vendor ID e Product ID apropriados do dispositivo que você está a visar.

Exemplo 2: Filtrando por Qualquer Gamepad

Se você quiser permitir que o utilizador selecione qualquer gamepad, pode usar um filtro que especifica a usagePage e usage para gamepads:

            const filters = [
  {
    usagePage: 0x01, // Controles de Desktop Genéricos
    usage: 0x05, // Gamepad
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Lidar com o(s) dispositivo(s) selecionado(s)
  })
  .catch((error) => {
    // Lidar com erros
  });

            

              
                Copy
              
            
          

Este filtro corresponderá a qualquer dispositivo HID que se identifique como um gamepad usando os códigos de uso HID padrão.

Exemplo 3: Combinando Filtros

Você pode combinar vários filtros para fornecer mais flexibilidade. Por exemplo, você pode querer permitir que o utilizador selecione um modelo de gamepad específico ou qualquer gamepad:

            const filters = [
  {
    vendorId: 0x045e, // Microsoft
    productId: 0x028e, // Controle Xbox 360
  },
  {
    usagePage: 0x01, // Controles de Desktop Genéricos
    usage: 0x05, // Gamepad
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Lidar com o(s) dispositivo(s) selecionado(s)
  })
  .catch((error) => {
    // Lidar com erros
  });

            

              
                Copy
              
            
          

Neste caso, o seletor de dispositivos mostrará tanto o Controle Xbox 360 específico (se conectado) quanto qualquer outro dispositivo que se identifique como um gamepad.

Exemplo 4: Filtrando por um tipo de teclado específico no sistema

Alguns teclados de nicho requerem códigos HID específicos para inicializar corretamente. O exemplo a seguir assume que você conhece o vendor ID, product ID, usage page e usage do teclado. Geralmente, você pode encontrar essas informações na documentação do fabricante ou usando ferramentas de listagem de dispositivos disponíveis na maioria dos sistemas operacionais.

            const filters = [
    {
        vendorId: 0x1234,  // Substitua pelo seu vendor ID
        productId: 0x5678, // Substitua pelo seu product ID
        usagePage: 0x07,   // Substitua pela sua usage page (ex: Teclado/Teclado Numérico)
        usage: 0x01      // Substitua pelo seu usage (ex: Teclado)
    }
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Lidar com o(s) dispositivo(s) selecionado(s)
  })
  .catch((error) => {
    // Lidar com erros
  });

            

              
                Copy
              
            
          

Obtendo Informações do Dispositivo

Depois que o utilizador selecionar um dispositivo, você pode aceder às suas informações usando o objeto HIDDevice.

Propriedades do HIDDevice

• vendorId: O ID de Fornecedor (Vendor ID) USB do dispositivo.
• productId: O ID de Produto (Product ID) USB do dispositivo.
• productName: O nome do dispositivo.
• collections: Um array de objetos HIDCollection que representam os descritores de relatório HID do dispositivo.

Você pode usar essas informações para identificar o dispositivo e configurar sua aplicação de acordo.

Lidando com Relatórios HID

Depois de obter um HIDDevice, você precisa abri-lo e começar a ouvir os relatórios HID. Os relatórios HID são os dados brutos enviados pelo dispositivo para a sua aplicação.

Abrindo o Dispositivo

            device.open()
  .then(() => {
    console.log('Dispositivo aberto');

    // Começar a ouvir relatórios de entrada
    device.addEventListener('inputreport', (event) => {
      const { data, reportId } = event;
      // Processar o relatório de entrada
      console.log(`Relatório de entrada recebido com ID ${reportId}:`, data);
    });
  })
  .catch((error) => {
    console.error('Falha ao abrir o dispositivo:', error);
  });

            

              
                Copy
              
            
          

Processando Relatórios de Entrada

Os relatórios de entrada são recebidos como objetos DataView. A estrutura dos dados depende do descritor de relatório HID do dispositivo. Você precisará consultar a documentação do dispositivo para entender como interpretar os dados.

Aqui está um exemplo simplificado de como processar um relatório de entrada:

            device.addEventListener('inputreport', (event) => {
  const { data, reportId } = event;

  // Assumindo que o primeiro byte do relatório representa o estado do botão
  const buttonState = data.getUint8(0);

  // Processar o estado do botão
  if (buttonState & 0x01) {
    console.log('Botão 1 pressionado');
  }
  if (buttonState & 0x02) {
    console.log('Botão 2 pressionado');
  }
});

            

              
                Copy
              
            
          

Este é um exemplo muito básico. Dispositivos HID do mundo real geralmente têm estruturas de relatório mais complexas. A engenharia reversa do Relatório HID pode ser um processo complexo; no entanto, existem ferramentas disponíveis que ajudam no processo de análise.

Tratamento de Erros

É importante lidar com os erros de forma elegante ao trabalhar com WebHID. Aqui estão alguns erros comuns que você pode encontrar:

• SecurityError: O utilizador negou permissão para aceder a dispositivos HID.
• NotFoundError: Nenhum dispositivo correspondente foi encontrado.
• InvalidStateError: O dispositivo já está aberto.
• Outros erros: Erros de USB, desconexões inesperadas de dispositivos.

Sempre envolva seu código WebHID em blocos try...catch e forneça mensagens de erro informativas ao utilizador.

Melhores Práticas para o Desenvolvimento com WebHID

• Use Filtros de Dispositivo: Sempre use filtros de dispositivo para restringir a lista de dispositivos apresentados ao utilizador.
• Forneça Instruções Claras: Oriente os utilizadores sobre como conectar e autorizar o dispositivo. Se o dispositivo não aparecer, explique ao utilizador onde encontrar os Vendor IDs e Product IDs para dispositivos comuns.
• Lide com Erros de Forma Elegante: Implemente um tratamento de erros robusto para fornecer uma experiência de utilizador suave.
• Consulte a Documentação do Dispositivo: Consulte a documentação do dispositivo para entender seu descritor de relatório HID.
• Teste em Múltiplas Plataformas: Teste sua aplicação em diferentes navegadores e sistemas operacionais para garantir a compatibilidade.
• Considere a Segurança: Esteja ciente das implicações de segurança ao trabalhar com a entrada do utilizador. Higienize os dados e evite executar código não confiável.
• Forneça Opções de Fallback: Se o WebHID não for suportado ou o utilizador negar a permissão, forneça métodos de entrada alternativos.

Técnicas Avançadas

Relatórios de Recursos (Feature Reports)

Além dos relatórios de entrada, os dispositivos HID também podem enviar e receber relatórios de recursos. Os relatórios de recursos são usados para configurar o dispositivo ou recuperar seu status.

Para enviar um relatório de recurso, use o método device.sendFeatureReport().

            const reportId = 0x01;
const data = new Uint8Array([0x01, 0x02, 0x03]); // Dados de exemplo

device.sendFeatureReport(reportId, data)
  .then(() => {
    console.log('Relatório de recurso enviado com sucesso');
  })
  .catch((error) => {
    console.error('Falha ao enviar relatório de recurso:', error);
  });

            

              
                Copy
              
            
          

Para receber um relatório de recurso, use o método device.getFeatureReport().

            const reportId = 0x01;

device.getFeatureReport(reportId)
  .then((data) => {
    console.log('Relatório de recurso recebido:', data);
  })
  .catch((error) => {
    console.error('Falha ao obter relatório de recurso:', error);
  });

            

              
                Copy
              
            
          

Relatórios de Saída (Output Reports)

O WebHID também suporta relatórios de saída, que permitem enviar dados *para* o dispositivo. Por exemplo, você pode usar relatórios de saída para controlar LEDs ou outros atuadores no dispositivo.

Para enviar um relatório de saída, use o método device.sendReport().

            const reportId = 0x01;
const data = new Uint8Array([0x01, 0x02, 0x03]); // Dados de exemplo

device.sendReport(reportId, data)
  .then(() => {
    console.log('Relatório de saída enviado com sucesso');
  })
  .catch((error) => {
    console.error('Falha ao enviar relatório de saída:', error);
  });

            

              
                Copy
              
            
          

Considerações de Segurança

O acesso ao WebHID requer permissão do utilizador, o que ajuda a mitigar alguns riscos de segurança. No entanto, ainda é importante estar ciente de potenciais vulnerabilidades.

• Higienização de Dados: Sempre higienize os dados recebidos de dispositivos HID para prevenir injeção de código ou outros ataques.
• Restrições de Origem: O WebHID está sujeito à política de mesma origem (same-origin policy), que impede o acesso de origens cruzadas a dispositivos HID.
• Consciência do Utilizador: Eduque os utilizadores sobre os riscos de conceder acesso a dispositivos HID e incentive-os a conceder permissão apenas a sites confiáveis.

Perspetivas e Exemplos Globais

A API WebHID tem implicações globais, permitindo que desenvolvedores criem aplicações web que suportam uma vasta gama de dispositivos de diferentes fabricantes e regiões. Considere estes exemplos:

• Jogos: Suporte a gamepads de vários fabricantes em diferentes países (por exemplo, controles Sony PlayStation, controles Microsoft Xbox, Nintendo Switch Pro Controller e marcas menos conhecidas da Ásia e Europa).
• Acessibilidade: Criação de dispositivos de entrada personalizados para utilizadores com deficiência, levando em consideração diferentes padrões e preferências de acessibilidade regionais. Por exemplo, teclados especializados ou interfaces de interruptor projetadas para necessidades específicas e disponíveis em diferentes layouts.
• Automação Industrial: Interface com controladores e sensores industriais usados em fábricas ao redor do mundo, suportando diferentes protocolos de comunicação e formatos de dados.
• Pesquisa Científica: Conexão a instrumentos científicos usados em laboratórios de pesquisa globalmente, permitindo que pesquisadores coletem e analisem dados diretamente em aplicações web. Imagine controlar equipamentos de laboratório numa universidade em Tóquio a partir do laptop de um pesquisador em Londres.
• Educação: Suporte a robôs educacionais e dispositivos interativos usados em salas de aula em todo o mundo, proporcionando aos alunos experiências de aprendizagem práticas. Isso poderia incluir robôs de codificação fabricados na China sendo usados numa sala de aula no Brasil.

WebHID vs. Outras APIs Web

Vale a pena notar como o WebHID se compara a outras APIs web relacionadas à interação com dispositivos:

• API Gamepad: A API Gamepad fornece uma interface de nível superior especificamente para gamepads. O WebHID oferece mais flexibilidade e controle, mas requer mais manuseio manual dos dados do dispositivo. A API Gamepad é adequada para gamepads comuns, enquanto o WebHID pode suportar dispositivos de entrada mais exóticos ou especializados.
• API WebUSB: A WebUSB permite que aplicações web se comuniquem diretamente com dispositivos USB. O WebHID é projetado especificamente para Dispositivos de Interface Humana, enquanto a WebUSB pode ser usada para uma gama mais ampla de dispositivos USB. A WebUSB pode ser usada para um instrumento científico especializado conectado via USB, enquanto o WebHID seria usado para um teclado ou mouse personalizado.
• API Web Serial: A Web Serial permite a comunicação por portas seriais. Isso é útil para interagir com sistemas embarcados e outros dispositivos que se comunicam por conexões seriais. Um microcontrolador enviando dados por uma conexão serial poderia usar a Web Serial, enquanto um joystick construído sob medida usaria o WebHID.

O Futuro do WebHID

A API WebHID está em contínua evolução, com esforços contínuos para melhorar sua segurança, desempenho e facilidade de uso. À medida que mais dispositivos adotam o padrão HID, o WebHID se tornará uma ferramenta cada vez mais importante para desenvolvedores web. Espere ver recursos mais avançados e suporte aprimorado dos navegadores no futuro.

Conclusão

WebHID é uma API poderosa que abre uma vasta gama de possibilidades para aplicações web. Ao entender os filtros de dispositivo e como lidar com relatórios HID, você pode criar experiências web envolventes e interativas que aproveitam todo o potencial dos Dispositivos de Interface Humana. Quer esteja a construir um jogo, uma ferramenta de acessibilidade ou um sistema de controle industrial, o WebHID pode ajudá-lo a conectar sua aplicação web ao mundo físico. Lembre-se de priorizar a experiência do utilizador, a segurança e a compatibilidade entre plataformas para criar aplicações WebHID de sucesso e globalmente acessíveis.