Conversando com dispositivos USB, comece a concluir (aplicativo UWP)

  • Artigo

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

Use as APIs Windows Runtime 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, por outro lado, obter fluxos de dados do dispositivo e sondar o dispositivo para obter dados de interrupção.

Aqui, descrevemos como seu aplicativo UWP pode implementar essas tarefas e vincular a exemplos que demonstram o uso de classes incluídas em Windows.Devices.Usb. Examinaremos os recursos de 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 suspender para conservar a duração da bateria.

Passo a passo – Escrever um aplicativo UWP para dispositivos USB

Siga as etapas neste artigo ou pule diretamente para o exemplo de acesso de 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 na seção de 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 facilmente encontrar código sem precisar fazer drill down por várias camadas de arquivos de origem. Mas talvez você prefira separar e organizar seu próprio projeto de forma diferente.

Instalar o driver do Microsoft WinUSB

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

Instalação do QuickStart:WinUSB (Winusb.sys)

Você pode instalar Winusb.sys destas 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 em 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 referencie o arquivo Winusb.inf fornecido pela Microsoft. Para obter mais informações, consulte Instalação do WinUSB (Winusb.sys).

Obter informações sobre seu dispositivo

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

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

  • Identificadores de fornecedor e produto

    Em Gerenciador de Dispositivos, exiba as propriedades do dispositivo. Na guia Detalhes , exiba o valor da propriedade ID de 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 de dispositivo, subclasse e protocolo

  • GUID da interface do dispositivo

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

Determinar se o conjunto de API USB permite a classe de dispositivo, a subclasse e o protocolo

Você pode escrever um aplicativo UWP, se a classe de dispositivo, 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

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

<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>

Encontre-o no exemplo: Os recursos do dispositivo USB estão no arquivo Package.appxmanifest.

Abrir 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 enumerados.
  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 da instância do dispositivo e obtenha o objeto UsbDevice .

Encontre-o no exemplo: Consulte arquivos chamados Scenario1_DeviceConnect.

Estudar o layout do dispositivo USB

Estude o layout do dispositivo USB.

Examine os conceitos básicos de USB sobre como configurar o dispositivo e executar transferências de dados: Conceitos para todos os desenvolvedores 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 procurar 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 arquivos chamados 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 do fornecedor 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 esses métodos, dependendo da direção da transferência:

Encontre-o no exemplo: Consulte 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 pipe 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. Obter resultados da operação de transferência.

Encontre-o no exemplo: Consulte 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 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.

Fechar 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 de exclusão. Os aplicativos C#/VB devem chamar o método UsbDevice.Dispose . Os aplicativos JavaScript devem chamar UsbDevice.Close.

Encontre-o no exemplo: Consulte arquivos chamados Scenario1_DeviceConnect.

Criar um pacote de metadados do dispositivo

Crie um pacote de metadados do dispositivo para o aplicativo.

Tool:Device Metadata Authoring Wizard

  • Se você tiver o WDK (Kit de Driver do Windows) instalado, abra Criação> demetadados> do dispositivo dedriver.
  • 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 no assistente. Insira estas informações sobre 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 publicador e a ID do aplicativo UWP.

    Captura de tela do Visual Studio mostrando o metatdata do dispositivo para aplicativos privilegiados.

    Observação

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

  2. Abra a guia Concluir. Selecione a caixa Copiar pacotes para o repositório de metadados local do sistema marcar caixa.

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

Encontre-o no exemplo: Consulte a pasta DeviceMetadata.

Implementar a ativação de 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.

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 (com privilégios 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 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 'Declarações' selecionadas e 'Dispositivo de Reprodução Automática' adicionado.

  3. No método OnActivated da classe App, marcar 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 é disparada e 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 tarefa 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 para o aplicativo da Microsoft Store e registrar-se 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 de DeviceUseTrigger. O aplicativo registra, dispara e lida com 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 para o 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 StartSyncBackgroundTaskAsync privado 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, de modo que 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 verifica se todas as verificações de política de inicializaçã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 está em execução 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á todos os 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 OnSyncWithDeviceCompleted privado 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 está concluída e atualiza a interface do usuário para notificar o usuário.
  7. Implementa manipuladores de eventos de clique no botão privado da interface do usuário para iniciar e cancelar a tarefa em segundo plano.
    1. O manipulador de eventos Sync_Click privado chama o método SyncWithDeviceAsync descrito nas etapas anteriores.
    2. O manipulador de eventos 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 qualquer sincronização de dispositivo ativa para que o dispositivo possa ser reaberto usando o método Unregister no objeto BackgroundTaskRegistration.

Encontre-o no exemplo: Consulte arquivos nomeados 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 do aplicativo Windows.

Usando o Kit de Certificação de Aplicativos Windows

Recomendável. Executar o 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 principais ao seu aplicativo.

Interface do usuário do aplicativo UWP, início a término (XAML)

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

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

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

Programação assíncrona (aplicativos UWP)

Saiba mais sobre como tornar seus aplicativos responsivos quando eles funcionam, o que pode levar um longo período de tempo.

APIs importantes