Metadata-Version: 2.4
Name: sdev
Version: 0.7.8
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 [scope] [filters...]`**：扫描本地 / 远程可用串口。
  - `scope`: `local`, `remote` 或不填。
  - `filters`: 如 `type=XC01` 或 `host=192.168.1.101`。
  - `-f, --fast`: 快速模式，找到第一个符合条件的设备后立即输出（适合脚本）。
- **`sdev run [cmd...]`**：执行命令。
  - `-i, --interrupt-only`: 仅发送一次 Ctrl-C，随后被动收集输出（不发送新命令）。
  - `-t, --timeout`: 整体超时限制。
  - `-w, --wait-forever`: 永久等待输出，直至整体超时或手动中断。
- **`sdev server [action]`**：管理本机串口共享服务。
  - `action`: `start`, `stop`, `restart`, `status`。
- **`sdev mcp [action]`**：AI 集成（Model Context Protocol）。
  - `action`: `install` (一键配置到 IDE), `run` (由 IDE 调起的后台服务)。
- `sdev set` / `sdev show` / `sdev reset`：管理默认设备与缓存。

典型流程：

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

# 2. 扫描并筛选可用设备
sdev list remote              # 仅扫描远程
sdev list type=XC01           # 仅列出特定型号
sdev list -f type=XC01        # 快速模式：找到第一个 XC01 立即返回（适合脚本）

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

# 4. 执行命令
sdev run 'cat /proc/meminfo'  # 执行完整交互
sdev run -i                   # 仅发送 Ctrl-C (用于中断正在跑的任务并查看输出)
```

---

## 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`，用于识别设备类型。

---

## AI 集成 (MCP)

`sdev` 支持 **Model Context Protocol (MCP)**，允许 AI 助手（如 Cursor、Claude Desktop）直接操作串口，执行命令并感知设备状态。

### 1. 获取配置信息
在本地环境执行：
```bash
sdev mcp install
```
该命令会自动生成可用于粘贴的 JSON 配置片段，并提示 Cursor 或 Claude Desktop 的配置路径。

### 2. 提供的能力 (Tools)
安装后，AI 助手将获得以下工具：
- `sdev_list`: 获取本地及远程可用设备列表。
- `sdev_run`: 在指定设备上执行命令并获取输出。
- `sdev_set_default`: 设置当前会话的默认设备。

---

## 适用 / 不适用的场景

**适用：**

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

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

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

---

## 更多文档

- **内部架构与设计说明**：`docs/arch_design.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()`），以 `SerialNotebook` 作为上层统一入口，并通过 `SerialRWServer`/`SerialRWClient` 实现远程 `run / list / server` 等子命令。


