sdev 0.3.6__tar.gz → 0.4.0__tar.gz

sdev-0.4.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: sdev
+Version: 0.4.0
+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
+
+串口控制器工具包：后台按行读缓冲、按 flag 扫描与回显着色、执行命令、存活检测。
+
+**注意**：同一串口同一时间只能被一个 sdev 进程使用。系统会自动处理跨进程锁，后来的进程会阻塞等待。
+
+## 安装
+
+```bash
+pip install sdev
+```
+
+## 命令行用法
+
+安装后可使用 `sdev` 命令。默认会执行存活检测（check_alive）。
+
+```bash
+# 执行单条命令并回显
+sdev shell "lsmod | grep -E 'mmz|nnp|vdsp'"
+
+# 指定串口和波特率
+sdev -p /dev/ttyUSB1 -b 115200 shell "ls"
+
+# 跳过存活检测执行命令
+sdev --no-check-alive shell "echo hello"
+
+# 检查本机所有串口状态
+sdev demoboard status
+```
+
+- `-p` / `--port`：串口路径（默认取环境变量 `SDEV_PORT` 或 `/dev/ttyUSB0`）
+- `-b` / `--baudrate`：波特率（默认取 `SDEV_BAUDRATE` 或 `115200`）
+- `--flag`：提示符结束标志（默认 `" #"`）
+- `--timeout`：等待输出超时秒数
+
+## Python API 使用
+
+推荐使用 `sdev()` 工厂函数或 `Demoboard` 类，它们提供了更高层的封装。
+
+### 推荐做法
+
+```python
+from sdev import sdev
+
+# 使用上下文管理器，自动处理 connect() / disconnect()
+with sdev("/dev/ttyUSB0", 115200) as board:
+    # 默认 connect 时会阻塞直到拿到串口锁
+    # 执行命令，返回输出行列表
+    output = board.shell("ls")
+    print(output)
+```
+
+### 存活检测
+
+`Demoboard.check_alive()` 能够处理设备处于 U-Boot、内核启动中或已进入 Shell 的各种状态：
+
+```python
+with sdev("/dev/ttyUSB0") as board:
+    # 自动识别 U-Boot 并执行 reboot，直到进入 Shell
+    board.check_alive() 
+    board.shell("cat /proc/version")
+```
+
+### 核心 API 说明
+
+| 类/方法 | 说明 |
+|-------------|------|
+| `sdev(port, baudrate, device_type="demoboard")` | 工厂函数，返回设备实例（Demoboard 或 Relay） |
+| `Demoboard.shell(cmd, prompt_flag=" #", timeout=None, stream=False)` | 执行命令。`stream=True` 时返回 generator |
+| `Demoboard.check_alive(...)` | 综合检查存活状态，支持 U-Boot 自动重启和等待唤醒 |
+| `SerialDevice.send(text)` | 底层接口：发送一行（自动加换行） |
+| `SerialDevice.scan(end_flag, timeout)` | 底层接口：从缓冲中读取直到匹配 flag |
+
+## 特色
+
+- **回显着色**：匹配到 flag 的行为绿色，命令回显行为青色，其余灰色。
+- **拼行匹配**：设备折行时会自动拼接多行进行 flag 匹配，提高成功率。
+- **跨进程互斥**：基于文件锁，确保多进程安全访问串口。
+- **异步读取**：后台线程实时消费串口数据，避免缓冲区溢出丢失数据。
+
+## 依赖
+
+- Python >= 3.7
+- pyserial >= 3.5
+- loguru >= 0.6.0

sdev-0.4.0/README.md

