Berbicara dengan perangkat USB, mulailah menyelesaikan (aplikasi UWP)

  • Artikel

Artikel ini menyediakan panduan menyeluruh untuk membuat aplikasi UWP yang berbicara dengan perangkat USB.

Gunakan WINDOWS Runtime API untuk menulis aplikasi UWP yang memberi pengguna akses ke perangkat USB periferal mereka. Aplikasi tersebut dapat terhubung ke perangkat berdasarkan kriteria yang ditentukan pengguna, mendapatkan informasi tentang perangkat, mengirim data ke perangkat dan sebaliknya mendapatkan aliran data dari perangkat, dan melakukan polling perangkat untuk mengganggu data.

Di sini, kami menjelaskan bagaimana aplikasi UWP Anda dapat menerapkan tugas tersebut, dan menautkan ke contoh yang menunjukkan penggunaan kelas yang disertakan dalam Windows.Devices.Usb. Kita akan membahas kemampuan perangkat yang diperlukan dalam manifes aplikasi dan cara meluncurkan aplikasi saat perangkat terhubung. Dan kita akan menunjukkan cara menjalankan tugas transfer data di latar belakang bahkan ketika aplikasi menangguhkan untuk menghemat masa pakai baterai.

Panduan—Menulis aplikasi UWP untuk perangkat USB

Ikuti langkah-langkah dalam artikel ini atau, lewati langsung ke sampel akses perangkat USB Kustom. Sampel pendamping mengimplementasikan semua langkah di sini, tetapi untuk menjaga hal-hal tetap bergerak, kami tidak menelusuri kode. Langkah-langkah tertentu memiliki Temukan di bagian sampel untuk membantu Anda menemukan kode dengan cepat. Struktur file sumber sampel sederhana dan datar sehingga Anda dapat dengan mudah menemukan kode tanpa harus menelusuri beberapa lapisan file sumber. Tetapi Anda mungkin lebih suka memecah dan mengatur proyek Anda sendiri secara berbeda.

Menginstal driver Microsoft WinUSB

Instal driver WinUSB yang disediakan Microsoft sebagai driver fungsi untuk perangkat Anda.

Penginstalan QuickStart:WinUSB (Winusb.sys)

Anda dapat menginstal Winusb.sys dengan cara berikut:

  • Saat menyambungkan perangkat, Anda mungkin melihat bahwa Windows dimuat Winusb.sys secara otomatis karena perangkat tersebut adalah Perangkat WinUSB.
  • Instal driver dengan menentukan kelas perangkat yang disediakan sistem di Manajer Perangkat.
  • Instal driver dengan menggunakan INF kustom. Anda bisa mendapatkan INF dengan salah satu dari dua cara berikut:
    • Dapatkan INF dari vendor perangkat keras.
    • Tulis INF kustom yang mereferensikan file Winusb.inf yang disediakan Microsoft. Untuk informasi selengkapnya, lihat Penginstalan WinUSB (Winusb.sys).

Mendapatkan informasi tentang perangkat Anda

Dapatkan GUID antarmuka perangkat, ID perangkat keras, dan informasi kelas perangkat tentang perangkat Anda.

Anda bisa mendapatkan informasi tersebut dari produsen perangkat.

  • Pengidentifikasi vendor dan produk

    Di Manajer Perangkat, lihat properti perangkat. Pada tab Detail , lihat nilai properti Id Perangkat Keras . Nilai tersebut adalah kombinasi dari dua pengidentifikasi tersebut. Misalnya, untuk perangkat SuperMUTT, Id Perangkat Keras adalah "USB\VID_045E&PID_F001"; ID vendor adalah "0x045E" dan ID produk adalah "0xF001".

  • Kelas perangkat, subkelas, dan kode protokol

  • GUID antarmuka perangkat

Atau, Anda dapat melihat informasi registri. Untuk informasi selengkapnya, lihat Entri registri perangkat USB.

Tentukan apakah set USB API memungkinkan kelas perangkat, subkelas, dan protokol

Anda dapat menulis aplikasi UWP, jika kelas perangkat, subkelas, dan kode protokol perangkat ada dalam daftar berikut:

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

Membuat proyek Visual Studio dasar

Buat proyek Visual Studio dasar yang dapat Anda perluas dalam tutorial ini.

