WebUSB için cihaz oluşturma

WebUSB API'den tam olarak yararlanmak için bir cihaz oluşturun.

Reilly Grant

Bu makalede, WebUSB API'den tam olarak yararlanmak için nasıl cihaz oluşturulacağı açıklanmaktadır. API'nin kendisi hakkında kısa bir tanıtım için Web'deki USB Cihazlarına Erişme bölümüne bakın.

Arka plan

Universal Serial Bus (USB), çevre birimlerini masaüstü ve mobil bilgisayar cihazlarına bağlamak için en yaygın fiziksel arayüz haline geldi. USB spesifikasyonları, veri yolunun elektriksel özelliklerini ve bir cihazla iletişim kurmak için genel bir modeli tanımlamanın yanı sıra bir dizi cihaz sınıfı spesifikasyonu içerir. Bunlar, cihaz üreticilerinin uygulayabileceği depolama, ses, video, ağ vb. belirli cihaz sınıfları için genel modellerdir. Bu cihaz sınıfı özelliklerinin avantajı, işletim sistemi tedarikçisinin sınıf spesifikasyonuna dayalı tek bir sürücü ("sınıf sürücüsü") uygulayabilmesi ve bu sınıfı uygulayan tüm cihazların desteklenmesidir. Bu, her üreticinin kendi cihaz sürücülerini yazması gerekmesine kıyasla büyük bir gelişmeydi.

Ancak bazı cihazlar bu standartlaştırılmış cihaz sınıflarından birine uymaz. Bunun yerine üretici, cihazını tedarikçiye özel sınıfı uygulayan olarak etiketleyebilir. Bu durumda işletim sistemi, tedarikçi firmanın sürücü paketinde sağlanan bilgilere göre hangi cihaz sürücüsünün yükleneceğini seçer. Bu bilgiler genellikle, belirli bir tedarikçiye özgü protokolü uyguladığı bilinen bir dizi tedarikçi firma ve ürün kimliğidir.

USB'nin bir diğer özelliği de cihazların bağlı oldukları ana makineye birden fazla arayüz sağlayabilmesidir. Her arayüz ya standartlaştırılmış bir sınıf uygulayabilir veya satıcıya özgü olabilir. Bir işletim sistemi, cihazı yönetmek için doğru sürücüleri seçtiğinde her arayüz için farklı bir sürücü hak talebinde bulunabilir. Örneğin, bir USB web kamerası genellikle biri USB video sınıfını (kamera için) diğeri USB ses sınıfını (mikrofon için) uygulayan iki arayüz sağlar. İşletim sistemi tek bir "web kamerası sürücüsü" yüklemez. Bunun yerine, cihazın farklı işlevlerinden sorumlu olan bağımsız video ve ses sınıfı sürücülerini yükler. Arayüz sınıflarının bu bileşimi daha fazla esneklik sağlar.

API temel bilgileri

Standart USB sınıflarının çoğu, ilgili web API'lerine sahiptir. Örneğin, bir sayfa getUserMedia() kullanarak video sınıfı bir cihazdan video yakalayabilir veya KeyboardEvents ya da PointerEvents'i dinleyerek ya da Gamepad'i ya da WebHID API'yi kullanarak insan arayüzü (HID) sınıfı bir cihazdan giriş etkinlikleri alabilir. Tüm cihazlar standartlaştırılmış bir sınıf tanımı uygulamadığı gibi, tüm cihazlar mevcut web platformu API'lerine karşılık gelen özellikleri de uygulamaz. Bu durumda WebUSB API, sitelerin tedarikçiye özel bir arayüz için hak talebinde bulunmasına ve doğrudan kendi sayfalarından bu arayüz için destek uygulamasına olanak tanıyarak bu boşluğu doldurabilir.

Bir cihazın WebUSB üzerinden erişilebilir olması için gereken belirli koşullar, işletim sistemlerinin USB cihazları yönetme biçimindeki farklılıklar nedeniyle platformdan platforma biraz farklılık gösterir. Ancak temel koşul, cihazda sayfanın kontrol etmek istediği arayüzü talep eden bir sürücü olmamasıdır. Bu, işletim sistemi tedarikçisi tarafından sağlanan genel bir sınıf sürücüsü veya tedarikçinin sağladığı bir cihaz sürücüsü olabilir. USB cihazlar, her biri kendi sürücüsüne sahip olabilecek birden fazla arayüz sağlayabileceğinden, bazı arayüzlerin bir sürücü tarafından talep edildiği ve diğerlerinin tarayıcıya erişilebilir bırakıldığı bir cihaz oluşturmak mümkündür.