@@ -0,0 +1,85 @@
+# SDEV
+
+串口控制器工具包：后台按行读缓冲、按 flag 扫描与回显着色、执行命令、存活检测。
+
+**注意**：同一串口同一时间只能被一个 sdev 进程使用。系统会自动处理跨进程锁，后来的进程会阻塞等待。
+
+## 安装
+
+```bash
+pip install sdev
+```
+
+## 命令行用法
+
+安装后可使用 `sdev` 命令。默认会执行存活检测（check_alive）。
+
+```bash
+# 执行单条命令并回显
+sdev shell "lsmod | grep -E 'mmz|nnp|vdsp'"
+
+# 指定串口和波特率
+sdev -p /dev/ttyUSB1 -b 115200 shell "ls"
+
+# 跳过存活检测执行命令
+sdev --no-check-alive shell "echo hello"
+
+# 检查本机所有串口状态
+sdev demoboard status
+```
+
+- `-p` / `--port`：串口路径（默认取环境变量 `SDEV_PORT` 或 `/dev/ttyUSB0`）
+- `-b` / `--baudrate`：波特率（默认取 `SDEV_BAUDRATE` 或 `115200`）
+- `--flag`：提示符结束标志（默认 `" #"`）
+- `--timeout`：等待输出超时秒数
+
+## Python API 使用
+
+推荐使用 `sdev()` 工厂函数或 `Demoboard` 类，它们提供了更高层的封装。
+
+### 推荐做法
+
+```python
+from sdev import sdev
+
+# 使用上下文管理器，自动处理 connect() / disconnect()
+with sdev("/dev/ttyUSB0", 115200) as board:
+    # 默认 connect 时会阻塞直到拿到串口锁
+    # 执行命令，返回输出行列表
+    output = board.shell("ls")
+    print(output)
+```
+
+### 存活检测
+
+`Demoboard.check_alive()` 能够处理设备处于 U-Boot、内核启动中或已进入 Shell 的各种状态：
+
+```python
+with sdev("/dev/ttyUSB0") as board:
+    # 自动识别 U-Boot 并执行 reboot，直到进入 Shell
+    board.check_alive() 
+    board.shell("cat /proc/version")
+```
+
+### 核心 API 说明
+
+| 类/方法 | 说明 |
+|-------------|------|
+| `sdev(port, baudrate, device_type="demoboard")` | 工厂函数，返回设备实例（Demoboard 或 Relay） |
+| `Demoboard.shell(cmd, prompt_flag=" #", timeout=None, stream=False)` | 执行命令。`stream=True` 时返回 generator |
+| `Demoboard.check_alive(...)` | 综合检查存活状态，支持 U-Boot 自动重启和等待唤醒 |
+| `SerialDevice.send(text)` | 底层接口：发送一行（自动加换行） |
+| `SerialDevice.scan(end_flag, timeout)` | 底层接口：从缓冲中读取直到匹配 flag |
+
+## 特色
+
+- **回显着色**：匹配到 flag 的行为绿色，命令回显行为青色，其余灰色。
+- **拼行匹配**：设备折行时会自动拼接多行进行 flag 匹配，提高成功率。
+- **跨进程互斥**：基于文件锁，确保多进程安全访问串口。
+- **异步读取**：后台线程实时消费串口数据，避免缓冲区溢出丢失数据。
+
+## 依赖
+
+- Python >= 3.7
+- pyserial >= 3.5
+- loguru >= 0.6.0

