WebUSB için cihaz oluşturma

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

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 Cihazlara Erişim bölümünü inceleyin.

Arka plan

Evrensel Seri Yol (USB), çevre birimlerini masaüstü ve mobil bilgi işlem cihazlarına bağlamak için kullanılan en yaygın fiziksel arayüz haline gelmiştir. USB özellikleri, bir otobüsün elektriksel özelliklerini ve bir cihazla iletişim için genel bir modeli tanımlamanın yanı sıra bir dizi cihaz sınıfı spesifikasyonu da içerir. Bunlar, cihaz üreticilerinin uygulayabileceği depolama, ses, video, ağ iletişimi gibi belirli cihaz sınıflarına yönelik genel modellerdir. Bu cihaz sınıfı özelliklerinin avantajı, işletim sistemi tedarikçisinin sınıf spesifikasyonuna göre tek bir sürücü uygulayabilmesi ("sınıf sürücüsü") ve bu sınıfı uygulayan tüm cihazların desteklenmesidir. Bu, kendi cihaz sürücülerini yazması gereken her üreticiye göre büyük bir gelişmeydi.

Ancak bazı cihazlar bu standartlaştırılmış cihaz sınıflarından birine dahil değildir. Bunun yerine bir üretici, cihazını tedarikçiye özel sınıfı uyguluyor olarak etiketlemeyi tercih edebilir. Bu durumda işletim sistemi, tedarikçinin sürücü paketinde sağlanan bilgilere (genellikle tedarikçi firmaya özel belirli bir protokol uyguladığı bilinen bir dizi tedarikçi firma ve ürün kimliği) dayanarak hangi cihaz sürücüsünün yükleneceğini seçer.

USB'nin bir başka özelliği de bağlı oldukları ana makineye birden çok arayüz sunabilmesidir. Her arayüz standart bir sınıf uygulayabilir veya sağlayıcıya özel olabilir. Bir işletim sistemi cihazı işlemek için doğru sürücüleri seçtiğinde her bir arayüz farklı bir sürücü tarafından talep edilebilir. Örneğin, bir USB web kamerası genellikle biri USB video sınıfını uygulayan (kamera için) diğeri de USB ses sınıfını uygulayan (mikrofon için) 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üleri 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ğuna karşılık gelen web API'leri vardır. Örneğin, bir sayfa getUserMedia() kullanarak video sınıfı cihazından video yakalayabilir ya da KeyboardEvents veya PointerEvents dinleyerek ya da Gamepad veya WebHID API kullanarak insan arayüz (HID) sınıf cihazından giriş etkinlikleri alabilir. Tüm cihazlarda standartlaştırılmış bir sınıf tanımı uygulanmadığı gibi tüm cihazlarda da mevcut web platformu API'lerine karşılık gelen özellikler uygulanmayabilir. Böyle bir durumda WebUSB API, sitelerin satıcıya özel bir arayüz talep etmesi ve doğrudan kendi sayfalarından bunun için destek uygulaması için bir yol sağlayarak bu boşluğu doldurabilir.

Bir cihazın WebUSB üzerinden erişilebilir olması için gerekli şartlar, işletim sistemlerinin USB cihazları yönetme biçimindeki farklılıklar nedeniyle platformdan platforma biraz farklılık gösterir. Ancak temel gereksinim, cihazda, sayfanın kontrol etmek istediği arayüzü talep eden bir sürücü bulunmamasıdır. Bu, işletim sistemi satıcısı tarafından sağlanan genel bir sınıf sürücüsü veya tedarikçi firma tarafından sağlanan bir cihaz sürücüsü olabilir. USB cihazları, her biri kendi sürücüsüne sahip olabilen birden çok arayüz sağlayabildiğinden, bazı arayüzleri bir sürücünün talep ettiği, diğerlerinin ise tarayıcı tarafından erişilebilir olduğu bir cihaz oluşturmak mümkündür.

Örneğin, ileri teknoloji bir USB klavye, işletim sisteminin giriş alt sistemi tarafından talep edilecek HID sınıfı bir arayüz ve bir yapılandırma aracı tarafından kullanılmak üzere WebUSB'de kalmaya devam eden satıcıya özel bir arayüz sağlayabilir. Bu araç üreticinin web sitesinde yayınlanabilir. Bu sayede kullanıcı, platforma özel herhangi bir yazılım yüklemeden cihazın makro tuşlar ve ışık efektleri gibi çalışma özelliklerini değiştirebilir. Böyle bir cihazın yapılandırma tanımlayıcısı aşağıdaki gibi görünür:

Yapılandırma açıklayıcısı, birleştirilen birden çok tanımlayıcıdan oluşur. Her biri, tanımlanabilmesi için bLength ve bDescriptorType alanlarıyla başlar. İlk arayüz, ilişkili bir HID tanımlayıcısına ve giriş etkinliklerini işletim sistemine 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 buna karşılık yanıt almak için kullanılabilen 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ışabilse de, cihazın WebUSB desteğini belirten belirli tanımlayıcılarla işaretlenmesiyle ek işlevler etkinleştirilir. Örneğin, cihazınız takılı olduğunda 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'da kullanıma sunulan bir kavramdır ancak 2.1 sürümünün bir parçası olarak USB 2.0 cihazlara da geri getirilmiştir. WebUSB desteğinin bildirilmesi, BOS tanımlayıcısına aşağıdaki Platform Yeteneği Tanımlayıcısının eklenmesiyle başlar:

Platform özelliği UUID, bunu cihaz hakkında temel bilgiler sağlayan WebUSB Platform Özelliği açıklayıcısı olarak tanımlar. Tarayıcı, cihazla ilgili daha fazla bilgi getirebilmek için bVendorCode değerini kullanarak cihaza ek istekler gönderir. Şu anda belirtilen tek istek, URL açıklayıcı döndüren GET_URL isteğidir. Bunlar dize tanımlayıcılara benzer, ancak URL'leri en az bayt olarak kodlayacak şekilde tasarlanmıştır. "https://google.com" için URL açıklayıcısı şöyle görünür:

Cihazınız ilk kez fişe takıldığında, tarayıcı şu standart GET_DESCRIPTOR kontrol aktarımını yayınlayarak BOS açıklayıcısını okur:

Bu istek genellikle iki kez yapılır. İlkinde ana makinenin büyük bir aktarım yapmadan wTotalLength alanının değerini öğrenmesi için ilk kez yeterince büyük bir wLength ile yapılır. Daha sonra da tam açıklayıcı uzunluğu bilindiğinde istek yapılır.

WebUSB Platform Capability açıklayıcısı, iLandingPage alanı sıfır dışında bir değere ayarlanırsa tarayıcı, bRequest öğesi platform özelliği tanımlayıcıdan bVendorCode değerine ve wValue değeri iLandingPage değerine ayarlanmış şekilde bir kontrol aktarımı yayınlayarak WebUSB'ye özel bir GET_URL isteği gerçekleştirir. GET_URL (0x02) için istek kodu wIndex olur:

Yine, ilk olarak okunan tanımlayıcının uzunluğunu kontrol etmek için bu istek iki kez gönderilebilir.

Platforma özgü konular

WebUSB API, USB cihazlarına erişmek için tutarlı bir arayüz sağlamaya çalışsa da geliştiriciler, cihazlara erişmek için web tarayıcısı gereksinimleri gibi uygulamalara uygulanan şartların farkında olmalıdırlar.

macOS

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

Linux

Linux, macOS'e benzer. Ancak varsayılan olarak çoğu dağıtım, USB cihazlarını açma izniyle kullanıcı hesabı oluşturmaz. Udev adlı sistem arka plan programı, bir cihaza erişmesine izin verilen kullanıcı ve grubu atamaktan sorumludur. Bunun gibi bir kural, belirtilen tedarikçi firma ve ürün kimlikleri ile 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 yerine cihazınızın onaltılı tedarikçi firma ve ürün kimliklerini yazın. Örneğin ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11", bir Nexus One telefonla eşleşir. Bunlar, her zamanki "0x" ön eki olmadan yazılmalı ve doğru şekilde tanınması için hepsi küçük harfle yazılmalıdır. Cihazınızın kimliklerini bulmak için lsusb komut satırı aracını çalıştırın.

Bu kural, /etc/udev/rules.d dizinindeki bir dosyaya yerleştirilmelidir ve cihaz fişe takıldığında geçerli olur. Udev'i yeniden başlatmanıza gerek yoktur.

Android

