Membuat perangkat untuk WebUSB

Bangun perangkat untuk memanfaatkan sepenuhnya WebUSB API.

Artikel ini menjelaskan cara membuat perangkat untuk memanfaatkan sepenuhnya WebUSB API. Untuk pengantar singkat tentang API itu sendiri, lihat Mengakses Perangkat USB di Web.

Latar belakang

{i>Universal Serial Bus<i} (USB) telah menjadi antarmuka fisik yang paling umum untuk menghubungkan periferal ke perangkat komputasi {i>desktop<i} dan seluler. Selain dengan mendefinisikan karakteristik kelistrikan bus dan model umum untuk berkomunikasi dengan perangkat, spesifikasi USB mencakup serangkaian kelas perangkat spesifikasi produk. Ini adalah model umum untuk kelas perangkat tertentu seperti seperti penyimpanan, audio, video, jaringan, dll. yang dapat disediakan oleh produsen perangkat diterapkan. Keuntungan dari spesifikasi kelas perangkat ini adalah bahwa sebuah vendor sistem operasi dapat menerapkan {i>driver<i} tunggal berdasarkan kelas ("driver kelas") dan perangkat apa pun yang menerapkan kelas tersebut didukung. Ini adalah peningkatan besar atas setiap produsen yang perlu menulis {i>driver <i}perangkat mereka sendiri.

Namun, beberapa perangkat tidak sesuai dengan salah satu kelas perangkat standar ini. J Produsen dapat memilih melabeli perangkat mereka sebagai menerapkan kelas khusus vendor. Dalam hal ini sistem operasi memilih perangkat mana {i>driver<i} untuk dimuat berdasarkan informasi yang disediakan dalam paket {i>driver<i} vendor, biasanya seperangkat ID vendor dan produk yang diketahui untuk menerapkan protokol khusus vendor tertentu.

Fitur lain dari USB adalah bahwa perangkat dapat menyediakan beberapa antarmuka untuk {i>host<i} yang terhubung dengan mereka. Setiap antarmuka dapat mengimplementasikan standar atau khusus vendor. Ketika sistem operasi memilih {i>driver<i} yang tepat untuk menangani perangkat. Setiap antarmuka dapat diklaim oleh komputer {i>driver<i}. Misalnya, {i>webcam<i} USB biasanya menyediakan dua antarmuka, satu menerapkan class video USB (untuk kamera) dan satu lagi menerapkan USB kelas audio (untuk mikrofon). Sistem operasinya tidak memuat satu pun "driver webcam" tetapi sebagai gantinya memuat driver kelas video dan audio independen yang bertanggung jawab untuk fungsi perangkat yang terpisah. Ini komposisi class antarmuka memberikan fleksibilitas yang lebih besar.

Dasar-dasar API

Banyak class USB standar memiliki API web yang sesuai. Sebagai contoh, dapat merekam video dari perangkat kelas video menggunakan getUserMedia() atau menerima peristiwa input dari perangkat class antarmuka manusia (HID) dengan memproses untuk KeyboardEvents atau PointerEvents, atau dengan menggunakan Gamepad atau WebHID API. Sama seperti tidak semua perangkat mengimplementasikan definisi kelas yang terstandardisasi, tidak semua perangkat menerapkan fitur yang sesuai dengan API platform web yang ada. Kapan dalam kasus ini, WebUSB API dapat mengisi kesenjangan itu dengan menyediakan cara bagi situs untuk mengklaim antarmuka khusus vendor dan menerapkan dukungannya dari dalam halaman mereka.

Persyaratan khusus agar perangkat dapat diakses melalui WebUSB sedikit berbeda dari platform ke platform karena perbedaan dalam cara sistem operasi mengelola USB perangkat tetapi persyaratan dasarnya adalah perangkat seharusnya tidak sudah memiliki {i>driver<i} yang mengklaim antarmuka yang ingin dikendalikan laman tersebut. Ini bisa berupa {i>driver<i} kelas generik yang disediakan oleh vendor OS atau {i>driver<i} perangkat yang disediakan oleh vendor. Karena perangkat USB dapat menyediakan banyak antarmuka, yang masing-masing dapat memiliki {i>driver<i} sendiri, maka mungkin untuk membuat perangkat dengan beberapa antarmuka diklaim oleh {i>driver<i} dan yang lainnya masih dapat diakses oleh {i>browser<i}.