{sdev-0.3.6 → sdev-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sdev"
-version = "0.3.6"
+version = "0.4.0"
 description = "串口控制器工具包"
 readme = "README.md"
 license = {text = "MIT"}
@@ -38,4 +38,8 @@ sdev = "sdev.cli_wrapper:main"
 [project.urls]
 Homepage = "https://github.com/klrc/sdev"
 Repository = "https://github.com/klrc/sdev"
-"Bug Tracker" = "https://github.com/klrc/sdev/issues" 
+"Bug Tracker" = "https://github.com/klrc/sdev/issues"
+
+[tool.ruff.lint]
+# 注释里使用中文逗号等全角标点不报错
+ignore = ["RUF003"] 

sdev-0.4.0/sdev/__init__.py

@@ -0,0 +1,40 @@
+"""
+SDEV - 串口控制器工具包
+
+- SerialDevice：底层串口基础类（连接、后台异步读、send/scan/display/clear）；
+- Demoboard / Relay：面向对象封装；
+- sdev() 工厂方法：快速构建设备实例；
+- sdev.demoboard：Demoboard 相关函数式 API（shell, check_alive）。
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from .core import SerialDevice
+from .class_wrapper import Demoboard, Relay
+
+__version__ = "0.4.0"
+__author__ = "klrc"
+__email__ = "1440698245@qq.com"
+
+
+def sdev(
+    port: str,
+    baudrate: int = 115200,
+    *,
+    device_type: Literal["demoboard", "relay"] = "demoboard",
+):
+    """
+    构造一个设备实例。
+
+    默认返回 Demoboard，后续可根据需要扩展其它类型。
+    """
+    if device_type == "demoboard":
+        return Demoboard(port, baudrate)
+    if device_type == "relay":
+        return Relay(port, baudrate)
+    raise ValueError(f"unsupported device_type: {device_type!r}")
+
+
+__all__ = ["SerialDevice", "Demoboard", "Relay", "sdev"]

sdev-0.4.0/sdev/class_wrapper.py

@@ -0,0 +1,67 @@
+"""
+面向对象封装：
+
+- Demoboard：继承 SerialDevice，并把 demoboard.functional 里的函数挂成方法；
+- Relay：占位类，后续扩展继电器相关串口控制。
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .core import SerialDevice
+from .demoboard import check_alive as _check_alive_func
+from .demoboard import shell as _shell_func
+
+
+class Demoboard(SerialDevice):
+    """
+    Demoboard 设备：
+    - 保留 SerialDevice 的所有底层能力；
+    - 提供 shell() / check_alive() 等高层方法。
+    """
+
+    def shell(
+        self,
+        cmd: str,
+        *,
+        prompt_flag: str = " #",
+        timeout: Optional[float] = None,
+        stream: bool = False,
+    ):
+        return _shell_func(self, cmd, prompt_flag=prompt_flag, timeout=timeout, stream=stream)
+
+    def check_alive(
+        self,
+        *,
+        uboot_flag: str = "uboot#",
+        awaken_flag: str = "Process",
+        prompt_flag: str = " #",
+        ctrl_c_timeout: float = 5.0,
+        reboot_timeout: float = 120.0,
+        prompt_timeout: float = 60.0,
+    ) -> None:
+        _check_alive_func(
+            self,
+            uboot_flag=uboot_flag,
+            awaken_flag=awaken_flag,
+            prompt_flag=prompt_flag,
+            ctrl_c_timeout=ctrl_c_timeout,
+            reboot_timeout=reboot_timeout,
+            prompt_timeout=prompt_timeout,
+        )
+
+
+class Relay(SerialDevice):
+    """
+    继电器设备占位类：
+    - 继承 SerialDevice；
+    - 具体继电器控制逻辑后续在 sdev.relay.functional 中补充。
+    """
+
+    # 先占位，避免 API 变动；后续按需要扩展方法。
+    pass
+
+
+__all__ = ["Demoboard", "Relay"]
+

sdev-0.4.0/sdev/cli_wrapper.py

@@ -0,0 +1,141 @@
+"""
+命令行入口：
+
+- sdev shell "cmd"：在串口设备上执行单条命令并回显输出；
+- sdev demoboard status：枚举本机串口并通过 check_alive 检查是否存活。
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from typing import List
+
+from serial.tools import list_ports
+
+from .class_wrapper import Demoboard
+from .demoboard.functional import check_alive as demoboard_check_alive
+from .demoboard.functional import shell as demoboard_shell
+
+
+def _get_default_port() -> str:
+    return os.environ.get("SDEV_PORT", "/dev/ttyUSB0")
+
+
+def _get_default_baudrate() -> int:
+    try:
+        return int(os.environ.get("SDEV_BAUDRATE", "115200"))
+    except ValueError:
+        return 115200
+
+
+def _list_serial_ports() -> List[str]:
+    """跨平台列出本机可用串口设备路径。"""
+    ports = [info.device for info in list_ports.comports()]
+    return sorted(ports)
+
+
+def cmd_shell(args: argparse.Namespace) -> int:
+    port = args.port or _get_default_port()
+    baudrate = args.baudrate or _get_default_baudrate()
+    with Demoboard(port, baudrate) as board:
+        try:
+            if not args.no_check_alive:
+                demoboard_check_alive(board)
+            demoboard_shell(board, args.command, prompt_flag=args.flag, timeout=args.timeout)
+        except TimeoutError as e:
+            print(e, file=sys.stderr)
+            return 1
+    return 0
+
+
+def cmd_demoboard_status(args: argparse.Namespace) -> int:  # noqa: ARG001
+    """
+    sdev demoboard status
+
+    通过 check_alive 检查本机所有串口是否「alive」。
+    """
+    GREEN = "\033[32m"
+    RED = "\033[31m"
+    RESET = "\033[0m"
+
+    baudrate = _get_default_baudrate()
+    ports = _list_serial_ports()
+    if not ports:
+        print("no serial ports found")
+        return 0
+
+    for port in ports:
+        try:
+            with Demoboard(port, baudrate) as board:
+                # 使用较短的超时时间，避免 status 长时间卡死
+                demoboard_check_alive(
+                    board,
+                    ctrl_c_timeout=2.0,
+                    reboot_timeout=30.0,
+                    prompt_timeout=10.0,
+                )
+            print(f"{GREEN}{port} alive{RESET}")
+        except Exception:  # noqa: BLE001
+            print(f"{RED}{port} not connected{RESET}")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="sdev",
+        description="串口开发板控制器：在串口设备上执行命令或检查状态。",
+    )
+    parser.add_argument(
+        "-p",
+        "--port",
+        default=None,
+        help="串口路径（默认: SDEV_PORT 或 /dev/ttyUSB0）",
+    )
+    parser.add_argument(
+        "-b",
+        "--baudrate",
+        type=int,
+        default=None,
+        help="波特率（默认: SDEV_BAUDRATE 或 115200）",
+    )
+    subparsers = parser.add_subparsers(dest="subcommand", required=True)
+
+    # sdev shell "cmd"
+    shell_parser = subparsers.add_parser("shell", help="在板子上执行单条命令并回显输出")
+    shell_parser.add_argument(
+        "command",
+        help='要执行的命令，如: ls 或 "lsmod | grep nnp"',
+    )
+    shell_parser.add_argument(
+        "--flag",
+        default=" #",
+        help="提示符结束标志（默认: %(default)r）",
+    )
+    shell_parser.add_argument(
+        "--timeout",
+        type=float,
+        default=None,
+        help="等待命令输出的超时秒数",
+    )
+    shell_parser.add_argument(
+        "--no-check-alive",
+        action="store_true",
+        help="connect 后不执行 check_alive",
+    )
+    shell_parser.set_defaults(func=cmd_shell)
+
+    # sdev demoboard status
+    demoboard_parser = subparsers.add_parser("demoboard", help="Demoboard 相关操作")
+    demoboard_subparsers = demoboard_parser.add_subparsers(dest="demoboard_subcommand", required=True)
+
+    status_parser = demoboard_subparsers.add_parser("status", help="检查本机关联的 Demoboard 串口状态")
+    status_parser.set_defaults(func=cmd_demoboard_status)
+
+    parsed = parser.parse_args()
+    return parsed.func(parsed)
+
+
+if __name__ == "__main__":
+    sys.exit(main())