בניית מכשיר ל-WebUSB

פיתוח מכשיר כדי לנצל את מלוא היתרונות של WebUSB API.

Reilly Grant

במאמר הזה נסביר איך ליצור מכשיר שיעשה שימוש מלא ב-WebUSB API. מבוא קצר לממשק ה-API עצמו זמין במאמר גישה להתקני USB באינטרנט.

רקע

האפיק הטורי האוניברסלי (USB) הפך לממשק הפיזי הנפוץ ביותר לחיבור ציוד היקפי למכשירי מחשוב נייחים וניידים. בנוסף להגדרת המאפיינים החשמליים של האוטובוס ומודל כללי לתקשורת עם מכשיר, מפרטי ה-USB כוללים קבוצה של מפרטי סיווג התקנים. אלה מודלים כלליים לסיווגים מסוימים של מכשירים, כמו אחסון, אודיו, וידאו, רשתות וכו', שאותם יצרני המכשירים יכולים להטמיע. היתרון של המפרטים האלה של סיווג המכשירים הוא שספק של מערכת הפעלה יכול להטמיע מנהל יחיד על סמך מפרט הכיתה ('מנהל כיתה'), וכל מכשיר שמטמיע את הכיתה הזו יקבל תמיכה. זה היה שיפור משמעותי בהשוואה למצב שבו כל יצרן היה צריך לכתוב את מנהלי ההתקנים שלו.

עם זאת, יש מכשירים שלא מתאימים לאף אחת מהקטגוריות הסטנדרטיות האלה. במקום זאת, היצרן יכול לבחור לתייג את המכשיר שלו כמכשיר שמטמיע את הכיתה הספציפית לספק. במקרה כזה, מערכת ההפעלה בוחרת איזה מנהל התקן של מכשיר לטעון על סמך מידע שמסופק בחבילת מנהלי ההתקנים של הספק. בדרך כלל מדובר בקבוצה של מזהי מוצרים ומזהי ספקים שידועים כהטמעה של פרוטוקול ספציפי לספק.

תכונה נוספת של USB היא שמכשירים יכולים לספק כמה ממשקים למארח שאליו הם מחוברים. כל ממשק יכול להטמיע מחלקה סטנדרטית או להיות ספציפי לספק. כשמערכת הפעלה בוחרת את מנהלי ההתקנים המתאימים לטיפול במכשיר, כל ממשק יכול להיות מוגדר על ידי מנהל התקנים אחר. לדוגמה, מצלמת אינטרנט מסוג USB מספקת בדרך כלל שני ממשקים, אחד שמטמיע את USB Video Class (למצלמה) ואחד שמטמיע את USB Audio Class (למיקרופון). מערכת ההפעלה לא טוענת 'מנהל התקן מצלמת אינטרנט' יחיד, אלא מנהלי התקן עצמאיים של סוגים שונים של וידאו ואודיו, שמתחלקים באחריות על הפונקציות הנפרדות של המכשיר. ההרכב הזה של כיתות ממשק מספק גמישות רבה יותר.

יסודות של ממשקי API

למחלקות USB רגילות רבות יש ממשקי API מתאימים לאינטרנט. לדוגמה, דף יכול לצלם וידאו ממכשיר מסוג וידאו באמצעות getUserMedia(), או לקבל אירועי קלט ממכשיר מסוג ממשק אנושי (HID) על ידי האזנה ל-KeyboardEvents או ל-PointerEvents, או באמצעות Gamepad או ה-API של WebHID. בדיוק כמו שלא כל המכשירים מטמיעים הגדרת כיתה סטנדרטית, לא כל המכשירים מטמיעים תכונות שתואמות לממשקי API קיימים של פלטפורמות אינטרנט. במקרה כזה, WebUSB API יכול למלא את הפער הזה על ידי מתן דרך לאתרים לטעון בעלות על ממשק ספציפי לספק ולהטמיע תמיכה בו ישירות מהדף שלהם.

