Partilhar via

Conversando com dispositivos USB, do início ao fim (aplicativo UWP)

  • Artigo

Este artigo fornece um passo a passo de ponta a ponta da criação de um aplicativo UWP que se comunica com um dispositivo USB.

Use as APIs do Tempo de Execução do Windows para escrever aplicativos UWP que dão aos usuários acesso ao dispositivo USB periférico. Esses aplicativos podem se conectar a um dispositivo com base em critérios especificados pelo usuário, obter informações sobre o dispositivo, enviar dados para o dispositivo e, inversamente, obter fluxos de dados do dispositivo e sondar o dispositivo em busca de dados de interrupção.

Aqui, descrevemos como seu aplicativo UWP pode implementar essas tarefas e vinculamos a exemplos que demonstram o uso de classes incluídas em Windows.Devices.Usb. Examinaremos os recursos do dispositivo necessários no manifesto do aplicativo e como iniciar o aplicativo quando o dispositivo se conectar. E mostraremos como executar uma tarefa de transferência de dados em segundo plano, mesmo quando o aplicativo é suspenso para conservar a vida útil da bateria.

Passo a passo – Escrevendo um aplicativo UWP para dispositivos USB

Siga as etapas neste artigo ou pule diretamente para o exemplo de acesso a dispositivo USB personalizado. O exemplo complementar implementa todas as etapas aqui, mas para manter as coisas em movimento, não percorremos o código. Determinadas etapas têm uma seção Localizar no exemplo para ajudá-lo a encontrar o código rapidamente. A estrutura dos arquivos de origem do exemplo é simples e simples para que você possa encontrar facilmente o código sem precisar fazer uma busca detalhada em várias camadas de arquivos de origem. Mas você pode preferir dividir e organizar seu próprio projeto de maneira diferente.

Instale o driver Microsoft WinUSB

Instale o driver WinUSB fornecido pela Microsoft como driver de função para seu dispositivo.

Início Rápido: instalação do WinUSB (Winusb.sys)

Você pode instalar Winusb.sys das seguintes maneiras:

  • Ao conectar seu dispositivo, você pode observar que o Windows carrega Winusb.sys automaticamente porque o dispositivo é um dispositivo WinUSB.
  • Instale o driver especificando a classe de dispositivo fornecida pelo sistema no Gerenciador de Dispositivos.
  • Instale o driver usando um INF personalizado. Você pode obter o INF de uma destas duas maneiras:
    • Obtenha o INF do fornecedor de hardware.
    • Escreva um INF personalizado que faça referência ao arquivo Winusb.inf fornecido pela Microsoft. Para obter mais informações, consulte Instalação do WinUSB (Winusb.sys).

Obter informações sobre o seu dispositivo

Obtenha o GUID da interface do dispositivo, a ID de hardware e as informações de classe de dispositivo sobre seu dispositivo.

Você pode obter essas informações com o fabricante do dispositivo.

  • Identificadores de fornecedores e produtos

    No Gerenciador de dispositivos, exiba as propriedades do dispositivo. Na guia Detalhes , exiba o valor da propriedade ID do Hardware . Esse valor é uma combinação desses dois identificadores. Por exemplo, para o dispositivo SuperMUTT, a ID de hardware é "USB\VID_045E&PID_F001"; a ID do fornecedor é "0x045E" e a ID do produto é "0xF001".

  • Códigos de classe, subclasse e protocolo de dispositivo

  • GUID da interface do dispositivo

Como alternativa, você pode exibir informações do registro. Para obter mais informações, consulte Entradas do Registro do dispositivo USB.

Determine se o conjunto de APIs USB permite a classe, a subclasse e o protocolo do dispositivo

Você pode escrever um aplicativo UWP, se a classe, a subclasse e o código de protocolo do dispositivo estiverem na lista a seguir:

  • name:cdcControl, classId:02 * *
  • name:physical, classId:05 * *
  • name:personalHealthcare, classId:0f 00 00
  • name:activeSync, classId:ef 01 01
  • name:palmSync, classId:ef 01 02
  • name:deviceFirmwareUpdate, classId:fe 01 01
  • name:irda, classId:fe 02 00
  • name:measurement, classId:fe 03 *
  • name:vendorSpecific, classId:ff * *