Örneğin, üst düzey bir USB klavye, işletim sisteminin giriş alt sistemi tarafından talep edilecek bir HID sınıfı arayüzü ve bir yapılandırma aracı tarafından kullanılması için WebUSB'nin kullanabileceği tedarikçiye özel bir arayüz sağlayabilir. Bu araç, üreticinin web sitesinde sunulabilir. Böylece kullanıcı, platforma özgü bir yazılım yüklemeden cihazın davranışıyla ilgili makro tuşlar ve ışık efektleri gibi özellikleri değiştirebilir. Bu tür bir cihazın yapılandırma tanımlayıcısı aşağıdaki gibi görünür:

Yapılandırma tanımlayıcısı, birbirine bağlanmış birden fazla tanımlayıcıdan oluşur. Her biri, tanımlanabilmeleri için bLength ve bDescriptorType alanlarıyla başlar. İlk arayüz, ilişkili bir HID tanımlayıcısı ve işletim sistemine giriş etkinlikleri yayınlamak için kullanılan tek bir uç noktaya sahip bir HID arayüzüdür. İkinci arayüz, cihaza komut göndermek ve yanıt almak için kullanılabilecek iki uç noktaya sahip, tedarikçi firmaya özel bir arayüzdür.

WebUSB tanımlayıcılar

WebUSB, donanım yazılımı değişiklikleri olmadan birçok cihazla çalışabilir. Ancak cihaz, WebUSB desteğini belirten belirli tanımlayıcılarla işaretlenerek ek işlevler etkinleştirilir. Örneğin, cihazınız güç kaynağına takılıyken tarayıcının kullanıcıyı yönlendirebileceği bir açılış sayfası URL'si belirtebilirsiniz.

İkili cihaz nesne deposu (BOS), USB 3.0'ta kullanıma sunulan ancak 2.1 sürümü kapsamında USB 2.0 cihazlara da geriye dönük olarak uygulanan bir kavramdır. WebUSB desteğini beyan etmek, BOS tanımlayıcısı içine aşağıdaki Platform Yeteneği Tanımlayıcısını eklemekle başlar:

Platform özelliği UUID'si, bunu cihazla ilgili temel bilgiler sağlayan bir WebUSB Platform Özelliği tanımlayıcısı olarak tanımlar. Tarayıcı, cihazla ilgili daha fazla bilgi almak için cihaza ek istekler göndermek üzere bVendorCode değerini kullanır. Şu anda belirtilen tek istek, URL tanımlayıcısı döndüren GET_URL isteğidir. Bunlar dize tanımlayıcılarına benzer ancak URL'leri en az baytla kodlayacak şekilde tasarlanmıştır. "https://google.com" için bir URL tanımlayıcısı şöyle görünür:

Cihazınız ilk kez prize takıldığında tarayıcı, bu standart GET_DESCRIPTOR kontrol aktarımını yayınlayarak BOS tanımlayıcısını okur:

Bu istek genellikle iki kez, ilkinde yeterince büyük bir wLength ile yapılır. Böylece ana makine, büyük bir aktarım yapmadan wTotalLength alanının değerini bulur ve daha sonra, tam tanımlayıcı uzunluğu bilindiğinde tekrar işlev görür.

WebUSB Platform Yeteneği tanımlayıcısında iLandingPage alanı sıfır dışında bir değere ayarlanmışsa tarayıcı, platform özelliği tanımlayıcısında bVendorCode değerine ayarlanmış ve wValue iLandingPage değerine ayarlanmış bir bRequest ile kontrol aktarımı göndererek WebUSB'ye özel bir GET_URL isteği gerçekleştirir. GET_URL (0x02) için istek kodu wIndex alanına girilir:

Yine de bu istek, önce okunan tanımlayıcı uzunluğunu incelemek için iki kez gönderilebilir.