הדרישות הספציפיות כדי שאפשר יהיה לגשת למכשיר דרך WebUSB משתנות מעט מפלטפורמה לפלטפורמה בגלל ההבדלים באופן שבו מערכות ההפעלה מנהלות את מכשירי ה-USB, אבל הדרישה הבסיסית היא שלא צריך להיות למכשיר כבר נהג שמצהיר על הממשק שהדף רוצה לשלוט בו. זה יכול להיות מנהל התקן של סוג כללי שסופק על ידי ספק מערכת ההפעלה, או מנהל התקן של מכשיר שסופק על ידי הספק. מכשירים עם חיבור USB יכולים לספק כמה ממשקים, לכל אחד מהם יכול להיות מנהל התקן משלו, כך שאפשר ליצור מכשיר שבו מנהל התקן תובע בעלות על חלק מהממשקים, ואחרים נותרים נגישים לדפדפן.

לדוגמה, מקלדת USB מתקדמת עשויה לספק ממשק של סוג HID שיוכר על ידי מערכת המשנה של הקלט של מערכת ההפעלה, וממשק ספציפי לספק שיישאר זמין ל-WebUSB לשימוש בכלי הגדרה. הכלי הזה יכול להופיע באתר של היצרן, ומאפשר למשתמש לשנות היבטים של התנהגות המכשיר, כמו מקשי מאקרו ואפקטים של תאורה, בלי להתקין תוכנה ספציפית לפלטפורמה. התיאור של ההגדרות של מכשיר כזה ייראה בערך כך:

מתאר התצורה מורכב מכמה מתארים שמקושרים יחד. כל אחד מהם מתחיל בשדות bLength ו-bDescriptorType כדי שאפשר יהיה לזהות אותו. הממשק הראשון הוא ממשק HID עם מתאר HID משויך ונקודת קצה יחידה שמשמשת להעברת אירועי קלט למערכת ההפעלה. הממשק השני הוא ממשק ספציפי לספק עם שני נקודות קצה שאפשר להשתמש בהן כדי לשלוח פקודות למכשיר ולקבל תשובות בתמורה.

מתארי WebUSB

WebUSB יכול לפעול עם מכשירים רבים ללא שינויים בקושחת הקצרה, אבל כדי להפעיל פונקציונליות נוספת צריך לסמן את המכשיר באמצעות מתארים ספציפיים שמציינים תמיכה ב-WebUSB. לדוגמה, אפשר לציין כתובת URL של דף נחיתה שהדפדפן יוכל להפנות אליה את המשתמש כשהמכשיר מחובר.

Binary device Object Store‏ (BOS) הוא מושג שהוצג ב-USB 3.0, אבל הוא הועבר גם למכשירי USB 2.0 כחלק מגרסה 2.1. כדי להצהיר על תמיכה ב-WebUSB, צריך לכלול את מתאר יכולות הפלטפורמה הבא בתיאור ה-BOS:

מזהה ה-UUID של יכולות הפלטפורמה מזהה את הקוד הזה בתור תיאור של יכולות הפלטפורמה של WebUSB, שמספק מידע בסיסי על המכשיר. כדי שהדפדפן יוכל לאחזר מידע נוסף על המכשיר, הוא משתמש בערך bVendorCode כדי לשלוח בקשות נוספות למכשיר. הבקשה היחידה שצוינה כרגע היא GET_URL, שמחזירה תיאור של כתובת URL. הם דומים לתיאורים של מחרוזות, אבל הם מיועדים לקידוד כתובות URL במספר הבייטים הנמוך ביותר. מתאר כתובת URL של "https://google.com" ייראה כך:

כשמחברים את המכשיר בפעם הראשונה, הדפדפן קורא את מתאר ה-BOS על ידי שליחת העברת הבקרה הרגילה GET_DESCRIPTOR:

בדרך כלל שולחים את הבקשה הזו פעמיים, בפעם הראשונה עם ערך wLength גדול מספיק כדי שהמארח יוכל למצוא את הערך של השדה wTotalLength בלי להתחייב להעברה גדולה, ואז שוב כשידוע אורך המתאר המלא.

אם בשדה iLandingPage של מתאר יכולות הפלטפורמה של WebUSB מוגדר ערך שאינו אפס, הדפדפן מבצע בקשה ספציפית ל-WebUSB מסוג GET_URL על ידי הנפקת העברת בקרה עם bRequest שמוגדר לערך bVendorCode מהמתאר של יכולות הפלטפורמה ו-wValue שמוגדר לערך iLandingPage. קוד הבקשה של GET_URL (0x02) מופיע ב-wIndex:

שוב, יכול להיות שהבקשה הזו תישלח פעמיים כדי לבדוק קודם את האורך של המתאר שנקרא.

