Condividi tramite

Comunicare con i dispositivi USB, dall'inizio alla fine (app UWP)

Questo articolo fornisce una procedura dettagliata end-to-end per la creazione di un'app UWP che comunica con un dispositivo USB.

Usa le API di Windows Runtime per scrivere app UWP che consentono agli utenti di accedere al dispositivo USB periferico. Tali app possono connettersi a un dispositivo in base ai criteri specificati dall'utente, ottenere informazioni sul dispositivo, inviare dati al dispositivo e viceversa ottenere flussi di dati dal dispositivo ed eseguire il polling del dispositivo per i dati di interrupt.

Qui viene descritto come l'app UWP può implementare tali attività e collegarsi a esempi che illustrano l'uso delle classi incluse in Windows.Devices.Usb. Verranno descritte le funzionalità del dispositivo necessarie nel manifesto dell'app e come avviare l'app quando il dispositivo si connette. Verrà inoltre illustrato come eseguire un'attività di trasferimento dei dati in background anche quando l'app viene sospesa per risparmiare durata della batteria.

Procedura dettagliata: Scrittura di un'app UWP per dispositivi USB

Seguire la procedura descritta in questo articolo o passare direttamente all'esempio di accesso al dispositivo USB personalizzato . L'esempio complementare implementa tutti i passaggi qui, ma per non rallentare il processo, non esaminiamo il codice. Alcuni passaggi hanno un trovarlo nella sezione di esempio per facilitare la ricerca rapida del codice. La struttura dei file di origine dell'esempio è semplice e lineare, quindi puoi trovare facilmente il codice senza dover scendere attraverso più livelli di file di origine. Ma potresti preferire di suddividere e organizzare il tuo progetto in modo diverso.

Installare il driver Microsoft WinUSB

Installare il driver WinUSB fornito da Microsoft come driver di funzione per il dispositivo.

Avvio rapido di :installazione di WinUSB (Winusb.sys)

È possibile installare Winusb.sys in questi modi:

  • Quando si connette il dispositivo, è possibile notare che Windows carica automaticamente Winusb.sys perché il dispositivo è un dispositivo WinUSB.
  • Installare il driver specificando la classe di dispositivo fornita dal sistema in Gestione dispositivi.
  • Installare il driver usando un INF personalizzato. È possibile ottenere l'INF in uno dei due modi seguenti:
    • Ottenere l'INF dal fornitore dell'hardware.
    • Scrivere un INF personalizzato che faccia riferimento al file Winusb.inf fornito da Microsoft. Per altre informazioni, vedere 'installazione di WinUSB (Winusb.sys).

Ottenere informazioni sul dispositivo

Ottenere il GUID dell'interfaccia del dispositivo, l'ID hardware e le informazioni sulla classe del dispositivo.

È possibile ottenere tali informazioni dal produttore del dispositivo.

  • identificatori di fornitore e prodotto

    In Gestione dispositivi visualizzare le proprietà del dispositivo. Nella scheda Dettagli, visualizzare il valore della proprietà ID hardware. Tale valore è una combinazione di questi due identificatori. Ad esempio, per il dispositivo SuperMUTT, l'ID hardware è "USB\VID_045E&PID_F001"; l'ID fornitore è "0x045E" e l'ID prodotto è "0xF001".

  • i codici di classe, sottoclasse e protocollo del dispositivo

  • GUID dell'interfaccia del dispositivo

In alternativa, è possibile visualizzare le informazioni nel Registro di sistema. Per altre informazioni, vedere voci del registro dei dispositivi USB.

Determinare se il set di API USB consente la classe del dispositivo, la sottoclasse e il protocollo

Puoi scrivere un'app UWP, se la classe del dispositivo, la sottoclasse e il codice del protocollo del dispositivo si trova nell'elenco seguente:

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

Creare un progetto di Visual Studio di base

Creare un progetto di Visual Studio di base che è possibile estendere in questa esercitazione.

Per altre informazioni, vedere Introduzione alle app UWP.

Aggiungere funzionalità del dispositivo USB al manifesto dell'app

