ساخت دستگاه برای WebUSB

برای استفاده کامل از WebUSB API دستگاهی بسازید.

Reilly Grant

این مقاله نحوه ساخت دستگاهی برای استفاده کامل از WebUSB API را توضیح می دهد. برای معرفی مختصر خود API، به دسترسی به دستگاه‌های USB در وب مراجعه کنید.

پس زمینه

گذرگاه سریال جهانی (USB) به رایج‌ترین رابط فیزیکی برای اتصال وسایل جانبی به دستگاه‌های رایانه رومیزی و موبایل تبدیل شده است. علاوه بر تعریف مشخصات الکتریکی اتوبوس و یک مدل کلی برای برقراری ارتباط با یک دستگاه، مشخصات USB شامل مجموعه ای از مشخصات کلاس دستگاه می باشد. اینها مدل های کلی برای کلاس های خاصی از دستگاه ها مانند ذخیره سازی، صوتی، تصویری، شبکه و غیره هستند که سازندگان دستگاه می توانند آنها را پیاده سازی کنند. مزیت این مشخصات کلاس دستگاه این است که یک فروشنده سیستم عامل می تواند یک درایور را بر اساس مشخصات کلاس (یک "درایور کلاس") پیاده سازی کند و هر دستگاهی که آن کلاس را پیاده سازی کند پشتیبانی می شود. این یک پیشرفت بزرگ نسبت به هر سازنده ای بود که نیاز به نوشتن درایورهای دستگاه خود داشت.

با این حال، برخی از دستگاه‌ها در یکی از این کلاس‌های دستگاه استاندارد قرار نمی‌گیرند. در عوض، یک سازنده ممکن است تصمیم بگیرد که دستگاه خود را به عنوان یک کلاس خاص فروشنده برچسب گذاری کند. در این مورد، سیستم عامل بر اساس اطلاعات ارائه شده در بسته درایور فروشنده، معمولاً مجموعه‌ای از شناسه‌های فروشنده و محصول که برای پیاده‌سازی یک پروتکل خاص فروشنده مشخص هستند، انتخاب می‌کند که کدام درایور دستگاه را بارگیری کند.

یکی دیگر از ویژگی های USB این است که دستگاه ها ممکن است چندین رابط را برای میزبانی که به آن متصل هستند ارائه دهند. هر رابط می تواند یک کلاس استاندارد شده را پیاده سازی کند یا خاص فروشنده باشد. هنگامی که یک سیستم عامل درایورهای مناسب را برای مدیریت دستگاه انتخاب می کند، هر رابط می تواند توسط یک درایور متفاوت ادعا شود. به عنوان مثال، یک وب‌کم USB معمولاً دو رابط ارائه می‌دهد، یکی کلاس ویدیویی USB (برای دوربین) و دیگری کلاس صوتی USB (برای میکروفون) را پیاده‌سازی می‌کند. سیستم عامل یک "درایور وب کم" را بارگیری نمی کند، بلکه درایورهای کلاس صوتی و تصویری مستقل را بارگیری می کند که مسئولیت عملکردهای جداگانه دستگاه را بر عهده می گیرند. این ترکیب کلاس های رابط انعطاف پذیری بیشتری را فراهم می کند.

اصول API

بسیاری از کلاس‌های USB استاندارد دارای APIهای وب مربوطه هستند. به عنوان مثال، یک صفحه می تواند با استفاده از getUserMedia() از یک دستگاه کلاس ویدیویی فیلم بگیرد یا با گوش دادن به KeyboardEvents یا PointerEvents یا با استفاده از Gamepad یا WebHID API، رویدادهای ورودی را از دستگاه کلاس رابط انسانی (HID) دریافت کند. همانطور که همه دستگاه‌ها تعریف کلاس استاندارد شده را پیاده‌سازی نمی‌کنند، همه دستگاه‌ها ویژگی‌هایی را اجرا نمی‌کنند که با APIهای پلتفرم وب موجود مطابقت دارند. در این صورت، WebUSB API می‌تواند این شکاف را با ارائه راهی برای سایت‌ها برای ادعای یک رابط خاص فروشنده و پیاده‌سازی پشتیبانی از آن مستقیماً در صفحه خود، پر کند.

