Metadata-Version: 2.4
Name: sdev
Version: 0.4.3
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 进程使用。请勿并行执行多条 `sdev shell ...` 或快速连续执行，否则可能报「串口已被其他 sdev 进程占用」或挂死；需等前一条命令结束后再执行下一条。

## 安装

```bash
pip install sdev
```

## 命令行

安装后可使用 `sdev` 命令，在默认串口上执行单条命令并回显：

```bash
sdev shell "lsmod | grep -E 'mmz|nnp|vdsp'"
sdev -p /dev/ttyUSB1 -b 115200 shell "ls"
sdev --no-check-alive shell "echo hello"
```

- `-p` / `--port`：串口路径（默认取环境变量 `SDEV_PORT` 或 `/dev/ttyUSB0`）
- `-b` / `--baudrate`：波特率（默认取 `SDEV_BAUDRATE` 或 `115200`）
- `--flag`：提示符结束标志（默认 `" #"`）
- `--timeout`：等待输出超时秒数
- `--no-check-alive`：连接后不执行存活检测

## 快速使用 (Python)

推荐使用 `sdev()` 工厂函数或 `Demoboard` 类，它们提供了更高层、更易用的接口：

```python
from sdev import sdev

# 使用 context manager 自动连接/断开
with sdev("/dev/ttyUSB0", 115200) as board:
    # connect 时默认会执行 check_alive()，确保板子已就绪
    out = board.shell("ls")  # 执行命令并返回输出行列表
    print(out)
```

手动控制连接与存活检测：

```python
from sdev import Demoboard

board = Demoboard("/dev/ttyUSB0", 115200)
board.connect()
board.check_alive()  # 检查并确保进入 shell 提示符
board.shell("echo hello")
board.disconnect()
```

## 主要接口

### Demoboard (推荐)

继承自 `SerialDevice`，提供针对开发板的高层封装。

| 方法 | 说明 |
|------|------|
| `shell(cmd, prompt_flag=" #", timeout=None, stream=False)` | 清缓冲 -> 发送命令 -> 等待命令回显 -> 等待提示符。返回输出列表或生成器。 |
| `check_alive(uboot_flag="uboot#", prompt_flag=" #", response_timeout=3)` | 存活检测：处理 U-Boot 挂起、发送 Ctrl-C 唤醒并等待提示符。 |

### SerialDevice (底层)

| 方法 / 属性 | 说明 |
|-------------|------|
| `STABLE_FLAG` | 类常量 `" #"`，常用作默认提示符。 |
| `connect()` / `disconnect()` | 打开/关闭串口并启停后台读线程。 |
| `send(text)` | 发送一行（自动加换行）。 |
| `scan(end_flag, timeout=None)` | 从缓存中持续读取直到目标 flag，或读到 timeout 结束。 |
| `display(lines, flag=None, flag_type=None)` | 对传入的行按 flag 类型回显（着色）并 yield 原始行。 |
| `clear()` | 清空读缓冲。 |

- **回显着色**：匹配到 `flag` 的行为绿色，命令回显行为青色，其余灰色；支持设备折行后的跨行匹配。

## 依赖

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