إنشاء جهاز لـ WebUSB

يمكنك تصميم جهاز لتحقيق الاستفادة الكاملة من WebUSB API.

Reilly Grant

توضّح هذه المقالة كيفية إنشاء جهاز للاستفادة إلى أقصى حد من WebUSB API. للحصول على مقدّمة موجزة عن واجهة برمجة التطبيقات نفسها، يُرجى الاطّلاع على مقالة الوصول إلى أجهزة USB على الويب.

الخلفية

أصبح الناقل التسلسلي العالمي (USB) هو الواجهة المادية الأكثر شيوعًا لربط الأجهزة الطرفية بأجهزة الكمبيوتر المكتبي والمحمول. بالإضافة إلى تحديد الخصائص الكهربائية للناقل ونموذج عام للتواصل مع الجهاز، تتضمّن مواصفات USB مجموعة من مواصفات فئة الجهاز. هذه نماذج عامة لفئات معيّنة من الأجهزة، مثل سعة التخزين والصوت والفيديو والشبكات وما إلى ذلك، والتي يمكن للشركات المصنّعة للأجهزة تنفيذها. تتمثل ميزة مواصفات فئات الأجهزة هذه في أنّه يمكن لموفّر نظام التشغيل تنفيذ برنامج تشغيل واحد استنادًا إلى مواصفات الفئة (يُعرف باسم "برنامج تشغيل الفئة")، وسيكون أي جهاز يستخدم هذه الفئة متوافقًا. كان هذا تحسينًا كبيرًا مقارنةً بوقت كان فيه كلّ مصنع يحتاج إلى كتابة برامج تشغيل الأجهزة الخاصة به.

ومع ذلك، لا تندرج بعض الأجهزة ضمن إحدى فئات الأجهزة العادية هذه. وبدلاً من ذلك، قد تختار الشركة المُصنّعة تصنيف جهازه على أنّه تابع للفئة الخاصة بالمورِّد. في هذه الحالة، يختار نظام التشغيل برنامج تشغيل الجهاز المراد تحميله بناءً على المعلومات المقدمة في حزمة برنامج التشغيل للمورد، وعادة ما تكون مجموعة من معرّفات المنتج والبائعين المعروفة لتنفيذ بروتوكول معين خاص بالمورد.

من الميزات الأخرى لواجهة USB أنّ الأجهزة قد توفّر واجهات متعددة للجهاز المضيف الذي تكون متصلة به. يمكن لكل واجهة تنفيذ إما فئة موحدة أو أن تكون خاصة بالبائع. عندما يختار نظام التشغيل برامج التشغيل المناسبة للتعامل مع الجهاز، يمكن المطالبة بكل واجهة من خلال برنامج تشغيل مختلف. على سبيل المثال، توفّر كاميرا الويب USB عادةً واجهتَين، إحداهما تطبّق فئة بث الفيديو عبر USB (للكاميرا) والأخرى تطبّق فئة الصوت عبر USB (للميكروفون). لا يحمِّل نظام التشغيل "برنامج تشغيل كاميرا ويب" واحدًا، بل يحمِّل بدلاً من ذلك برامج تشغيل مستقلة للفئة الصوتية والفيديوية تتحمل مسؤولية الوظائف المنفصلة للجهاز. توفّر هذه البنية لصفوف الواجهات مرونة أكبر.

أساسيات واجهة برمجة التطبيقات

تحتوي العديد من فئات USB العادية على واجهات برمجة تطبيقات ويب مقابلة. على سبيل المثال، يمكن ل الصفحة تسجيل فيديو من جهاز من فئة الفيديو باستخدام getUserMedia() أو تلقّي أحداث إدخال من جهاز من فئة واجهة المستخدم (HID) من خلال الاستماع إلى KeyboardEvents أو PointerEvents، أو باستخدام Gamepad أو واجهة برمجة التطبيقات WebHID. تمامًا كما أنّ بعض الأجهزة لا تطبّق تعريفًا موحّدًا للفئة، لا تطبّق بعض الأجهزة ميزات تتوافق مع واجهات برمجة تطبيقات منصات الويب الحالية. في هذه الحالة، يمكن لواجهة برمجة التطبيقات WebUSB سدّ هذه الفجوة من خلال توفير طريقة للمواقع الإلكترونية للمطالبة بواجهة خاصة بالمورّد وتنفيذ دعم لها مباشرةً من داخل صفحتها.

