Metadata-Version: 2.4
Name: sdev
Version: 0.7.1
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：串口设备管理调试

`sdev` 是一个 **串口调试与管理工具包**，统一了以下场景：

- **命令行调试**：用一条 `sdev` 命令在本地或远程开发板上执行 shell 命令；
- **Python 自动化脚本**：用 `sdev.api.Demoboard` 在脚本里批量配置环境、跑测试；
- **远程串口共享**：通过 `sdev server` 把一台机器上的串口暴露给局域网内其他机器使用。

它不关心具体芯片 SDK，只负责「稳定拿到板子的串口、可靠地收发命令和回显」。

---

## 安装

```bash
pip install sdev
```

建议在虚拟环境（如 conda `dev` 环境）中安装和使用。

---

## 命令行快速上手

安装后会提供一个 `sdev` 命令，包括：

- `sdev list`：扫描本地 / 远程可用串口；
- `sdev run`：在选定设备上执行命令；
- `sdev server`：启动/停止本机串口共享服务；
- `sdev set` / `sdev show` / `sdev reset`：管理默认设备与缓存。

典型流程：

```bash
# 1. （可选）在“串口所在机器”上启动 server
sdev server start

# 2. 扫描可用设备
sdev list

# 3. （推荐）选中一块板，配置为默认设备
sdev set default <DEVICE_ID>

# 4. 之后即可直接执行命令
sdev run 'cat /proc/meminfo'
sdev run -t 10 'dmesg | tail'
```

更详细的 CLI 用法与行为说明，参考项目内的 skill 文档：

- `docs/skills/serial-sdev-cli/SKILL.md`

---

## Python API 快速上手（SerialNotebook）

在 Python 中，推荐直接使用 `SerialNotebook` 作为最高层入口（适合脚本和 Notebook 场景）。

本地串口示例：

```python
from sdev.modules.serial_notebook import SerialNotebook

def main():
    with SerialNotebook(device="/dev/ttyUSB0", baudrate=115200) as nb:
        # 执行一条命令并等待提示符（默认 prompt 为 " #"）
        nb.run("echo hello-from-sdev")

if __name__ == "__main__":
    main()
```

远程串口示例（已在远端机器上启动 `sdev server start`）：

```python
from sdev.modules.serial_notebook import SerialNotebook

HOST = "192.168.1.50"          # 串口所在主机 IP
SERIAL_PORT = "/dev/ttyUSB0"   # 远端串口路径

with SerialNotebook(device=SERIAL_PORT, baudrate=115200, host=HOST, port=7000) as nb:
    nb.run("ifconfig", overall_timeout=5)
```

`SerialNotebook` 基于与 CLI 相同的内核（`SerialRW` / `SerialRWClient`），提供：

- `run(...)`：发送命令并按提示符或超时结束；
- `send_interrupt()`：发送一次 Ctrl-C；
- `get_model_type()`：读取 `/proc/device-tree/model`，用于识别设备类型。

---

## 适用 / 不适用的场景

**适用：**

- 串口为主的 Linux 开发板（如 ARM SoC 开发板）；
- 需要频繁登录、配置网络/NFS、加载驱动模块的日常调试；
- 在 CI 或脚本里做自动化回归测试（通过串口控制板子）。

**不适用（当前阶段）：**

- 需要高吞吐量二进制数据流的场景（如大规模文件传输、逻辑分析仪替代等）；
- 对实时性有极高要求的硬实时控制。

---

## 更多文档

- **内部架构与设计说明**：`docs/arch_design.md`
- **技能（在 Cursor 里集成使用方式）**：
  - `docs/skills/serial-sdev-cli/SKILL.md`
  - `docs/skills/serial-sdev-api/SKILL.md`

源码结构概览（仅列出现行实现）：

- `sdev/modules/`：底层串口与远程共享内核  
  - `serial_rw.py`：本地串口读写与锁管理（`SerialRW`）、运行控制器（`SerialRunner`）、端口扫描与快速探测；
  - `serial_rw_server.py`：远程串口共享服务与客户端（`SerialRWServer` / `SerialRWClient`），以及主机发现逻辑；
  - `serial_notebook.py`：Notebook / 脚本场景下的最高层 Python 入口（`SerialNotebook`），基于 `SerialRW` / `SerialRWClient` 实现。
- `sdev/cli/`：命令行入口 `sdev`（`__init__.py` 中的 `main()`），直接基于 `SerialRW` / `SerialRunner` 与 `SerialRWClient` 实现 `run / list / server` 等子命令。

