Xây dựng thiết bị cho WebUSB

Tạo một thiết bị để khai thác tối đa API WebUSB.

Bài viết này giải thích cách xây dựng một thiết bị để khai thác tối đa API WebUSB. Để biết giới thiệu ngắn gọn về chính API này, hãy xem Truy cập thiết bị USB trên web.

Thông tin khái quát

Universal Serial Bus (USB) đã trở thành giao diện thực phổ biến nhất cho kết nối thiết bị ngoại vi với máy tính để bàn và thiết bị di động. Ngoài xác định các đặc điểm điện của xe buýt và mô hình chung của giao tiếp với một thiết bị, thông số kỹ thuật USB bao gồm một tập hợp loại thiết bị thông số kỹ thuật. Đây là các mẫu chung cho các loại thiết bị cụ thể như làm bộ nhớ, âm thanh, video, kết nối mạng, v.v. mà nhà sản xuất thiết bị có thể triển khai. Ưu điểm của những thông số kỹ thuật theo lớp thiết bị này là nhà cung cấp hệ điều hành có thể triển khai một trình điều khiển duy nhất dựa trên lớp ("trình điều khiển lớp") và bất kỳ thiết bị nào triển khai lớp đó sẽ được hỗ trợ. Đây là một cải tiến lớn so với mọi nhà sản xuất cần ghi trình điều khiển thiết bị của riêng họ.

Tuy nhiên, một số thiết bị không phù hợp với một trong các lớp thiết bị được chuẩn hoá này. Đáp thay vào đó, nhà sản xuất có thể chọn gắn nhãn thiết bị của họ là triển khai lớp học của từng nhà cung cấp. Trong trường hợp này, hệ điều hành sẽ chọn thiết bị nào trình điều khiển tải dựa trên thông tin được cung cấp trong gói trình điều khiển của nhà cung cấp, thường là một tập hợp mã nhà cung cấp và mã sản phẩm được biết là để triển khai giao thức cụ thể của nhà cung cấp.

Một tính năng khác của USB là thiết bị có thể cung cấp nhiều giao diện để máy chủ lưu trữ mà chúng được kết nối. Mỗi giao diện có thể triển khai một được chuẩn hoá hoặc theo từng nhà cung cấp. Khi hệ điều hành chọn trình điều khiển bên phải để xử lý thiết bị, mỗi giao diện có thể được xác nhận trình điều khiển. Ví dụ: webcam USB thường cung cấp hai giao diện, một giao diện triển khai lớp video USB (dành cho máy ảnh) và một triển khai USB lớp âm thanh (dành cho micrô). Hệ điều hành không tải một trang web nào "trình điều khiển webcam" nhưng thay vào đó, tải các trình điều khiển lớp âm thanh và video độc lập chịu trách nhiệm cho các chức năng riêng biệt của thiết bị. Chiến dịch này cấu trúc của các lớp giao diện giúp tăng tính linh hoạt.

Kiến thức cơ bản về API

Nhiều lớp USB tiêu chuẩn có API web tương ứng. Ví dụ: một trang có thể quay video từ thiết bị lớp video bằng getUserMedia() hoặc nhận các sự kiện đầu vào từ thiết bị lớp giao diện người dùng (HID) bằng cách lắng nghe cho KeyboardEvents hoặc PointerEvents hoặc bằng cách sử dụng Gamepad hoặc API WebHID. Giống như việc không phải mọi thiết bị đều triển khai định nghĩa lớp được chuẩn hoá, không phải tất cả thiết bị triển khai các tính năng tương ứng với API nền tảng web hiện có. Thời gian đây là trường hợp API WebUSB có thể lấp đầy khoảng trống đó bằng cách đưa ra một cách cho các trang web để xác nhận giao diện dành riêng cho nhà cung cấp và triển khai hỗ trợ cho giao diện đó trực tiếp trên trang của mình.

Yêu cầu cụ thể đối với một thiết bị có thể truy cập qua WebUSB có sự khác biệt đôi chút từ nền tảng này sang nền tảng khác do sự khác biệt về cách hệ điều hành quản lý USB Tuy nhiên, yêu cầu cơ bản là một thiết bị chưa có người lái xe xác nhận giao diện mà trang muốn kiểm soát. Đây có thể là trình điều khiển lớp chung do nhà cung cấp hệ điều hành hoặc trình điều khiển thiết bị cung cấp bởi nhà cung cấp. Vì thiết bị USB có thể cung cấp nhiều giao diện, mỗi giao diện có thể có trình điều khiển riêng, bạn có thể tạo một thiết bị với một số giao diện được xác nhận quyền sở hữu bởi một người lái xe và những người khác có thể truy cập vào trình duyệt.