Informazioni su come aggiungere funzionalità del dispositivo USB al manifesto dell'app.

Avvio rapido:Come aggiungere funzionalità del dispositivo USB al manifesto dell'app

Apri il file Package.appxmanifest in un editor di testo e aggiungi l'elemento DeviceCapability con l'attributo Name impostato su "usb", come illustrato in questo esempio.

Nota

Non è possibile modificare la funzionalità del dispositivo USB in Visual Studio. È necessario fare clic con il pulsante destro del mouse sul file Package.appxmanifest in Esplora soluzioni e selezionare Apri con..., e quindi Editor di testo (XML). Il file viene aperto in formato XML normale.

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

Trova nell'esempio: Le funzionalità del dispositivo USB si trovano nel file Package.appxmanifest.

Aprire il dispositivo per la comunicazione

Estendere l'app per aprire il dispositivo per la comunicazione.

Avvio rapido :Come connettersi a un dispositivo USB (app UWP)

  1. Trovare il dispositivo creando una stringa AQS (Advanced Query Syntax) che contiene i criteri di ricerca per trovare il dispositivo nella raccolta di dispositivi enumerata.
  2. Aprire il dispositivo in uno dei due modi seguenti:
  3. Ottieni l'istanza del dispositivo dalla proprietà DeviceInformation.Id.
  4. Chiamare FromIdAsync passando la stringa dell'istanza del dispositivo e ottenere l'oggetto UsbDevice .

Trovarlo nell'esempio: Vedere i file denominati Scenario1_DeviceConnect.

Studiare il layout del dispositivo USB

Studia il layout del tuo dispositivo USB .

Esaminare i concetti di base relativi alla configurazione del dispositivo e all'esecuzione dei trasferimenti di dati: concetti di per tutti gli sviluppatori USB.

Visualizzare il descrittore di configurazione del dispositivo, i descrittori di interfaccia per ogni impostazione alternativa supportata e i descrittori degli endpoint. Usando USBView, è possibile esplorare tutti i controller USB e i dispositivi USB connessi e controllare anche la configurazione del dispositivo.

Ottenere e visualizzare i descrittori USB nell'interfaccia utente

Estendere l'app per ottenere e visualizzare i descrittori USB nell'interfaccia utente.

Avvio rapido :Come ottenere descrittori USB (app UWP)

  • Recuperare il descrittore del dispositivo ottenendo il valore UsbDevice.DeviceDescriptor.

  • Ottenere il descrittore di configurazione recuperando il valore UsbConfiguration.ConfigurationDescriptor.

  • Ottenere la matrice di interfacce all'interno della configurazione ottenendo la proprietàUsbConfiguration.UsbInterfaces.

  • Ottenere la matrice di impostazioni alternative ottenendo UsbInterface.InterfaceSettings.

  • Nell'impostazione alternativa attiva enumerare le pipe e ottenere gli endpoint associati.

    Questi oggetti rappresentano i descrittori di endpoint:

Trovarlo nell'esempio: Vedere i file denominati Scenario5_UsbDescriptors.

Inviare trasferimenti di controllo USB definiti dal fornitore

Estendere l'app per inviare trasferimenti di controllo USB definiti dal fornitore.

Guida introduttiva:Come inviare una richiesta di trasferimento del controllo USB (app UWP)

  1. Ottieni il comando del fornitore dalla specifica hardware del dispositivo.
  2. Creare un UsbSetupPacket oggetto e popolare il pacchetto di installazione impostando varie proprietà.
  3. Avviare un'operazione asincrona per inviare il trasferimento del controllo tramite questi metodi a seconda della direzione del trasferimento:

Trovarlo nell'esempio: Vedere i file denominati Scenario2_ControlTransfer.

Leggere o scrivere dati in blocco

Estendere l'app per leggere o scrivere dati in blocco.

Guida introduttiva:Come inviare una richiesta di trasferimento in blocco USB (app UWP)

  1. Ottieni l'oggetto del tubo bulk (UsbBulkOutPipe oppure UsbBulkInPipe).
  2. Configurare la pipe bulk per impostare i parametri dei criteri.
  3. Configurare il flusso di dati usando l'oggetto DataReader o DataWriter.
  4. Avviare un'operazione di trasferimento asincrona chiamando DataReader.LoadAsync o DataWriter.StoreAsync.
  5. Ottenere i risultati dell'operazione di trasferimento.

