lihao
/
photovoltaic-pc
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Browse Source

feat: 功能文档

master
WIN-87ES3P38OPV\EDY 7 days ago
parent
3cc201d62f
commit
8f8e0f94b4
1 changed files with 298 additions and 0 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 298
      md/webview-usb-serial.md

298
md/webview-usb-serial.md
Unescape View File

@ -0,0 +1,298 @@ @@ -0,0 +1,298 @@
# USB Serial JS 桥接文档
## 概述
`usbSerial` 对象由 Android 端注入 WebView，提供 USB 串口设备的发现、探测、连接及数据读写能力。
## 注入对象
Android 端在初始化 WebView 时会注入全局对象 `usbSerial`，web 端可直接通过 `window.usbSerial` 或 `usbSerial` 访问。
## 方法
### 设备发现
| 方法 | 描述 | 参数 | 返回值 |
| -------------------- | -------------------------- | ---- | ------ |
| startDiscovery() | 开始 USB 设备发现 | 无 | 无 |
| stopDiscovery() | 停止 USB 设备发现 | 无 | 无 |
| getDiscoveredDevices() | 获取已发现的设备列表 | 无 | 空数组 `"[]"`（预留接口） |
### 设备探测
| 方法 | 描述 | 参数 | 返回值 |
| ------------------------------------------------------------ | -------------------------- | ----------------------------------------------------------------------- | ------ |
| deviceProbe(deviceName, portNumber, baudRate, hexCmd, timeoutMs) | 手动探测指定设备的串口响应 | deviceName: 设备名称 (String)<br>portNumber: 端口号 (Int)<br>baudRate: 波特率 (Int)<br>hexCmd: 探测命令十六进制字符串，不发送时传空串 `""` (String)<br>timeoutMs: 超时毫秒数 (Int) | 无 |
### 设备连接
| 方法 | 描述 | 参数 | 返回值 |
| -------------------------------------------- | ------------------ | ---------------------------------------------------------------------------- | ------ |
| deviceOpen(deviceName, portNumber, baudRate) | 打开设备串口连接 | deviceName: 设备名称 (String)<br>portNumber: 端口号 (Int)<br>baudRate: 波特率 (Int) | 无 |
| deviceClose(deviceName, portNumber) | 关闭设备串口连接 | deviceName: 设备名称 (String)<br>portNumber: 端口号 (Int) | 无 |
### 数据写入
| 方法 | 描述 | 参数 | 返回值 |
| ---------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------- | ------ |
| deviceWrite(deviceName, portNumber, hexData) | 向已连接的设备发送数据 | deviceName: 设备名称 (String)<br>portNumber: 端口号 (Int)<br>hexData: 十六进制字符串 (String) | 无 |
> **注意**：`deviceWrite` 仅在连接状态为 `CONNECTED` 时才会实际发送数据，且需要 hexData 非空。
---
## 回调函数
web 端需要在 `usbSerial` 对象上实现以下回调函数，以接收 Android 端的异步通知。所有回调函数均无返回值。
> 回调函数注册方式：
> ```js
> usbSerial.onDeviceAttached = function(jsonStr) {
> const data = JSON.parse(jsonStr);
> console.log("设备插入:", data);
> };
> ```
### 设备插拔回调
| 方法 | 描述 | 参数 |
| ------------------------------- | ------------------ | -------------------------------- |
| onDeviceAttached(jsonStr) | USB 设备插入时回调 | JSON 字符串，结构见下文 |
| onDeviceDetached(jsonStr) | USB 设备拔出时回调 | JSON 字符串，结构见下文 |
### 设备发现回调
| 方法 | 描述 | 参数 |
| ----------------------------------- | ---------------------------------- | -------------------------------- |
| onDeviceDiscovered(jsonStr) | 设备匹配到探测协议时回调 | JSON 字符串，结构见下文 |
| onDeviceProbeResult(jsonStr) | `deviceProbe()` 执行结果回调 | JSON 字符串，结构见下文 |
### 设备连接回调
| 方法 | 描述 | 参数 |
| ------------------------------- | ------------------------ | -------------------------------- |
| onDeviceOpened(jsonStr) | `deviceOpen()` 执行结果 | JSON 字符串，结构见下文 |
| onDeviceState(jsonStr) | 连接状态变化时回调 | JSON 字符串，结构见下文 |
### 数据接收回调
| 方法 | 描述 | 参数 |
| --------------------------- | -------------------------- | -------------------------------- |
| onDeviceData(jsonStr) | 收到设备上报数据时回调 | JSON 字符串，结构见下文 |
---
## 数据结构
### onDeviceAttached 回调
```json
{
"deviceName": "/dev/bus/usb/001/002",
"deviceId": 1002,
"ports": [1, 2]
}
```
| 字段 | 类型 | 描述 |
| ------------ | -------- | ------------------------ |
| deviceName | String | 设备路径名称 |
| deviceId | Number | USB 设备 ID |
| ports | Array | 可用串口端口号列表 |
### onDeviceDetached 回调
```json
{
"deviceName": "/dev/bus/usb/001/002",
"deviceId": 1002
}
```
| 字段 | 类型 | 描述 |
| ------------ | -------- | ------------------------ |
| deviceName | String | 设备路径名称 |
| deviceId | Number | USB 设备 ID |
### onDeviceDiscovered 回调
```json
{
"deviceName": "/dev/bus/usb/001/002",
"port": 1,
"probeId": "my-probe",
"baudRate": 9600,
"responseHex": "01020304"
}
```
| 字段 | 类型 | 描述 |
| ------------ | -------- | -------------------------------- |
| deviceName | String | 设备路径名称 |
| port | Number | 端口号 |
| probeId | String | 匹配的探测协议 ID |
| baudRate | Number | 探测到的波特率 |
| responseHex | String | 设备响应数据的十六进制字符串 |
### onDeviceProbeResult 回调
```json
{
"deviceName": "/dev/bus/usb/001/002",
"port": 1,
"baudRate": 115200,
"success": true,
"responseHex": "AABBCC",
"error": ""
}
```
| 字段 | 类型 | 描述 |
| ------------ | -------- | ------------------------------------------ |
| deviceName | String | 设备路径名称 |
| port | Number | 端口号 |
| baudRate | Number | 探测使用的波特率 |
| success | Boolean | 探测是否成功 |
| responseHex | String | 设备响应数据的十六进制字符串（失败时为空串） |
| error | String | 错误信息（成功时为空串） |
### onDeviceOpened 回调
```json
{
"deviceName": "/dev/bus/usb/001/002",
"port": 1,
"success": true,
"error": ""
}
```
| 字段 | 类型 | 描述 |
| ------------ | -------- | ------------------------------------------ |
| deviceName | String | 设备路径名称 |
| port | Number | 端口号 |
| success | Boolean | 打开是否成功 |
| error | String | 错误信息（成功时为空串）；可能值：`"Device not found"`、`"Port not found"` |
### onDeviceState 回调
```json
{
"deviceName": "/dev/bus/usb/001/002",
"port": 1,
"state": "CONNECTED"
}
```
| 字段 | 类型 | 描述 |
| ------------ | -------- | ------------------------------------------------------ |
| deviceName | String | 设备路径名称 |
| port | Number | 端口号 |
| state | String | 连接状态：`"CONNECTED"` \| `"CONNECTING"` \| `"DISCONNECTED"` |
### onDeviceData 回调
```json
{
"deviceName": "/dev/bus/usb/001/002",
"port": 1,
"hexData": "01020304AABB"
}
```
| 字段 | 类型 | 描述 |
| ------------ | -------- | ------------------------------ |
| deviceName | String | 设备路径名称 |
| port | Number | 端口号 |
| hexData | String | 收到的数据，十六进制大写字符串 |
---
## 连接状态枚举
| 状态 | 触发时机 |
| ----------------- | ------------------------------------- |
| `CONNECTING` | `deviceOpen` 后正在尝试打开串口 |
| `CONNECTED` | 串口打开成功，可以发送和接收数据 |
| `DISCONNECTED` | 串口未连接、连接失败或被拔出 |
---
## 典型使用流程
### 1. 启动发现
```js
// 注册回调
usbSerial.onDeviceAttached = function(json) {
const dev = JSON.parse(json);
console.log("发现设备:", dev.deviceName, "ports:", dev.ports);
};
usbSerial.onDeviceDetached = function(json) {
const dev = JSON.parse(json);
console.log("设备拔除:", dev.deviceName);
};
usbSerial.onDeviceState = function(json) {
const s = JSON.parse(json);
console.log("连接状态:", s.deviceName, s.port, s.state);
};
usbSerial.onDeviceData = function(json) {
const d = JSON.parse(json);
console.log("收到数据:", d.hexData);
};
// 开始发现
usbSerial.startDiscovery();
```
### 2. 手动探测设备
```js
usbSerial.onDeviceProbeResult = function(json) {
const result = JSON.parse(json);
if (result.success) {
console.log("探测成功, 响应:", result.responseHex);
} else {
console.log("探测失败:", result.error);
}
};
// 对 /dev/bus/usb/001/002 端口1 以 9600 波特率发 "010300000001" 超时 500ms
usbSerial.deviceProbe("/dev/bus/usb/001/002", 1, 9600, "010300000001", 500);
```
### 3. 打开设备进行通信
```js
usbSerial.onDeviceOpened = function(json) {
const result = JSON.parse(json);
if (result.success) {
console.log("设备打开成功");
// 发送数据（十六进制字符串）
usbSerial.deviceWrite(result.deviceName, result.port, "010300000001");
} else {
console.log("打开失败:", result.error);
}
};
usbSerial.deviceOpen("/dev/bus/usb/001/002", 1, 9600);
```
### 4. 关闭设备
```js
usbSerial.deviceClose("/dev/bus/usb/001/002", 1);
```
---
## 注意事项
1. **串口参数固定**：数据位 8、停止位 1、无校验位，不可配置。
2. **设备键值**：内部以 `"deviceName:portNumber"` 唯一标识一个连接，同一设备不同端口可同时打开。
3. **拔除自动清理**：设备拔出时对应连接会自动销毁，无需手动调用 `deviceClose`。
4. **线程安全**：所有方法可以在 JS 主线程直接调用，Android 侧会处理线程调度。
5. **`getDiscoveredDevices`** 为预留接口，当前仅返回 `"[]"`，后续版本会实现。
Write Preview
Loading…
Cancel
Save