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 tạo thiết bị để tận dụng tối đa API WebUSB. Để tìm hiểu giới thiệu ngắn gọn về chính API này, hãy xem bài viết 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 các thiết bị ngoại vi với máy tính và thiết bị điện toán di động. Ngoài việc xác định các đặc điểm điện của xe buýt và một mô hình chung để giao tiếp với một thiết bị, thông số kỹ thuật của 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 dành cho các loại thiết bị cụ thể, chẳng hạn như bộ nhớ, âm thanh, video, 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 của 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 thông số kỹ thuật của lớp ("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 tuyệt vời đối với mọi nhà sản xuất cần phải 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ị đã 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 mình 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ị để 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à cung cấp và mã sản phẩm được biết đến để triển khai một giao thức cụ thể của 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 cho máy chủ lưu trữ đã kết nối với chúng. 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ột trình điều khiển khác có thể xác nhận quyền sở hữu mỗi giao diện. Ví dụ: webcam USB thường cung cấp 2 giao diện, một giao diện triển khai lớp video USB (cho máy ảnh) và một giao diện triển khai lớp âm thanh USB (cho micrô). Hệ điều hành không tải một "trình điều khiển webcam" 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 cho các chức năng riêng biệt của thiết bị. Thành phần này của các lớp giao diện mang lại sự linh hoạt cao hơn.

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ừ mộ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 có giao diện người dùng (HID) bằng cách nghe KeyboardEvents hoặc PointerEvents hoặc bằng cách sử dụng Gamepad hoặc API WebHID. Giống như không phải thiết bị nào cũng triển khai định nghĩa lớp chuẩn, 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ể bổ sung thông tin còn thiếu bằng cách cung cấp một cách để các trang web xác nhận giao diện dành riêng cho nhà cung cấp và triển khai dịch vụ hỗ trợ cho giao diện đó ngay trên trang.

Các yêu cầu cụ thể để có thể truy cập một thiết bị qua WebUSB sẽ khác nhau đôi chút theo từng nền tảng do sự khác biệt về cách hệ điều hành quản lý thiết bị USB. Tuy nhiên, yêu cầu cơ bản là thiết bị phải chưa có trình điều khiển xác nhận giao diện mà trang muốn điều khiển. Đâ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ể xây dựng 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 cho 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 đầ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 để công cụ cấu hình sử dụng. Công cụ này có thể được phân phát trên trang web của nhà sản xuất. Nhờ đó, người dùng có thể thay đổi hành vi của thiết bị, chẳng hạn như các khoá macro và hiệu ứng ánh sáng mà không cần cài đặt bất kỳ phần mềm dành riêng cho nền tảng nào. Mã mô tả cấu hình của thiết bị như vậy sẽ có dạng như sau:

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

Chỉ số 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 bạn có thể bật thêm chức năng bằng cách đánh dấu thiết bị kèm theo các phần mô tả cụ thể cho biết có hỗ trợ WebUSB. Ví dụ: bạn có thể chỉ định 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.

Kho lưu trữ đối tượng thiết bị nhị phân (Binary Device Object Store) 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ũ bằng các thiết bị USB 2.0 như một phần của phiên bản 2.1. Việc khai báo tính năng hỗ trợ cho WebUSB bắt đầu bằng việc đưa nội dung mô tả chức năng của nền tảng sau đây vào phần mô tả BOS:

Mã nhận dạng duy nhất (UUID) của tính năng nền tảng xác định đây là mã mô tả Khả năng của nền tảng WebUSB. Mã này 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ử 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ề chỉ số mô tả URL. Các ký tự này tương tự như mã mô tả chuỗi nhưng được thiết kế để mã hoá URL có ít byte nhất. Phần 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 vào trình duyệt, sẽ đọc thông tin mô tả BOS bằng cách truyền 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ủ lưu trữ tìm ra giá trị của trường wTotalLength mà không cần cam kết chuyển số lượng lớn, sau đó thực hiện lại lần nữa khi xác định được độ dài đầy đủ của chỉ số mô tả.

Nếu bộ mô tả Khả năng của nền tảng WebUSB đặt trường iLandingPage 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 quyền kiểm soát với bRequest được đặt thành giá trị bVendorCode từ chỉ số mô tả chức 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) sẽ có trong wIndex:

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

Những điểm cần cân nhắc tuỳ 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 thiết bị USB, các nhà phát triển vẫn cần lưu ý đến các yêu cầu áp dụng cho ứng dụng, chẳng hạn như yêu cầu của trình duyệt web để truy cập vào thiết bị.