Untuk informasi selengkapnya, lihat Mulai menggunakan aplikasi UWP.

Menambahkan kemampuan perangkat USB ke manifes aplikasi

Pelajari cara menambahkan kemampuan perangkat USB ke manifes aplikasi.

Mulai Cepat:Cara menambahkan kemampuan perangkat USB ke manifes aplikasi

Buka file Package.appxmanifest Anda di editor teks dan tambahkan elemen DeviceCapability dengan atribut Name diatur ke "usb" seperti yang ditunjukkan dalam contoh ini.

Catatan

Anda tidak dapat mengubah kemampuan perangkat USB di Visual Studio. Anda harus mengklik kanan file Package.appxmanifest di Penjelajah Solusi dan memilih Buka Dengan..., lalu EDITOR XML (Teks). File terbuka dalam XML biasa.

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

Temukan dalam sampel: Kemampuan perangkat USB ada dalam file Package.appxmanifest.

Buka perangkat untuk komunikasi

Perluas aplikasi untuk membuka perangkat untuk komunikasi.

Mulai cepat:Cara menyambungkan ke perangkat USB (aplikasi UWP)

  1. Temukan perangkat dengan membuat string Advanced Query Syntax (AQS) yang berisi kriteria pencarian untuk menemukan perangkat dalam kumpulan perangkat yang dijumlahkan.
  2. Buka perangkat dengan salah satu dari dua cara:
  3. Dapatkan instans perangkat dari properti DeviceInformation.Id .
  4. Panggil FromIdAsync dengan meneruskan string instans perangkat dan dapatkan objek UsbDevice .

Temukan dalam sampel: Lihat file bernama Scenario1_DeviceConnect.

Mempelajari tata letak perangkat USB Anda

Pelajari tata letak perangkat USB Anda.

Tinjau konsep USB dasar tentang mengonfigurasi perangkat dan melakukan transfer data: Konsep untuk semua pengembang USB.

Lihat deskriptor konfigurasi perangkat, deskriptor antarmuka untuk setiap pengaturan alternatif yang didukung, dan deskriptor titik akhirnya. Dengan menggunakan USBView, Anda dapat menelusuri semua pengontrol USB dan perangkat USB yang terhubung ke sana, dan juga memeriksa konfigurasi perangkat.

Mendapatkan dan menampilkan deskriptor USB di UI

Perluas aplikasi untuk mendapatkan dan menampilkan deskriptor USB di UI.

Mulai cepat:Cara mendapatkan deskriptor USB (aplikasi UWP)

Temukan dalam sampel: Lihat file bernama Scenario5_UsbDescriptors.

Mengirim transfer kontrol USB yang ditentukan vendor

Perluas aplikasi untuk mengirim transfer kontrol USB yang ditentukan vendor.

Mulai cepat:Cara mengirim permintaan transfer kontrol USB (aplikasi UWP)

  1. Dapatkan perintah vendor dari spesifikasi perangkat keras perangkat.
  2. Buat objek UsbSetupPacket dan isi paket penyiapan dengan mengatur berbagai properti.
  3. Mulai operasi asinkron untuk mengirim transfer kontrol dengan metode ini tergantung pada arah transfer:

Temukan dalam sampel: Lihat file bernama Scenario2_ControlTransfer.

Membaca atau menulis data massal

Perluas aplikasi untuk membaca atau menulis data massal.

Mulai cepat:Cara mengirim permintaan transfer massal USB (aplikasi UWP)

  1. Dapatkan objek pipa massal (UsbBulkOutPipe atau UsbBulkInPipe).
  2. Konfigurasikan pipa massal untuk mengatur parameter kebijakan.
  3. Siapkan aliran data dengan menggunakan objek DataReader atau DataWriter .
  4. Mulai operasi transfer asinkron dengan memanggil DataReader.LoadAsync atau DataWriter.StoreAsync.
  5. Dapatkan hasil operasi transfer.

Temukan dalam sampel: Lihat file bernama Scenario4_BulkPipes.

Mendapatkan data gangguan perangkat keras

Perluas aplikasi untuk mendapatkan data gangguan perangkat keras.