تختلف المتطلبات المحدّدة للوصول إلى جهاز عبر WebUSB قليلاً من منصة إلى أخرى بسبب الاختلافات في كيفية إدارة أنظمة التشغيل لأجهزة USB ، ولكن الشرط الأساسي هو أنّه يجب ألا يكون لدى الجهاز برنامج تشغيل يطالب بالواجهة التي تريد الصفحة التحكّم فيها. يمكن أن يكون إما برنامج تشغيل عام للفئة يوفره بائع نظام التشغيل أو برنامج تشغيل الجهاز الذي يقدمه المورد. بما أنّ أجهزة USB يمكن أن توفّر واجهات متعددة، قد يكون لكل منها برنامج تشغيل خاص بها، من الممكن إنشاء جهاز يطالب برنامج تشغيل ببعض واجهاته ويترك البعض الآخر متاحًا للمتصفح.

على سبيل المثال، قد توفّر لوحة مفاتيح USB عالية الجودة واجهة فئة HID سيطالب بها النظام الفرعي للإدخال في نظام التشغيل وواجهة خاصة بالمورّد تظل متاحة لواجهة WebUSB لاستخدامها من خلال أداة ضبط. يمكن عرض هذه الأداة على الموقع الإلكتروني للشركة المصنّعة، ما يتيح للمستخدم تغيير بعض جوانب سلوك الجهاز، مثل مفاتيح الماكرو والتأثيرات الضوئية، بدون تثبيت أي برامج خاصة بالنظام الأساسي. سيبدو وصف إعدادات هذا الجهاز على النحو التالي:

ملاحظة: يتم عرض القيم في هذا الجدول والجداول الأخرى في هذا المستند باستخدام النظام الست عشري أو الثنائي، أيهما أسهل للقراءة. USB عبارة عن ناقل صغير، لذا فإن أي قيمة صحيحة تزيد عن 1 بايت يجب إرسال البايت الأقل أهمية أولاً.

