Comunicare con i dispositivi USB, iniziare a terminare (app UWP)

  • Articolo

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 ai dispositivi USB personalizzati. L'esempio complementare implementa tutti i passaggi qui, ma per mantenere gli elementi in movimento, non viene illustrato il codice. Alcuni passaggi includono una sezione Trova nella sezione di esempio che consente di trovare rapidamente il codice. La struttura dei file di origine dell'esempio è semplice e semplice, quindi è possibile trovare facilmente il codice senza dover eseguire il drill-down di 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.

Guida introduttiva: 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 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".

  • Codici di protocollo, sottoclasse e classe dispositivo

  • GUID dell'interfaccia del dispositivo

In alternativa, è possibile visualizzare le informazioni nel Registro di sistema. Per altre informazioni, vedere Voci del Registro di sistema 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, vedi 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.

Guida introduttiva: Come aggiungere funzionalità del dispositivo USB al manifesto dell'app

Aprire il file Package.appxmanifest in un editor di testo e aggiungere 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 scegliere Apri con e quindi editor XML (testo). 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>

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

Guida introduttiva: 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. Ottenere 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

Studiare il layout del dispositivo USB.

Esaminare i concetti di base relativi alla configurazione del dispositivo e all'esecuzione di trasferimenti di dati: concetti 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, nonché controllare 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.

Guida introduttiva: Come ottenere descrittori USB (app UWP)

  • Ottenere il descrittore del dispositivo recuperando il valore usbDevice.DeviceDescriptor.

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

    • Ottenere il descrittore di configurazione completo impostato recuperando la proprietà UsbConfiguration.Descriptors.

  • 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. Ottenere il comando fornitore dalla specifica hardware del dispositivo.
  2. Creare un oggetto UsbSetupPacket 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 bulk USB (app UWP)

  1. Ottenere l'oggetto pipe bulk (UsbBulkOutPipe o 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.

Ottenere i dati di interrupt hardware

Estendere l'app per ottenere i dati di interrupt hardware.

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

  1. Ottenere l'oggetto 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

Estendere l'app per chiudere il dispositivo.

Guida introduttiva: Come connettersi a un dispositivo USB (app UWP)

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

Le app C++ devono rilasciare il riferimento usando la parola chiave delete . Le app C#/VB devono chiamare il metodo UsbDevice.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 metadati dispositivo

  • Se è installato Windows Driver Kit (WDK), aprire Creazione metadati> del dispositivo driver.>
  • 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 dispositivo immettere Nome modello, Produttore e 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 immettere il nome del pacchetto, il nome del server di pubblicazione e l'ID app UWP nel gruppo di applicazioni con privilegi.

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

    Nota

    Non selezionare l'opzione Access custom driver .Do not check the Access custom driver option.

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

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

Trovarlo nell'esempio: Vedi 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 aggiungere la dichiarazione del dispositivo AutoPlay e le informazioni di avvio, come illustrato di seguito:

    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 di parametro DeviceEventArgs che contiene il valore della proprietà DeviceInformation.Id. Questo è lo stesso valore descritto in Aprire il dispositivo per la comunicazione.

Trovarlo nell'esempio: Vedere 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 l'attività in background, sono necessarie due classi.

La classe di attività in background implementa l'interfaccia IBackgroundTask e 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, vedi Supporto dell'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 di Microsoft Store e per la registrazione 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. Crea 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 ed avanzamento dall'attività in background in modo che l'app di Microsoft Store possa fornire aggiornamenti di completamento e stato 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'app al dispositivo per assicurarsi che l'attività in background sia in grado di aprire il dispositivo all'avvio.

      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 eventi click del pulsante privato dall'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: vedere i file denominati Scenario7_Sync file. La classe in 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

Requisiti consigliati. 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.

Interfaccia utente dell'app UWP, inizio alla fine (XAML)

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

Roadmap per le app UWP che usano 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)

Informazioni su come rendere le app reattive quando lavorano potrebbero richiedere un periodo di tempo prolungato.

API importanti