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

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

Reilly Grant

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

الخلفية

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

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

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

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

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

تختلف المتطلبات المحدّدة لإتاحة الوصول إلى الجهاز عبر 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 (الهند)
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 (الهند)
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 للصفحة المقصودة يمكن للمتصفح توجيه المستخدم إليه عندما يكون الجهاز موصولاً بمصدر طاقة.

إشعار WebUSB:

متجر كائنات الجهاز الثنائي (BOS) هو مفهوم تم طرحه في USB 3.0 ولكن تمت إعادة توفيره أيضًا إلى أجهزة USB 2.0 كجزء من الإصدار 2.1. يبدأ توضيح إتاحة WebUSB بتضمين واصف إمكانيات النظام الأساسي التالي في واصف BOS:

القيمة	الحقل	الوصف
واصف Object Store للجهاز الثنائي
0x05	bLength	حجم أداة الوصف هذه
0x0F	bDescriptorType	واصف Object Store للجهاز الثنائي
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	واصف إمكانية النظام الأساسي لـ WebUSB بتنسيق GUID بتنسيق صغير الأطراف
0x0100	bcdVersion	الإصدار 1.0 من أداة وصف WebUSB
0x01	bVendorCode	قيمة bRequest لـ WebUSB
0x01	iLandingPage	عنوان URL للصفحة المقصودة

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

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

macOS

ما مِن إجراءات خاصة يجب اتّخاذها في نظام التشغيل 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" المعتادة ويجب أن تكون كل الأحرف صغيرة حتى يتم التعرف عليها بشكل صحيح. للعثور على أرقام التعريف لجهازك، عليك تشغيل أداة سطر الأوامر lsusb.

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

Android

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

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

ChromeOS

يستند نظام التشغيل ChromeOS إلى نظام التشغيل Linux أيضًا ولا يتطلب أي تعديل على إعداد النظام. تتحكّم خدمة License_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. استخدِم أمر New-Guid PowerShell أو أداة على الإنترنت لإنشاء معرّف GUID عشوائي.

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

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

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

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

القيمة	الحقل	الوصف
واصف إمكانية النظام الأساسي Microsoft OS 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	واصف التوافق مع النظام الأساسي لـ Microsoft OS 2.0 GUID بتنسيق صغير النهاية
0x06030000	dwWindowsVersion	الحد الأدنى من إصدار Windows المتوافق (Windows 8.1)
0x00B2	wMSOSDescriptorSetTotalLength	إجمالي طول مجموعة الواصف
0x02	bMS_VendorCode	قيمة طلب استرداد المزيد من واصف Microsoft
0x00	bAltEnumCode	الجهاز لا يتيح التعداد البديل

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

bmRequestType	bRequest	wValue	wIndex	wLength	البيانات (الاستجابة)
0b11000000	0x02	0x0000	0x0007	*	مجموعة الواصف لـ MS OS 2.0

يمكن أن يكون لجهاز USB وظائف متعدّدة، لذا فإنّ الجزء الأول من مجموعة الواصف يصف الوظيفة التي ترتبط بها السمات التالية. يعمل المثال أدناه على تهيئة الواجهة 1 للجهاز المركّب. يعطي الواصف لنظام التشغيل جزأين مهمين من المعلومات حول هذه الواجهة. ويُعلم واصف رقم التعريف المتوافق نظام التشغيل Windows بأن هذا الجهاز متوافق مع برنامج تشغيل WinUSB. يعمل واصف خصائص السجلّ بشكل مشابه للقسم [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 OS 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