Metadata-Version: 2.4
Name: sdev
Version: 0.6.7
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 快速上手

在脚本中使用 `Demoboard` 进行自动化操作：

```python
from sdev.api.demoboard import Demoboard

def main():
    # 本地串口
    with Demoboard("/dev/ttyUSB0", 115200) as board:
        out = board.execute_command("echo hello-from-sdev", timeout=5)
        print("".join(out))

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

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

```python
from sdev.api.demoboard import Demoboard

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

with Demoboard(SERIAL_PORT, 115200, host=HOST) as board:
    board.execute_command("ifconfig", timeout=5)
```

更系统的 API 使用说明与示例，参考：

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

---

## 适用 / 不适用的场景

**适用：**

- 串口为主的 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/`：底层串口与远程共享实现；
- `sdev/cli/`：命令行入口 `sdev`；
- `sdev/api/`：Python API（如 `Demoboard`）。