Ví dụ: bàn phím USB cao cấp có thể cung cấp giao diện lớp HID sẽ được xác nhận quyền sở hữu theo hệ thống con đầu vào của hệ điều hành và quyền sở hữu riêng của nhà cung cấp giao diện vẫn có sẵn cho WebUSB để công cụ cấu hình sử dụng. Chiến dịch này công cụ này có thể được cung cấp trên trang web của nhà sản xuất để cho phép người dùng thay đổi các khía cạnh hành vi của thiết bị như phím macro và hiệu ứng ánh sáng không có cài đặt bất kỳ phần mềm dành riêng cho nền tảng nào. Bộ mô tả cấu hình của thiết bị như vậy sẽ sẽ có dạng như sau:

Phần mô tả cấu hình bao gồm nhiều mã mô tả nối với nhau khi kết hợp cùng nhau. Mỗi trường bắt đầu bằng các trường bLength và bDescriptorType để chúng có thể được xác định. Giao diện đầu tiên là giao diện HID với Bộ mô tả HID và một điểm cuối duy nhất dùng để phân phối các sự kiện đầu vào đến hệ điều hành. Giao diện thứ hai là giao diện dành riêng cho nhà cung cấp với hai điểm cuối có thể dùng để gửi lệnh đến thiết bị và nhận phản hồi của bạn.

Mã mô tả WebUSB

Mặc dù WebUSB có thể hoạt động với nhiều thiết bị mà không cần sửa đổi chương trình cơ sở, bật chức năng bổ sung bằng cách đánh dấu thiết bị với mã mô tả cho biết có hỗ trợ WebUSB. Ví dụ: bạn có thể chỉ định một URL trang đích mà trình duyệt có thể hướng người dùng đến khi thiết bị của bạn đã cắm điện.

Kho lưu trữ đối tượng của thiết bị nhị phân (BOS) là một khái niệm được giới thiệu trong USB 3.0 nhưng có cũng được điều chỉnh cho phiên bản cũ là USB 2.0. Đang khai báo hỗ trợ cho WebUSB bắt đầu bằng việc bao gồm Khả năng nền tảng sau Phần mô tả trong phần mô tả BOS:

Mã nhận dạng duy nhất (UUID) của khả năng nền tảng xác định đây là Khả năng nền tảng WebUSB description [mã_nhận_dạng] cung cấp thông tin cơ bản về thiết bị. Đối với trình duyệt để tìm nạp thêm thông tin về thiết bị, cần sử dụng giá trị bVendorCode để đưa ra yêu cầu bổ sung cho thiết bị. Yêu cầu duy nhất hiện được chỉ định là GET_URL trả về phần mô tả URL. Các thông số này tương tự như chuỗi nhưng được thiết kế để mã hoá URL bằng ít byte nhất. Một URL phần mô tả cho "https://google.com" sẽ có dạng như sau:

Khi thiết bị của bạn được cắm lần đầu tiên vào trình duyệt, trình duyệt sẽ đọc chỉ số mô tả BOS theo cấp chuyển quyền kiểm soát GET_DESCRIPTOR tiêu chuẩn này:

Yêu cầu này thường được thực hiện hai lần, lần đầu là với wLength đủ lớn để máy chủ lưu trữ tìm ra giá trị của trường wTotalLength mà không thực hiện một giao dịch chuyển giao lớn và sau đó thực hiện lại một lần nữa khi độ dài mô tả đầy đủ là đã biết.

Nếu phần mô tả Chức năng nền tảng WebUSB có trường iLandingPage được đặt thành một giá trị khác 0, trình duyệt thực hiện yêu cầu GET_URL dành riêng cho WebUSB bằng cách chuyển giao quyền kiểm soát với bRequest được đặt thành giá trị bVendorCode từ bộ mô tả chức năng của nền tảng và wValue được đặt thành iLandingPage giá trị. Mã yêu cầu cho GET_URL (0x02) nằm trong wIndex:

Xin nhắc lại, yêu cầu này có thể được đưa ra hai lần để lần đầu thăm dò độ dài của phần mô tả đang được đọc.