macOS

Không có gì đặc biệ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 bất kỳ giao diện nào chưa được trình điều khiển nhân hệ điều hành 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 udev chịu trách nhiệm chỉ định người dùng và nhóm được phép truy cập vào thiết bị. Một quy tắc như thế này sẽ chỉ định quyền sở hữu một thiết bị khớp với mã sản phẩm và nhà cung cấp đã cho cho nhóm plugdev. Đây là một nhóm phổ biến cho những người dùng có quyền truy cập vào các 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ẽ khớp với điện thoại Nexus One. Những mã này phải được viết mà không có tiền tố "0x" thông thường và tất cả chữ thường phải được nhận dạng chính xác. Để tìm mã nhận dạng cho thiết bị của bạn, hãy chạy công cụ dòng lệnh lsusb.

Bạn phải đặt quy tắc này trong một tệp ở 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 vào nguồn. Bạn không cần phải 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ó trình điều khiển tích hợp vào hệ điều hành đều có sẵn cho trình duyệt. Tuy nhiên, nhà phát triển nê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 lại nếu người dùng quay lại 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, sẽ có nhiều thiết bị truy cập được trên Android hơn so với Linux trên máy tính vì có ít trình điều khiển được đưa vào theo mặc định. Ví dụ: một thiếu sót đáng chú ý là loại 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 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 cần 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 thêm một yêu cầu. 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 của người dùng không phải là tính nă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 trình điều khiển đặc biệt, WinUSB, cần được tải để cung cấp giao diện mà các ứng dụng dùng để truy cập vào thiết bị. Bạn có thể thực hiện việc này bằng một tệp thông tin tuỳ chỉnh về 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 chương trình cơ sở của thiết bị để cung cấp Nội dung mô tả về khả năng tương thích với hệ điều hành của Microsoft trong quá trình liệt kê.

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

Tệp thông tin trình điều khiển sẽ cho Windows biết việc cần làm trong lần đầu tiên gặp phải thiết bị. 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 phải 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 dưới đây là một ví dụ cơ bản. Lưu vào một tệp có đuôi .inf, thay đổi các phần được đánh dấu bằng dấu "X", sau đó nhấp chuột phải vào tệp đó và chọn "Cài đặt" trên 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ị phải có GUID để ứng dụng tìm và kết nối với ứng dụng đó thông qua API Windows. Hãy sử dụng lệnh ghép nhỏ PowerShell New-Guid hoặc một công cụ trực tuyến để tạo một 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.

Bộ 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 rườm rà vì yêu cầu đị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 bộ 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. Thông tin này sẽ được đưa vào tệp INF.

Sau khi thiết lập bộ mô tả WebUSB, bạn cũng 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 chỉ số mô tả BOS bằng mã mô tả chức năng bổ sung của nền tảng này. Hãy nhớ cập nhật wTotalLength và bNumDeviceCaps để tính đến.

Tương tự như với bộ mô tả WebUSB, bạn phải chọn một giá trị bRequest để sử dụng trong quá trình chuyển quyền kiểm soát liên quan đến các bộ mô tả này. Trong ví dụ này, tôi đã chọn 0x02. 0x07, nằm trong wIndex, là lệnh để truy xuất Bộ mô tả Microsoft OS 2.0 qua 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 chỉ số mô tả sẽ mô tả hàm mà các thuộc tính theo sau được liên kết. 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 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 sẽ cho Windows biết rằng thiết bị này tương thích với trình điều khiển WinUSB. Mã mô tả thuộc tính đăng ký hoạt động tương tự như phần [Dev_AddReg] của ví dụ INF ở trên, khi thiết lập thuộc tính sổ đă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ị đối với thông tin này một lần. Nếu thiết bị không phản hồi với phần mô tả hợp lệ, thì thiết bị sẽ không hỏi lại vào lần tiếp theo thiết bị được kết nối. Microsoft đã cung cấp danh sách các Mục đă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 được tạo cho thiết bị để buộc Windows phải đọc lại mã mô tả.

Để biết thêm thông tin, hãy xem bài đăng trên blog của Microsoft để biết cách sử dụng các thuộc tính 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 có cả bộ mô tả WebUSB và bộ mô tả hệ điều hành Microsoft trong các dự án sau:

• WebLight
• Thư viện WebUSB Arduino