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, veja Acessar dispositivos USB na Web.

Contexto

O USB (Universal Serial Bus) tornou-se a interface física mais comum para conectar periféricos a computadores e dispositivos móveis de computação. Além de definir as características elétricas do ônibus e um modelo geral para comunicando com um dispositivo, as especificações de USB incluem um conjunto de classes especificações. 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 de sistema operacional pode implementar um único driver com base na classe (um "driver de classe") e qualquer dispositivo que implemente essa classe será suporte. Essa foi uma grande melhoria em relação a todos os fabricantes que precisavam escrever os próprios drivers de dispositivo.

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

Outra característica do USB é que os dispositivos podem fornecer várias interfaces para ao host ao qual estão conectados. Cada interface pode implementar uma classe padronizada ou ser específico do fornecedor. Quando um sistema operacional escolhe os drivers certos para o dispositivo. Cada interface pode ser reivindicada por um motorista. Por exemplo, uma webcam USB normalmente tem duas interfaces, uma implementando a classe de vídeo USB (para a câmera) e outra implementando a classe de áudio (para o microfone). O sistema operacional não carrega um único "driver da webcam" mas carrega drivers independentes de classe de vídeo e áudio que assumem a responsabilidade pelas funções separadas do dispositivo. Isso 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, 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) ouvindo para KeyboardEvents ou PointerEvents, ou ao usar o Gamepad ou o API WebHID. Assim como nem todos os dispositivos implementam uma definição de classe padronizada, nem todos dispositivos implementam recursos que correspondem às APIs de plataforma web existentes. Quando neste caso, a API WebUSB pode preencher essa lacuna oferecendo uma maneira reivindicar uma interface específica do fornecedor e implementar o suporte diretamente dentro de suas páginas.

Os requisitos específicos para que um dispositivo possa ser acessado via WebUSB variam um pouco de plataforma para plataforma devido a diferenças na forma como os sistemas operacionais gerenciam USB do Google, mas o requisito básico é que ele não tenha um que reivindica a interface que a página quer controlar. Pode ser um driver de classe genérica fornecido pelo fornecedor do SO ou um driver de dispositivo fornecido pelo com o fornecedor. Como os dispositivos USB podem fornecer várias interfaces, cada uma delas pode tem driver próprio, é possível criar um dispositivo para o qual algumas interfaces são reivindicados por um motorista, e os demais podem ser acessados pelo navegador.

Por exemplo, um teclado USB de última geração pode fornecer uma interface de classe HID que será reivindicado pelo subsistema de entrada do sistema operacional e por um nome de que continua disponível para o WebUSB para uso por uma ferramenta de configuração. Isso ferramenta pode ser exibida no site do fabricante, permitindo que o usuário altere aspectos do comportamento do dispositivo, como teclas macro e efeitos de iluminação sem sem instalar softwares específicos da plataforma. Esse descritor de configuração de dispositivo será mais ou menos assim:

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

Descritores WebUSB

Embora a WebUSB funcione com muitos dispositivos sem modificações no firmware, Para ativar esse recurso, marque o dispositivo com informações descritores que indicam compatibilidade com WebUSB. Por exemplo, é possível especificar URL da página de destino para a qual o navegador pode direcionar o usuário quando o dispositivo está conectado.

O armazenamento de objetos binários (BOS, na sigla em inglês) de dispositivos binários é um conceito introduzido no USB 3.0, mas também passou por backport para dispositivos USB 2.0 como parte da versão 2.1. Declaração o suporte para WebUSB começa com a inclusão da seguinte capacidade da plataforma Descritor no BOS:

O UUID da capacidade da plataforma identifica esse recurso como uma Capacidade da plataforma WebUSB descritor, que fornece informações básicas sobre o dispositivo. Para o navegador para buscar mais informações sobre o dispositivo em que o valor bVendorCode é usado. emitir solicitações adicionais ao dispositivo. A única solicitação especificada atualmente é GET_URL, que retorna um descritor de URL. Elas são semelhantes às strings descritores, mas são projetados para codificar URLs com menos bytes. Um URL descritor de "https://google.com" ficaria assim:

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

Essa solicitação geralmente é feita duas vezes, a primeira vez com um wLength grande o suficiente para que o host descubra o valor do campo wTotalLength sem fazer uma transferência grande e novamente quando o comprimento completo do descritor for conhecidos.

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

Novamente, essa solicitação pode ser emitida duas vezes para a primeira sondagem do descritor que está sendo lido.

Considerações específicas da plataforma

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

macOS

Nada de especial é necessário para o macOS. Um site que usa WebUSB pode se conectar ao o dispositivo e reivindicar quaisquer interfaces que não sejam reivindicadas por um driver de kernel ou outro aplicativo.