Mulai cepat:Cara mengirim permintaan transfer interupsi USB (aplikasi UWP)

  1. Dapatkan objek pipa interupsi (UsbInterruptInPipe atau UsbInterruptOutPipe).
  2. Terapkan handler interupsi untuk peristiwa DataReceived .
  3. Daftarkan penanganan aktivitas untuk mulai menerima data.
  4. Batalkan pendaftaran penanganan aktivitas untuk berhenti menerima data.

Temukan dalam sampel: Lihat file bernama Scenario3_InterruptPipes.

Pilih pengaturan antarmuka yang saat ini tidak aktif

Perluas aplikasi untuk memilih pengaturan antarmuka yang saat ini tidak aktif.

Mulai cepat:Cara memilih pengaturan antarmuka USB (aplikasi UWP)

Ketika perangkat dibuka untuk komunikasi, antarmuka default dan pengaturan pertamanya dipilih. Jika Anda ingin mengubah pengaturan tersebut, ikuti langkah-langkah berikut:

  1. Dapatkan pengaturan aktif antarmuka USB dengan menggunakan nilai UsbInterfaceSetting.Selected .
  2. Atur pengaturan antarmuka USB dengan memulai operasi asinkron dengan memanggil UsbInterfaceSetting.SelectSettingAsync.

Tutup perangkat

Perluas aplikasi untuk menutup perangkat.

Mulai cepat:Cara menyambungkan ke perangkat USB (aplikasi UWP)

Setelah Anda selesai menggunakan objek UsbDevice, tutup perangkat.

Aplikasi C++ harus merilis referensi dengan menggunakan kata kunci hapus . Aplikasi C#/VB harus memanggil metode UsbDevice.Dispose . Aplikasi JavaScript harus memanggil UsbDevice.Close.

Temukan dalam sampel: Lihat file bernama Scenario1_DeviceConnect.

Membuat paket metadata perangkat

Buat paket metadata perangkat untuk aplikasi.

Alat:Wizard Penulisan Metadata Perangkat

  • Jika Anda telah menginstal Windows Driver Kit (WDK), bukaPenulisanMetadata> Perangkat Driver>.
  • Jika Anda memiliki SDK Mandiri yang terinstal, alat ini terletak di <install_path>\bin\x86\DeviceMetadataWizardexe.

Kaitkan aplikasi Anda dengan perangkat dengan mengikuti langkah-langkah dalam wizard. Masukkan informasi ini tentang perangkat Anda:

  • Pada halaman Info Perangkat , masukkan Nama Model, Produsen, dan Deskripsi.
  • Pada halaman Info Perangkat Keras , masukkan ID perangkat keras perangkat Anda.

Untuk mendeklarasikan aplikasi sebagai aplikasi istimewa untuk perangkat Anda, ikuti petunjuk berikut:

  1. Pada halaman Info Aplikasi , di grup Aplikasi istimewa , masukkan Nama paket, Nama penerbit, dan ID aplikasi UWP.

    Cuplikan layar Visual Studio, memperlihatkan metatdata perangkat untuk aplikasi istimewa.

    Catatan

    Jangan centang opsi Akses driver kustom .

  2. Buka tab Selesai . Pilih kotak centang Salin paket ke penyimpanan metadata lokal sistem Anda .

  3. Sambungkan perangkat, di Panel Kontrol, buka Tampilkan perangkat dan printer dan verifikasi bahwa ikon perangkat sudah benar.

Temukan dalam sampel: Lihat folder DeviceMetadata.

Menerapkan aktivasi AutoPlay

Perluas aplikasi dengan menerapkan aktivasi AutoPlay untuk meluncurkan aplikasi saat perangkat terhubung ke sistem.

Mulai cepat:Mendaftarkan aplikasi untuk perangkat AutoPlay

Anda dapat menambahkan kemampuan AutoPlay sehingga aplikasi diluncurkan saat perangkat terhubung ke sistem. Anda dapat mengaktifkan Putar Otomatis untuk semua aplikasi UWP (istimewa atau sebaliknya).

  1. Dalam paket metadata perangkat, Anda harus menentukan bagaimana perangkat harus merespons pemberitahuan AutoPlay. Pada tab Info Windows , pilih opsi aplikasi perangkat UWP dan masukkan informasi aplikasi seperti yang ditunjukkan di sini:

  2. Dalam manifes aplikasi, tambahkan deklarasi Perangkat AutoPlay dan luncurkan informasi seperti yang ditunjukkan di sini:

    Cuplikan layar yang memperlihatkan manifes aplikasi dengan 'Deklarasi' dipilih dan 'Perangkat AutoPlay' ditambahkan.

  3. Dalam metode OnActivated dari kelas Aplikasi, periksa apakah perangkat mengaktifkan aplikasi. Jika ya, maka metode menerima nilai parameter DeviceEventArgs yang berisi nilai properti DeviceInformation.Id . Ini adalah nilai yang sama yang dijelaskan dalam Buka perangkat untuk komunikasi.

