Metadata-Version: 2.4
Name: sdev
Version: 0.6.2
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
Requires-Dist: zeroconf>=0.39.0
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# SDEV

串口开发板控制器：支持本地与远程串口、list/activate 工作流、跨进程串口锁与人性化命令回显。

**注意**：内置跨进程串口锁（flock），多进程连接同一串口时后启动者会阻塞等待，避免冲突或挂死。

## 安装

```bash
pip install sdev
```

## 命令行

安装后使用 `sdev` 命令。常用子命令：

| 命令 | 说明 |
|------|------|
| `sdev list` | 列出本地 + 远程 demoboard（先执行以填充缓存，供 activate / 脚本使用） |
| `sdev list --local` | 仅列本机串口 |
| `sdev activate HASH` | 按 list 表中的 HASH 激活一块板（本地或远程） |
| `sdev activate DEVICE` | 按 DEVICE 名称模糊匹配并激活 |
| `sdev deactivate` | 清空当前激活状态 |
| `sdev reset` | 停止本机 sdev server 并删除整个 sdev 配置/缓存目录 |
| `sdev server start \| stop \| restart \| status` | 本机远程服务启停与状态 |
| `sdev "cmd"` | 在当前激活的板上执行单条命令并回显 |
| `sdev HASH "cmd"` | 先按 HASH 激活，再执行命令 |

示例：

```bash
# 列出所有板（本地 + 远程），表格含 HASH / HOST / PORT / DEVICE 等
sdev list

# 激活 HASH 为 f0b129 的板，然后执行命令
sdev activate f0b129
sdev "ls"

# 或一步：按 HASH 激活并执行
sdev f0b129 "lsmod | grep vdsp"

# 按 DEVICE 名称激活（需先 sdev list 有缓存）
sdev activate xc01
sdev "echo hello"
```

- 未激活时，`sdev "cmd"` 使用默认本地串口（见 `-p` / 环境变量 `SDEV_PORT`）。
- `-p` / `--port`、`-b` / `--baudrate`、`--timeout`、`--flag` 等可覆盖默认行为。

## Python 接口

### 推荐：any_device（按 DEVICE 取板）

从 **list 缓存** 中按 DEVICE 模糊匹配第一块可用板，不发起扫描。需先执行过 `sdev list` 或脚本内用其它方式写入缓存。

```python
from sdev import any_device

with any_device("xc01") as board:
    out = board.execute_command("ls")
    print(out)
```

- 首行会打印当前连接前缀，如 `(sdev local:/dev/ttyUSB0 baud=115200)`，与 CLI 一致。
- 无缓存或未命中时会抛 `RuntimeError`，提示先执行 `sdev list` 或刷新 list。

### 直接指定串口：Demoboard

已知 host/port 时可直接用 `Demoboard`：

```python
from sdev import Demoboard

# 本地串口
with Demoboard("/dev/ttyUSB0", 115200) as board:
    out = board.execute_command("ls", flag=" #")
    print(out)

# 远程串口（需对端已运行 sdev server）
with Demoboard("/dev/ttyUSB0", 115200, host="192.168.1.12", service_port=7000) as board:
    out = board.execute_command("ls")
    print(out)
```

### 主要方法（Demoboard）

| 方法 | 说明 |
|------|------|
| `execute_command(cmd, flag=" #", timeout=None, display=True)` | 发命令、等回显与提示符，返回输出行列表或流。 |
| `check_model_type(timeout=2.0)` | 探测板型（如 xc01），用于 list 填充 DEVICE。 |
| `check_alive(...)` | 存活检测（U-Boot/提示符等）。 |
| `connect()` / `disconnect()` | 显式连接/断开；也可用 `with` 自动管理。 |

## 缓存与 reset

- **list 缓存**：`sdev list` 的结果会写入统一缓存（含本地+远程、DEVICE 等），路径由 `XDG_CONFIG_HOME` / `~/.config` 下的 `sdev` 目录决定。
- **激活记录**：本地与远程的「当前激活」也保存在同一配置目录。
- **sdev reset**：停止本机 sdev server，并**删除整个 sdev 配置目录与缓存目录**（不再逐文件清理），因此后续新增的 cache 也会被清掉，无需再在 reset 里登记。

## 依赖

- Python >= 3.7
- pyserial >= 3.5

可选：`zeroconf`（mDNS 发现）、`loguru`（server 日志）。