Misalnya, keyboard USB kelas atas mungkin menyediakan antarmuka kelas HID yang akan diklaim oleh subsistem input sistem operasi dan permintaan yang tetap tersedia bagi WebUSB untuk digunakan oleh alat konfigurasi. Ini dapat ditayangkan di situs web produsen yang memungkinkan pengguna untuk mengubah aspek perilaku perangkat seperti tombol makro dan efek pencahayaan tanpa menginstal perangkat lunak khusus platform. Deskriptor konfigurasi perangkat tersebut akan akan terlihat seperti ini:

Deskriptor konfigurasi terdiri dari beberapa deskriptor yang digabungkan secara bersamaan. Setiap tabel diawali dengan kolom bLength dan bDescriptorType sehingga dapat diidentifikasi. Antarmuka pertama adalah antarmuka HID dengan Deskriptor HID dan endpoint tunggal yang digunakan untuk mengirim peristiwa input ke sistem operasi seluler. Antarmuka kedua adalah antarmuka khusus vendor dengan dua endpoint yang dapat digunakan untuk mengirimkan perintah ke perangkat dan menerima respons sebagai hasilnya.

Deskriptor WebUSB

Meskipun WebUSB dapat bekerja dengan banyak perangkat tanpa modifikasi firmware, fungsi tambahan diaktifkan dengan menandai perangkat dengan deskriptor yang menunjukkan dukungan untuk WebUSB. Misalnya, Anda dapat menentukan URL halaman landing yang dapat digunakan browser untuk mengarahkan pengguna saat perangkat Anda dicolokkan.

{i>Biner device Object Store<i} (BOS) adalah konsep yang diperkenalkan di USB 3.0 tetapi memiliki juga telah di-backport ke perangkat USB 2.0 sebagai bagian dari versi 2.1. Mendeklarasikan untuk WebUSB dimulai dengan menyertakan Kemampuan Platform berikut Deskripsi dalam deskripsi BOS:

UUID kemampuan platform mengidentifikasi ini sebagai Kemampuan WebUSB Platform deskripsi, yang memberikan informasi dasar tentang perangkat. Untuk browser untuk mengambil informasi selengkapnya tentang perangkat, nilai bVendorCode digunakan untuk mengirimkan permintaan tambahan ke perangkat. Satu-satunya permintaan yang saat ini adalah GET_URL yang menampilkan deskripsi URL. Ini mirip dengan {i>string<i} tapi dirancang untuk mengenkode URL dalam byte paling kecil. URL untuk "https://google.com" akan terlihat seperti ini:

Ketika perangkat Anda pertama kali dicolokkan, browser akan membaca deskriptor BOS dengan menerbitkan transfer kontrol GET_DESCRIPTOR standar ini:

Permintaan ini biasanya dibuat dua kali, yaitu untuk pertama kalinya dengan wLength yang cukup besar sehingga host mengetahui nilai kolom wTotalLength tanpa berkomitmen untuk mentransfer besar dan kemudian lagi ketika panjang deskriptor penuh adalah dikenal.

Jika deskriptor WebUSB Platform Capability memiliki kolom iLandingPage yang ditetapkan ke nilai bukan nol, browser kemudian melakukan permintaan GET_URL khusus WebUSB dengan mengeluarkan transfer kontrol dengan bRequest yang disetel ke nilai bVendorCode dari deskriptor kemampuan platform dan wValue ditetapkan ke iLandingPage dengan sejumlah nilai. Kode permintaan untuk GET_URL (0x02) masuk di wIndex:

Sekali lagi, permintaan ini mungkin diajukan dua kali untuk mengetahui terlebih dahulu panjangnya deskriptor yang sedang dibaca.

Pertimbangan khusus platform

Sementara WebUSB API mencoba menyediakan antarmuka yang konsisten untuk mengakses Pengembang perangkat USB harus tetap mengetahui persyaratan yang diberlakukan pada aplikasi seperti persyaratan {i>browser<i} web untuk mengakses perangkat.

macOS

Tidak ada hal khusus yang diperlukan untuk macOS. Situs web yang menggunakan WebUSB dapat terhubung ke perangkat dan mengklaim antarmuka apa pun yang tidak diklaim oleh {i>driver<i} {i>kernel<i} atau aplikasi lain.

Linux

Linux seperti macOS, tetapi secara default sebagian besar distribusi tidak menyiapkan akun yang memiliki izin untuk membuka perangkat USB. {i>Daemon<i} sistem yang disebut {i>udev <i}adalah bertanggung jawab untuk menetapkan pengguna dan grup yang diizinkan untuk mengakses perangkat. Aturan seperti ini akan menetapkan kepemilikan perangkat yang cocok dengan vendor yang diberikan dan ID produk ke grup plugdev yang merupakan grup umum untuk pengguna yang memiliki akses ke periferal:

SUBSYSTEM=="usb", ATTR{idVendor}=="XXXX", ATTR{idProduct}=="XXXX", GROUP="plugdev"

Ganti XXXX dengan ID produk dan vendor heksadesimal untuk perangkat Anda, mis. ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11" akan cocok dengan Nexus One ponsel. Kolom ini harus ditulis tanpa "0x" yang biasa awalan dan huruf kecil semua agar dikenali dengan benar. Untuk menemukan ID perangkat, jalankan command line alat lsusb.

Aturan ini harus ditempatkan dalam file di direktori /etc/udev/rules.d dan berfungsi segera setelah perangkat dicolokkan. Tidak perlu memulai ulang {i>udev<i}.

Android

Platform Android berbasis pada Linux tetapi tidak memerlukan modifikasi apa pun untuk konfigurasi sistem. Secara {i>default<i} setiap perangkat yang tidak memiliki {i>driver<i} ke dalam sistem operasi yang tersedia untuk {i>browser<i}. Pengembang seharusnya namun mengetahui bahwa pengguna akan mengalami langkah tambahan saat terhubung ke perangkat. Setelah pengguna memilih perangkat sebagai respons terhadap panggilan ke requestDevice(), Android akan menampilkan perintah yang menanyakan apakah akan mengizinkan Chrome untuk mengaksesnya. Dialog ini juga akan muncul kembali jika pengguna kembali ke situs yang sudah memiliki izin untuk terhubung ke perangkat dan situs web memanggil open()

Selain itu, lebih banyak perangkat yang akan dapat diakses di Android dibandingkan di desktop Linux karena lebih sedikit {i>driver<i} yang disertakan secara {i>default<i}. Kelalaian yang signifikan, misalnya, adalah kelas USB CDC-ACM yang umumnya diimplementasikan oleh adaptor USB-ke-serial karena ada tidak ada API di Android SDK untuk berkomunikasi dengan perangkat serial.

ChromeOS

ChromeOS juga berbasis Linux dan tidak memerlukan modifikasi apa pun ke konfigurasi sistem. Layanan permissions_broker mengontrol akses ke USB perangkat seluler dan akan mengizinkan browser mengaksesnya selama setidaknya ada satu antarmuka yang tidak diklaim.

Windows

Model {i>driver<i} Windows memperkenalkan persyaratan tambahan. Tidak seperti platform di atas kemampuan untuk membuka perangkat USB dari aplikasi pengguna tidak {i>default-<i}nya, bahkan jika tidak ada {i>driver<i} yang dimuat. Sebagai gantinya, ada {i>driver<i}, WinUSB, yang perlu dimuat untuk menyediakan antarmuka digunakan aplikasi untuk mengakses perangkat. Hal ini dapat dilakukan dengan {i>driver information file<i} (INF) yang diinstal pada sistem atau dengan memodifikasi perangkat untuk memberikan Deskripsi Kompatibilitas Microsoft OS selama enumerasi (enumerasi).

File Informasi Pengemudi (INF)

File informasi {i>driver<i} memberi tahu Windows apa yang harus dilakukan saat bertemu dengan perangkat untuk pertama kalinya. Karena sistem pengguna sudah menyertakan {i>driver<i} WinUSB yang diperlukan hanyalah agar file INF dapat mengaitkan vendor dan ID produk Anda dengan aturan penginstalan baru ini. File di bawah ini adalah contoh dasar. Simpan ke file dengan ekstensi .inf, ubah bagian yang ditandai dengan "X", lalu ke kanan klik dan pilih "{i>Install<i}" dari menu konteks.

[Version]
Signature   = "$Windows NT$"
Class       = USBDevice
ClassGUID   = {88BAE032-5A81-49f0-BC3D-A4FF138216D6}
Provider    = %ManufacturerName%
CatalogFile = WinUSBInstallation.cat
DriverVer   = 09/04/2012,13.54.20.543

; ========== Manufacturer/Models sections ===========

[Manufacturer]
%ManufacturerName% = Standard,NTx86,NTia64,NTamd64

[Standard.NTx86]
%USB\MyCustomDevice.DeviceDesc% = USB_Install,USB\VID_XXXX&PID_XXXX

[Standard.NTia64]
%USB\MyCustomDevice.DeviceDesc% = USB_Install,USB\VID_XXXX&PID_XXXX