Temukan dalam sampel: Lihat file bernama Autoplay. Untuk JavaScript, lihat default.js.

Menerapkan tugas latar belakang

Perluas aplikasi untuk menerapkan tugas latar belakang yang dapat melakukan transfer panjang ke perangkat, seperti pembaruan firmware tanpa aplikasi ditangguhkan.

Untuk menerapkan tugas latar belakang, Anda memerlukan dua kelas.

Kelas tugas latar belakang mengimplementasikan antarmuka IBackgroundTask dan berisi kode aktual yang Anda buat untuk menyinkronkan atau memperbarui perangkat periferal Anda. Kelas tugas latar belakang dijalankan saat tugas latar belakang memicu dan dari titik entri yang disediakan dalam manifes aplikasi aplikasi Anda.

Catatan

Infrastruktur tugas latar belakang perangkat yang disediakan oleh Windows 8.1. Untuk informasi selengkapnya tentang tugas latar belakang Windows, lihat Mendukung aplikasi Anda dengan tugas latar belakang.

Kelas tugas latar belakang

  1. Menerapkan antarmuka IBackgroundTask yang diperlukan oleh infrastruktur tugas latar belakang Windows.
  2. Mendapatkan instans DeviceUseDetails yang diteruskan ke kelas dalam metode Jalankan dan menggunakan instans ini untuk melaporkan kemajuan kembali ke aplikasi Microsoft Store dan mendaftar untuk peristiwa pembatalan.
  3. Metode Jalankan juga memanggil metode OpenDevice dan WriteToDeviceAsync privat yang mengimplementasikan kode sinkronisasi perangkat latar belakang.

Aplikasi UWP mendaftar dan memicu tugas latar belakang DeviceUseTrigger. Aplikasi mendaftar, memicu, dan menangani kemajuan pada tugas latar belakang.

Catatan

