การสร้างอุปกรณ์สำหรับ WebUSB

สร้างอุปกรณ์เพื่อใช้ประโยชน์จาก WebUSB API อย่างเต็มที่

Reilly Grant

บทความนี้อธิบายวิธีสร้างอุปกรณ์เพื่อใช้ประโยชน์จาก WebUSB API สำหรับข้อมูลเบื้องต้นเกี่ยวกับ API เอง โปรดดูที่เข้าถึงอุปกรณ์ USB บนเว็บ

ที่มา

Universal Serial Bus (USB) ได้กลายมาเป็นอินเทอร์เฟซที่ใช้กันมากที่สุดสำหรับ เชื่อมต่ออุปกรณ์ต่อพ่วงกับอุปกรณ์คอมพิวเตอร์เดสก์ท็อปและอุปกรณ์เคลื่อนที่ นอกจาก การกำหนดลักษณะทางไฟฟ้าของรถบัสและรุ่นทั่วไปของ ในการสื่อสารกับอุปกรณ์ ข้อมูลจำเพาะของ USB จะรวมชุดคลาสของอุปกรณ์ นี่เป็นโมเดลทั่วไปสำหรับอุปกรณ์บางประเภท เช่น เป็นพื้นที่เก็บข้อมูล เสียง วิดีโอ เครือข่าย และอื่นๆ ที่ผู้ผลิตอุปกรณ์สามารถ สำหรับการใช้งานจริง ข้อดีของข้อกำหนดจำเพาะระดับอุปกรณ์เหล่านี้คือ ผู้ให้บริการระบบปฏิบัติการ สามารถติดตั้งใช้งานไดรเวอร์เดี่ยวโดยพิจารณาจากคลาส ("ไดรเวอร์คลาส") และอุปกรณ์ใดๆ ที่นำคลาสดังกล่าวไปใช้ ที่รองรับ นี่เป็นการพัฒนาที่ยอดเยี่ยมสำหรับผู้ผลิตทุกรายที่ต้องเขียน ไดรเวอร์อุปกรณ์ของตนเอง

แต่อุปกรณ์บางเครื่องไม่เข้ากับคลาสอุปกรณ์มาตรฐานเหล่านี้ ต ผู้ผลิตอาจเลือกที่จะติดป้ายกำกับอุปกรณ์ของตนว่า คลาสเฉพาะผู้ให้บริการ ในกรณีนี้ ระบบปฏิบัติการจะเลือกอุปกรณ์ ไดรเวอร์ที่จะโหลดโดยอิงจากข้อมูลที่ให้ไว้ในแพ็กเกจคนขับของผู้ให้บริการ โดยปกติเป็นชุดผู้ให้บริการและรหัสผลิตภัณฑ์ซึ่งเป็นที่ทราบว่าควรใช้ โปรโตคอลเฉพาะผู้ให้บริการ

ฟีเจอร์อีกอย่างหนึ่งของ USB คืออุปกรณ์อาจมีอินเทอร์เฟซที่หลากหลาย โฮสต์ที่อุปกรณ์เชื่อมต่ออยู่ แต่ละอินเทอร์เฟซสามารถใช้ คลาสที่เป็นมาตรฐานหรือเจาะจงผู้ให้บริการ เมื่อระบบปฏิบัติการเลือก ในการจัดการอุปกรณ์ อินเทอร์เฟซแต่ละแบบสามารถอ้างสิทธิ์ คนขับ ตัวอย่างเช่น เว็บแคม USB มักมีอินเทอร์เฟซ 2 แบบ ได้แก่ ใช้คลาสวิดีโอ USB (สำหรับกล้อง) และอีกชุดหนึ่งใช้ USB คลาสเสียง (สำหรับไมโครโฟน) ระบบปฏิบัติการไม่ได้โหลด "ไดรเวอร์เว็บแคม" แต่จะโหลดไดรเวอร์คลาสวิดีโอและเสียงอิสระแทน ซึ่งทำหน้าที่แยกฟังก์ชันต่างๆ ของอุปกรณ์ ช่วงเวลานี้ องค์ประกอบของคลาสอินเทอร์เฟซมีความยืดหยุ่นมากขึ้น