שיקולים ספציפיים לפלטפורמה

למרות ש-WebUSB API מנסה לספק ממשק עקבי לגישה למכשירי USB, מפתחים עדיין צריכים להיות מודעים לדרישות שחלות על אפליקציות, כמו דרישות של דפדפני אינטרנט כדי לגשת למכשירים.

macOS

אין צורך בדבר מיוחד ב-macOS. אתר שמשתמש ב-WebUSB יכול להתחבר למכשיר ולטעון בעלות על ממשקים שלא נטען עליהם בעלות על ידי מנהל ליבה או אפליקציה אחרת.

Linux

Linux דומה ל-macOS, אבל כברירת מחדל רוב הפצות Linux לא מגדירות לחשבונות משתמשים הרשאה לפתוח התקני 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 לסידור טורי, כי אין API ב-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] מגדירים את הקבוצה של DeviceInterfaceGUIDs למכשיר. כל ממשק של מכשיר חייב לכלול מזהה GUID כדי שאפליקציה תוכל למצוא אותו ולהתחבר אליו דרך Windows API. אפשר להשתמש ב-cmdlet של PowerShell‏ New-Guid או בכלי אונליין כדי ליצור מזהה GUID אקראי.

למטרות פיתוח, הכלי Zadig מספק ממשק קל להחלפת מנהל ההתקן שנטען לממשק USB במנהל ההתקן WinUSB.

מתארי תאימות של Microsoft OS

הגישה של קובץ ה-INF שמפורטת למעלה היא מסורבלת כי היא דורשת להגדיר מראש את המכונה של כל משתמש. ב-Windows 8.1 ואילך יש חלופה באמצעות שימוש בתוויות USB בהתאמה אישית. התיאורים האלה מספקים למערכת ההפעלה Windows מידע, בזמן החיבור הראשון של המכשיר, שבדרך כלל נכלל בקובץ ה-INF.

אחרי שמגדירים את מתארי WebUSB, קל להוסיף גם את מתארי התאימות למערכת ההפעלה של Microsoft. קודם צריך להרחיב את מתאר ה-BOS באמצעות מתאר היכולות הנוסף הזה של הפלטפורמה. חשוב לעדכן את wTotalLength ו-bNumDeviceCaps בהתאם.

בדומה לתוויות התיאור של WebUSB, צריך לבחור ערך bRequest שישמש להעברות בקרה שקשורות לתוויות התיאור האלה. בדוגמה הזו בחרתי ב-0x02. 0x07, שמופיעה ב-wIndex, היא הפקודה לאחזור מהמכשיר את קבוצת התיאורים של Microsoft OS 2.0.

למכשיר USB יכולות להיות כמה פונקציות, ולכן החלק הראשון של קבוצת המתאר מתאר את הפונקציה שאליה משויכים המאפיינים הבאים. בדוגמה הבאה מוגדר ממשק 1 של מכשיר מורכב. בתיאור מופיעים שני פרטים חשובים לגבי הממשק הזה למערכת ההפעלה. מתאר המזהה התואם מאפשר ל-Windows לדעת שהמכשיר תואם למנהל WinUSB. מתאר מאפיין הרישום פועל באופן דומה לקטע [Dev_AddReg] בדוגמה של קובץ ה-INF שלמעלה, ומגדיר מאפיין רישום כדי להקצות לפונקציה הזו מזהה GUID של ממשק מכשיר.

Windows תבצע שאילתה למכשיר לגבי המידע הזה רק פעם אחת. אם המכשיר לא מגיב עם מתארים תקינים, לא תופיע שוב שאלה כזו בפעם הבאה שהמכשיר יתחבר. Microsoft מספקת רשימת רשומות במרשם של מכשירי USB שמתארת את רשומות המרשם שנוצרות במהלך ספירת המכשירים. כשבודקים, צריך למחוק את הרשומות שנוצרו למכשיר כדי לאלץ את Windows לנסות לקרוא שוב את התיאורים.

מידע נוסף זמין בפוסט בבלוג של Microsoft בנושא השימוש בתיאורים האלה.

דוגמאות

בפרויקטים הבאים אפשר למצוא דוגמאות לקוד שמטמיע התקנים שתומכים ב-WebUSB, שכוללים גם מתארי WebUSB וגם מתארי מערכת ההפעלה של Microsoft:

• WebLight
• ספריית Arduino של WebUSB