Platforma özgü dikkat edilmesi gereken noktalar

WebUSB API, USB cihazlara erişmek için tutarlı bir arayüz sunmaya çalışırken geliştiricilerin, cihazlara erişmek için web tarayıcıları gibi uygulamalara uygulanan şartlardan haberdar olması gerekir.

macOS

macOS için özel bir şey gerekmez. WebUSB kullanan bir web sitesi, cihaza bağlanabilir ve bir çekirdek sürücüsü veya başka bir uygulama tarafından hak talebinde bulunulmayan tüm arayüzler için hak talebinde bulunabilir.

Linux

Linux, macOS'e benzer ancak çoğu dağıtım, varsayılan olarak kullanıcı hesaplarını USB cihazlarını açma izniyle oluşturmaz. Bir cihaza erişmesine izin verilen kullanıcıyı ve grubu atamaktan udev adlı bir sistem hizmet programı sorumludur. Bu tür bir kural, belirli tedarikçi ve ürün kimlikleriyle eşleşen bir cihazın sahipliğini, çevre birimlerine erişimi olan kullanıcılar için ortak bir grup olan plugdev grubuna atar:

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

XXXX değerini, cihazınızın onaltılık tedarikçi ve ürün kimlikleriyle değiştirin. Örneğin, ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11" bir Nexus One telefonuyla eşleşir. Doğru şekilde tanınmaları için bu değerler, normal "0x" ön ekiyle yazılmamalı ve tümüyle küçük harflerle yazılmalıdır. Cihazınızın kimliklerini bulmak için komut satırı aracı lsusb'ü çalıştırın.

Bu kural, /etc/udev/rules.d dizinindeki bir dosyaya yerleştirilmelidir ve cihaz takılır takılmaz geçerli olur. udev'i yeniden başlatmanız gerekmez.

Yapay Zeka

Android platformu Linux tabanlıdır ancak sistem yapılandırmasında değişiklik gerektirmez. Varsayılan olarak, işletim sistemine yerleşik sürücü bulunmayan tüm cihazlar tarayıcı tarafından kullanılabilir. Ancak geliştiriciler, kullanıcıların cihaza bağlanırken ek bir adımla karşılaşacağını bilmelidir. Kullanıcı, requestDevice() çağrısına yanıt olarak bir cihaz seçtikten sonra Android, Chrome'un bu cihaza erişmesine izin verilip verilmeyeceğini soran bir istem görüntüler. Bu istem, kullanıcı bir cihaza bağlanma izni olan bir web sitesine geri döndüğünde ve web sitesi open()'i çağrdığında da yeniden görünür.

Ayrıca, varsayılan olarak daha az sürücü dahil edildiğinden Android'de masaüstü Linux'a kıyasla daha fazla cihaza erişilebilir. Örneğin, Android SDK'sında seri cihazla iletişim kurmak için API olmadığından, USB'den seri bağdaştırıcılar tarafından yaygın olarak uygulanan USB CDC-ACM sınıfı önemli bir eksikliktir.

ChromeOS

ChromeOS, Linux'u da temel alır ve sistem yapılandırmasında değişiklik gerektirmez. permission_broker hizmeti, USB cihazlarına erişimi kontrol eder ve hak talebinde bulunulmamış en az bir arayüz olduğu sürece tarayıcıya bu cihazlara erişmesine izin verir.

Windows

Windows sürücü modeli ek bir şart getirir. Yukarıdaki platformların aksine, sürücü yüklü olmasa bile bir USB cihazını kullanıcı uygulamasından açma özelliği varsayılan olarak etkin değildir. Bunun yerine, cihaza erişmek için kullanılan arayüz uygulamalarının sağlanması için WinUSB adlı özel bir sürücünün yüklenmesi gerekir. Bu işlem, sisteme yüklenen özel bir sürücü bilgi dosyası (INF) ile veya cihaz donanım yazılımını, numaralandırma sırasında Microsoft OS Compatibility Descriptors'ı sağlayacak şekilde değiştirerek yapılabilir.

Sürücü Bilgi Dosyası (INF)