Android platformu Linux tabanlıdır ancak sistem yapılandırmasında herhangi bir değişiklik yapılması gerekmez. Varsayılan olarak, işletim sisteminde 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şacaklarını bilmelidir. Kullanıcı requestDevice() çağrısına yanıt olarak bir cihaz seçtiğinde Android, Chrome'un bu cihaza erişmesine izin verip vermeyeceğinizi soran bir istem görüntüler. Bu istem, bir kullanıcı 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'tan daha fazla cihaza erişilebilir. Örneğin, Android SDK'da seri cihazlarla iletişim kurmak için bir API bulunmadığından, genellikle USB-seri adaptörler tarafından uygulanan USB CDC-ACM sınıfı dikkate değer bir eksikliktir.

ChromeOS

ChromeOS, Linux'a da dayanır ve sistem yapılandırmasında herhangi bir değişiklik gerektirmez. allow_broker hizmeti USB cihazlarına erişimi kontrol eder ve sahiplenilmemiş en az bir arayüz olduğu sürece tarayıcının bu cihazlara erişmesine izin verir.

Windows

Windows sürücü modelinde ek bir gereklilik bulunuyor. USB cihazı, kullanıcı uygulamasından açabilme olanağının üzerindeki platformlardan farklı olarak, sürücü yüklü olmasa bile varsayılan seçenek bu değildir. Bunun yerine, cihaza erişmek üzere kullanılan arayüz uygulamalarının sağlanması amacıyla, WinUSB adlı özel bir sürücünün yüklenmesi gerekir. Bu işlem, sistemde yüklü bir özel sürücü bilgileri dosyası (INF) ile veya numaralandırma sırasında Microsoft OS Uyumluluk Açıklayıcılarını sağlamak için cihazın donanım yazılımı değiştirilerek yapılabilir.

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

Sürücü bilgi dosyası, Windows'a bir cihazla ilk kez karşılaştığında ne yapılacağını bildirir. Kullanıcının sistemi zaten WinUSB sürücüsünü içerdiğinden, INF dosyasının tedarikçi firmanızı ve ürün kimliğinizi bu yeni yükleme kuralıyla ilişkilendirmesi için tek gereken yeterlidir. Aşağıdaki dosya temel bir örnektir. .inf uzantısına sahip bir dosyaya kaydedin, "X" ile işaretli bölümleri değiştirin, ardından sağ tıklayın ve içerik 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ın DeviceInterfaceGUID grubunu yapılandırır. Bir uygulamanın Windows API aracılığıyla kendisini bulması ve ona bağlanması için her cihaz arayüzünün bir GUID'si olmalı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ünün WinUSB sürücüsüyle değiştirilmesini sağlayan kolay bir arayüz sağlar.

Microsoft OS uyumluluğu açıklayıcıları

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

WebUSB açıklayıcılarını ayarladıktan sonra, Microsoft'un işletim sistemi uyumluluk tanımlayıcılarını da kolayca ekleyebilirsiniz. Öncelikle BOS açıklayıcısını bu ek platform özelliği açıklayıcıyla genişletin. wTotalLength ve bNumDeviceCaps öğelerini buna göre güncellediğinizden emin olun.

WebUSB açıklayı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 değerini seçtim. wIndex içine yerleştirilen 0x07, cihazdan Microsoft OS 2.0 Açıklayıcı Grubu'nu alma komutudur.

Bir USB cihazının birden çok işlevi olabilir. Bu nedenle, açıklayıcı grubunun ilk bölümünde, sonraki özelliklerin hangi işlevle ilişkili olduğu açıklanır. Aşağıdaki örnekte, birleşik bir cihazın 1. arayüzü yapılandırılır. Açıklayıcı, işletim sistemine bu arayüzle ilgili 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 özelliği açıklayıcısı, yukarıdaki INF örneğinin [Dev_AddReg] bölümüne benzer şekilde çalışır ve bu işleve cihaz arayüzü GUID'si atayacak bir kayıt defteri özelliği ayarlar.

Windows, bu bilgi için cihazı yalnızca bir kez sorgular. Cihaz geçerli tanımlayıcılarla yanıt vermezse cihaz tekrar bağlandığında tekrar sorulmaz. Microsoft, bir cihazı numaralandırırken oluşturulan kayıt defteri girişlerini açıklayan bir USB Cihaz Kaydı Girişleri listesini sağlamıştır. Test sırasında bir cihaz için oluşturulan girişleri silin. Böylece Windows, tanımlayıcıları tekrar okumayı dener.

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ı hem de Microsoft OS tanımlayıcıları içeren WebUSB uyumlu cihazları uygulayan örnek kodlar şu projelerde bulunabilir:

• WebLight
• WebUSB Arduino Kitaplığı