photovoltaic-pc/md/webview-usb-serial.md

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) portNumber: 端口号 (Int) baudRate: 波特率 (Int) hexCmd: 探测命令十六进制字符串，不发送时传空串 "" (String) timeoutMs: 超时毫秒数 (Int)	无

设备连接

方法	描述	参数	返回值
deviceOpen(deviceName, portNumber, baudRate)	打开设备串口连接	deviceName: 设备名称 (String) portNumber: 端口号 (Int) baudRate: 波特率 (Int)	无
deviceClose(deviceName, portNumber)	关闭设备串口连接	deviceName: 设备名称 (String) portNumber: 端口号 (Int)	无

数据写入

方法	描述	参数	返回值
deviceWrite(deviceName, portNumber, hexData)	向已连接的设备发送数据	deviceName: 设备名称 (String) portNumber: 端口号 (Int) hexData: 十六进制字符串 (String)	无

注意：deviceWrite 仅在连接状态为 CONNECTED 时才会实际发送数据，且需要 hexData 非空。

---

回调函数

web 端需要在 usbSerial 对象上实现以下回调函数，以接收 Android 端的异步通知。所有回调函数均无返回值。

回调函数注册方式：

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 回调

{
    "deviceName": "/dev/bus/usb/001/002",
    "deviceId": 1002,
    "ports": [1, 2]
}

字段	类型	描述
deviceName	String	设备路径名称
deviceId	Number	USB 设备 ID
ports	Array	可用串口端口号列表

onDeviceDetached 回调

{
    "deviceName": "/dev/bus/usb/001/002",
    "deviceId": 1002
}

字段	类型	描述
deviceName	String	设备路径名称
deviceId	Number	USB 设备 ID

onDeviceDiscovered 回调

{
    "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 回调

{
    "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 回调

{
    "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 回调

{
    "deviceName": "/dev/bus/usb/001/002",
    "port": 1,
    "state": "CONNECTED"
}

字段	类型	描述
deviceName	String	设备路径名称
port	Number	端口号
state	String	连接状态："CONNECTED" | "CONNECTING" | "DISCONNECTED"

onDeviceData 回调

{
    "deviceName": "/dev/bus/usb/001/002",
    "port": 1,
    "hexData": "01020304AABB"
}

字段	类型	描述
deviceName	String	设备路径名称
port	Number	端口号
hexData	String	收到的数据，十六进制大写字符串

---

连接状态枚举

状态	触发时机
CONNECTING	deviceOpen 后正在尝试打开串口
CONNECTED	串口打开成功，可以发送和接收数据
DISCONNECTED	串口未连接、连接失败或被拔出

---

典型使用流程

1. 启动发现

// 注册回调
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. 手动探测设备

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. 打开设备进行通信

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. 关闭设备

usbSerial.deviceClose("/dev/bus/usb/001/002", 1);

---

注意事项

1. 串口参数固定：数据位 8、停止位 1、无校验位，不可配置。
2. 设备键值：内部以 "deviceName:portNumber" 唯一标识一个连接，同一设备不同端口可同时打开。
3. 拔除自动清理：设备拔出时对应连接会自动销毁，无需手动调用 deviceClose。
4. 线程安全：所有方法可以在 JS 主线程直接调用，Android 侧会处理线程调度。
5. getDiscoveredDevices 为预留接口，当前仅返回 "[]"，后续版本会实现。