Criar um projeto básico do Visual Studio

Crie um projeto básico do Visual Studio que você pode estender neste tutorial.

Para obter mais informações, consulte Introdução aos aplicativos UWP.

Adicionar recursos de dispositivo USB ao manifesto do aplicativo

Saiba como adicionar recursos de dispositivo USB ao manifesto do aplicativo.

Início Rápido: Como adicionar recursos de dispositivo USB ao manifesto do aplicativo

Abra o arquivo Package.appxmanifest em um editor de texto e adicione o elemento DeviceCapability com o atributo Name definido como "usb", conforme mostrado neste exemplo.

Observação

Você não pode modificar a funcionalidade do dispositivo USB no Visual Studio. Você deve clicar com o botão direito do mouse no arquivo Package.appxmanifest no Gerenciador de Soluções e selecionar Abrir Com... e, em seguida , Editor XML (Texto). O arquivo é aberto em XML simples.

<Capabilities>
  <!--When the device's classId is FF * *, there is a predefined name for the class.
      You can use the name instead of the class id.
      There are also other predefined names that correspond to a classId.-->
  <m2:DeviceCapability Name="usb">
    <!--SuperMutt Device-->
    <m2:Device Id="vidpid:045E 0611">
      <!--<wb:Function Type="classId:ff * *"/>-->
      <m2:Function Type="name:vendorSpecific"/>
    </m2:Device>
  </m2:DeviceCapability>
</Capabilities>

Localize-o no exemplo: os recursos do dispositivo USB estão no arquivo Package.appxmanifest.

Abra o dispositivo para comunicação

Estenda o aplicativo para abrir o dispositivo para comunicação.

Início Rápido: Como se conectar a um dispositivo USB (aplicativo UWP)

  1. Localize o dispositivo criando uma cadeia de caracteres AQS (Sintaxe de Consulta Avançada) que contém critérios de pesquisa para localizar o dispositivo na coleção de dispositivos enumerada.
  2. Abra o dispositivo de duas maneiras:
  3. Obtenha a instância do dispositivo da propriedade DeviceInformation.Id .
  4. Chame FromIdAsync passando a cadeia de caracteres de instância do dispositivo e obtenha o objeto UsbDevice .

Encontre-o no exemplo: consulte os arquivos nomeados Scenario1_DeviceConnect.

Estude o layout do seu dispositivo USB

Estude o layout do seu dispositivo USB.

Revise os conceitos básicos de USB sobre como configurar o dispositivo e executar transferências de dados: Conceitos para todos os desenvolvedores de USB.

Exiba o descritor de configuração do dispositivo, os descritores de interface para cada configuração alternativa com suporte e seus descritores de ponto de extremidade. Usando o USBView, você pode navegar por todos os controladores USB e os dispositivos USB conectados a eles e também inspecionar a configuração do dispositivo.

Obter e mostrar descritores USB na interface do usuário

Estenda o aplicativo para obter e mostrar descritores USB na interface do usuário.

Início Rápido: Como obter descritores USB (aplicativo UWP)

Encontre-o no exemplo: Consulte os arquivos nomeados Scenario5_UsbDescriptors.

Enviar transferências de controle USB definidas pelo fornecedor

Estenda o aplicativo para enviar transferências de controle USB definidas pelo fornecedor.

Início Rápido: Como enviar uma solicitação de transferência de controle USB (aplicativo UWP)

  1. Obtenha o comando vendor da especificação de hardware do dispositivo.
  2. Crie um objeto UsbSetupPacket e preencha o pacote de instalação definindo várias propriedades.
  3. Inicie uma operação assíncrona para enviar a transferência de controle por estes métodos, dependendo da direção da transferência:

Encontre-o no exemplo: Consulte os arquivos chamados Scenario2_ControlTransfer.

Ler ou gravar dados em massa

Estenda o aplicativo para ler ou gravar dados em massa.

