Como criar um dispositivo para WebUSB

Crie um dispositivo para aproveitar ao máximo a API WebUSB.

Reilly Grant

Este artigo explica como criar um dispositivo para aproveitar ao máximo a API WebUSB. Para uma breve introdução à API, consulte Acessar dispositivos USB na Web.

Contexto

O Universal Serial Bus (USB) se tornou a interface física mais comum para conectar periféricos a dispositivos de computação para computadores e dispositivos móveis. Além de definir as características elétricas do barramento e um modelo geral para se comunicar com um dispositivo, as especificações USB incluem um conjunto de especificações de classe de dispositivo. Esses são modelos gerais para classes específicas de dispositivos, como armazenamento, áudio, vídeo, rede etc., que os fabricantes de dispositivos podem implementar. A vantagem dessas especificações de classe de dispositivo é que um fornecedor do sistema operacional pode implementar um único driver com base na especificação da classe (um "driver de classe") e qualquer dispositivo que implemente essa classe terá suporte. Isso foi uma grande melhoria em relação a cada fabricante precisar escrever os próprios drivers de dispositivo.

No entanto, alguns dispositivos não se encaixam em uma dessas classes padronizadas. Um fabricante pode optar por rotular o dispositivo como implementando a classe específica do fornecedor. Nesse caso, o sistema operacional escolhe qual driver do dispositivo carregar com base nas informações fornecidas no pacote de drivers do fornecedor, normalmente um conjunto de IDs de fornecedor e produto que implementam um protocolo específico do fornecedor.

Outro recurso do USB é que os dispositivos podem oferecer várias interfaces ao host ao qual estão conectados. Cada interface pode implementar uma classe padronizada ou ser específica do fornecedor. Quando um sistema operacional escolhe os drivers certos para processar o dispositivo, cada interface pode ser reivindicada por um driver diferente. Por exemplo, uma webcam USB geralmente oferece duas interfaces, uma que implementa a classe de vídeo USB (para a câmera) e outra que implementa a classe de áudio USB (para o microfone). O sistema operacional não carrega um único "driver de webcam", mas carrega drivers de classe de vídeo e áudio independentes que assumem a responsabilidade pelas funções separadas do dispositivo. Essa composição de classes de interface oferece maior flexibilidade.

Princípios básicos da API

Muitas das classes USB padrão têm APIs da Web correspondentes. Por exemplo, uma página pode capturar vídeo de um dispositivo de classe de vídeo usando getUserMedia() ou receber eventos de entrada de um dispositivo de classe de interface humana (HID, na sigla em inglês) detectando KeyboardEvents ou PointerEvents ou usando o Gamepad ou a API WebHID. Assim como nem todos os dispositivos implementam uma definição de classe padronizada, nem todos implementam recursos que correspondem às APIs da plataforma da Web. Nesse caso, a API WebUSB pode preencher essa lacuna, oferecendo uma maneira de os sites reivindicarem uma interface específica do fornecedor e implementar o suporte diretamente na página.

Os requisitos específicos para que um dispositivo seja acessível pelo WebUSB variam um pouco de uma plataforma para outra devido às diferenças na forma como os sistemas operacionais gerenciam dispositivos USB. No entanto, o requisito básico é que um dispositivo não pode ter um driver que reivindica a interface que a página quer controlar. Pode ser um driver de classe genérico fornecido pelo fornecedor do SO ou um driver de dispositivo fornecido pelo fornecedor. Como os dispositivos USB podem fornecer várias interfaces, cada uma com o próprio driver, é possível criar um dispositivo em que algumas interfaces são reivindicadas por um driver e outras são deixadas acessíveis ao navegador.

Por exemplo, um teclado USB de última geração pode fornecer uma interface de classe HID que será reivindicada pelo subsistema de entrada do sistema operacional e uma interface específica do fornecedor que permanece disponível para o WebUSB para uso por uma ferramenta de configuração. Essa ferramenta pode ser oferecida no site do fabricante, permitindo que o usuário mude aspectos do comportamento do dispositivo, como teclas de macro e efeitos de iluminação, sem instalar nenhum software específico da plataforma. O descritor de configuração de um dispositivo desse tipo ficaria assim:

O descritor de configuração consiste em vários descritores concatenados juntos. Cada um começa com os campos bLength e bDescriptorType para que possam ser identificados. A primeira interface é uma interface HID com um descritor HID associado e um único endpoint usado para enviar eventos de entrada ao sistema operacional. A segunda interface é específica do fornecedor e tem dois endpoints que podem ser usados para enviar comandos ao dispositivo e receber respostas em troca.

Descritores do WebUSB

Embora o WebUSB possa funcionar com muitos dispositivos sem modificações de firmware, a funcionalidade adicional é ativada marcando o dispositivo com descritores específicos que indicam suporte ao WebUSB. Por exemplo, você pode especificar um URL da página de destino para que o navegador direcione o usuário quando o dispositivo estiver conectado.

O Binary Device Object Store (BOS) é um conceito introduzido no USB 3.0, mas também foi transferido para dispositivos USB 2.0 como parte da versão 2.1. A declaração de suporte ao WebUSB começa com a inclusão do seguinte descritor de capacidade da plataforma no descritor BOS:

O UUID de capacidade da plataforma identifica isso como um descritor de capacidade da plataforma WebUSB, que fornece informações básicas sobre o dispositivo. Para que o navegador busque mais informações sobre o dispositivo, ele usa o valor bVendorCode para emitir outras solicitações ao dispositivo. A única solicitação especificada no momento é GET_URL, que retorna um descritor de URL. Eles são semelhantes aos descritores de string, mas foram projetados para codificar URLs nos bytes mais curtos. Um descritor de URL para "https://google.com" seria assim:

Quando o dispositivo é conectado pela primeira vez, o navegador lê o descritor do BOS emitindo esta transferência de controle GET_DESCRIPTOR padrão:

Essa solicitação geralmente é feita duas vezes, a primeira com um wLength grande para que o host descubra o valor do campo wTotalLength sem se comprometer com uma transferência grande e, em seguida, quando o comprimento do descritor completo é conhecido.

Se o descritor de capacidade da plataforma WebUSB tiver o campo iLandingPage definido como um valor diferente de zero, o navegador vai executar uma solicitação GET_URL específica do WebUSB emitindo uma transferência de controle com o bRequest definido como o valor bVendorCode do descritor de capacidade da plataforma e wValue definido como o valor iLandingPage. O código de solicitação de GET_URL (0x02) vai para wIndex:

Novamente, essa solicitação pode ser emitida duas vezes para primeiro verificar o comprimento do descritor que está sendo lido.

Considerações específicas da plataforma

Embora a API WebUSB tente fornecer uma interface consistente para acessar dispositivos USB, os desenvolvedores ainda precisam estar cientes dos requisitos impostos aos aplicativos, como os requisitos de navegadores da Web para acessar dispositivos.

macOS

Não é necessário nada especial para o macOS. Um site que usa o WebUSB pode se conectar ao dispositivo e reivindicar todas as interfaces que não são reivindicadas por um driver do kernel ou outro aplicativo.

Linux

O Linux é como o macOS, mas por padrão a maioria das distribuições não configura contas de usuário com permissão para abrir dispositivos USB. Um daemon do sistema chamado udev é responsável por atribuir o usuário e o grupo permitidos para acessar um dispositivo. Uma regra como essa vai atribuir a propriedade de um dispositivo correspondente aos IDs de fornecedor e produto ao grupo plugdev, que é um grupo comum para usuários com acesso a periféricos:

SUBSYSTEM=="usb", ATTR{idVendor}=="XXXX", ATTR{idProduct}=="XXXX", GROUP="plugdev"

Substitua XXXX pelos IDs de fornecedor e produto hexadecimais do dispositivo, por exemplo, ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11" corresponderia a um smartphone Nexus One. Eles precisam ser escritos sem o prefixo "0x" e em letras minúsculas para serem reconhecidos corretamente. Para encontrar os IDs do dispositivo, execute a ferramenta de linha de comando lsusb.

Essa regra precisa ser colocada em um arquivo no diretório /etc/udev/rules.d e entra em vigor assim que o dispositivo é conectado. Não é necessário reiniciar o udev.

Android

A plataforma Android é baseada no Linux, mas não requer nenhuma modificação na configuração do sistema. Por padrão, qualquer dispositivo que não tenha um driver integrado ao sistema operacional está disponível para o navegador. Os desenvolvedores precisam estar cientes de que os usuários vão encontrar uma etapa extra ao se conectar ao dispositivo. Quando um usuário seleciona um dispositivo em resposta a uma chamada para requestDevice(), o Android mostra uma mensagem perguntando se o Chrome pode acessá-lo. Esse aviso também vai reaparecer se um usuário retornar a um site que já tem permissão para se conectar a um dispositivo e o site chamar open().

Além disso, mais dispositivos serão acessíveis no Android do que no Linux para computador porque menos drivers são incluídos por padrão. Uma omissão notável, por exemplo, é a classe USB CDC-ACM comumente implementada por adaptadores USB-serial, já que não há uma API no SDK do Android para se comunicar com um dispositivo serial.

ChromeOS

O ChromeOS também é baseado no Linux e não requer nenhuma modificação na configuração do sistema. O serviço permission_broker controla o acesso a dispositivos USB e permite que o navegador os acesse, desde que haja pelo menos uma interface não reivindicada.

Windows

O modelo de driver do Windows apresenta um requisito extra. Ao contrário das plataformas acima, a capacidade de abrir um dispositivo USB de um aplicativo do usuário não é o padrão, mesmo que não haja um driver carregado. Em vez disso, há um driver especial, o WinUSB, que precisa ser carregado para fornecer a interface usada pelos aplicativos para acessar o dispositivo. Isso pode ser feito com um arquivo de informações de driver (INF) personalizado instalado no sistema ou modificando o firmware do dispositivo para fornecer os descritores de compatibilidade do SO da Microsoft durante a enumeração.

Arquivo de informações do driver (INF)