القيمة	الحقل	الوصف
وصف الإعدادات
0x09	bLength	حجم هذا الوصف
0x02	bDescriptorType	واصف الإعدادات
0x0039	wTotalLength	إجمالي طول هذه السلسلة من الأوصاف
0x02	bNumInterfaces	عدد الواجهات
0x01	bConfigurationValue	الإعداد 1
0x00	iConfiguration	اسم الإعداد (بدون)
0b1010000	bmAttributes	جهاز ذاتي التشغيل مع تفعيل عن بُعد
0x32	bMaxPower	يتم التعبير عن الحد الأقصى للطاقة بزيادة قدرها 2 مللي أمبير.
واصف الواجهة
0x09	bLength	حجم هذا الوصف
0x04	bDescriptorType	واصف الواجهة
0x00	bInterfaceNumber	الواجهة 0
0x00	bAlternateSetting	الإعداد البديل 0 (تلقائي)
0x01	bNumEndpoints	نقطة نهاية واحدة
0x03	bInterfaceClass	فئة واجهة HID
0x01	bInterfaceSubClass	الفئة الفرعية لواجهة الإقلاع
0x01	bInterfaceProtocol	لوحة المفاتيح
0x00	iInterface	اسم الواجهة (لا شيء)
واصف HID
0x09	bLength	حجم هذا الوصف
0x21	bDescriptorType	واصف HID
0x0101	bcdHID	الإصدار 1.1 من HID
0x00	bCountryCode	البلد المستهدَف للأجهزة
0x01	bNumDescriptors	عدد أوصاف فئة HID التي يجب اتّباعها
0x22	bDescriptorType	نوع وصف التقرير
0x003F	wDescriptorLength	إجمالي طول وصف التقرير
واصف نقطة النهاية
0x07	bLength	حجم هذا الوصف
0x05	bDescriptorType	واصف نقطة النهاية
0b10000001	bEndpointAddress	نقطة النهاية 1 (IN)
0b00000011	bmAttributes	المقاطعة
0x0008	wMaxPacketSize	حزم بحجم 8 بايت
0x0A	bInterval	فاصل زمني 10 ملي ثانية
واصف الواجهة
0x09	bLength	حجم هذا الوصف
0x04	bDescriptorType	واصف الواجهة
0x01	bInterfaceNumber	الواجهة 1
0x00	bAlternateSetting	الإعداد البديل 0 (تلقائي)
0x02	bNumEndpoints	نقطتا نهاية
0xFF	bInterfaceClass	فئة الواجهة الخاصة بالمورّد
0x00	bInterfaceSubClass
0x00	bInterfaceProtocol
0x00	iInterface	اسم الواجهة (لا شيء)
واصف نقطة النهاية
0x07	bLength	حجم هذا الوصف
0x05	bDescriptorType	واصف نقطة النهاية
0b10000010	bEndpointAddress	نقطة النهاية 1 (IN)
0b00000010	bmAttributes	مجمَّع
0x0040	wMaxPacketSize	حزم بحجم 64 بايت
0x00	bInterval	لا ينطبق على نقاط النهاية المجمّعة
واصف نقطة النهاية
0x07	bLength	حجم هذا الوصف
0x05	bDescriptorType	واصف نقطة النهاية
0b00000011	bEndpointAddress	نقطة النهاية 3 (OUT)
0b00000010	bmAttributes	مجمَّع
0x0040	wMaxPacketSize	حزم بحجم 64 بايت
0x00	bInterval	لا ينطبق على نقاط النهاية المجمّعة

يتألّف وصف الضبط من أوصاف متعددة يتم تسلسلها معًا. ويبدأ كلٌ منهما بالحقلين bLength وbDescriptorType بحيث يمكن تحديدهما. الواجهة الأولى هي واجهة HID تتضمّن وصف HID مرتبطًا ونقطة نهاية واحدة تُستخدَم لإرسال أحداث الإدخال إلى نظام التشغيل. الواجهة الثانية هي واجهة خاصة بالمورّد تتضمّن نقطتَي نهاية يمكن استخدامهما لإرسال أوامر إلى الجهاز وتلقّي ردود بدوره.

أوصاف WebUSB

على الرغم من أنّ WebUSB يمكن أن يعمل مع العديد من الأجهزة بدون تعديلات على البرامج الثابتة، يتم تفعيل وظائف إضافية من خلال وضع علامة على الجهاز باستخدام وصفي ملف شخصي محدّدين يشيرَين إلى توافقه مع WebUSB. على سبيل المثال، يمكنك تحديد عنوان URL لصفحة مقصودة يمكن للمتصفّح توجيه المستخدم إليها عندما يكون جهازك plugged in.

إشعار WebUSB:

‫Binary device Object Store (BOS) هو مفهوم تم تقديمه في USB 3.0، ولكنه تم أيضًا نقله إلى أجهزة USB 2.0 كجزء من الإصدار 2.1. يبدأ تحديد توافق مع WebUSB من خلال تضمين ملف وصف إمكانيات المنصة التالي في ملف وصف BOS:

القيمة	الحقل	الوصف
وصف مساحة تخزين العناصر للجهاز الثنائي
0x05	bLength	حجم هذا الوصف
0x0F	bDescriptorType	وصف مساحة تخزين العناصر للجهاز الثنائي
0x001D	wTotalLength	إجمالي طول هذه السلسلة من الأوصاف
0x01	bNumDeviceCaps	عدد أوصاف إمكانات الجهاز في BOS
وصف إمكانات منصة WebUSB
0x18	bLength	حجم هذا الوصف
0x10	bDescriptorType	وصف إمكانات الجهاز
0x05	bDevCapabilityType	واصف إمكانات النظام الأساسي
0x00	bReserved
{0x38, 0xB6, 0x08, 0x34, 0xA9, 0x09, 0xA0, 0x47, 0x8B, 0xFD, 0xA0, 0x76, 0x88, 0x15, 0xB6, 0x65}	PlatformCapablityUUID	معرّف GUID لوصف إمكانات منصة WebUSB بتنسيق little-endian
0x0100	bcdVersion	الإصدار 1.0 من واصف WebUSB
0x01	bVendorCode	قيمة bRequest لواجهة WebUSB
0x01	iLandingPage	عنوان URL للصفحة المقصودة

