remote-serial / boardctl

开发板控制工具(设计参考 ostool):每块开发板一个 TOML 配置,模块化 + 插件化架构——加传输方式/执行方式只需在插件目录丢一个文件, 改某块功能只需动对应模块。

当前接入的板卡:Sipeed LicheeRv Nano(Sophgo SG2002 / CV181x,RISC-V 玄铁 C906, U-Boot 2021.10,提示符 soph#),串口经 TCP 桥(gem12)透传,电源为小米智能插座。

快速上手

./boardctl.sh -b sg2002 run           # 列出该板一键启动目标
./boardctl.sh -b sg2002 run hello     # 裸机测试:冷启动→传输→go→断言→断电
./boardctl.sh -b sg2002 run script    # U-Boot 脚本测试
./boardctl.sh -b sg2002 console       # 交互终端(Ctrl-\ 退出;配置 off_on_exit 时退出自动断电)
./boardctl.sh -b sg2002 cmd 'printenv'
./boardctl.sh -b sg2002 exec 'ls /srv/tftp'   # 在板卡命令环境执行 shell(配置 ssh_host 则经 ssh 远端执行)
./boardctl.sh -b sg2002 send FILE [--method loady|tftp] [--addr 0x80080000]
./boardctl.sh -b sg2002 power on|off|status
./boardctl.sh -b sg2002 reset
# 等价:./.venv/bin/python -m boardctl ...(任意目录可用 boardctl.sh)

架构(松耦合,单向依赖)

boardctl/
├── cli.py        命令行接线(argparse + 分发,无业务逻辑)
├── config.py     板卡 TOML 加载(不依赖其他模块)
├── session.py    U-Boot 串口会话 ← config
├── power.py      电源/冷启动   ← config, session
├── console.py    交互终端       ← config, session, power
├── runner.py     run/cmd 编排   ← 上述全部 + plugins
└── plugins/      插件(目录约定自动发现,零注册代码)
    ├── transport/   传输插件:loady.py、tftp.py
    ├── executors/   执行插件:go.py、source.py、none.py
    └── power/       电源插件:mijia.py(原生小米云调用,免子进程)

插件接口(接口约定写在各 __init__.py 里;插件可选声明 CFG_SECTION + DEFAULTS 自带配置默认值,TOML 优先):

• 传输插件(plugins/transport/xxx.py):NAME + send(cfg, path, addr) -> bool
• 执行插件(plugins/executors/xxx.py):NAME + build_cmd(addr) -> str | None
• 电源插件(plugins/power/xxx.py):NAME + set_power(cfg, on) + get_power(cfg) -> bool | None

新建插件 = 加一个文件,--method/[run].exec 立即可用,核心代码零改动。

板卡配置(boards/*.toml)

搜索顺序(先找到的优先):$BOARDCTL_BOARDS → 当前目录 ./boards → ~/.config/boardctl/boards/(推荐:用户自己的板放这里) → 包内置示例。

端到端验收

./.venv/bin/python tests/verify_e2e.py     # reset→tftp 部署→原始流逐字节断言,两套测试

裸机测试:tests/baremetal/(riscv64-linux-gnu-gcc,注意 DW APB UART reg-shift=2、 -fno-pie、--build-id=none)。脚本测试:tests/script/(source 需 mkimage 的 legacy uImage 头)。构建细节与踩坑记录见 tests/README.md。

依赖

Python 3.11+(stdlib tomllib)+ pyserial(见 requirements.txt)。交叉构建另需 riscv64-linux-gnu-gcc、mkimage(uboot-tools)、lrzsz。

安装与发布

# 从 PyPI 安装(发布后)
pip install boardctl            # 核心:串口/console/cmd/send(loady)
pip install 'boardctl[mijia]'   # + 小米云电源插件

# 板卡配置搜索顺序:$BOARDCTL_BOARDS → ./boards → ~/.config/boardctl/boards → 包内置示例
# 用户自己的板卡放 ~/.config/boardctl/boards/(优先级高于包内置示例),不碰安装目录

# 发布(项目根目录)
uv build                        # 产出 dist/*.whl + *.tar.gz
uv publish --token <PyPI_API_Token>   # 建议先发 TestPyPI 演练

可选发布路径:GitHub 仓库 + Actions trusted publishing(打 tag 自动发布,免 token), 或直接 pip install git+https://...(零发布设施,适合私有/内网)。

依赖