Linux

O Linux é como o macOS, mas, por padrão, a maioria das distribuições não configura contas com permissão para abrir dispositivos USB. Um daemon do sistema chamado udev é responsável por atribuir o usuário e o grupo com permissão para acessar um dispositivo. Uma regra como isso atribui a propriedade de um dispositivo correspondente ao fornecedor e IDs de produtos ao grupo plugdev, que é um grupo comum de 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 seu dispositivo. Por exemplo: ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11" corresponderia a um Nexus One celular. Eles devem ser escritos sem o "0x" normal, prefixo e todos em minúsculas para ser reconhecido corretamente. Para encontrar os IDs do seu dispositivo, execute a linha de comando ferramenta lsusb.

Essa regra deve 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 udev.

Android

A plataforma Android é baseada em Linux, mas não requer nenhuma modificação para configuração do sistema. Por padrão, qualquer dispositivo que não tenha um driver integrado. no sistema operacional está disponível para o navegador. Os desenvolvedores devem ser mas que os usuários encontrarão uma etapa adicional ao se conectarem o dispositivo. Quando um usuário seleciona um dispositivo em resposta a uma chamada para requestDevice(), o Android vai mostrar uma solicitação perguntando se você quer permitir Chrome para acessá-lo. Essa solicitação também reaparece 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 estarão acessíveis no Android do que no Linux para computador porque há menos drivers incluídos por padrão. Uma omissão importante, por exemplo, é a classe USB CDC-ACM geralmente implementada por adaptadores USB para serial, não há uma API no SDK do Android para comunicação com um dispositivo serial.

ChromeOS

O ChromeOS também é baseado no Linux e também não requer nenhuma modificação à configuração do sistema. O serviço permission_broker controla o acesso ao USB dispositivos e permitirá que o navegador os acesse, desde que haja pelo menos uma interface sem reivindicação.

Windows

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

Arquivo de informações do motorista (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 fornecedor e o ID do produto com essa nova regra de instalação. O arquivo abaixo é um exemplo básico. Salvar em um com a extensão .inf, mude as seções marcadas com "X" e depois clique nele 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. Cada interface de dispositivo deve ter um GUID para que um aplicativo encontrá-lo e se conectar a ele pela API do Windows. Usar o PowerShell New-Guid cmdlet ou uma ferramenta on-line para gerar um GUID aleatório.

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

Descritores de compatibilidade do SO Microsoft

A abordagem de arquivo INF acima é trabalhosa porque exige a configuração de todos os na máquina do usuário com antecedência. O Windows 8.1 e as versões mais recentes com o uso de descritores USB personalizados. Esses descritores fornecem informações ao sistema operacional Windows quando o dispositivo é conectado pela primeira vez normalmente ser incluídas no arquivo INF.

Depois de configurar os descritores WebUSB, é fácil adicionar o sistema operacional da Microsoft descritores de compatibilidade. Primeiro, estenda o descritor BOS com este descritor de capacidade adicional da plataforma. Não se esqueça de atualizar o app wTotalLength e bNumDeviceCaps para considerar isso.

Assim como nos descritores WebUSB, você precisa escolher um valor bRequest para ser usado pelo e controla as transferências relacionadas a esses descritores. Neste exemplo, escolhi 0x02: 0x07, colocado em wIndex, é o comando para recuperar o SO Microsoft 2.0 Conjunto do descritor do dispositivo.

Um dispositivo USB pode ter várias funções e, portanto, a primeira parte do descritor O conjunto descreve a qual função as propriedades a seguir estão associadas. A abaixo configura a interface 1 de um dispositivo composto. O descritor fornece duas informações importantes sobre essa interface. Os modelos O descritor de ID informa ao Windows que este dispositivo é compatível com a rede WinUSB motorista. O descritor de propriedade do registro funciona de forma semelhante à Seção [Dev_AddReg] do exemplo INF acima, definindo uma propriedade de registro como atribua um GUID da interface do dispositivo a essa função.

O Windows só consulta o dispositivo uma vez para encontrar essas informações. Se o dispositivo não responder com descritores válidos, ele não perguntará novamente na próxima vez que o dispositivo está conectado. A Microsoft forneceu uma lista de registros de dispositivos USB Entradas que descrevem as entradas de registro criadas ao enumerar um dispositivo. Quando o teste exclui 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 usá-los descritores.

Exemplos

Exemplo de código que implementa dispositivos com reconhecimento de WebUSB que incluem WebUSB descritores do Microsoft OS e podem ser encontrados nestes projetos:

• WebLight
• Biblioteca WebUSB Arduino