[Standard.NTamd64]
%USB\MyCustomDevice.DeviceDesc% = USB_Install,USB\VID_XXXX&PID_XXXX

; ========== Class definition ===========

[ClassInstall32]
AddReg = ClassInstall_AddReg

[ClassInstall_AddReg]
HKR,,,,%ClassName%
HKR,,NoInstallClass,,1
HKR,,IconPath,%REG_MULTI_SZ%,"%systemroot%\system32\setupapi.dll,-20"
HKR,,LowerLogoVersion,,5.2

; =================== Installation ===================

[USB_Install]
Include = winusb.inf
Needs   = WINUSB.NT

[USB_Install.Services]
Include = winusb.inf
Needs   = WINUSB.NT.Services

[USB_Install.HW]
AddReg = Dev_AddReg

[Dev_AddReg]
HKR,,DeviceInterfaceGUIDs,0x10000,"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}"

; =================== Strings ===================

[Strings]
ManufacturerName              = "Your Company Name Here"
ClassName                     = "Your Company Devices"
USB\MyCustomDevice.DeviceDesc = "Your Device Name Here"

Bagian [Dev_AddReg] mengonfigurasi kumpulan DeviceInterfaceGUID untuk perangkat seluler. Setiap antarmuka perangkat harus memiliki GUID agar aplikasi menemukan dan menghubungkannya melalui Windows API. Menggunakan PowerShell New-Guid {i>cmdlet<i} atau alat {i>online<i} untuk membuat GUID acak.

Untuk tujuan pengembangan, alat Zadig menyediakan antarmuka yang mudah bagi mengganti {i>driver<i} yang dimuat untuk antarmuka USB dengan {i>driver<i} WinUSB.

Deskriptor kompatibilitas Microsoft OS

Pendekatan file INF di atas rumit karena memerlukan konfigurasi setiap komputer pengguna sebelumnya. Windows 8.1 dan yang lebih tinggi menawarkan alternatif melalui penggunaan deskriptor USB khusus. Deskripsi ini memberikan informasi ke sistem operasi Windows ketika perangkat pertama kali dicolokkan akan biasanya disertakan dalam file INF.

Setelah Anda menyiapkan deskriptor WebUSB, mudah untuk menambahkan OS Microsoft juga deskriptor kompatibilitas. Pertama, perluas deskriptor BOS dengan deskriptor kemampuan platform tambahan. Pastikan untuk mengupdate wTotalLength dan bNumDeviceCaps untuk memperhitungkannya.

Seperti deskripsi WebUSB, Anda harus memilih nilai bRequest untuk digunakan oleh mengontrol transfer yang terkait dengan deskriptor ini. Dalam contoh ini, saya memilih 0x02. 0x07, yang ditempatkan di wIndex, adalah perintah untuk mengambil Microsoft OS 2.0 Kumpulan Deskripsi dari perangkat.

Perangkat USB dapat memiliki beberapa fungsi dan jadi bagian pertama dari deskriptor {i>set <i}menggambarkan {i>function<i} mana yang terkait dengan properti yang mengikutinya. Tujuan contoh di bawah ini mengonfigurasi antarmuka 1 dari perangkat gabungan. Deskriptor memberi OS dua bagian informasi penting tentang antarmuka ini. ID Deskriptor ID memberi tahu Windows bahwa perangkat ini kompatibel dengan WinUSB {i>driver<i}. Fungsi deskriptor properti registry mirip dengan Bagian [Dev_AddReg] dari contoh INF di atas, menetapkan properti registry ke tetapkan GUID antarmuka perangkat pada fungsi ini.

Windows hanya akan mengkueri perangkat untuk informasi ini sekali. Jika perangkat Anda tidak merespons dengan keterangan yang valid, maka tidak akan bertanya lagi perangkat terhubung. Microsoft telah menyediakan daftar USB Device Registry Entri yang menjelaskan entri registry yang dibuat saat menghitung perangkat. Kapan pengujian, menghapus entri yang dibuat perangkat untuk memaksa Windows mencoba membaca deskriptor lagi.

Untuk mengetahui informasi selengkapnya, lihat postingan blog Microsoft tentang cara menggunakan fitur ini deskripsi.

Contoh

Contoh kode yang menerapkan perangkat berbasis WebUSB yang menyertakan WebUSB dan deskriptor Microsoft OS dapat ditemukan dalam project ini:

• WebLight
• Library Arduino WebUSB