Início Rápido: Como enviar uma solicitação de transferência em massa USB (aplicativo UWP)

  1. Obtenha o objeto de tubulação em massa (UsbBulkOutPipe ou UsbBulkInPipe).
  2. Configure o pipe em massa para definir parâmetros de política.
  3. Configure o fluxo de dados usando o objeto DataReader ou DataWriter.
  4. Inicie uma operação de transferência assíncrona chamando DataReader.LoadAsync ou DataWriter.StoreAsync.
  5. Obtenha os resultados da operação de transferência.

Encontre-o no exemplo: consulte os arquivos chamados Scenario4_BulkPipes.

Obter dados de interrupção de hardware

Estenda o aplicativo para obter dados de interrupção de hardware.

Início Rápido: Como enviar uma solicitação de transferência de interrupção USB (aplicativo UWP)

  1. Obtenha o objeto de pipe de interrupção (UsbInterruptInPipe ou UsbInterruptOutPipe).
  2. Implemente o manipulador de interrupção para o evento DataReceived .
  3. Registre o manipulador de eventos para começar a receber dados.
  4. Cancele o registro do manipulador de eventos para parar de receber dados.

Encontre-o no exemplo: consulte os arquivos chamados Scenario3_InterruptPipes.

Selecione uma configuração de interface que não esteja ativa no momento

Estenda o aplicativo para selecionar uma configuração de interface que não esteja ativa no momento.

Início Rápido: Como selecionar uma configuração de interface USB (aplicativo UWP)

Quando o dispositivo é aberto para comunicação, a interface padrão e sua primeira configuração são selecionadas. Se você quiser alterar essa configuração, siga estas etapas:

  1. Obtenha a configuração ativa de uma interface USB usando o valor UsbInterfaceSetting.Selected.
  2. Defina uma configuração de interface USB iniciando uma operação assíncrona chamando UsbInterfaceSetting.SelectSettingAsync.

Feche o dispositivo

Estenda o aplicativo para fechar o dispositivo.

Início Rápido: Como se conectar a um dispositivo USB (aplicativo UWP)

Depois de terminar de usar o objeto UsbDevice, feche o dispositivo.

Os aplicativos C++ devem liberar a referência usando a palavra-chave delete . Os aplicativos C#/VB devem chamar o método UsbDevice.Dispose. Os aplicativos JavaScript devem chamar UsbDevice.Close.

Encontre-o no exemplo: consulte os arquivos nomeados Scenario1_DeviceConnect.

Criar um pacote de metadados do dispositivo

Crie um pacote de metadados do dispositivo para o aplicativo.

Ferramenta: Assistente de Criação de Metadados do Dispositivo

  • Se você tiver o WDK (Windows Driver Kit) instalado, abra a Criação de Metadados>do Dispositivo de Driver.>
  • Se você tiver o SDK autônomo instalado, a ferramenta estará localizada em <install_path>\bin\x86\DeviceMetadataWizardexe.

Associe seu aplicativo ao dispositivo seguindo as etapas do assistente. Insira estas informações sobre o seu dispositivo:

  • Na página Informações do dispositivo, insira Nome do modelo, Fabricante e Descrição.
  • Na página Informações de hardware , insira a ID de hardware do seu dispositivo.

Para declarar o aplicativo como um aplicativo privilegiado para seu dispositivo, siga estas instruções:

  1. Na página Informações do Aplicativo, no grupo de aplicativos com privilégios, insira o Nome do pacote, o Nome do editor e a ID do aplicativo UWP.

    Captura de tela do Visual Studio, mostrando metadados do dispositivo para aplicativos privilegiados.

    Observação

    Não marque a opção Acessar driver personalizado.

  2. Abra a guia Concluir . Marque a caixa de seleção Copiar pacotes para o armazenamento de metadados local do sistema.

  3. Conecte o dispositivo, no Painel de Controle, abra Exibir dispositivos e impressoras e verifique se o ícone do dispositivo está correto.

Localize-o no exemplo: consulte a pasta DeviceMetadata.

Implementar a ativação da Reprodução Automática

Estenda o aplicativo implementando a ativação de Reprodução Automática para iniciar o aplicativo quando o dispositivo se conectar ao sistema.

Guia de início rápido: registrar um aplicativo para um dispositivo de Reprodução Automática