ملاحظة: سيتم كتابة معرّف UUID أعلاه على النحو التالي: {3408b638-09a9-47a0-8bfd-a0768815b665}، ولكن عند إرساله كجزء من وصف USB، يجب إرسال حقول المكوّنات بترتيب endian الأصغر. وهذا التحويل معقد، لذا تم إعطاء الترميز المناسب هنا كمرجع. راجِع RFC4122.

يحدد المعرّف الفريد العام لإمكانات النظام الأساسي هذا الوصف باعتباره واصفًا لإمكانات النظام الأساسي WebUSB، ويوفر معلومات أساسية حول الجهاز. لكي يتمكّن المتصفّح من جلب المزيد من المعلومات عن الجهاز، يستخدم القيمة bVendorCode ل إصدار طلبات إضافية إلى الجهاز. الطلب الوحيد المحدّد حاليًا هو GET_URL الذي يعرض وصفًا لعنوان URL. تشبه هذه العناصر وصفاء سلاسل العلامات، ولكنّها مصمّمة لتشفير عناوين URL باستخدام أقل عدد من البايتات. سيظهر واصف عنوان URL لـ "https://google.com" على النحو التالي:

القيمة	الحقل	الوصف
وصف عنوان URL
0x0D	bLength	حجم هذا الوصف
0x03	bDescriptorType	وصف عنوان URL
0x01	bScheme	https://‎
"google.com"	عنوان URL	محتوى عنوان URL بترميز UTF-8

عند توصيل جهازك لأول مرة، يقرأ المتصفّح وصف BOS من خلال إصدار عملية نقل التحكّم GET_DESCRIPTOR العادية هذه:

bmRequestType	bRequest	wValue	wIndex	wLength	البيانات (الردّ)
0b10000000	0x06	0x0F00	0x0000	*	وصف BOS

يتم عادةً تقديم هذا الطلب مرّتين، في المرّة الأولى باستخدام wLength كبير بما يكفي ليتمكّن المضيف من معرفة قيمة حقل wTotalLength بدون الالتزام بنقل بيانات كبيرة، ثم مرة أخرى عندما يكون طول الوصف الكامل معروفًا.

إذا تم ضبط الحقل iLandingPage في واصف إمكانية النظام الأساسي WebUSB على قيمة غير صفرية، سيُجري المتصفّح طلب GET_URL خاصًا بـ WebUSB من خلال إصدار عملية نقل عنصر تحكّم مع ضبط bRequest على القيمة bVendorCode من واصف إمكانية النظام الأساسي وضبط wValue على قيمة iLandingPage. يُرجى إدخال رمز الطلب الخاص بـ GET_URL (0x02) في wIndex:

bmRequestType	bRequest	wValue	wIndex	wLength	البيانات (الردّ)
0b11000000	0x01	0x0001	0x0002	*	واصف عنوان URL

ومرة أخرى، قد يتم إصدار هذا الطلب مرتين للتحقيق أولاً في طول أداة الوصف التي تتم قراءتها.

ملاحظة: لا تتوفّر ميزة عرض إشعار عند توصيل جهاز USB على أجهزة Android بعد.

اعتبارات خاصة بالمنصة

على الرغم من أنّ واجهة برمجة التطبيقات WebUSB API تحاول توفير واجهة متّسقة للوصول إلى أجهزة USB، يجب أن يكون المطوّرون على دراية بالمتطلبات المفروضة على التطبيقات، مثل متطلبات متصفّحات الويب للوصول إلى الأجهزة.

نظام التشغيل Mac