Những điểm cần cân nhắc theo nền tảng cụ thể

Mặc dù WebUSB API cố gắng cung cấp giao diện nhất quán để truy cập Nhà phát triển thiết bị USB vẫn cần nắm được các yêu cầu đặt ra ứng dụng như yêu cầu về trình duyệt web để truy cập vào thiết bị.

macOS

Không có gì đặc biệt cần thiết đối với macOS. Một trang web sử dụng WebUSB có thể kết nối với thiết bị đó và xác nhận quyền sở hữu mọi giao diện chưa được trình điều khiển nhân hệ điều hành xác nhận quyền sở hữu hoặc một ứng dụng khác.

Linux

Linux giống như macOS nhưng theo mặc định, hầu hết các bản phân phối không thiết lập tài khoản người dùng tài khoản có quyền mở thiết bị USB. Một trình nền hệ thống có tên là udev chịu trách nhiệm chỉ định người dùng và nhóm được phép truy cập vào một thiết bị. Một quy tắc chẳng hạn như thao tác này sẽ gán quyền sở hữu một thiết bị khớp với nhà cung cấp cụ thể và mã sản phẩm vào nhóm plugdev. Đây là một nhóm chung cho những người dùng có quyền truy cập đến thiết bị ngoại vi:

SUBSYSTEM=="usb", ATTR{idVendor}=="XXXX", ATTR{idProduct}=="XXXX", GROUP="plugdev"

Thay thế XXXX bằng mã sản phẩm và mã nhà cung cấp hệ thập lục phân cho thiết bị của bạn, ví dụ: ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11" sẽ phù hợp với Nexus One điện thoại. Bạn phải viết chúng mà không có ký tự "0x" thông thường tiền tố và tất cả chữ thường để được nhận dạng chính xác. Để tìm mã của thiết bị, hãy chạy dòng lệnh công cụ lsusb.

Bạn phải đặt quy tắc này trong một tệp trong thư mục /etc/udev/rules.d và sẽ có hiệu lực ngay khi bạn cắm thiết bị. Không cần khởi động lại udev.

Android

Nền tảng Android dựa trên Linux nhưng không yêu cầu sửa đổi cấu hình hệ thống. Theo mặc định, mọi thiết bị không được tích hợp trình điều khiển vào hệ điều hành mà trình duyệt có thể sử dụng. Nhà phát triển phải Tuy nhiên, người dùng sẽ gặp phải một bước bổ sung khi kết nối với thiết bị. Sau khi người dùng chọn một thiết bị để phản hồi cuộc gọi đến requestDevice(), Android sẽ hiển thị lời nhắc hỏi xem có cho phép hay không Chrome để sử dụng tính năng này. Lời nhắc này cũng sẽ xuất hiện lại nếu người dùng quay lại một trang web đã có quyền kết nối với một thiết bị và trang web gọi open().

Ngoài ra, bạn sẽ có thể truy cập vào nhiều thiết bị hơn trên Android so với Linux trên máy tính để bàn vì theo mặc định, có ít trình điều khiển hơn. Một thiếu sót đáng chú ý, ví dụ: lớp USB CDC-ACM thường được triển khai bằng bộ chuyển đổi USB sang nối tiếp không phải là API trong SDK Android để giao tiếp với một thiết bị nối tiếp.

ChromeOS

ChromeOS cũng hoạt động dựa trên Linux và cũng không yêu cầu sửa đổi cho cấu hình hệ thống. Dịch vụ permission_broker kiểm soát quyền truy cập vào USB thiết bị và sẽ cho phép trình duyệt truy cập vào các thiết bị đó miễn là có ít nhất một giao diện chưa được xác nhận quyền sở hữu.

Windows

Mô hình trình điều khiển Windows đưa ra một yêu cầu bổ sung. Không giống như các nền tảng cao hơn khả năng mở thiết bị USB từ ứng dụng của người dùng mặc định, ngay cả khi không có trình điều khiển nào được tải. Thay vào đó, có một chương trình khuyến mãi trình điều khiển, WinUSB, cần được tải để cung cấp giao diện dùng để truy cập vào thiết bị. Bạn có thể thực hiện việc này bằng cách sử dụng tệp thông tin trình điều khiển (INF) được cài đặt trên hệ thống hoặc bằng cách sửa đổi thiết bị chương trình cơ sở để cung cấp Mã mô tả khả năng tương thích với Microsoft OS trong thời gian liệt kê.