Um arquivo de informações do driver informa ao Windows o que fazer ao encontrar um dispositivo pela primeira vez. Como o sistema do usuário já inclui o driver WinUSB, basta que o arquivo INF associe o ID do fornecedor e do produto a essa nova regra de instalação. O arquivo abaixo é um exemplo básico. Salve-o em um arquivo com a extensão .inf, mude as seções marcadas com "X", clique com o botão direito do mouse e escolha "Instalar" no menu de contexto.

[Version]
Signature   = "$Windows NT$"
Class       = USBDevice
ClassGUID   = {88BAE032-5A81-49f0-BC3D-A4FF138216D6}
Provider    = %ManufacturerName%
CatalogFile = WinUSBInstallation.cat
DriverVer   = 09/04/2012,13.54.20.543

; ========== Manufacturer/Models sections ===========

[Manufacturer]
%ManufacturerName% = Standard,NTx86,NTia64,NTamd64

[Standard.NTx86]
%USB\MyCustomDevice.DeviceDesc% = USB_Install,USB\VID_XXXX&PID_XXXX

[Standard.NTia64]
%USB\MyCustomDevice.DeviceDesc% = USB_Install,USB\VID_XXXX&PID_XXXX

[Standard.NTamd64]
%USB\MyCustomDevice.DeviceDesc% = USB_Install,USB\VID_XXXX&PID_XXXX

; ========== Class definition ===========

[ClassInstall32]
AddReg = ClassInstall_AddReg

[ClassInstall_AddReg]
HKR,,,,%ClassName%
HKR,,NoInstallClass,,1
HKR,,IconPath,%REG_MULTI_SZ%,"%systemroot%\system32\setupapi.dll,-20"
HKR,,LowerLogoVersion,,5.2

; =================== Installation ===================

[USB_Install]
Include = winusb.inf
Needs   = WINUSB.NT

[USB_Install.Services]
Include = winusb.inf
Needs   = WINUSB.NT.Services

[USB_Install.HW]
AddReg = Dev_AddReg

[Dev_AddReg]
HKR,,DeviceInterfaceGUIDs,0x10000,"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}"

; =================== Strings ===================

[Strings]
ManufacturerName              = "Your Company Name Here"
ClassName                     = "Your Company Devices"
USB\MyCustomDevice.DeviceDesc = "Your Device Name Here"

A seção [Dev_AddReg] configura o conjunto de DeviceInterfaceGUIDs para o dispositivo. Todas as interfaces de dispositivo precisam ter um GUID para que um aplicativo possa encontrar e se conectar a elas pela API do Windows. Use o cmdlet do PowerShell New-Guid ou uma ferramenta on-line para gerar um GUID aleatório.

Para fins de desenvolvimento, a ferramenta Zadig oferece uma interface fácil para substituir o driver carregado para uma interface USB pelo driver WinUSB.

Descritores de compatibilidade do SO da Microsoft

A abordagem do arquivo INF acima é complicada porque exige a configuração de cada máquina do usuário com antecedência. O Windows 8.1 e versões mais recentes oferecem uma alternativa com o uso de descritores USB personalizados. Esses descritores fornecem informações ao sistema operacional Windows quando o dispositivo é conectado pela primeira vez, o que normalmente seria incluído no arquivo INF.

Depois de configurar os descritores do WebUSB, é fácil adicionar os descritores de compatibilidade do sistema operacional da Microsoft. Primeiro, estenda o descritor BOS com este descritor de recursos de plataforma adicional. Atualize wTotalLength e bNumDeviceCaps para considerar isso.

Assim como nos descritores do WebUSB, você precisa escolher um valor bRequest para ser usado pelas transferências de controle relacionadas a esses descritores. Neste exemplo, escolhi 0x02. 0x07, colocado em wIndex, é o comando para extrair o conjunto de descritores 2.0 do SO da Microsoft do dispositivo.

Um dispositivo USB pode ter várias funções. Portanto, a primeira parte do conjunto de descritores descreve a função a que as propriedades a seguir estão associadas. O exemplo abaixo configura a interface 1 de um dispositivo composto. O descritor fornece ao SO duas informações importantes sobre essa interface. O descritor de ID compatível informa ao Windows que o dispositivo é compatível com o driver WinUSB. O descritor de propriedade do registro funciona de maneira semelhante à seção [Dev_AddReg] do exemplo de INF acima, definindo uma propriedade do registro para atribuir um GUID de interface de dispositivo a essa função.

O Windows só vai consultar o dispositivo para essas informações uma vez. Se o dispositivo não responder com descritores válidos, ele não vai perguntar novamente na próxima vez que for conectado. A Microsoft forneceu uma lista de entradas de registro de dispositivo USB que descrevem as entradas de registro criadas ao enumerar um dispositivo. Ao testar, exclua as entradas criadas para um dispositivo para forçar o Windows a tentar ler os descritores novamente.

Para mais informações, confira a postagem do blog da Microsoft sobre como usar esses descriptores.

Exemplos

Exemplos de código que implementam dispositivos compatíveis com o WebUSB que incluem descritores do WebUSB e do Microsoft OS podem ser encontrados nestes projetos:

• WebLight
• Biblioteca Arduino do WebUSB