Metadata-Version: 2.4
Name: sdev
Version: 0.4.13
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

串口开发板控制器：基于后台异步读缓冲、提供快速存活检测、多进程串口互斥锁、以及人性化的命令回显。

**注意**：`sdev` 内置了跨进程串口锁（flock），支持多个进程同时尝试连接同一串口。后启动的进程会阻塞等待，直到前一个进程释放串口，从而避免了串口冲突或挂死。

## 安装

```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` 类，它们提供了更高层、更易用的接口。`Demoboard` 在实例化时默认会自动执行 `check_alive()`。

```python
from sdev import sdev

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

使用旧版兼容接口：

```python
from sdev import Demoboard

with Demoboard("/dev/ttyUSB0", 115200) as board:
    # execute_command 是 shell 的别名，方便旧代码迁移
    out = board.execute_command("ls", flag=" #")
    print(out)
```

## 主要接口

### Demoboard (推荐)

继承自 `SerialDevice`，提供针对开发板的高层封装。实例化时会自动调用 `check_alive()`。

| 方法 | 说明 |
|------|------|
| `shell(cmd, prompt_flag=" #", timeout=None, stream=False)` | 清缓冲 -> 发送命令 -> 等待命令回显 -> 等待提示符。返回输出列表或生成器。 |
| `execute_command(cmd, flag, timeout=None, stream=False)` | `shell` 方法的别名，用于兼容旧版代码。 |
| `check_alive(uboot_flag="uboot#", prompt_flag=" #", timeout=2.0, block=True)` | 鲁棒存活检测：自动处理串口残留输出、U-Boot 挂起、发送 Ctrl-C 唤醒。`block=True`（默认）走完整阻塞流程，失败抛异常；`block=False` 仅做乐观探测，不满足条件即返回 `False`，不抛异常、不等待。 |
| `silence()` | 调用后不再输出任何日志（info/success/warning/error 变为空操作）。 |

### SerialDevice (底层驱动)

底层串口基础类，仅负责 I/O 和锁管理，不包含任何 UI/显示逻辑。

| 方法 / 属性 | 说明 |
|-------------|------|
| `connect()` / `disconnect()` | 打开/关闭串口并启停后台读线程。 |
| `send(text)` | 发送一行（自动加换行）。 |
| `scan(end_flag, timeout=None)` | 从缓存中持续读取直到目标 flag，或读到 timeout 结束。 |
| `clear()` | 清空读缓冲。 |
| `silence()` | 调用后不再输出任何日志（info/success/warning/error 变为空操作）。 |

- **回显样式**：`Demoboard` 提供了增强的视觉体验。用户输入的命令和提示符符号 `>` 以黄色高亮显示，命令执行结果以白色显示，而普通的板端日志则以深灰色背景化。

## 依赖

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