Trovarlo nell'esempio: Vedere i file denominati Scenario4_BulkPipes.

Recuperare i dati degli interrupt hardware

Ampliare l'app per ottenere i dati sugli interrupt hardware.

Avvio rapido :Come inviare una richiesta di trasferimento di interrupt USB (app UWP)

  1. Ottieni l'oggetto della pipe di interrupt (UsbInterruptInPipe o UsbInterruptOutPipe).
  2. Implementare il gestore interrupt per l'evento DataReceived.
  3. Registrare il gestore eventi per avviare la ricezione dei dati.
  4. Annullare la registrazione del gestore eventi per interrompere la ricezione dei dati.

Trovarlo nell'esempio: Vedere i file denominati Scenario3_InterruptPipes.

Selezionare un'impostazione dell'interfaccia non attualmente attiva

Estendere l'app per selezionare un'impostazione di interfaccia che non è attualmente attiva.

Guida introduttiva:Come selezionare un'impostazione dell'interfaccia USB (app UWP)

Quando il dispositivo viene aperto per la comunicazione, vengono selezionate l'interfaccia predefinita e la sua prima impostazione. Per modificare questa impostazione, seguire questa procedura:

  1. Ottenere l'impostazione attiva di un'interfaccia USB usando il valore UsbInterfaceSetting.Selected.
  2. Impostare un'impostazione dell'interfaccia USB avviando un'operazione asincrona chiamando UsbInterfaceSetting.SelectSettingAsync.

Chiudere il dispositivo

Estendi le funzionalità dell'app per spegnere il dispositivo.

Avvio rapido :Come connettersi a un dispositivo USB (app UWP)

Al termine dell'uso dell'oggetto UsbDevice, chiudere il dispositivo.

Le applicazioni C++ devono rilasciare il riferimento utilizzando la parola chiave delete. Le app C#/VB devono chiamare il metodousbDevice.Dispose. Le app JavaScript devono chiamare UsbDevice.Close.

Trovarlo nell'esempio: Vedere i file denominati Scenario1_DeviceConnect.

Creare un pacchetto di metadati del dispositivo

Creare un pacchetto di metadati del dispositivo per l'app.

Strumento : Creazione guidata dei metadati del dispositivo

  • Se hai installato il Windows Driver Kit (WDK), apri Driver>Metadati del Dispositivo>Authoring.
  • Se è installato l'SDK autonomo, lo strumento si trova in <install_path>\bin\x86\DeviceMetadataWizardexe.

Associare l'app al dispositivo seguendo i passaggi della procedura guidata. Immettere queste informazioni sul dispositivo:

  • Nella pagina Informazioni sul dispositivo, immettere Nome del modello, Produttoree Descrizione.
  • Nella pagina Informazioni hardware immettere l'ID hardware del dispositivo.

Per dichiarare l'app come app con privilegi per il dispositivo, seguire queste istruzioni:

  1. Nella pagina informazioni sull'app , nel gruppo applicazione privilegiata , immettere il Nome pacchetto , il Nome dell'editore , e l'ID app UWP .

    Screenshot di Visual Studio, che mostra i metadati del dispositivo per le app con privilegi.

    Nota

    Non selezionare l'opzione driver personalizzato di Access.

  2. Aprire la scheda Fine. Selezionare la casella di controllo Copia pacchetti nell'archivio metadati locale del sistema.

  3. Connettere il dispositivo, nel Pannello di controllo, aprire Visualizza dispositivi e stampanti e verificare che l'icona del dispositivo sia corretta.

Trovarlo nell'esempio: Vedere la cartella DeviceMetadata.

Implementare l'attivazione autoPlay

Estendere l'app implementando l'attivazione autoPlay per avviare l'app quando il dispositivo si connette al sistema.

Guida introduttiva:Registrare un'app per un dispositivo AutoPlay

