Cordova plugin for serial port communication using com.github.cl-6666:serialPort library
npm install cordova-plugin-serialport-y0A1B2C。
window.SerialPort 与 cordova.plugins.serialPort。
bash
cordova plugin add cordova-plugin-serialport-y
`
或从你的 Git 仓库安装：
`bash
cordova plugin add https://github.com/l0z0y/cordova-plugin-compilations.git
`
快速开始
`javascript
// 初始化并打开串口（配置参数可选）
SerialPort.init(
"/dev/ttyS4", // 串口路径
115200, // 波特率
{
intervalSleep: 50, // 轮询间隔(ms)，默认 50
enableLog: false, // 是否开启底层日志，默认 false
logTag: "SerialPort",
databits: 8, // 数据位：5/6/7/8，默认 8
parity: 0, // 校验位：0-None 1-Odd 2-Even 3-Mark 4-Space，默认 0
stopbits: 1, // 停止位：1/2，默认 1
strategy: 0, // 黏包处理策略索引，默认 0
},
function () {
console.log("Serial port initialized and opened")
// 设置数据接收监听器
SerialPort.listen(
function (hex) {
// 每当串口收到数据都会回调一次，例如："0A1B2C"
console.log("RX:", hex)
},
function (err) {
console.error("Listen error", err)
}
)
},
function (err) {
console.error("Init error", err)
}
)
// 发送字节数组（十六进制字符串格式，例如 "0A1B2C"）
SerialPort.sendBytes(
"0A1B2C", // 发送字节 0x0A, 0x1B, 0x2C
function () {
console.log("Bytes sent ok")
},
function (err) {
console.error("Send bytes error", err)
}
)
// 发送字符串
SerialPort.sendString(
"AT+CMD\r\n", // 发送字符串
function () {
console.log("String sent ok")
},
function (err) {
console.error("Send string error", err)
}
)
// 关闭串口（停止监听）
SerialPort.close(
function () {
console.log("Closed")
},
function (err) {
console.error("Close error", err)
}
)
`
你也可以通过 cordova.plugins.serialPort 使用相同 API：
`javascript
cordova.plugins.serialPort.init("/dev/ttyS4", 115200, {}, onInitSuccess, onError)
cordova.plugins.serialPort.listen(onData, onError)
`
API 说明
所有方法都遵循 Cordova exec(success, error, ...) 的风格。
- SerialPort.init(port, baudRate, options, success, error)
- port string：串口路径，例如 /dev/ttyS4
- baudRate number：波特率，例如 115200
- options object（可选）：配置参数
- intervalSleep number 默认 50
- enableLog boolean 默认 false
- logTag string 默认 "SerialPort"
- databits number 默认 8
- parity number 默认 0
- stopbits number 默认 1
- strategy number 默认 0（对应底层 SimpleSerialPortManager 的策略枚举索引）
- success：初始化并打开串口成功回调
- error：失败回调
- SerialPort.listen(success, error)
- success(hex: string)：数据接收回调函数，每当串口收到数据都会调用一次，参数为大写十六进制字符串（无空格，例如 "0A1B2C"）
- error(err)：出错回调
- 注意：此方法会保持回调连接，持续接收数据
- SerialPort.sendBytes(hexData, success, error)
- hexData string：十六进制字符串格式（例如 "0A1B2C"），会自动转换为字节数组发送
- success：发送成功回调
- error：发送失败回调
- SerialPort.sendString(data, success, error)
- data string：要发送的字符串（例如 "AT+CMD\r\n"），直接以字符串形式发送
- success：发送成功回调
- error：发送失败回调
- SerialPort.close(success, error)
- 关闭串口并停止后续数据回调
- success：关闭成功回调
- error：关闭失败回调
数据格式
- 串口物理层传输的是字节流（byte[]），插件在 Android 端接收到字节后会把其转换为「大写十六进制字符串」再回调 JS。
- 示例：字节 0x0A, 0x1B, 0x2C -> "0A1B2C"。
- 如需空格分隔或小写形式，可在 Android 端或 JS 端自行转换；如你需要插件内置不同格式开关，可提 issue 或 PR。
平台支持
- Android（基于 com.cl.serialportlibrary.SimpleSerialPortManager）
引用的库 / 依赖
- Android 串口实现基于第三方库：com.cl.serialportlibrary.SimpleSerialPortManager
- Gradle 依赖（已在本插件 src/android/build.gradle 中声明）：
`gradle
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
implementation 'com.github.cl-6666:serialPort:v5.0.7'
}
`
- 主要用途：负责底层串口打开、发送、接收与黏包处理策略，本插件在其回调上封装为 Cordova 的持续监听回调（keepCallback）。
注意事项
- Android 权限与清单由插件自动注入。
- 若你自定义包名或目录（例如 com.yy.serialport），请确认 plugin.xml 中 与 source-file target-dir 一致。
- 某些设备节点可能需要 root 或特定权限。
常见问题
1. 为什么数据是十六进制字符串？
为了避免字符集误判及提升通用性，插件统一以十六进制返回原始字节。你可以在 JS 侧自行解析为数值或字符串。
2. 能否改为返回 ArrayBuffer 或 Uint8Array？
可以。当前实现已在 Android 侧做了 hex 规范返回。如你更偏好二进制回调，可提需求，我可以添加配置开关。
3. 如何确认串口节点与波特率？
请参考硬件设备说明书，或通过 adb/shell 查看设备 /dev/tty*` 列表。