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

בונים מכשיר כדי להפיק את המקסימום מ-WebUSB API.

Reilly Grant

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

רקע

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

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

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

עקרונות בסיסיים של API

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

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

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

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

מתארי WebUSB

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

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

ה-UUID של יכולת הפלטפורמה מזהה זאת כיכולת של פלטפורמת WebUSB descriptor, שמספק מידע בסיסי על המכשיר. לדפדפן כדי לאחזר מידע נוסף על המכשיר שבו הוא משתמש בערך bVendorCode להנפיק בקשות נוספות למכשיר. הבקשה היחידה שצוינה כרגע היא הפונקציה GET_URL מחזירה מתאר כתובת 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. דימון (daemon) של מערכת שנקרא 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 ולא צריך לבצע בו שינויים לתצורת המערכת. השירות train_broker שולט בגישה ל-USB והם יאפשרו לדפדפן לגשת אליהם כל עוד הם נמצאים ממשק אחד שלא נתבעה עליו בעלות.

Windows

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

קובץ מידע לנהג (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] מגדיר את הקבוצה של DeviceInterfaceGUID עבור במכשיר. כל ממשק של מכשיר חייב לכלול GUID כדי שאפליקציה למצוא אותו ולהתחבר אליו באמצעות ממשק ה-API של Windows. שימוש ב-PowerShell של New-Guid cmdlet או כלי אונליין ליצירת 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 יכולות להיות מספר פונקציות, ולכן החלק הראשון של מתאר set מתאר לאיזה פונקציה המאפיינים הבאים משויכים. בדוגמה הבאה מגדיר את ממשק 1 של מכשיר מורכב. המתאר מעניק לגבי מערכת ההפעלה, שני פריטי מידע חשובים לגבי הממשק הזה. הגרסה התואמת מתאר מזהה אומר ל-Windows שהמכשיר הזה תואם ל-WinUSB לנהג. מתאר מאפיין המרשם פועל באופן דומה הקטע [Dev_AddReg] בדוגמת INF שלמעלה, הגדרת נכס מרשם בתור צריך להקצות לפונקציה הזו GUID של ממשק המכשיר.

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

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

דוגמאות

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

• WebLight
• ספריית WebUSB Arduino