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

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

Reilly Grant

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

Thông tin khái quát

Bus nối tiếp đa năng (USB) đã trở thành giao diện vật lý phổ biến nhất để kết nối thiết bị ngoại vi với máy tính để bàn và thiết bị điện toán di động. Ngoài việc xác định các đặc tính điện của bus và mô hình chung để giao tiếp với thiết bị, thông số kỹ thuật USB còn bao gồm một tập hợp thông số kỹ thuật của lớp thiết bị. Đây là các mô hình chung cho các lớp thiết bị cụ thể như 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 các thông số kỹ thuật về 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 dựa trên thông số kỹ thuật về lớp (một "trình điều khiển lớp") và mọi thiết bị 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 viết 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. 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 dành riêng cho nhà cung cấp. Trong trường hợp này, hệ điều hành sẽ chọn trình điều khiển thiết bị nào sẽ 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 nhóm mã nhận dạng sản phẩm và nhà cung cấp được biết là triển khai một giao thức cụ thể dành riêng cho nhà cung cấp.

Một tính năng khác của USB là các thiết bị có thể cung cấp nhiều giao diện với máy chủ mà chúng được kết nối. Mỗi giao diện có thể triển khai một lớp được chuẩn hoá hoặc dành riêng cho nhà cung cấp. Khi hệ điều hành chọn trình điều khiển phù hợp để xử lý thiết bị, mỗi giao diện có thể được một trình điều khiển khác nhau xác nhận quyền sở hữu. 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 giao diện triển khai lớp âm thanh USB (dành cho micrô). Hệ điều hành không tải một "trình điều khiển webcam" duy nhất mà thay vào đó sẽ 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 về các chức năng riêng biệt của thiết bị. Cấu trúc này 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 sự kiện đầu vào từ thiết bị lớp giao diện người dùng (HID) bằng cách theo dõi KeyboardEvents hoặc PointerEvents, hoặc bằng cách sử dụng Gamepad hoặc API WebHID. Cũng giống như không phải thiết bị nào cũng triển khai định nghĩa lớp được chuẩn hoá, không phải thiết bị nào cũng triển khai các tính năng tương ứng với API nền tảng web hiện có. Trong trường hợp này, API WebUSB có thể lấp đầy khoảng trống đó bằng cách cung cấp cách để các trang web xác nhận quyền sở hữu giao diện dành riêng cho nhà cung cấp và triển khai tính năng hỗ trợ cho giao diện đó ngay trong trang của họ.

Các yêu cầu cụ thể để có thể truy cập vào một thiết bị thông qua WebUSB sẽ khác nhau một chút giữa các nền tảng do sự khác biệt trong cách hệ điều hành quản lý các thiết bị USB, nhưng yêu cầu cơ bản là thiết bị không được có trình điều khiển xác nhận quyền sở hữu 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 cung cấp hoặc trình điều khiển thiết bị do nhà cung cấp cung cấp. Vì các 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, nên bạn có thể tạo một thiết bị mà một số giao diện được trình điều khiển xác nhận quyền sở hữu và các giao diện khác được trình duyệt truy cập.

Ví dụ: bàn phím USB cao cấp có thể cung cấp giao diện lớp HID sẽ được hệ thống con đầu vào của hệ điều hành xác nhận quyền sở hữu và giao diện dành riêng cho nhà cung cấp vẫn có sẵn cho WebUSB để sử dụng bằng một công cụ định cấu hình. Công cụ này có thể được phân phát 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 về hành vi của thiết bị, chẳng hạn như phím macro và hiệu ứng ánh sáng mà không cần cài đặt phần mềm dành riêng cho nền tảng. Phần mô tả cấu hình của một thiết bị như vậy sẽ có dạng như sau:

Mã mô tả cấu hình bao gồm nhiều mã mô tả được nối với nhau. Mỗi phần tử bắt đầu bằng các trường bLength và bDescriptorType để có thể xác định được. Giao diện đầu tiên là giao diện HID có mô tả HID liên kết và một điểm cuối duy nhất dùng để phân phối sự kiện đầu vào cho 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.

Trình 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ở, nhưng chức năng bổ sung sẽ được bật bằng cách đánh dấu thiết bị bằng các đoạn mô tả cụ thể 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 cắm vào.

Kho đối tượng thiết bị tệp nhị phân (BOS) là một khái niệm được giới thiệu trong USB 3.0 nhưng cũng được điều chỉnh cho phiên bản cũ để hỗ trợ các thiết bị USB 2.0 trong phiên bản 2.1. Việc khai báo tính năng hỗ trợ WebUSB bắt đầu bằng việc đưa Nội dung mô tả chức năng nền tảng sau đây vào phần mô tả BOS:

UUID chức năng nền tảng xác định đây là trình mô tả chức năng nền tảng WebUSB, cung cấp thông tin cơ bản về thiết bị. Để trình duyệt tìm nạp thêm thông tin về thiết bị, trình duyệt sẽ sử dụng giá trị bVendorCode để đưa ra các 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. Yêu cầu này trả về một trình mô tả URL. Các chỉ số này tương tự như chỉ số mô tả chuỗi nhưng được thiết kế để mã hoá URL trong ít byte nhất. Chỉ số mô tả URL 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 bằng cách cấp lệnh chuyển điều khiển 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 tiên với wLength đủ lớn để máy chủ tìm ra giá trị của trường wTotalLength mà không cần cam kết chuyển một lượng lớn dữ liệu, sau đó thực hiện lại khi biết được toàn bộ chiều dài chỉ số mô tả.

Nếu chỉ số mô tả Khả năng của nền tảng WebUSB có trường iLandingPage được đặt thành giá trị khác 0, thì trình duyệt sẽ 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ừ chỉ số mô tả khả năng của nền tảng và wValue được đặt thành giá trị iLandingPage. 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 để trước tiên thăm dò độ dài của chỉ số mô tả đang được đọc.