لا حاجة إلى إجراء أيّ خطوات خاصة في نظام التشغيل macOS. يمكن لأي موقع إلكتروني يستخدم WebUSB الاتصال بالجهاز والمطالبة بأي واجهات لم تتم المطالبة بها بواسطة برنامج تشغيل kernel أو تطبيق آخر.

Linux

يشبه نظام التشغيل Linux نظام التشغيل macOS، ولكن لا تُعدّ معظم عمليات التوزيع تلقائيًا حسابات مستخدمين تملك الإذن بفتح أجهزة USB. إنّ برنامج الخدمة الدائمة للنظام المُسمى udev هو المسؤول عن منح المستخدم والمجموعة الإذن بالوصول إلى جهاز. ستؤدي قاعدة مماثلة إلى منح ملكية جهاز مطابق لمعرّفات المورّد والمنتجات المحدّدة إلى مجموعة plugdev، وهي مجموعة شائعة للمستخدمين الذين يمكنهم الوصول إلى الأجهزة الطرفية:

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

استبدِل XXXX بمعرّفَي المورّد والمنتج السداسيَين لعملك، مثلاً، سيتطابق ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11" مع هاتف Nexus One . يجب كتابة هذه القيم بدون البادئة المعتادة "0x" وكلها بأحرف لاتينية صغيرة لكي يتم التعرّف عليها بشكل صحيح. للعثور على أرقام تعريف جهازك، يمكنك تشغيل سطر الأوامر tool lsusb.

يجب وضع هذه القاعدة في ملف في دليل /etc/udev/rules.d، وسيبدأ تطبيقها فور توصيل الجهاز بمصدر الطاقة. لست بحاجة إلى إعادة تشغيل udev.

Android

تستند منصة Android إلى نظام التشغيل Linux، ولكنها لا تتطلّب إجراء أي تعديل على إعدادات النظام. يتوفّر المتصفح تلقائيًا لأي جهاز لا يتضمّن برنامج تشغيل مدمجًا في نظام التشغيل. ومع ذلك، يجب أن يكون المطوّرون على عِلم بأنّ المستخدمين سيواجهون خطوة إضافية عند الربط بالجهاز. بعد أن يختار المستخدم جهازًا استجابةً لمكالمة على requestDevice()، سيعرض Android رسالة تطلب منه السماح لمتصفّح Chrome بالوصول إلى الجهاز. ويظهر هذا الطلب أيضًا إذا عاد المستخدم إلى موقع إلكتروني يملك الإذن بالاتصال بجهاز وكان الموقع الإلكتروني يستدعي open().

بالإضافة إلى ذلك، يمكن الوصول إلى المزيد من الأجهزة على Android مقارنةً بأجهزة Linux المكتبية، لأنّه يتم تضمين عدد أقل من برامج التشغيل تلقائيًا. ومن أهمّ الحذف، على سبيل المثال، فئة USB CDC-ACM التي يتم تنفيذها عادةً بواسطة محوّلات USB إلى تسلسلية، وذلك لعدم توفّر واجهة برمجة تطبيقات في حزمة Android SDK للاتصال بجهاز تسلسلي.

ChromeOS

يستند نظام التشغيل ChromeOS أيضًا إلى Linux ولا يتطلّب أيضًا أي تعديل على إعدادات النظام. تتحكّم خدمة permission_broker في الوصول إلى أجهزة USB ، وستسمح للمتصفّح بالوصول إليها ما دامت هناك واجهة واحدة على الأقل لم يتمّ المطالبة بها.

Windows

يفرض نموذج برنامج تشغيل Windows شرطًا إضافيًا. بخلاف الأنظمة الأساسية التي تفوق إمكانية فتح جهاز USB من تطبيق مستخدم ليست الإعداد التلقائي، حتى إذا لم يتم تحميل أي برنامج تشغيل. بدلاً من ذلك، هناك برنامج تشغيل خاص، WinUSB، يجب تحميله من أجل توفير الواجهة التي تستخدمها تطبيقات الوصول إلى الجهاز. ويمكن إجراء ذلك باستخدام ملف معلومات المشغِّل المخصّص (INF) المثبَّت على النظام أو من خلال تعديل ملف برمجية الثابت للجهاز لتقديم أوصاف توافق نظام التشغيل Microsoft أثناء التعداد.