الزامات خاص برای دسترسی به یک دستگاه از طریق WebUSB از پلت فرمی به پلتفرم دیگر به دلیل تفاوت در نحوه مدیریت دستگاه های USB توسط سیستم عامل ها کمی متفاوت است، اما شرط اساسی این است که دستگاه از قبل دارای درایوری نباشد که ادعا می کند رابط صفحه می خواهد کنترل کند. این می تواند یک درایور کلاس عمومی ارائه شده توسط فروشنده سیستم عامل یا یک درایور دستگاه ارائه شده توسط فروشنده باشد. از آنجایی که دستگاه‌های USB می‌توانند چندین رابط ارائه دهند، که هر کدام ممکن است درایور خاص خود را داشته باشند، می‌توان دستگاهی ساخت که برخی از رابط‌ها توسط درایور ادعا شده و برخی دیگر در دسترس مرورگر قرار می‌گیرند.

به عنوان مثال، یک صفحه کلید USB سطح بالا ممکن است یک رابط کلاس HID ارائه کند که توسط زیرسیستم ورودی سیستم عامل ادعا می شود و یک رابط خاص فروشنده که برای استفاده توسط ابزار پیکربندی در دسترس WebUSB باقی می ماند. این ابزار را می توان در وب سایت سازنده ارائه کرد و به کاربر این امکان را می دهد تا جنبه هایی از رفتار دستگاه مانند کلیدهای ماکرو و جلوه های نوری را بدون نصب نرم افزار مخصوص پلتفرم تغییر دهد. توصیف کننده پیکربندی چنین دستگاهی چیزی شبیه به این خواهد بود:

توصیفگر پیکربندی از چندین توصیفگر به هم پیوسته تشکیل شده است. هر کدام با فیلدهای bLength و bDescriptorType شروع می شوند تا بتوان آنها را شناسایی کرد. اولین رابط یک رابط HID با یک توصیفگر HID مرتبط و یک نقطه پایانی است که برای ارائه رویدادهای ورودی به سیستم عامل استفاده می شود. رابط دوم یک رابط خاص فروشنده با دو نقطه پایانی است که می تواند برای ارسال دستورات به دستگاه و دریافت پاسخ در ازای آن استفاده شود.

توصیفگرهای WebUSB

در حالی که WebUSB می‌تواند با بسیاری از دستگاه‌ها بدون تغییرات سفت‌افزار کار کند، عملکرد اضافی با علامت‌گذاری دستگاه با توصیف‌گرهای خاص که نشان‌دهنده پشتیبانی از WebUSB است، فعال می‌شود. به عنوان مثال، می‌توانید URL صفحه فرود را مشخص کنید که مرورگر بتواند کاربر را هنگامی که دستگاه شما وصل است به آن هدایت کند.

فروشگاه اشیاء دستگاه باینری (BOS) مفهومی است که در USB 3.0 معرفی شده است اما به عنوان بخشی از نسخه 2.1 به دستگاه های USB 2.0 نیز پشتیبان داده شده است. اعلام پشتیبانی از WebUSB با گنجاندن توصیفگر قابلیت پلتفرم زیر در توصیفگر BOS شروع می شود:

قابلیت پلتفرم UUID این را به عنوان یک توصیفگر قابلیت پلتفرم WebUSB شناسایی می کند که اطلاعات اولیه را در مورد دستگاه ارائه می دهد. برای اینکه مرورگر اطلاعات بیشتری درباره دستگاه دریافت کند، از مقدار bVendorCode برای ارسال درخواست‌های اضافی به دستگاه استفاده می‌کند. تنها درخواستی که در حال حاضر مشخص شده است GET_URL است که یک توصیفگر URL را برمی گرداند. اینها شبیه به توصیفگرهای رشته هستند اما برای کدگذاری URLها در کمترین بایت طراحی شده اند. توصیفگر URL برای "https://google.com" به شکل زیر است:

هنگامی که دستگاه شما برای اولین بار به برق وصل می شود، مرورگر با صدور این انتقال کنترل استاندارد GET_DESCRIPTOR توصیفگر BOS را می خواند:

این درخواست معمولاً دو بار انجام می شود، بار اول با wLength به اندازه کافی بزرگ به طوری که میزبان بدون تعهد به انتقال بزرگ، مقدار فیلد wTotalLength را دریابد و سپس دوباره زمانی که طول کامل توصیفگر مشخص شد.

اگر توصیفگر قابلیت پلتفرم WebUSB دارای فیلد iLandingPage روی مقدار غیر صفر باشد، مرورگر یک درخواست GET_URL مخصوص WebUSB را با صدور یک انتقال کنترل با تنظیم bRequest به مقدار bVendorCode از توصیفگر قابلیت پلتفرم و تنظیم wValue به مقدار انجام می دهد. مقدار iLandingPage . کد درخواست برای GET_URL ( 0x02 ) در wIndex می رود:

مجدداً، این درخواست ممکن است دو بار صادر شود تا ابتدا طول توصیفگر خوانده شده را بررسی کنیم.

ملاحظات خاص پلت فرم

در حالی که WebUSB API تلاش می‌کند تا یک رابط ثابت برای دسترسی به دستگاه‌های USB ارائه دهد، توسعه‌دهندگان همچنان باید از الزامات تحمیل شده بر روی برنامه‌ها مانند الزامات مرورگرهای وب برای دسترسی به دستگاه‌ها آگاه باشند.

macOS

هیچ چیز خاصی برای macOS لازم نیست. وب‌سایتی که از WebUSB استفاده می‌کند می‌تواند به دستگاه متصل شود و هر رابطی را که توسط درایور هسته یا برنامه دیگری ادعا نشده است ادعا کند.

لینوکس

لینوکس مانند macOS است اما به طور پیش‌فرض اکثر توزیع‌ها حساب‌های کاربری را با مجوز باز کردن دستگاه‌های USB تنظیم نمی‌کنند. یک شبح سیستم به نام udev مسئول اختصاص دادن کاربر و گروه مجاز به دسترسی به یک دستگاه است. قاعده‌ای مانند این، مالکیت دستگاهی را که با شناسه‌های فروشنده و محصول منطبق است به گروه plugdev که یک گروه رایج برای کاربرانی است که به تجهیزات جانبی دسترسی دارند، اختصاص می‌دهد:

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

XXXX با شناسه فروشنده و محصول هگزا دسیمال دستگاه خود جایگزین کنید، به عنوان مثال ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11" با تلفن Nexus One مطابقت دارد. اینها باید بدون پیشوند معمول "0x" نوشته شوند و همه حروف کوچک به درستی تشخیص داده شوند. برای پیدا کردن شناسه های دستگاه خود، ابزار خط فرمان lsusb را اجرا کنید.

این قانون باید در فایلی در پوشه /etc/udev/rules.d قرار داده شود و به محض وصل شدن دستگاه اعمال می شود. نیازی به راه اندازی مجدد udev نیست.

اندروید

پلتفرم اندروید مبتنی بر لینوکس است اما نیازی به هیچ تغییری در پیکربندی سیستم ندارد. به طور پیش فرض هر دستگاهی که درایور داخلی در سیستم عامل نداشته باشد در دسترس مرورگر است. با این حال، توسعه دهندگان باید بدانند که کاربران هنگام اتصال به دستگاه با یک مرحله اضافی روبرو می شوند. هنگامی که کاربر دستگاهی را در پاسخ به یک تماس با requestDevice() انتخاب کرد، Android درخواستی را نمایش می‌دهد که از شما می‌پرسد آیا به Chrome اجازه دسترسی به آن را می‌دهد یا خیر. همچنین اگر کاربر به وب‌سایتی که قبلاً مجوز اتصال به دستگاهی را دارد بازگردد و وب‌سایت open() فراخوانی کند، این اعلان دوباره ظاهر می‌شود.

علاوه بر این، دستگاه‌های بیشتری در Android نسبت به لینوکس دسکتاپ در دسترس خواهند بود، زیرا درایورهای کمتری به طور پیش‌فرض گنجانده شده است. به عنوان مثال، یک حذف قابل توجه، کلاس USB CDC-ACM است که معمولاً توسط آداپتورهای USB-to-Serial پیاده سازی می شود، زیرا هیچ API در Android SDK برای برقراری ارتباط با دستگاه سریال وجود ندارد.

ChromeOS

ChromeOS نیز مبتنی بر لینوکس است و همچنین نیازی به تغییر در پیکربندی سیستم ندارد. سرویس permission_broker دسترسی به دستگاه‌های USB را کنترل می‌کند و به مرورگر اجازه می‌دهد تا زمانی که حداقل یک رابط بدون ادعا وجود دارد به آنها دسترسی داشته باشد.

ویندوز

مدل درایور ویندوز یک نیاز اضافی را معرفی می کند. برخلاف پلتفرم‌های بالاتر، توانایی باز کردن یک دستگاه USB از یک برنامه کاربر پیش‌فرض نیست، حتی اگر درایوری بارگذاری نشده باشد. در عوض یک درایور ویژه به نام WinUSB وجود دارد که باید بارگذاری شود تا برنامه‌های رابطی که برای دسترسی به دستگاه استفاده می‌کنند، ارائه شود. این کار را می توان با یک فایل اطلاعات راننده سفارشی (INF) نصب شده بر روی سیستم یا با تغییر سفت افزار دستگاه برای ارائه توصیفگرهای سازگاری سیستم عامل مایکروسافت در حین شمارش انجام داد.

