diff --git a/README.md b/README.md index 63ac79b..adc1f35 100644 --- a/README.md +++ b/README.md @@ -105,10 +105,20 @@ npx serve . # 或 python -m http.server 8080 也就是说:**安卓端零驱动**(这正是本项目的重点),桌面端用系统/官方驱动 + 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` 除外),且要用**用户手势**(点击)触发连接。 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 与充电互斥、供电不足会表现为反复掉线。 4. **CH340 是 vendor-specific 类(0xFF)**,安卓内核不会去绑定它,所以能被浏览器抢占; CDC-ACM 类设备在个别 ROM 上会被内核 `cdc_acm` 先占,`claimInterface` 会失败(报错已给出提示)。 @@ -170,6 +180,30 @@ $ node test/driver.test.mjs > (WebUSB 只认 WinUSB/libusb 绑定的设备),所以桌面端请用 Web Serial(本库的垫片在桌面不会安装, > 测试页会自动走原生 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 diff --git a/docs/ch34x-registers.md b/docs/ch34x-registers.md index c8d241f..3e315ea 100644 --- a/docs/ch34x-registers.md +++ b/docs/ch34x-registers.md @@ -98,6 +98,15 @@ write(0x9A, 0x0F2C, factor & 0xFF); // 低位 - open 时如果 `device.configuration` 为空,先 `selectConfiguration(configurations[0])`; 然后 `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 内核**不会**给它绑定