È possibile aggiungere funzionalità AutoPlay in modo che l'app venga avviata quando il dispositivo si connette al sistema. Puoi abilitare La riproduzione automatica per tutte le app UWP (con privilegi o in altro modo).

  1. Nel pacchetto di metadati del dispositivo è necessario specificare il modo in cui il dispositivo deve rispondere a una notifica autoPlay. Nella scheda Windows Info, selezionare l'opzione app per dispositivi UWP e immettere le informazioni sull'app come illustrato di seguito.

  2. Nel manifesto dell'app, aggiungi la dichiarazione del dispositivo AutoPlay e le informazioni di avvio, come mostrato qui:

    Screenshot che mostra il manifesto dell'app con 'Dichiarazioni' selezionate e 'Dispositivo AutoPlay' aggiunto.

  3. Nel metodo OnActivated della classe App verificare se il dispositivo ha attivato l'app. In caso affermativo, il metodo riceve un valore del parametro DeviceEventArgs che contiene il valore della proprietà DeviceInformation.Id. Questo è lo stesso valore descritto in Aprire il dispositivo per la comunicazione.

Trova nell'esempio: Visualizzare i file denominati Autoplay. Per JavaScript, vedere default.js.

Implementare un'attività in background

Estendere l'app per implementare un'attività in background in grado di eseguire trasferimenti di lunghezza nel dispositivo, ad esempio l'aggiornamento del firmware senza che l'app venga sospesa.

Per implementare un'attività in background, sono necessarie due classi.

La classe di attività in background implementa l'interfacciaIBackgroundTaske contiene il codice effettivo creato per sincronizzare o aggiornare il dispositivo periferico. La classe di attività in background viene eseguita quando l'attività in background viene attivata e dal punto di ingresso fornito nel manifesto dell'applicazione dell'app.

Nota

Infrastruttura delle attività in background del dispositivo fornita da Windows 8.1. Per altre informazioni sulle attività in background di Windows, vedere Supportare la tua app con attività in background.

Classe di attività in background

  1. Implementa l'interfaccia IBackgroundTask richiesta dall'infrastruttura delle attività in background di Windows.
  2. Ottiene l'istanza DeviceUseDetails passata alla classe nel metodo Run e usa questa istanza per segnalare lo stato di avanzamento all'app Microsoft Store e per registrarsi per gli eventi di annullamento.
  3. Il metodo Run chiama anche i metodi OpenDevice e WriteToDeviceAsync privati che implementano il codice di sincronizzazione del dispositivo in background.

L'app UWP registra e attiva un'attività in background DeviceUseTrigger. L'app registra, attiva e gestisce lo stato di avanzamento in un'attività in background.

Nota

