1 Commits
Author SHA1 Message Date
jiangchen 929bf061d0 docs: 补上先例调研与安卓 Web Serial 的真实进展
test / test (push) Canceled after 0s
- 新增"先例与定位":Linux ch341.c / selevo / 3fffff / calcite / web-serial-polyfill /
  bbamorachi 站点 / SchoepsLabs 等,明确本库是工程化而非首创
- 修正"安卓没有 Web Serial"的表述:Chrome Android 138+ 已支持蓝牙 RFCOMM,
  USB 串口依赖 Android Serial API(2026 Q2 起、部分机型,预计 M149)
- docs 补"与其它实现的关系"
2026-09-23 00:48:32 +08:00
2 changed files with 43 additions and 0 deletions
+34
View File
@@ -105,10 +105,20 @@ npx serve . # 或 python -m http.server 8080
也就是说:**安卓端零驱动**(这正是本项目的重点),桌面端用系统/官方驱动 + Web Serial 即可。 也就是说:**安卓端零驱动**(这正是本项目的重点),桌面端用系统/官方驱动 + Web Serial 即可。
垫片只在"有 WebUSB 且没有 Web Serial"时安装,桌面端不会被改变行为。 垫片只在"有 WebUSB 且没有 Web Serial"时安装,桌面端不会被改变行为。
> **平台动向(2026-09 现状,做选型时要看)**
> Chrome for Android **138+ 起已经有 Web Serial**,但覆盖的是**蓝牙 RFCOMM** 串口;
> **USB 串口**要等新的 Android Serial API——按 blink-dev 的 PSA,
> 它从 **2026 Q2** 起、且**仅在部分机型**上可用(预计里程碑 M149)。
> 也就是说:对绝大多数安卓机来说,USB 串口今天仍然只能靠 WebUSB 自己带驱动,
> 这正是本项目存在的理由;等 Android Serial API 普及后,本库依然适用于
> 未覆盖机型、WebView 套壳应用与旧版浏览器。
> 参考:chromestatus feature 6043992171085824、blink-dev PSA "Web Serial API on Android"(2026-02-10)、caniuse issue #7413。
## 安卓注意事项 ## 安卓注意事项
1. **必须 HTTPS**(`localhost` 除外),且要用**用户手势**(点击)触发连接。 1. **必须 HTTPS**(`localhost` 除外),且要用**用户手势**(点击)触发连接。
2. 只有 **Chromium 系**浏览器可以:Chrome / Edge / Brave / Kiwi。Firefox 安卓没有 WebUSB,iOS 全线没有。 2. 只有 **Chromium 系**浏览器可以:Chrome / Edge / Brave / Kiwi。Firefox 安卓没有 WebUSB,iOS 全线没有。
注意别和"安卓已经有 Web Serial 了"混淆:138+ 的安卓 Web Serial 只覆盖**蓝牙**串口,**USB** 串口要等 Android Serial API(2026 Q2 起、部分机型)。
3. 需要 **OTG**:手机要支持 USB Host;部分机型 OTG 与充电互斥、供电不足会表现为反复掉线。 3. 需要 **OTG**:手机要支持 USB Host;部分机型 OTG 与充电互斥、供电不足会表现为反复掉线。
4. **CH340 是 vendor-specific 类(0xFF)**,安卓内核不会去绑定它,所以能被浏览器抢占; 4. **CH340 是 vendor-specific 类(0xFF)**,安卓内核不会去绑定它,所以能被浏览器抢占;
CDC-ACM 类设备在个别 ROM 上会被内核 `cdc_acm` 先占,`claimInterface` 会失败(报错已给出提示)。 CDC-ACM 类设备在个别 ROM 上会被内核 `cdc_acm` 先占,`claimInterface` 会失败(报错已给出提示)。
@@ -170,6 +180,30 @@ $ node test/driver.test.mjs
> (WebUSB 只认 WinUSB/libusb 绑定的设备),所以桌面端请用 Web Serial(本库的垫片在桌面不会安装, > (WebUSB 只认 WinUSB/libusb 绑定的设备),所以桌面端请用 Web Serial(本库的垫片在桌面不会安装,
> 测试页会自动走原生 Web Serial)。安卓没有这个问题——内核根本不绑定 CH340。 > 测试页会自动走原生 Web Serial)。安卓没有这个问题——内核根本不绑定 CH340。
## 先例与定位(我们不是第一个)
CH340 用 WebUSB 直连这件事**早有先例**,本项目的价值在于"把它做成能直接用的库",而不是发明了新方法:
| 先例 | 做了什么 | 与本库的关系 |
|---|---|---|
| Linux 内核 drivers/usb/serial/ch341.c | CH340/CH341 寄存器与初始化序列的原始出处 | 本库的控制传输序列就是对齐它 |
| [selevo/WebUsbSerialTerminal](https://github.com/selevo/WebUsbSerialTerminal) 15星 | WebUSB 串口终端,README 明写 work on android browser,serial.js 注释写明"把 Linux ch341.c 改写成 WebUSB" | 核心手法相同;形态是终端页面,不是可复用库 |
| [3fffff/webusb-ch341](https://github.com/3fffff/webusb-ch341) 6星 | WebUSB CH341:UART / I2C / SPI / GPIO | 单芯片、偏工具 |
| [calcite/WebUSB-CP2102](https://github.com/calcite/WebUSB-CP2102) | WebUSB CP2102 通信库 | 同类思路,另一种芯片 |
| [web-serial-polyfill](https://www.npmjs.com/package/web-serial-polyfill)(Chrome 团队原型) | 用 WebUSB 实现 Serial API,官方说明"对安卓这类有 WebUSB 无 Web Serial 的平台仍然有用" | 垫片思路的先例;但它依赖设备未被系统驱动占用,不做 CH340 的厂商寄存器初始化 |
| tools.bbamorachi.us(生产站点) | 五芯片 WebUSB 驱动 + 按 UA 分流,安卓可用 | 本库的参考实现之一 |
| [SchoepsLabs/webserial-android](https://github.com/SchoepsLabs/webserial-android)(Kotlin/APK) | 套壳浏览器,替网页桥接 USB 串口 | 说明平台缺口真实存在,而本库是免安装的网页侧解法 |
| [therealmacoy360/aries-vigilant-gui](https://github.com/therealmacoy360/aries-vigilant-gui) 等 | "桌面 Web Serial + 安卓 WebUSB" 双路模式 | 与本库同一套取舍 |
本库补上的空白(截至发版时未找到对应开源实现):
1. **npm 上没有 CH340/CH341 的浏览器端驱动包** —— 检索 ch340 / ch341 / webusb ch340 driver 只得到 Node 侧或无关包;
2. **CH340 版的 navigator.serial 垫片**:让未修改的 Web Serial 站点在安卓上跑起来(web-serial-polyfill 不做厂商初始化,CH340 用不了);
3. **五芯片 + 全部支持 DTR/RTS + 拔插事件 + 诊断 + 单测 + TS 类型 + CI** 的打包形态。
换句话说:**不是开创先河,是把已验证的路子工程化**。想真正"开创",最实在的两条路是把
CH340 支持提给上游(如 web-serial-polyfill)或发布到 npm 让别人直接用。
## 许可 ## 许可
MIT MIT
+9
View File
@@ -98,6 +98,15 @@ write(0x9A, 0x0F2C, factor & 0xFF); // 低位
- open 时如果 `device.configuration` 为空,先 `selectConfiguration(configurations[0])`; - open 时如果 `device.configuration` 为空,先 `selectConfiguration(configurations[0])`;
然后 `claimInterface`,非 0 的 alt setting 需要 `selectAlternateInterface`。 然后 `claimInterface`,非 0 的 alt setting 需要 `selectAlternateInterface`。
## 与其它实现的关系
本文件描述的序列与下列实现一致,可互相印证:
- Linux 内核 drivers/usb/serial/ch341.c(原始出处)
- selevo/WebUsbSerialTerminal 的 serial.js(WebUSB 版移植,README 声明 work on android browser)
- tools.bbamorachi.us 前端驱动(五芯片,含 CH340)
- Google 的 web-serial-polyfill(Serial API over WebUSB,但不含 CH340 厂商初始化)
## 为什么安卓不用装驱动 ## 为什么安卓不用装驱动
CH340 的接口类标志是 `0xFF`(vendor-specific),安卓/Linux 内核**不会**给它绑定 CH340 的接口类标志是 `0xFF`(vendor-specific),安卓/Linux 内核**不会**给它绑定