Metadata-Version: 2.4
Name: sdev
Version: 0.4.0
Summary: 串口控制器工具包
Home-page: https://github.com/klrc/sdev
Author: klrc
Author-email: klrc <144069824@qq.com>
License: MIT
Project-URL: Homepage, https://github.com/klrc/sdev
Project-URL: Repository, https://github.com/klrc/sdev
Project-URL: Bug Tracker, https://github.com/klrc/sdev/issues
Keywords: serial,controller,hardware,embedded
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyserial>=3.5
Requires-Dist: loguru>=0.6.0
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# SDEV

串口控制器工具包：后台按行读缓冲、按 flag 扫描与回显着色、执行命令、存活检测。

**注意**：同一串口同一时间只能被一个 sdev 进程使用。系统会自动处理跨进程锁，后来的进程会阻塞等待。

## 安装

```bash
pip install sdev
```

## 命令行用法

安装后可使用 `sdev` 命令。默认会执行存活检测（check_alive）。

```bash
# 执行单条命令并回显
sdev shell "lsmod | grep -E 'mmz|nnp|vdsp'"

# 指定串口和波特率
sdev -p /dev/ttyUSB1 -b 115200 shell "ls"

# 跳过存活检测执行命令
sdev --no-check-alive shell "echo hello"

# 检查本机所有串口状态
sdev demoboard status
```

- `-p` / `--port`：串口路径（默认取环境变量 `SDEV_PORT` 或 `/dev/ttyUSB0`）
- `-b` / `--baudrate`：波特率（默认取 `SDEV_BAUDRATE` 或 `115200`）
- `--flag`：提示符结束标志（默认 `" #"`）
- `--timeout`：等待输出超时秒数

## Python API 使用

推荐使用 `sdev()` 工厂函数或 `Demoboard` 类，它们提供了更高层的封装。

### 推荐做法

```python
from sdev import sdev

# 使用上下文管理器，自动处理 connect() / disconnect()
with sdev("/dev/ttyUSB0", 115200) as board:
    # 默认 connect 时会阻塞直到拿到串口锁
    # 执行命令，返回输出行列表
    output = board.shell("ls")
    print(output)
```

### 存活检测

`Demoboard.check_alive()` 能够处理设备处于 U-Boot、内核启动中或已进入 Shell 的各种状态：

```python
with sdev("/dev/ttyUSB0") as board:
    # 自动识别 U-Boot 并执行 reboot，直到进入 Shell
    board.check_alive() 
    board.shell("cat /proc/version")
```

### 核心 API 说明

| 类/方法 | 说明 |
|-------------|------|
| `sdev(port, baudrate, device_type="demoboard")` | 工厂函数，返回设备实例（Demoboard 或 Relay） |
| `Demoboard.shell(cmd, prompt_flag=" #", timeout=None, stream=False)` | 执行命令。`stream=True` 时返回 generator |
| `Demoboard.check_alive(...)` | 综合检查存活状态，支持 U-Boot 自动重启和等待唤醒 |
| `SerialDevice.send(text)` | 底层接口：发送一行（自动加换行） |
| `SerialDevice.scan(end_flag, timeout)` | 底层接口：从缓冲中读取直到匹配 flag |

## 特色

- **回显着色**：匹配到 flag 的行为绿色，命令回显行为青色，其余灰色。
- **拼行匹配**：设备折行时会自动拼接多行进行 flag 匹配，提高成功率。
- **跨进程互斥**：基于文件锁，确保多进程安全访问串口。
- **异步读取**：后台线程实时消费串口数据，避免缓冲区溢出丢失数据。

## 依赖

- Python >= 3.7
- pyserial >= 3.5
- loguru >= 0.6.0
