serial — 串口通信 | Pyrite Project

self.serial 提供串口通信能力，包括枚举端口、连接管理、原始数据收发、命令下发以及 REPL 执行。

使用 self.serial 需要在插件权限中声明 serial.read 与 serial.write。

方法

方法	说明
`list_ports`	列出可用串口
`get_status`	获取当前连接状态
`connect`	连接到指定串口
`disconnect`	断开串口连接
`send`	发送原始数据
`send_command`	发送命令（自动追加换行）
`read`	读取串口数据
`run_python`	在设备 REPL 执行代码
`hardware_reset`	硬件复位设备
`set_baud_rate`	设置波特率
`set_auto_reconnect`	设置自动重连

list_ports(callback?)

列出可用的串口设备。

self.serial.list_ports(
    callback=lambda **cb: print(cb.get("ports", []))
)

参数：

callback (callable, 可选) — 完成后的回调

get_status(callback?)

获取当前串口连接状态。

self.serial.get_status(
    callback=lambda **cb: print(cb)
)

connect(port, callback?)

连接到指定串口。

self.serial.connect("/dev/ttyUSB0",
    callback=lambda **cb: print("连接结果:", cb)
)

参数：

port (str) — 串口路径

disconnect(callback?)

断开当前串口连接。

self.serial.disconnect()

send(data, callback?)

发送原始数据。data 支持 str、bytes 或 int 组成的列表；bytes 会被转换为整数列表后再发送。

self.serial.send("hello")
self.serial.send(b"\x01\x02\x03")      # bytes 会转为 [1, 2, 3]
self.serial.send([0x01, 0x02, 0x03])   # 列表按原样发送

参数：

data (str | bytes | list[int]) — 要发送的数据

send_command(command, chunked?, callback?)

发送命令文本并自动处理换行格式。

self.serial.send_command("print('hello')")

参数：

command (str) — 命令文本
chunked (bool) — 是否分块发送，默认 True
callback (callable, 可选) — 完成后的回调

read(timeout_ms?, max_bytes?, callback?)

读取串口数据。

self.serial.read(
    timeout_ms=2000,
    max_bytes=1024,
    callback=lambda **cb: print(cb.get("data", "")),
)

参数：

timeout_ms (int) — 超时时间（毫秒），默认 1000
max_bytes (int, 可选) — 最大读取字节数
callback (callable, 可选) — 完成后的回调

run_python(code, timeout_ms?, callback?)

在已连接设备的 REPL 中执行 Python 代码并返回结果。

self.serial.run_python(
    "import sys; print(sys.version)",
    timeout_ms=10000,
    callback=lambda **cb: print(cb.get("output", "")),
)

参数：

code (str) — 要执行的 Python 代码
timeout_ms (int) — 执行超时（毫秒），默认 20000
callback (callable, 可选) — 完成后的回调

hardware_reset(callback?)

对设备执行硬件复位。

self.serial.hardware_reset()

set_baud_rate(value, callback?)

设置串口波特率。

self.serial.set_baud_rate(115200)

参数：

value (int) — 波特率值

set_auto_reconnect(value, callback?)

设置是否自动重连。

self.serial.set_auto_reconnect(True)

参数：

value (bool) — 是否自动重连

使用示例

class DeviceMonitor(ServicePlugin):
    def on_start(self):
        self.serial.connect(
            "/dev/ttyUSB0",
            callback=lambda **cb: self._connected(cb),
        )

    def _connected(self, result):
        if result.get("error"):
            print("连接失败:", result["error"])
            return
        self.serial.send(
            "READ_TEMP\r\n",
            callback=lambda **cb: print("已发送"),
        )
        self.serial.read(
            timeout_ms=2000,
            max_bytes=1024,
            callback=lambda **cb: print(cb.get("data", "")),
        )

    def on_dispose(self):
        self.serial.disconnect()

写入操作会真实影响设备，请在用户主动操作或明确的业务场景下调用。read 会按超时阻塞并等待数据，注意控制 timeout_ms 以避免长时间挂起。

serial — 串口通信

On this page