Tệp thông tin về người lái xe (INF)

Tệp thông tin về trình điều khiển cho Windows biết việc cần làm khi gặp thiết bị lần đầu tiên. Vì hệ thống của người dùng đã bao gồm trình điều khiển WinUSB tất cả những gì cần thiết là để tệp INF liên kết mã sản phẩm và nhà cung cấp của bạn bằng quy tắc cài đặt mới này. Tệp dưới đây là một ví dụ cơ bản. Lưu vào tệp có đuôi .inf, hãy thay đổi các phần được đánh dấu bằng "X", rồi thay đổi sang phải hãy nhấp vào ứng dụng đó rồi chọn "Cài đặt" từ trình đơn theo bối cảnh.

[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"

Mục [Dev_AddReg] định cấu hình tập hợp DeviceInterfaceGUIDs cho thiết bị. Mỗi giao diện thiết bị phải có một GUID để ứng dụng tìm và kết nối với ứng dụng đó thông qua API Windows. Sử dụng PowerShell New-Guid cmdlet hoặc công cụ trực tuyến để tạo GUID ngẫu nhiên.

Đối với mục đích phát triển, công cụ Zadig cung cấp giao diện dễ dàng cho thay thế trình điều khiển được tải cho giao diện USB bằng trình điều khiển WinUSB.

Mã mô tả khả năng tương thích với hệ điều hành của Microsoft

Phương pháp sử dụng tệp INF ở trên rất rườm rà vì nó yêu cầu định cấu hình mọi máy của người dùng. Windows 8.1 trở lên cung cấp một giải pháp thay thế thông qua việc sử dụng mã mô tả USB tuỳ chỉnh. Các phần mô tả này cung cấp thông tin vào hệ điều hành Windows khi thiết bị được cắm vào nguồn điện lần đầu. thường được bao gồm trong tệp INF.

Sau khi thiết lập bộ mô tả WebUSB, bạn có thể dễ dàng thêm hệ điều hành của Microsoft cả bộ mô tả khả năng tương thích. Trước tiên, hãy mở rộng phần mô tả BOS bằng thuộc tính này bộ mô tả chức năng bổ sung của nền tảng. Hãy nhớ cập nhật wTotalLength và bNumDeviceCaps để tính đến yếu tố này.

Tương tự như với phần mô tả WebUSB, bạn phải chọn một giá trị bRequest để sử dụng kiểm soát chuyển giao liên quan đến các chỉ số mô tả này. Trong ví dụ này, tôi đã chọn 0x02. 0x07, đặt trong wIndex, là lệnh để truy xuất Microsoft OS 2.0 Đặt từ thiết bị.

Một thiết bị USB có thể có nhiều chức năng nên phần đầu tiên của phần mô tả tập hợp mô tả hàm nào liên kết với các thuộc tính theo sau. Chiến lược phát hành đĩa đơn ví dụ bên dưới định cấu hình giao diện 1 của thiết bị kết hợp. Phần mô tả cung cấp hệ điều hành hai thông tin quan trọng về giao diện này. Thuộc tính tương thích Mã mô tả mã nhận dạng cho Windows biết rằng thiết bị này tương thích với WinUSB trình điều khiển. Bộ mô tả thuộc tính của sổ đăng ký hoạt động tương tự như Phần [Dev_AddReg] của ví dụ về INF ở trên, đặt thuộc tính đăng ký thành gán cho hàm này một GUID giao diện thiết bị.

Windows sẽ chỉ truy vấn thiết bị về thông tin này một lần. Nếu thiết bị có không trả lời kèm theo nội dung mô tả hợp lệ, ứng dụng sẽ không hỏi lại vào lần tới thiết bị đã được kết nối. Microsoft đã cung cấp danh sách USB Device Registry Các mục nhập mô tả các mục nhập đăng ký được tạo khi liệt kê một thiết bị. Thời gian kiểm thử xoá các mục được tạo cho thiết bị để buộc Windows cố gắng đọc mã mô tả một lần nữa.

Để biết thêm thông tin, hãy xem bài đăng trên blog của Microsoft về cách sử dụng mã mô tả.

Ví dụ

Mã mẫu triển khai các thiết bị nhận biết WebUSB bao gồm cả WebUSB có thể tìm thấy mã mô tả và mã mô tả Microsoft OS trong các dự án sau:

• WebLight
• Thư viện WebUSB Arduino