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

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

ریلی گرانت

این مقاله نحوه ساخت دستگاهی برای استفاده کامل از 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 باقی می ماند. این ابزار را می توان در وب سایت سازنده ارائه کرد و به کاربر این امکان را می دهد تا جنبه هایی از رفتار دستگاه مانند کلیدهای ماکرو و جلوه های نوری را بدون نصب نرم افزار مخصوص پلتفرم تغییر دهد. توصیف کننده پیکربندی چنین دستگاهی چیزی شبیه به این خواهد بود:

ارزش میدان توضیحات
توصیف کننده پیکربندی
0x09 طول اندازه این توصیفگر
0x02 bDescriptorType توصیف کننده پیکربندی
0x0039 طول کل طول کل این سری از توصیفگرها
0x02 bNumInterfaces تعداد رابط ها
0x01 bConfigurationValue پیکربندی 1
0x00 iConfiguration نام پیکربندی (هیچ)
0b1010000 bmAttributes دستگاه خود تغذیه با بیدار شدن از راه دور
0x32 bMaxPower حداکثر توان با افزایش 2 میلی آمپر بیان می شود
توصیفگر رابط
0x09 طول اندازه این توصیفگر
0x04 bDescriptorType توصیفگر رابط
0x00 bInterfaceNumber رابط 0
0x00 bAlternateSetting تنظیم جایگزین 0 (پیش‌فرض)
0x01 bNumEndpoints 1 نقطه پایانی
0x03 bInterfaceClass کلاس رابط HID
0x01 bInterfaceSubClass زیر کلاس رابط بوت
0x01 پروتکل bInterface صفحه کلید
0x00 iInterface نام رابط (هیچکدام)
توصیفگر HID
0x09 طول اندازه این توصیفگر
0x21 bDescriptorType توصیفگر HID
0x0101 bcdHID HID نسخه 1.1
0x00 bCountryCode کشور هدف سخت افزار
0x01 bNumDescriptors تعداد توصیفگرهای کلاس HID برای دنبال کردن
0x22 bDescriptorType نوع توصیفگر گزارش
0x003F wDescriptorLength طول کل توصیفگر گزارش
توصیفگر نقطه پایانی
0x07 طول اندازه این توصیفگر
0x05 bDescriptorType توصیفگر نقطه پایانی
0b10000001 bEndpointAddress نقطه پایانی 1 (IN)
0b00000011 bmAttributes قطع کنید
0x0008 wMaxPacketSize بسته های 8 بایتی
0x0A bInterval فاصله 10 میلی ثانیه
توصیفگر رابط
0x09 طول اندازه این توصیفگر
0x04 bDescriptorType توصیفگر رابط
0x01 bInterfaceNumber رابط 1
0x00 bAlternateSetting تنظیم جایگزین 0 (پیش‌فرض)
0x02 bNumEndpoints 2 نقطه پایانی
0xFF bInterfaceClass کلاس رابط خاص فروشنده
0x00 bInterfaceSubClass
0x00 پروتکل bInterface
0x00 iInterface نام رابط (هیچکدام)
توصیفگر نقطه پایانی
0x07 طول اندازه این توصیفگر
0x05 bDescriptorType توصیفگر نقطه پایانی
0b10000010 bEndpointAddress نقطه پایانی 1 (IN)
0b00000010 bmAttributes فله
0x0040 wMaxPacketSize بسته های 64 بایتی
0x00 bInterval برای نقاط پایانی انبوه وجود ندارد
توصیفگر نقطه پایانی
0x07 طول اندازه این توصیفگر
0x05 bDescriptorType توصیفگر نقطه پایانی
0b00000011 bEndpointAddress نقطه پایانی 3 (خروج)
0b00000010 bmAttributes فله
0x0040 wMaxPacketSize بسته های 64 بایتی
0x00 bInterval برای نقاط پایانی انبوه وجود ندارد

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

توصیفگرهای WebUSB

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

اسکرین شات اعلان WebUSB در کروم
اطلاع رسانی WebUSB.

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

ارزش میدان توضیحات
دستگاه باینری Object Store توصیف
0x05 طول اندازه این توصیفگر
0x0F bDescriptorType دستگاه باینری Object Store توصیف
0x001D طول کل طول کل این سری از توصیفگرها
0x01 bNumDeviceCaps تعداد توصیفگرهای قابلیت دستگاه در BOS
توصیف کننده قابلیت پلت فرم WebUSB
0x18 طول اندازه این توصیفگر
0x10 bDescriptorType توصیف کننده قابلیت دستگاه
0x05 bDevCapabilityType توصیف کننده قابلیت پلتفرم
0x00 b رزرو شده است
{0x38, 0xB6, 0x08, 0x34, 0xA9, 0x09, 0xA0, 0x47, 0x8B, 0xFD, 0xA0, 0x76, 0x88, 0x15, 0xB6, 0x65} PlatformCapablityUUID GUID توصیفگر قابلیت پلت فرم WebUSB در قالب کمی هندی
0x0100 bcdVersion توصیفگر WebUSB نسخه 1.0
0x01 bVendorCode bRequest مقدار برای WebUSB
0x01 آی لندینگ پیج URL برای صفحه فرود

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