Những điều cần cân nhắc theo nền tảng

Mặc dù API WebUSB cố gắng cung cấp một giao diện nhất quán để truy cập vào các thiết bị USB, nhưng nhà phát triển vẫn cần lưu ý đến các yêu cầu đối với ứng dụng, chẳng hạn như yêu cầu đối với 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 không do trình điều khiển hạt nhân hoặc ứng dụng khác xác nhận quyền sở hữu.

Linux

Linux giống như macOS nhưng theo mặc định, hầu hết các bản phân phối đều không thiết lập tài khoản người dùng 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 như vậy sẽ chỉ định quyền sở hữu của một thiết bị khớp với mã nhà cung cấp và mã sản phẩm đã cho cho nhóm plugdev. Đây là một nhóm chung cho những người dùng có quyền truy cập vào thiết bị ngoại vi:

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

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

Bạn nên đặt quy tắc này trong một tệp trong thư mục /etc/udev/rules.d và quy tắc này sẽ có hiệu lực ngay khi thiết bị được cắm điện. Bạn 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 bất kỳ sửa đổi nào đối vớ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 đều truy cập được vào trình duyệt. Tuy nhiên, nhà phát triển cần lưu ý rằng 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 lệnh gọi đến requestDevice(), Android sẽ hiển thị lời nhắc hỏi xem có cho phép Chrome truy cập vào thiết bị đó hay không. Lời nhắc này cũng xuất hiện trở lại nếu người dùng quay lại một trang web đã có quyền kết nối với thiết bị và trang web đó gọi open().

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

ChromeOS

ChromeOS cũng dựa trên Linux và cũng không yêu cầu sửa đổi cấu hình hệ thống. Dịch vụ permission_broker kiểm soát quyền truy cập vào các thiết bị USB 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 ở trên, khả năng mở thiết bị USB từ ứng dụng người dùng không phải là mặc định, ngay cả khi không có trình điều khiển nào được tải. Thay vào đó, bạn cần tải một trình điều khiển đặc biệt, WinUSB, để cung cấp giao diện mà các ứng dụng sử 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 người lái xe tuỳ chỉnh (INF) được cài đặt trên hệ thống hoặc bằng cách sửa đổi chương trình cơ sở của thiết bị để cung cấp Mã mô tả khả năng tương thích với Microsoft OS trong quá trình liệt kê.

Tệp thông tin trình điều khiển (INF)

Tệp thông tin trình điều khiển cho Windows biết cần làm gì 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, nên tất cả những gì cần thiết là tệp INF liên kết nhà cung cấp và mã sản phẩm của bạn với quy tắc cài đặt mới này. Tệp bên dưới là một ví dụ cơ bản. Lưu tệp đó vào một tệp có đuôi .inf, thay đổi các phần được đánh dấu bằng "X", sau đó nhấp chuột phải vào tệp đó rồi chọn "Cài đặt" trong 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"

Phần [Dev_AddReg] định cấu hình tập hợp các DeviceInterfaceGUID cho thiết bị. Mọi giao diện thiết bị đều phải có GUID để ứng dụng tìm và kết nối với giao diện đó thông qua API Windows. Sử dụng cmdlet PowerShell New-Guid hoặc một 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 một giao diện dễ dàng để 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 tệp INF ở trên khá rườm rà vì yêu cầu phải định cấu hình trước máy của mọi 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 chỉ số mô tả USB tuỳ chỉnh. Các chỉ số mô tả này cung cấp thông tin cho hệ điều hành Windows khi thiết bị được cắm lần đầu tiên. Thông tin này thường có trong tệp INF.

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

Cũng như với các chỉ số mô tả WebUSB, bạn phải chọn một giá trị bRequest để các lượt chuyển đổi điều khiển liên quan đến các chỉ số mô tả này sử dụng. Trong ví dụ này, tôi đã chọn 0x02. 0x07, được đặt trong wIndex, là lệnh để truy xuất Tập hợp chỉ số mô tả Microsoft OS 2.0 từ thiết bị.

Một thiết bị USB có thể có nhiều hàm, do đó, phần đầu tiên của tập hợp đặc tả mô tả hàm nào liên kết với các thuộc tính tiếp theo. Ví dụ bên dưới định cấu hình giao diện 1 của một thiết bị tổng hợp. Phần mô tả cung cấp cho hệ điều hành 2 thông tin quan trọng về giao diện này. Chỉ số mô tả mã nhận dạng tương thích cho Windows biết rằng thiết bị này tương thích với trình điều khiển WinUSB. Thuộc tính mô tả thuộc tính sổ đăng ký hoạt động tương tự như mục [Dev_AddReg] của ví dụ về INF ở trên, thiết lập thuộc tính đăng ký để 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ị để lấy thông tin này một lần. Nếu thiết bị không phản hồi bằng các chỉ số mô tả hợp lệ, thì thiết bị sẽ không hỏi lại vào lần tiếp theo khi thiết bị được kết nối. Microsoft đã cung cấp danh sách các mục nhập đăng ký thiết bị USB mô tả các mục nhập đăng ký được tạo khi liệt kê một thiết bị. Khi kiểm thử, hãy xoá các mục đã tạo cho một thiết bị để buộc Windows cố gắng đọc lại các chỉ số mô tả.

Để 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 các chỉ số mô tả này.

Ví dụ

Bạn có thể tìm thấy mã ví dụ triển khai các thiết bị nhận biết WebUSB bao gồm cả chỉ số mô tả WebUSB và chỉ số mô tả hệ điều hành Microsoft trong các dự án sau:

• WebLight
• Thư viện Arduino WebUSB