Il codice di esempio seguente può essere applicato all'attività in background DeviceServicingTrigger usando gli oggetti corrispondenti. L'unica differenza tra i due oggetti trigger e le API corrispondenti sono i controlli dei criteri eseguiti da Windows.

  1. Vengono creati oggetti DeviceUseTrigger e BackgroundTaskRegistration.
  2. Verifica se alcune attività in background sono state registrate in precedenza da questa applicazione di esempio e le annulla chiamando il metodo Unregister sull'attività.
  3. Registra l'attività in background sincronizzata con il dispositivo. Il metodo SetupBackgroundTask viene chiamato dal metodo SyncWithDeviceAsync nel passaggio successivo.
    1. Inizializza DeviceUseTrigger e lo salva per un uso successivo.
    2. Crea un oggetto BackgroundTaskBuilder e usa le proprietà Name, TaskEntryPoint e SetTrigger e il metodo per registrare l'oggetto DeviceUseTrigger dell'app e il nome dell'attività in background. La proprietà TaskEntryPoint dell'oggetto BackgroundTaskBuilder viene impostata sul nome completo della classe di attività in background che verrà eseguita quando viene attivata l'attività in background.
    3. Registra gli eventi di completamento e progresso dall'attività in background affinché l'app Microsoft Store possa fornire aggiornamenti di completamento e progresso all'utente.
  4. Il metodo Private SyncWithDeviceAsync registra l'attività in background che verrà sincronizzata con il dispositivo e avvia la sincronizzazione in background.

    1. Chiama il metodo SetupBackgroundTask dal passaggio precedente e registra l'attività in background che verrà sincronizzata con il dispositivo.

    2. Chiama il metodo privato StartSyncBackgroundTaskAsync che avvia l'attività in background.

    3. Chiude l'handle dell'applicazione sul dispositivo per garantire che l'attività in background sia in grado di aprire il dispositivo quando inizia.

      Nota

      L'attività in background dovrà aprire il dispositivo per eseguire l'aggiornamento in modo che l'app di Microsoft Store debba chiudere le connessioni al dispositivo prima di chiamare RequestAsync

    4. Chiama il metodo RequestAsync dell'oggetto DeviceUseTrigger che avvia l'attività in background e restituisce l'oggetto DeviceTriggerResults da RequestAsync usato per determinare se l'attività in background è stata avviata correttamente.

      Nota

      Controlli di Windows per assicurarsi che siano stati completati tutti i controlli dei criteri di avvio delle attività necessari. Se tutti i controlli dei criteri vengono completati, l'operazione di aggiornamento viene ora eseguita come attività in background all'esterno dell'app di Microsoft Store, consentendo all'app di essere sospesa in modo sicuro mentre l'operazione è in corso. Windows applica anche eventuali requisiti di runtime e annulla l'attività in background se tali requisiti non sono più soddisfatti.

    5. Usa l'oggetto DeviceTriggerResults restituito da StartSyncBackgroundTaskAsync per determinare se l'attività in background è stata avviata correttamente. Un'istruzione switch viene usata per controllare il risultato da DeviceTriggerResults.

  5. Implementa un gestore eventi OnSyncWithDeviceProgress privato che aggiornerà l'interfaccia utente dell'app con lo stato di avanzamento dall'attività in background.
  6. Implementa un gestore eventi OnSyncWithDeviceCompleted privato per gestire la transizione dalle attività in background all'app in primo piano al termine dell'attività in background.
    1. Usa il metodo CheckResults dell'oggetto BackgroundTaskCompletedEventArgs per determinare se sono state generate eccezioni dall'attività in background.
    2. L'app riapre il dispositivo per l'uso da parte dell'app in primo piano ora che l'attività in background è stata completata e aggiorna l'interfaccia utente per notificare all'utente.
  7. Implementa i gestori degli eventi di click del pulsante privato nell'interfaccia utente per avviare e annullare l'attività in background.
    1. Il gestore eventi Sync_Click privato chiama il metodo SyncWithDeviceAsync descritto nei passaggi precedenti.
    2. Il gestore eventi privato CancelSync_Click chiama il metodo CancelSyncWithDevice privato per annullare l'attività in background.
  8. Il metodo CancelSyncWithDevice privato annulla la registrazione e annulla le sincronizzazioni dei dispositivi attivi in modo che il dispositivo possa essere riaperto usando il metodo Unregister nell'oggetto BackgroundTaskRegistration.

Trovarlo nell'esempio: Visualizzare i file denominati Scenario7_Sync file. La classe Background viene implementata in IoSyncBackgroundTask.

Eseguire il kit di certificazione delle app Windows

Eseguire il kit di certificazione delle app Windows.

uso del Kit di certificazione app Windows

Raccomandato. L'esecuzione del kit di certificazione app Windows ti aiuta a assicurarti che l'app soddisfi i requisiti di Microsoft Store. È consigliabile eseguirla ogni volta che si aggiungono funzionalità principali all'app.

Dall'inizio alla fine: l'interfaccia utente dell'app UWP (XAML)

Altre informazioni sulla progettazione dell'interfaccia utente dell'app UWP.

Roadmap per le app UWP con C# e Visual Basic e Roadmap per le app UWP con C++

Altre informazioni sulla creazione di app UWP con C++, C# o Visual Basic in generale.

Programmazione asincrona (app UWP)

Scopri come rendere le tue app reattive quando eseguono operazioni che potrebbero richiedere un periodo di tempo prolungato.

API importanti