ข้อมูลเบื้องต้นเกี่ยวกับ API

คลาส USB มาตรฐานจำนวนมากมี API ของเว็บที่สอดคล้องกัน ตัวอย่างเช่น หน้าสามารถบันทึกวิดีโอจากอุปกรณ์คลาสวิดีโอโดยใช้ getUserMedia() หรือได้รับเหตุการณ์อินพุตจากอุปกรณ์คลาสที่มนุษย์สร้างขึ้น (HID) ด้วยการฟัง สำหรับ KeyboardEvents หรือ PointerEvents หรือใช้เกมแพดหรือ WebHID API เช่นเดียวกับอุปกรณ์บางประเภทที่ใช้คำจำกัดความคลาสมาตรฐาน ไม่ใช่ทุกอุปกรณ์ จะใช้ฟีเจอร์ที่สอดคล้องกับ API ของแพลตฟอร์มเว็บที่มีอยู่ วันและเวลา ในกรณีนี้ WebUSB API สามารถเติมเต็มช่องว่างดังกล่าวโดยมอบวิธีสำหรับเว็บไซต์ เพื่ออ้างสิทธิ์อินเทอร์เฟซเฉพาะผู้ให้บริการ และใช้การสนับสนุนโดยตรงจาก ภายในหน้าเว็บ

ข้อกำหนดเฉพาะสำหรับอุปกรณ์ที่เข้าถึงได้ผ่าน WebUSB จะแตกต่างกันไปเล็กน้อย จากแต่ละแพลตฟอร์ม เพราะวิธีที่ระบบปฏิบัติการจัดการ USB แตกต่างกัน อุปกรณ์ แต่ข้อกำหนดเบื้องต้นคือ อุปกรณ์ไม่ควรมี ไดรเวอร์ที่อ้างสิทธิ์อินเทอร์เฟซที่หน้าเว็บต้องการควบคุม ซึ่งอาจเป็น ไดรเวอร์คลาสทั่วไปที่จัดหาให้โดยผู้ให้บริการระบบปฏิบัติการหรือไดรเวอร์อุปกรณ์ที่จัดหาให้ ผู้ให้บริการ เนื่องจากอุปกรณ์ USB สามารถให้บริการได้หลายอินเทอร์เฟซ ซึ่งแต่ละอินเทอร์เฟซอาจ มีไดรเวอร์ของตัวเอง คุณสามารถสร้างอุปกรณ์สำหรับอินเทอร์เฟซบางรายการได้ ถูกอ้างสิทธิ์โดยคนขับและบุคคลอื่นๆ สามารถเข้าถึงได้โดยเบราว์เซอร์

ตัวอย่างเช่น แป้นพิมพ์ USB ระดับไฮเอนด์อาจมีอินเทอร์เฟซคลาส HID ที่ จะถูกอ้างสิทธิ์โดยระบบย่อยของระบบปฏิบัติการและข้อมูลเฉพาะผู้ให้บริการ ที่ยังคงพร้อมใช้งานกับ WebUSB เพื่อการใช้งานโดยเครื่องมือกำหนดค่า ช่วงเวลานี้ ในเว็บไซต์ของผู้ผลิต เพื่อให้ผู้ใช้สามารถเปลี่ยน ลักษณะการทํางานของอุปกรณ์ เช่น แป้นมาโคร และเอฟเฟกต์แสงโดยไม่มี ติดตั้งซอฟต์แวร์เฉพาะแพลตฟอร์ม ข้อบ่งชี้การกำหนดค่าของอุปกรณ์ดังกล่าว ซึ่งจะมีลักษณะดังนี้