Você pode adicionar recursos de Reprodução Automática para que o aplicativo seja iniciado quando o dispositivo se conectar ao sistema. Você pode habilitar a reprodução automática para todos os aplicativos UWP (privilegiados ou não).

  1. No pacote de metadados do dispositivo, você deve especificar como o dispositivo deve responder a uma notificação de Reprodução Automática. Na guia Informações do Windows, selecione a opção de aplicativo de dispositivo UWP e insira as informações do aplicativo, conforme mostrado aqui:

  2. No manifesto do aplicativo, adicione a declaração do dispositivo de reprodução automática e as informações de inicialização, conforme mostrado aqui:

    Captura de tela que mostra o manifesto do aplicativo com

  3. No método OnActivated da classe App, verifique se o dispositivo ativou o aplicativo. Se for, o método receberá um valor de parâmetro DeviceEventArgs que contém o valor da propriedade DeviceInformation.Id. Esse é o mesmo valor descrito em Abrir o dispositivo para comunicação.

Encontre-o no exemplo: consulte arquivos chamados Reprodução automática. Para JavaScript, consulte default.js.

Implementar uma tarefa em segundo plano

Estenda o aplicativo para implementar uma tarefa em segundo plano que possa executar transferências de comprimento para o dispositivo, como atualização de firmware sem que o aplicativo seja suspenso.

Para implementar a tarefa em segundo plano, você precisa de duas classes.

A classe de tarefa em segundo plano implementa a interface IBackgroundTask e contém o código real que você cria para sincronizar ou atualizar seu dispositivo periférico. A classe de tarefa em segundo plano é executada quando a tarefa em segundo plano é acionada e a partir do ponto de entrada fornecido no manifesto do aplicativo do aplicativo.

Observação

A infraestrutura de tarefas em segundo plano do dispositivo fornecida pelo Windows 8.1. Para obter mais informações sobre tarefas em segundo plano do Windows, consulte Suporte ao seu aplicativo com tarefas em segundo plano.

Classe de tarefa em segundo plano

  1. Implementa a interface IBackgroundTask exigida pela infraestrutura de tarefas em segundo plano do Windows.
  2. Obtém a instância DeviceUseDetails passada para a classe no método Run e usa essa instância para relatar o progresso de volta ao aplicativo da Microsoft Store e para se registrar para eventos de cancelamento.
  3. O método Run também chama os métodos OpenDevice e WriteToDeviceAsync privados que implementam o código de sincronização do dispositivo em segundo plano.

O aplicativo UWP registra e dispara uma tarefa em segundo plano DeviceUseTrigger. O aplicativo registra, dispara e manipula o progresso em uma tarefa em segundo plano.

Observação

