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

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

أوصاف WebUSB

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

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

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

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

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

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

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

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

على الرغم من أنّ واجهة برمجة التطبيقات 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 لمراعاة ذلك.

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

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

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

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

أمثلة

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

• WebLight
• مكتبة WebUSB Arduino