ملف معلومات برنامج التشغيل (INF)

يُعلم ملف معلومات برنامج التشغيل نظام التشغيل Windows بما يجب فعله عند العثور على جهاز للمرة الأولى. بما أنّ نظام المستخدم يتضمّن بالفعل برنامج تشغيل WinUSB، كل ما عليك فعله هو ربط ملف INF بموفّر المنتج ورقم تعريفه بقاعدة التثبيت الجديدة هذه. يُعدّ الملف أدناه مثالاً أساسيًا. احفظ الملف في ملف يحمل .inf، وغيِّر الأقسام التي تم وضع علامة "X" عليها، ثم انقر بزر الماوس الأيمن على الملف واختَر "تثبيت" من قائمة السياقات.

[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 لكي يتمكّن التطبيق من العثور عليها والاتصال بها من خلال واجهة برمجة التطبيقات Windows API. استخدِم cmdlet New-Guid أو أداة على الإنترنت لإنشاء معرف GUID عشوائي.

لأغراض التطوير، توفّر أداة Zadig واجهة سهلة لاستبدال برنامج التشغيل الذي تم تحميله لواجهة USB ببرنامج تشغيل WinUSB.

أوصاف التوافق مع نظام التشغيل Microsoft

إن أسلوب استخدام ملف INF المذكور أعلاه مرهق، لأنه يتطلب تهيئة جهاز كل مستخدم مسبقًا. يقدّم نظام التشغيل Windows 8.1 والإصدارات الأحدث بديلاً من خلال استخدام أوصاف USB مخصّصة. تقدّم هذه الأوصاف معلومات لنظام التشغيل Windows عند توصيل الجهاز لأول مرة، وهي معلومات يتم تضمينها عادةً في ملف INF.

بعد إعداد أوصاف WebUSB، من السهل إضافة أوصاف توافق نظام التشغيل من Microsoft أيضًا. أولاً، وسِّع وصف BOS باستخدام وصف ميزات المنصة الإضافي هذا. احرص على تحديث wTotalLength وbNumDeviceCaps لاحتسابها.

القيمة	الحقل	الوصف
وصف إمكانات النظام الأساسي لنظام التشغيل Microsoft 2.0
0x1C	bLength	حجم هذا الوصف
0x10	bDescriptorType	وصف إمكانات الجهاز
0x05	bDevCapabilityType	واصف إمكانات النظام الأساسي
0x00	bReserved
{0xDF, 0x60, 0xDD, 0xD8, 0x89, 0x45, 0xC7, 0x4C, 0x9C, 0xD2, 0x65, 0x9D, 0x9E, 0x64, 0x8A, 0x9F}	PlatformCapablityUUID	معرّف GUID لوصف توافق النظام الأساسي لنظام التشغيل Microsoft 2.0 بتنسيق little-endian
0x06030000	dwWindowsVersion	الحد الأدنى لإصدار Windows المتوافق (Windows 8.1)
0x00B2	wMSOSDescriptorSetTotalLength	إجمالي طول مجموعة الواصف
0x02	bMS_VendorCode	قيمة bRequest لاسترداد المزيد من أوصاف Microsoft
0x00	bAltEnumCode	الجهاز لا يتيح التعداد البديل

كما هو الحال مع أوصاف WebUSB، عليك اختيار قيمة bRequest لاستخدامها في عمليات نقل التحكّم المرتبطة بهذه الأوصاف. في هذا المثال، اخترت 0x02. 0x07، الذي تم وضعه في wIndex، هو الأمر لاسترداد مجموعة ملفّات Microsoft OS 2.0 Descriptor من الجهاز.

bmRequestType	bRequest	wValue	wIndex	wLength	البيانات (الردّ)
0b11000000	0x02	0x0000	0x0007	*	مجموعة أوصاف نظام التشغيل MS 2.0

يمكن أن يكون لجهاز USB وظائف متعددة، لذا يصف الجزء الأول من مجموعة الوصف الدالة التي تكون السمات التالية مرتبطة بها. يهيئ المثال أدناه الواجهة 1 لجهاز مركب. يعطي الواصف نظام التشغيل جزأين مهمين من المعلومات حول هذه الواجهة. يُعلم وصف ملف تعريف IDE المتوافق نظام التشغيل Windows بأنّ هذا الجهاز متوافق مع برنامج تشغيل WinUSB IDE. يعمل وصف خاصية السجلّ بشكل مشابه لقسم [Dev_AddReg] في مثال ملف INF أعلاه، حيث يتم ضبط خاصية السجلّ لتحديد قيمة GUID لواجهة الجهاز.

القيمة	الحقل	الوصف
عنوان ضبط واصف نظام التشغيل Microsoft OS 2.0
0x000A	wLength	حجم هذا الوصف
0x0000	wDescriptorType	وصف رأس مجموعة الأوصاف
0x06030000	dwWindowsVersion	الحد الأدنى لإصدار Windows المتوافق (Windows 8.1)
0x00B2	wTotalLength	إجمالي طول مجموعة الأوصاف
عنوان المجموعة الفرعية لإعداد Microsoft OS 2.0
0x0008	wLength	حجم هذا الوصف
0x0001	wDescriptorType	وصف لعنوان مجموعة فرعية من الإعدادات
0x00	bConfigurationValue	ينطبق على الإعداد 1 (تمت الفهرسة من 0 على الرغم من أن عمليات الضبط تتم فهرستها عادةً من 1)
0x00	bReserved	يجب الضبط على 0
0x00A8	wTotalLength	إجمالي طول المجموعة الفرعية بما في ذلك هذا الرأس
عنوان مجموعة فرعية للدالة في Microsoft OS 2.0
0x0008	wLength	حجم هذا الوصف
0x0002	wDescriptorType	وصف عنوان مجموعة فرعية من الدوالّ
0x01	bFirstInterface	الواجهة الأولى للدالة
0x00	bReserved	يجب الضبط على 0
0x00A0	wSubsetLength	إجمالي طول المجموعة الفرعية بما في ذلك هذا الرأس
واصف معرّف متوافق مع Microsoft OS 2.0
0x0014	wLength	حجم هذا الوصف
0x0003	wDescriptorType	وصف رقم التعريف المتوافق
"WINUSB\0\0"	CompatibileID	سلسلة ASCII تمّت إضافة مسافات إليها لتصبح 8 بايت
"\0\0\0\0\0\0\0\0"	SubCompatibleID	سلسلة ASCII تمّت إضافة مسافات إليها لتصبح 8 بايت
واصف خاصية السجلّ في نظام التشغيل Microsoft 2.0
0x0084	wLength	حجم هذا الوصف
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

سيطلب نظام التشغيل Windows من الجهاز هذه المعلومات مرة واحدة فقط. إذا لم يقدِّم الجهاز وصفًا صالحًا، لن يُطلب منك ذلك مرة أخرى في المرة التالية التي يتم فيها توصيل الجهاز. قدّمت Microsoft قائمة بتسجيلات قاعدة بيانات أجهزة USB التي تصف إدخالات السجلّ التي تم إنشاؤها عند إدراج جهاز. عند الاختبار، يمكنك حذف الإدخالات التي تم إنشاؤها لجهاز من أجل إجبار Windows على محاولة قراءة الموصّفات مرة أخرى.

لمزيد من المعلومات، يمكنك الاطّلاع على مشاركة المدوّنة من Microsoft حول كيفية استخدام هذه الوصفات.

أمثلة

يمكن العثور على أمثلة على الرموز البرمجية التي تنفِّذ الأجهزة المتوافقة مع WebUSB والتي تتضمّن كلاً من مُصَنِّفات WebUSB ومُصَنِّفات نظام التشغيل Microsoft في هذين المشروعَين:

• WebLight
• مكتبة WebUSB Arduino