O código de exemplo a seguir pode ser aplicado à tarefa em segundo plano DeviceServicingTrigger usando os objetos correspondentes. A única diferença entre os dois objetos de gatilho e suas APIs correspondentes são as verificações de política feitas pelo Windows.

  1. Cria objetos DeviceUseTrigger e BackgroundTaskRegistration.
  2. Verifica se alguma tarefa em segundo plano foi registrada anteriormente por este aplicativo de exemplo e as cancela chamando o método Unregister na tarefa.
  3. Registra a tarefa em segundo plano que é sincronizada com o dispositivo. O método SetupBackgroundTask é chamado do método SyncWithDeviceAsync na próxima etapa.
    1. Inicializa o DeviceUseTrigger e o salva para uso posterior.
    2. Cria um objeto BackgroundTaskBuilder e usa suas propriedades e método Name, TaskEntryPoint e SetTrigger para registrar o objeto DeviceUseTrigger do aplicativo e o nome da tarefa em segundo plano. A propriedade TaskEntryPoint do objeto BackgroundTaskBuilder é definida como o nome completo da classe de tarefa em segundo plano que será executada quando a tarefa em segundo plano for disparada.
    3. Registra-se para eventos de conclusão e progresso da tarefa em segundo plano para que o aplicativo da Microsoft Store possa fornecer atualizações de conclusão e progresso ao usuário.
  4. O método privado SyncWithDeviceAsync registra a tarefa em segundo plano que será sincronizada com o dispositivo e inicia a sincronização em segundo plano.

    1. Chama o método SetupBackgroundTask da etapa anterior e registra a tarefa em segundo plano que será sincronizada com o dispositivo.

    2. Chama o método privado StartSyncBackgroundTaskAsync que inicia a tarefa em segundo plano.

    3. Fecha o identificador do aplicativo para o dispositivo para garantir que a tarefa em segundo plano seja capaz de abrir o dispositivo quando ele for iniciado.

      Observação

      A tarefa em segundo plano precisará abrir o dispositivo para executar a atualização, portanto, o aplicativo da Microsoft Store deve fechar suas conexões com o dispositivo antes de chamar RequestAsync

    4. Chama o método RequestAsync do objeto DeviceUseTrigger, que inicia, dispara a tarefa em segundo plano e retorna o objeto DeviceTriggerResults de RequestAsync usado para determinar se a tarefa em segundo plano foi iniciada com êxito.

      Observação

      O Windows confere se todas as verificações de política de iniciação de tarefas necessárias foram concluídas. Se todas as verificações de política forem concluídas, a operação de atualização agora será executada como uma tarefa em segundo plano fora do aplicativo da Microsoft Store, permitindo que o aplicativo seja suspenso com segurança enquanto a operação está em andamento. O Windows também imporá requisitos de runtime e cancelará a tarefa em segundo plano se esses requisitos não forem mais atendidos.

    5. Usa o objeto DeviceTriggerResults retornado de StartSyncBackgroundTaskAsync para determinar se a tarefa em segundo plano foi iniciada com êxito. Uma instrução switch é usada para inspecionar o resultado de DeviceTriggerResults.

  5. Implementa um manipulador de eventos OnSyncWithDeviceProgress privado que atualizará a interface do usuário do aplicativo com o progresso da tarefa em segundo plano.
  6. Implementa um manipulador de eventos privado OnSyncWithDeviceCompleted para lidar com a transição de tarefas em segundo plano para o aplicativo em primeiro plano quando a tarefa em segundo plano for concluída.
    1. Usa o método CheckResults do objeto BackgroundTaskCompletedEventArgs para determinar se alguma exceção foi gerada pela tarefa em segundo plano.
    2. O aplicativo reabre o dispositivo para uso pelo aplicativo em primeiro plano agora que a tarefa em segundo plano foi concluída e atualiza a interface do usuário para notificar o usuário.
  7. Implementa manipuladores de eventos de clique de botão privado da interface do usuário para iniciar e cancelar a tarefa em segundo plano.
    1. O manipulador de eventos de Sync_Click privado chama o método SyncWithDeviceAsync descrito nas etapas anteriores.
    2. O manipulador de eventos de CancelSync_Click privado chama o método privado CancelSyncWithDevice para cancelar a tarefa em segundo plano.
  8. O método privado CancelSyncWithDevice cancela o registro e cancela todas as sincronizações de dispositivo ativas para que o dispositivo possa ser reaberto usando o método Unregister no objeto BackgroundTaskRegistration.

Encontre-o no exemplo: Consulte arquivos chamados Scenario7_Sync arquivos. A classe em segundo plano é implementada em IoSyncBackgroundTask.

Executar o kit de certificação de aplicativos do Windows

Execute o kit de certificação de aplicativos Windows.

Usando o Kit de Certificação de Aplicativos Windows

Recomendado. A execução do kit de certificação de aplicativos do Windows ajuda você a garantir que seu aplicativo atenda aos requisitos da Microsoft Store. Você deve executá-lo sempre que adicionar funcionalidades importantes ao seu aplicativo.

Interface do usuário do aplicativo UWP, do início ao fim (XAML)

Saiba mais sobre como criar a interface do usuário do aplicativo UWP.

Roteiro para aplicativos UWP em C# e Visual Basic e Roteiro para aplicativos UWP em C++

Saiba mais sobre como criar aplicativos UWP usando C++, C# ou Visual Basic em geral.

Programação assíncrona (aplicativos UWP)

Saiba como fazer com que seus aplicativos permaneçam responsivos quando eles fazem um trabalho que pode levar um longo período de tempo.

APIs importantes