Sürücü bilgileri dosyası, Windows'a bir cihazla ilk kez karşılaştığında ne yapacağını söyler. Kullanıcının sistemi zaten WinUSB sürücüsünü içerdiğinden, INF dosyasının tedarikçiniz ve ürün kimliğinizi bu yeni yükleme kuralıyla ilişkilendirmesi yeterlidir. Aşağıdaki dosya temel bir örnektir. Dosyayı .inf uzantılı bir dosyaya kaydedin, "X" ile işaretlenmiş bölümleri değiştirin, ardından dosyayı sağ tıklayıp bağlam menüsünden "Yükle"yi seçin.

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

[Dev_AddReg] bölümü, cihaz için DeviceInterfaceGUID grubunu yapılandırır. Bir uygulamanın Windows API üzerinden cihaz arayüzünü bulup bağlayabilmesi için her cihaz arayüzünde bir GUID bulunmalıdır. Rastgele bir GUID oluşturmak için New-Guid Powershell cmdlet'ini veya online bir aracı kullanın.

Geliştirme amacıyla Zadig aracı, USB arayüzü için yüklenen sürücüyü WinUSB sürücüsüyle değiştirmek için kolay bir arayüz sağlar.

Microsoft işletim sistemi uyumluluk tanımlayıcıları

Yukarıdaki INF dosyası yaklaşımı, her kullanıcının makinesinin önceden yapılandırılmasını gerektirdiği için zahmetli bir yöntemdir. Windows 8.1 ve sonraki sürümler, özel USB tanımlayıcıları kullanarak alternatif bir yöntem sunar. Bu tanımlayıcılar, cihaz ilk takıldığında Windows işletim sistemine normalde INF dosyasına eklenecek bilgileri sağlar.

WebUSB tanımlayıcılarını ayarladıktan sonra, Microsoft'un işletim sistemi uyumluluğu tanımlayıcılarını da kolayca ekleyebilirsiniz. Öncelikle BOS tanımlayıcını bu ek platform özelliği tanımlayıcıyla genişletin. Bu durumu hesaba katacak şekilde wTotalLength ve bNumDeviceCaps öğelerini güncellediğinizden emin olun.

WebUSB tanımlayıcılarında olduğu gibi, bu tanımlayıcılarla ilgili kontrol aktarımlarında kullanılacak bir bRequest değeri seçmeniz gerekir. Bu örnekte 0x02'yi seçtim. wIndex konumunda bulunan 0x07, cihazdan Microsoft OS 2.0 Tanımlayıcı Grubu'nu alma komutudur.

USB cihazların birden fazla işlevi olabilir. Bu nedenle, tanımlayıcı grubunun ilk kısmı, sonraki özelliklerin hangi işlevle ilişkili olduğunu açıklar. Aşağıdaki örnekte, karma bir cihazın 1. arayüzü yapılandırılmaktadır. Tanımlayıcı, işletim sistemine bu arayüz hakkında iki önemli bilgi verir. Uyumlu kimlik tanımlayıcısı, Windows'a bu cihazın WinUSB sürücüsüyle uyumlu olduğunu bildirir. Kayıt defteri mülk tanımlayıcısı, yukarıdaki INF örneğindeki [Dev_AddReg] bölümüne benzer şekilde çalışır ve bu işleve bir cihaz arayüzü GUID'si atamak için bir kayıt defteri mülkü ayarlar.

Windows, bu bilgi için cihazı yalnızca bir kez sorgular. Cihaz geçerli tanımlayıcılarla yanıt vermezse cihaz bir sonraki bağlanışında bu soru tekrar sorulmaz. Microsoft, bir cihaz numaralandırılırken oluşturulan kayıt defteri girişlerini açıklayan USB Cihaz Kaydı Girişlerinin bir listesini sunmuştur. Test sırasında, Windows'un tanımlayıcıları tekrar okumaya zorlaması için cihaz için oluşturulan girişleri silin.

Daha fazla bilgi için Microsoft'un bu tanımlayıcıların nasıl kullanılacağıyla ilgili blog yayınına göz atın.

Örnekler

Hem WebUSB tanımlayıcılarını hem de Microsoft OS tanımlayıcılarını içeren WebUSB uyumlu cihazları uygulayan örnek kodlar aşağıdaki projelerde bulunabilir:

• WebLight
• WebUSB Arduino Kitaplığı