1. HTML5 WebUSB 的核心原理
1.1 WebUSB 的目标与定位
HTML5 WebUSB 提供了一组浏览器端 API，使网页能够直接与 USB 设备进行通信，这对嵌入式设备开发尤为重要。核心目标是把底层 USB 协议握手提升为浏览器原生能力，同时约束在用户授权的场景下进行数据传输，提升跨平台开发的效率。
在实现层面，浏览器暴露了 navigator.usb、USBDevice、USBInterface 等对象，让前端页面可以发现、打开、配置以及与设备交互。设备描述符、端点和 传输类型成为网页端控制设备的关键要素。
1.2 浏览器接口与权限模型
与传统桌面应用不同，WebUSB 的访问必须经由被用户同意的对话框触发，这也构成了它的安全边界。在 HTTPS-origin 或本地开发环境下，页面通过 requestDevice 请求设备权限，获授权后才进入后续数据传输阶段。
此外，getDevices、requestDevice 等 API 提供了设备枚举与选择的能力，但都需要在用户明确互动后才会生效，这样能避免网页隐蔽访问设备的风险。
async function listDevices() {
const devices = await navigator.usb.getDevices();
devices.forEach(d => console.log(d.productName));
}
2. 安全模型与权限管理
2.1 HTTPS 与 origin 限制
为保证嵌入式设备接入的可控性，WebUSB 行为仅在 HTTPS-origin 生效，或者在本地开发环境下通过 localhost 进行调试。这一限制确保了网页不会在没有保护的连接中滥用设备。
源域身份 与 设备许可 是双重保障；浏览器会在用户交互后，才授权网站对特定 USB 设备的访问，并且通常只在当前页面或标签页中有效。
2.2 用户授权与对话框行为
当网页需要访问设备时，浏览器会弹出一个系统级的对话框，显示设备信息（如 厂商 ID、产品名 等）以供选择。用户确认后，网页才能继续执行数据传输。
授权状态可以在会话期间缓存，但离开页面或清空浏览器缓存后，权限将重置，这对于嵌入式设备的上线流程是一个清晰的边界。
async function connect() {
const device = await navigator.usb.requestDevice({ filters: [{ vendorId: 0x1234 }] });
await device.open();
if (device.configuration === null) {
await device.selectConfiguration(1);
}
await device.claimInterface(0);
}
3. 嵌入式设备的开发与对接实操
3.1 设备扫描与枚举
嵌入式设备通常通过 厂商 ID 与 产品 ID 来标识，固件需暴露可访问的 USB 接口描述符以便 WebUSB 发现。设备枚举在用户授权后才会返回实际设备列表。
前端可以通过 navigator.usb.getDevices() 获取已授权的设备，再结合 DeviceInformation 属性进行后续匹配和通信。
3.2 数据传输与控制传输
设备在建立连接后，常用的两类传输路径是 传输端点（bulk/interrupt/isochronous）和 控制传输。前者用于高吞吐数据，后者用于设置、配置与查询。
在前端，transferIn、transferOut、以及 controlTransferIn/Out 等 API 提供了对设备的读写能力，开发者需要根据设备的 接口号 与 端点号 组织数据帧。
async function transferData(device) {
// 假设接口 0、端点 1 用于输出数据
const dataOut = new Uint8Array([0x01, 0x02, 0x03]);
await device.transferOut(1, dataOut);
// 读取返回数据，期望长度 64 字节
const result = await device.transferIn(1, 64);
console.log('Received:', new Uint8Array(result.data.buffer));
}
4. 兼容性、生态与替代方案
4.1 主流浏览器支持现状
在桌面端，Chrome、Edge 等基于 Chromium 的浏览器对 WebUSB 的支持较为完善，而 Firefox、Safari 等浏览器对该能力的实现程度不同，需要关注各自的实验性开关与隐私策略。
在移动端，Android 版 Chrome 等浏览器支持较好，但iOS 端的 Safari 通常尚不提供稳定的 WebUSB API，因此跨平台方案需要以桌面端作为主入口，移动端通过其他传输方案补充。
4.2 与现有 USB API 的对比
相比原生桌面应用，WebUSB 将设备访问前置到网页层，但对权限控制更加严格。与 HID/CDC 等传统驱动模式相比，WebUSB 提供了更直观的网页交互语义，同时要求设备具备描述符以实现自动发现与安全验证。
在嵌入式设备上，设计时应确保固件能同时支持 WebUSB 描述符 与兼容性 G-code、控制传输等通用接口，以降低跨系统的接入成本。
5. 实操清单与常见错误排查
5.1 调试与日志定位
在调试阶段，务必通过 浏览器开发者工具 的控制台与网络面板观察 API 调用的返回值、错误码以及设备枚举结果。详细日志 能帮助定位设备描述符不匹配、端点号错配等问题。
要点包括：确保页面在 HTTPS 下运行、在用户操作后调用 requestDevice、正确处理 device.open、claimInterface 与传输的错误码。
5.2 典型错误与解决思路
若遇到设备未列出、权限被拒绝等情况，首要确认的有：厂商 ID/产品 ID匹配、固件描述符正确、浏览器对 WebUSB 的当前支持状态，以及设备在调试模式下是否需要特定模式进入传输。
排查流程建议：重置设备、在控制台输出设备信息、逐步放大传输分组大小，并确保 端点号 与固件一致。
navigator.usb.addEventListener('connect', (e) => {
console.log('USB device connected:', e.device.productName);
});
navigator.usb.addEventListener('disconnect', (e) => {
console.log('USB device disconnected:', e.device.productName);
});