فایل اطلاعات راننده (INF)

یک فایل اطلاعات درایور به ویندوز می گوید که هنگام مواجهه با دستگاه برای اولین بار چه کاری انجام دهد. از آنجایی که سیستم کاربر از قبل شامل درایور WinUSB است، تنها چیزی که لازم است این است که فایل INF فروشنده و شناسه محصول شما را با این قانون نصب جدید مرتبط کند. فایل زیر یک مثال اساسی است. آن را در فایلی با پسوند .inf ذخیره کنید، بخش هایی که با "X" مشخص شده اند را تغییر دهید، سپس روی آن کلیک راست کرده و "Install" را از منوی زمینه انتخاب کنید.

[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] مجموعه ای از DeviceInterfaceGUID ها را برای دستگاه پیکربندی می کند. هر رابط دستگاه باید یک GUID داشته باشد تا برنامه بتواند آن را از طریق API ویندوز پیدا کند و به آن متصل شود. از cmdlet New-Guid PowerShell یا یک ابزار آنلاین برای ایجاد یک GUID تصادفی استفاده کنید.

برای اهداف توسعه، ابزار Zadig یک رابط آسان برای جایگزینی درایور بارگذاری شده برای رابط USB با درایور WinUSB فراهم می کند.

توصیفگرهای سازگاری سیستم عامل مایکروسافت

روش فایل INF بالا دست و پا گیر است زیرا نیاز به پیکربندی ماشین هر کاربر قبل از زمان دارد. ویندوز 8.1 و بالاتر با استفاده از توصیفگرهای USB سفارشی جایگزینی را ارائه می دهد. این توصیفگرها هنگامی که دستگاه برای اولین بار به برق وصل می شود اطلاعاتی را در اختیار سیستم عامل ویندوز قرار می دهد که معمولاً در فایل INF گنجانده می شود.

هنگامی که توصیفگرهای WebUSB را تنظیم کردید، اضافه کردن توصیفگرهای سازگاری سیستم عامل مایکروسافت نیز آسان است. ابتدا توصیفگر BOS را با این توصیفگر قابلیت پلتفرم اضافی گسترش دهید. حتماً wTotalLength و bNumDeviceCaps را به‌روزرسانی کنید تا آن را در نظر بگیرید.

همانند توصیفگرهای WebUSB، باید یک مقدار bRequest را انتخاب کنید تا در انتقال کنترل مربوط به این توصیفگرها استفاده شود. در این مثال من 0x02 انتخاب کرده ام. 0x07 ، قرار داده شده در wIndex ، دستور بازیابی Microsoft OS 2.0 Descriptor Set از دستگاه است.

یک دستگاه USB می‌تواند عملکردهای متعددی داشته باشد، بنابراین قسمت اول مجموعه توصیفگر توضیح می‌دهد که ویژگی‌های بعدی با کدام عملکرد مرتبط هستند. مثال زیر رابط 1 یک دستگاه ترکیبی را پیکربندی می کند. توصیفگر دو اطلاعات مهم در مورد این رابط به سیستم عامل می دهد. توصیفگر شناسه سازگار به ویندوز می گوید که این دستگاه با درایور WinUSB سازگار است. توصیفگر ویژگی رجیستری مشابه بخش [Dev_AddReg] در مثال INF بالا عمل می کند و یک ویژگی رجیستری را تنظیم می کند تا به این تابع یک GUID رابط دستگاه اختصاص دهد.

ویندوز این اطلاعات را فقط یک بار از دستگاه استعلام می کند. اگر دستگاه با توصیفگرهای معتبر پاسخ ندهد، دفعه بعد که دستگاه وصل می شود، دوباره سؤال نخواهد کرد. مایکروسافت فهرستی از ورودی‌های رجیستری دستگاه USB را ارائه کرده است که ورودی‌های رجیستری ایجاد شده هنگام شمارش دستگاه را توصیف می‌کند. هنگام آزمایش، ورودی های ایجاد شده برای یک دستگاه را حذف کنید تا ویندوز مجبور شود دوباره سعی کند توصیفگرها را بخواند.

برای اطلاعات بیشتر، پست وبلاگ مایکروسافت را در مورد نحوه استفاده از این توصیفگرها بررسی کنید.

نمونه ها

نمونه کد پیاده‌سازی دستگاه‌های آگاه از WebUSB که شامل توصیفگرهای WebUSB و توصیف‌گرهای سیستم‌عامل مایکروسافت است را می‌توان در این پروژه‌ها یافت:

• WebLight
• کتابخانه آردوینو WebUSB