إنشاء جهاز لـ 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 هو ناقل يستخدم ترتيب البايت الأقل أهمية، لذا يجب إرسال أي قيمة عددية أكبر من بايت واحد باستخدام البايت الأقل أهمية أولاً.

القيمة	الحقل	الوصف
وصف الإعدادات
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.

يحدِّد المعرّف الفريد العالمي (UUID) لإمكانيات النظام الأساسي هذا العنصر على أنّه موصِّف WebUSB Platform Capability، الذي يقدّم معلومات أساسية عن الجهاز. لكي يتمكّن المتصفّح من جلب المزيد من المعلومات عن الجهاز، يستخدم القيمة 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 بدون الالتزام بنقل بيانات كبيرة، ثم مرة أخرى عندما يكون طول الوصف الكامل معروفًا.

إذا كان وصف إمكانات WebUSB على المنصة يحتوي على حقل iLandingPage تم ضبطه على قيمة غير صفرية، سينفِّذ المتصفّح بعد ذلك طلب 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 إلى تسلسلي، لأنّه ليس هناك واجهة برمجة تطبيقات في حزمة تطوير البرامج (SDK) لنظام Android للتواصل مع جهاز تسلسلي.

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] مجموعة DeviceInterfaceGUIDs للجهاز. يجب أن تحتوي كل واجهة جهاز على معرّف GUID لكي يتمكّن التطبيق من العثور عليها والاتصال بها من خلال واجهة برمجة التطبيقات Windows API. استخدِم الأمر New-Guid PowerShell أو أداة على الإنترنت لإنشاء معرّف 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 2.0
0x000A	wLength	حجم هذا الوصف
0x0000	wDescriptorType	وصف رأس مجموعة الأوصاف
0x06030000	dwWindowsVersion	الحد الأدنى لإصدار Windows المتوافق (Windows 8.1)
0x00B2	wTotalLength	إجمالي طول مجموعة الأوصاف
عنوان مجموعة فرعية من إعدادات نظام التشغيل Microsoft 2.0
0x0008	wLength	حجم هذا الوصف
0x0001	wDescriptorType	وصف لعنوان مجموعة فرعية من الإعدادات
0x00	bConfigurationValue	تنطبق على الإعداد 1 (الفهرسة من 0 على الرغم من أنّ الإعدادات يتم فهرستها عادةً من 1)
0x00	bReserved	يجب ضبط القيمة على 0.
0x00A8	wTotalLength	إجمالي طول المجموعة الفرعية بما في ذلك هذا الرأس
عنوان مجموعة فرعية من الدوال في نظام التشغيل Microsoft 2.0
0x0008	wLength	حجم هذا الوصف
0x0002	wDescriptorType	وصف عنوان مجموعة فرعية من الدوالّ
0x01	bFirstInterface	الواجهة الأولى للدالة
0x00	bReserved	يجب ضبط القيمة على 0.
0x00A0	wSubsetLength	إجمالي طول المجموعة الفرعية بما في ذلك هذا الرأس
وصف معرّف متوافق مع نظام التشغيل Microsoft 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