ค่า ช่อง คำอธิบาย
ข้อบ่งชี้การกำหนดค่า
0x09 bLength ขนาดของข้อบ่งชี้นี้
0x02 bDescriptorType ข้อบ่งชี้การกำหนดค่า
0x0039 wTotalLength ความยาวรวมของข้อบ่งชี้ชุดนี้
0x02 bNumInterfaces จำนวนอินเทอร์เฟซ
0x01 bConfigurationValue การกำหนดค่า 1
0x00 iConfiguration ชื่อการกำหนดค่า (ไม่มี)
0b1010000 bmAttributes อุปกรณ์ที่ขับเคลื่อนโดยตัวเองพร้อมการปลุกระบบจากระยะไกล
0x32 bMaxPower กำลังสูงสุดจะแสดงโดยเพิ่มครั้งละ 2 mA
ข้อบ่งชี้อินเทอร์เฟซ
0x09 bLength ขนาดของข้อบ่งชี้นี้
0x04 bDescriptorType ข้อบ่งชี้อินเทอร์เฟซ
0x00 bInterfaceNumber อินเทอร์เฟซ 0
0x00 bAlternateSetting การตั้งค่าอื่น 0 (ค่าเริ่มต้น)
0x01 bNumEndpoints 1 ปลายทาง
0x03 bInterfaceClass คลาสอินเทอร์เฟซ HID
0x01 bInterfaceSubClass คลาสย่อยของอินเทอร์เฟซการเปิดเครื่อง
0x01 bInterfaceProtocol แป้นพิมพ์
0x00 iInterface ชื่ออินเทอร์เฟซ (ไม่มี)
ข้อบ่งชี้ HID
0x09 bLength ขนาดของข้อบ่งชี้นี้
0x21 bDescriptorType ข้อบ่งชี้ HID
0x0101 bcdHID HID เวอร์ชัน 1.1
0x00 bCountryCode ประเทศเป้าหมายของฮาร์ดแวร์
0x01 bNumDescriptors จำนวนข้อบ่งชี้คลาส HID ที่จะติดตาม
0x22 bDescriptorType ประเภทข้อบ่งชี้รายงาน
0x003F wDescriptorLength ความยาวรวมของข้อบ่งชี้รายงาน
ข้อบ่งชี้ปลายทาง
0x07 bLength ขนาดของข้อบ่งชี้นี้
0x05 bDescriptorType ข้อบ่งชี้ปลายทาง
0b10000001 bEndpointAddress ปลายทาง 1 (IN)
0b00000011 bmAttributes ขัดจังหวะ
0x0008 wMaxPacketSize แพ็กเก็ต 8 ไบต์
0x0A bInterval ช่วงเวลา 10 มิลลิวินาที
ข้อบ่งชี้อินเทอร์เฟซ
0x09 bLength ขนาดของข้อบ่งชี้นี้
0x04 bDescriptorType ข้อบ่งชี้อินเทอร์เฟซ
0x01 bInterfaceNumber อินเทอร์เฟซ 1
0x00 bAlternateSetting การตั้งค่าอื่น 0 (ค่าเริ่มต้น)
0x02 bNumEndpoints 2 ปลายทาง
0xFF bInterfaceClass คลาสอินเทอร์เฟซเฉพาะผู้ให้บริการ
0x00 bInterfaceSubClass
0x00 bInterfaceProtocol
0x00 iInterface ชื่ออินเทอร์เฟซ (ไม่มี)
ข้อบ่งชี้ปลายทาง
0x07 bLength ขนาดของข้อบ่งชี้นี้
0x05 bDescriptorType ข้อบ่งชี้ปลายทาง
0b10000010 bEndpointAddress ปลายทาง 1 (IN)
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 และปลายทางเดี่ยวเพื่อส่งเหตุการณ์อินพุตไปยัง ระบบปฏิบัติการ อินเทอร์เฟซที่ 2 เป็นอินเทอร์เฟซเฉพาะผู้ให้บริการ โดยมี ปลายทางที่สามารถใช้เพื่อส่งคำสั่งไปยังอุปกรณ์และรับการตอบสนอง เป็นการตอบแทน