ارزش میدان توضیحات
توصیف کننده URL
0x0D طول اندازه این توصیفگر
0x03 bDescriptorType توصیف کننده URL
0x01 bScheme https://
"google.com" URL محتوای URL کدگذاری شده UTF-8

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

bmRequestType b درخواست wvalue wIndex طول داده ها (پاسخ)
0b10000000 0x06 0x0F00 0x0000 * توصیفگر BOS

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

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

bmRequestType b درخواست wvalue wIndex طول داده ها (پاسخ)
0b11000000 0x01 0x0001 0x0002 * توصیفگر URL

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

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

در حالی که 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 را به‌روزرسانی کنید تا آن را در نظر بگیرید.

ارزش میدان توضیحات
توصیف کننده قابلیت پلت فرم Microsoft OS 2.0
0x1C طول اندازه این توصیفگر
0x10 bDescriptorType توصیف کننده قابلیت دستگاه
0x05 bDevCapabilityType توصیف کننده قابلیت پلتفرم
0x00 b رزرو شده است
{0xDF, 0x60, 0xDD, 0xD8, 0x89, 0x45, 0xC7, 0x4C, 0x9C, 0xD2, 0x65, 0x9D, 0x9E, 0x64, 0x8A, 0x9F} PlatformCapablityUUID مایکروسافت OS 2.0 توصیفگر سازگاری پلت فرم GUID در قالب کمی هندی
0x06030000 نسخه dwWindows حداقل نسخه ویندوز سازگار (ویندوز 8.1)
0x00B2 wMSOSDescriptorSetTotalLength طول کل مجموعه توصیفگر
0x02 bMS_VendorCode مقدار درخواست برای بازیابی بیشتر توصیفگرهای مایکروسافت
0x00 bAltEnumCode دستگاه از شمارش جایگزین پشتیبانی نمی کند

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

bmRequestType b درخواست wvalue wIndex طول داده ها (پاسخ)
0b11000000 0x02 0x0000 0x0007 * مجموعه توصیفگر MS OS 2.0

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

ارزش میدان توضیحات
هدر مجموعه توصیفگر سیستم عامل Microsoft OS 2.0
0x000A طول اندازه این توصیفگر
0x0000 wDescriptorType توصیفگر مجموعه سرصفحه
0x06030000 نسخه dwWindows حداقل نسخه ویندوز سازگار (ویندوز 8.1)
0x00B2 طول کل طول کل مجموعه توصیفگر
سربرگ زیر مجموعه پیکربندی Microsoft OS 2.0
0x0008 طول اندازه این توصیفگر
0x0001 wDescriptorType شرح سرصفحه زیر مجموعه پیکربندی.
0x00 bConfigurationValue برای پیکربندی 1 اعمال می شود (ایندکس شده از 0 علیرغم پیکربندی هایی که معمولاً از 1 نمایه می شوند)
0x00 b رزرو شده است باید روی 0 تنظیم شود
0x00A8 طول کل طول کل زیر مجموعه از جمله این سرصفحه
هدر زیرمجموعه تابع Microsoft OS 2.0
0x0008 طول اندازه این توصیفگر
0x0002 wDescriptorType توصیفگر سرصفحه زیر مجموعه تابع
0x01 bFirstInterface رابط اول تابع
0x00 b رزرو شده است باید روی 0 تنظیم شود
0x00A0 wSubsetLength طول کل زیر مجموعه از جمله این سرصفحه
شرح شناسه سازگار با سیستم عامل Microsoft 2.0
0x0014 طول اندازه این توصیفگر
0x0003 wDescriptorType توصیفگر شناسه سازگار
"WINUSB\0\0" شناسه سازگار رشته ASCII به 8 بایت اضافه شد
"\0\0\0\0\0\0\0\0" شناسه SubCompatible رشته ASCII به 8 بایت اضافه شد
توصیفگر ویژگی رجیستری Microsoft OS 2.0
0x0084 طول اندازه این توصیفگر
0x0004 wDescriptorType توصیف کننده اموال ثبتی
0x0007 wPropertyDataType REG_MULTI_SZ
0x002A wPropertyNameLength طول نام ملک
"DeviceInterfaceGUIDs\0" PropertyName نام دارایی با پایان دهنده تهی کدگذاری شده در UTF-16LE
0x0050 wPropertyDataLength طول ارزش ملک
"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}\0\0" PropertyData GUID به علاوه دو پایان دهنده تهی کدگذاری شده در UTF-16LE

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

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

نمونه ها

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