בניית מכשיר ל-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 בלי להתחייב להעברה גדולה, ואז שוב כשאורך התיאור המלא ידוע.

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

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

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

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

macOS

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

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 לרשת טורית, כי אין 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 OS:

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