Contoh kode yang mengikuti dapat diterapkan ke tugas latar belakang DeviceServicingTrigger dengan menggunakan objek yang sesuai. Satu-satunya perbedaan antara dua objek pemicu dan API yang sesuai adalah pemeriksaan kebijakan yang dibuat oleh Windows.

  1. Membuat objek DeviceUseTrigger dan BackgroundTaskRegistration.
  2. Memeriksa untuk melihat apakah ada tugas latar belakang yang sebelumnya didaftarkan oleh aplikasi sampel ini dan membatalkannya dengan memanggil metode Batalkan pendaftaran pada tugas.
  3. Mendaftarkan tugas latar belakang yang disinkronkan dengan perangkat. Metode SetupBackgroundTask dipanggil dari metode SyncWithDeviceAsync di langkah berikutnya.
    1. Menginisialisasi DeviceUseTrigger dan menyimpannya untuk digunakan nanti.
    2. Membuat objek BackgroundTaskBuilder dan menggunakan properti dan metode Name, TaskEntryPoint, dan SetTrigger untuk mendaftarkan objek DeviceUseTrigger aplikasi dan nama tugas latar belakang. Properti TaskEntryPoint objek BackgroundTaskBuilder diatur ke nama lengkap kelas tugas latar belakang yang akan dijalankan saat tugas latar belakang dipicu.
    3. Mendaftar untuk penyelesaian dan kemajuan peristiwa dari tugas latar belakang sehingga aplikasi Microsoft Store dapat memberikan penyelesaian dan pembaruan kemajuan kepada pengguna.
  4. Metode SyncWithDeviceAsync privat mendaftarkan tugas latar belakang yang akan disinkronkan dengan perangkat dan memulai sinkronisasi latar belakang.

    1. Memanggil metode SetupBackgroundTask dari langkah sebelumnya dan mendaftarkan tugas latar belakang yang akan disinkronkan dengan perangkat.

    2. Memanggil metode StartSyncBackgroundTaskAsync privat yang memulai tugas latar belakang.

    3. Menutup handel aplikasi ke perangkat untuk memastikan bahwa tugas latar belakang dapat membuka perangkat saat dimulai.

      Catatan

      Tugas latar belakang harus membuka perangkat untuk melakukan pembaruan sehingga aplikasi Microsoft Store harus menutup koneksinya ke perangkat sebelum memanggil RequestAsync

    4. Memanggil metode RequestAsync objek DeviceUseTrigger yang mulai memicu tugas latar belakang dan mengembalikan objek DeviceTriggerResults dari RequestAsync yang digunakan untuk menentukan apakah tugas latar belakang berhasil dimulai.

      Catatan

      Windows memeriksa untuk memastikan bahwa semua pemeriksaan kebijakan inisiasi tugas yang diperlukan telah selesai. Jika semua pemeriksaan kebijakan selesai, operasi pembaruan sekarang berjalan sebagai tugas latar belakang di luar aplikasi Microsoft Store, memungkinkan aplikasi ditangguhkan dengan aman saat operasi sedang berlangsung. Windows juga akan memberlakukan persyaratan runtime apa pun dan membatalkan tugas latar belakang jika persyaratan tersebut tidak lagi terpenuhi.

    5. Menggunakan objek DeviceTriggerResults yang dikembalikan dari StartSyncBackgroundTaskAsync untuk menentukan apakah tugas latar belakang berhasil dimulai. Pernyataan pengalih digunakan untuk memeriksa hasil dari DeviceTriggerResults.

  5. Menerapkan penanganan aktivitas OnSyncWithDeviceProgress privat yang akan memperbarui UI aplikasi dengan kemajuan dari tugas latar belakang.
  6. Menerapkan penanganan aktivitas OnSyncWithDeviceCompleted privat untuk menangani transisi dari tugas latar belakang ke aplikasi latar depan saat tugas latar belakang telah selesai.
    1. Menggunakan metode CheckResults dari objek BackgroundTaskCompletedEventArgs untuk menentukan apakah ada pengecualian yang dilemparkan oleh tugas latar belakang.
    2. Aplikasi ini membuka kembali perangkat untuk digunakan oleh aplikasi latar depan sekarang setelah tugas latar belakang selesai dan memperbarui UI untuk memberi tahu pengguna.
  7. Menerapkan penanganan aktivitas klik tombol privat dari UI untuk memulai dan membatalkan tugas latar belakang.
    1. Penanganan aktivitas Sync_Click privat memanggil metode SyncWithDeviceAsync yang dijelaskan dalam langkah-langkah sebelumnya.
    2. Penanganan aktivitas CancelSync_Click privat memanggil metode CancelSyncWithDevice privat untuk membatalkan tugas latar belakang.
  8. Metode CancelSyncWithDevice privat membatalkan pendaftaran dan membatalkan sinkronisasi perangkat aktif sehingga perangkat dapat dibuka kembali dengan menggunakan metode Batalkan pendaftaran pada objek BackgroundTaskRegistration.

Temukan dalam sampel: Lihat file bernama Scenario7_Sync file. Kelas latar belakang diimplementasikan dalam IoSyncBackgroundTask.

Menjalankan kit sertifikasi aplikasi Windows

Jalankan kit sertifikasi aplikasi Windows.

Menggunakan Kit Sertifikasi Aplikasi Windows

Disarankan. Menjalankan kit sertifikasi aplikasi Windows membantu Anda memastikan aplikasi Anda memenuhi persyaratan Microsoft Store. Anda harus menjalankannya setiap kali Anda menambahkan fungsionalitas utama ke aplikasi Anda.

UI aplikasi UWP, mulai selesai (XAML)

Pelajari selengkapnya tentang merancang UI aplikasi UWP.

Peta strategi untuk aplikasi UWP menggunakan C# dan Visual Basic dan Roadmap untuk aplikasi UWP menggunakan C++

Pelajari selengkapnya tentang membuat aplikasi UWP menggunakan C++, C#, atau Visual Basic secara umum.

Pemrograman asinkron (aplikasi UWP)

Pelajari tentang cara membuat aplikasi Anda tetap responsif saat melakukan pekerjaan yang mungkin memakan waktu lama.

API penting