ตัวบอก WebUSB

แม้ว่า WebUSB จะทำงานกับอุปกรณ์จำนวนมากได้โดยไม่ต้องแก้ไขเฟิร์มแวร์ ใช้ฟังก์ชันเพิ่มเติมได้ด้วยการทำเครื่องหมายอุปกรณ์ด้วย ซึ่งบ่งชี้ถึงการรองรับ WebUSB เช่น คุณสามารถระบุ URL ของหน้า Landing Page ที่เบราว์เซอร์ สามารถนำผู้ใช้ไปได้เมื่ออุปกรณ์ของคุณคือ เสียบปลั๊กอยู่

วันที่ ภาพหน้าจอของการแจ้งเตือน WebUSB ใน Chrome
การแจ้งเตือน WebUSB

The Branch Device Object Store (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 GUID ความสามารถของแพลตฟอร์ม WebUSB ในรูปแบบ Little-endian
0x0100 bcdVersion WebUSB Descriptor เวอร์ชัน 1.0
0x01 bVendorCode ค่า bRequest สำหรับ WebUSB
0x01 iLandingPage URL สำหรับหน้า Landing Page

UUID ความสามารถของแพลตฟอร์มระบุว่าเป็นความสามารถของแพลตฟอร์ม WebUSB ข้อบ่งชี้ ซึ่งให้ข้อมูลพื้นฐานเกี่ยวกับอุปกรณ์ สำหรับเบราว์เซอร์ เพื่อดึงข้อมูลเพิ่มเติมเกี่ยวกับอุปกรณ์ที่ใช้ค่า 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

โดยปกติแล้วคำขอนี้จะเกิดขึ้น 2 ครั้ง ครั้งแรกที่มี wLength มีขนาดใหญ่พอ เพื่อให้โฮสต์ทราบค่าในช่อง wTotalLength โดยไม่มี กำลังทำการโอนขนาดใหญ่ แล้วดำเนินการอีกครั้งเมื่อความยาวของข้อบ่งชี้แบบเต็มคือ รู้จัก

หากตัวบ่งชี้ความสามารถของแพลตฟอร์ม WebUSB มีการตั้งค่าช่อง iLandingPage เป็น ค่าที่ไม่ใช่ 0 เบราว์เซอร์จะส่งคำขอ GET_URL สำหรับ WebUSB โดยเฉพาะ GET_URL ด้วยการโอนการควบคุมโดยตั้งค่า bRequest เป็นค่า bVendorCode จากข้อบ่งชี้ความสามารถของแพลตฟอร์มและตั้งค่า wValue เป็น iLandingPage รหัสคำขอสำหรับ GET_URL (0x02) จะอยู่ใน wIndex

bmRequestType bRequest wValue wIndex wLength ข้อมูล (คำตอบ)
0b11000000 0x01 0x0001 0x0002 * ข้อบ่งชี้ URL

ขอย้ำอีกครั้งว่าอาจมีการออกคำขอนี้ 2 ครั้งเพื่อตรวจสอบความยาวครั้งแรก ของข้อบ่งชี้ที่กำลังอ่านอยู่

ข้อควรพิจารณาเฉพาะแพลตฟอร์ม

แม้ว่า 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 เช่นกัน และไม่จำเป็นต้องมีการปรับเปลี่ยนใดๆ กับการกำหนดค่าระบบ บริการ permission_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 เพื่อให้แอปพลิเคชัน ค้นหาและเชื่อมต่อกับโดเมน ผ่าน Windows API ใช้ PowerShell ของ New-Guid cmdlet หรือเครื่องมือออนไลน์เพื่อสร้าง GUID แบบสุ่ม

เพื่อวัตถุประสงค์ในการพัฒนา เครื่องมือ Zadig มีอินเทอร์เฟซที่ใช้งานง่ายสำหรับ เปลี่ยนไดรเวอร์ที่โหลดสำหรับอินเทอร์เฟซ USB ด้วยไดรเวอร์ WinUSB

ข้อบ่งชี้ความเข้ากันได้ของ Microsoft OS

วิธีการไฟล์ 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 GUID ของความเข้ากันได้แพลตฟอร์ม Microsoft OS 2.0 ในรูปแบบ Little-endian
0x06030000 dwWindowsVersion เวอร์ชัน Windows ที่เข้ากันได้ขั้นต่ำ (Windows 8.1)
0x00B2 wMSOSDescriptorSetTotalLength ความยาวรวมของชุดข้อบ่งชี้
0x02 bMS_VendorCode ค่า bRequest สำหรับการเรียกข้อมูลข้อบ่งชี้ของ Microsoft เพิ่มเติม
0x00 bAltEnumCode อุปกรณ์ไม่รองรับการแจกแจงสำรอง

คุณต้องเลือกค่า bRequest ที่จะใช้ในข้อบ่งชี้ WebUSB ควบคุมการโอนที่เกี่ยวข้องกับข้อบ่งชี้เหล่านี้ ในตัวอย่างนี้ฉันเลือก 0x02 0x07 ที่วางไว้ใน wIndex เป็นคำสั่งในการเรียก Microsoft OS 2.0 การตั้งค่าข้อบ่งชี้จากอุปกรณ์

bmRequestType bRequest wValue wIndex wLength ข้อมูล (คำตอบ)
0b11000000 0x02 0x0000 0x0007 * ชุดข้อบ่งชี้ MS OS 2.0

อุปกรณ์ USB สามารถมีหลายฟังก์ชัน ดังนั้นส่วนแรกของข้อบ่งชี้ set จะอธิบายว่าพร็อพเพอร์ตี้ต่อไปนี้เชื่อมโยงกับฟังก์ชันใด ตัวอย่างด้านล่างกำหนดค่าอินเทอร์เฟซ 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 ชื่อพร็อพเพอร์ตี้ที่มีตัวระบุค่า Null ที่เข้ารหัสเป็น UTF-16LE
0x0050 wPropertyDataLength ความยาวของค่าพร็อพเพอร์ตี้
"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}\0\0" PropertyData GUID บวกเครื่องหมายสิ้นสุดที่เป็นค่าว่าง 2 ตัวที่เข้ารหัสเป็น UTF-16LE

Windows จะค้นหาข้อมูลจากอุปกรณ์ดังกล่าวเพียงครั้งเดียว หากอุปกรณ์รองรับ ไม่ตอบกลับด้วยข้อบ่งชี้ที่ถูกต้อง ระบบจะไม่ถามซ้ำในคราวต่อไป เชื่อมต่ออุปกรณ์แล้ว Microsoft ได้จัดเตรียมรายการรีจิสทรีอุปกรณ์ USB แล้ว รายการที่อธิบายรายการรีจิสทรีที่สร้างขึ้นเมื่อแจกแจงอุปกรณ์ วันและเวลา การทดสอบลบรายการที่สร้างขึ้นสำหรับอุปกรณ์เพื่อบังคับให้ Windows พยายามอ่าน คำอธิบายอีกครั้ง

สำหรับข้อมูลเพิ่มเติม โปรดดูบล็อกโพสต์ของ Microsoft เกี่ยวกับวิธีใช้ ข้อบ่งชี้

ตัวอย่าง

โค้ดตัวอย่างการใช้อุปกรณ์ WebUSB-Aware ที่มีทั้ง WebUSB คุณจะพบข้อบ่งชี้และข้อบ่งชี้ Microsoft OS ในโปรเจ็กต์ต่อไปนี้