boardctl 0.1.0__tar.gz

boardctl-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ['v*']   # 打 tag(如 v0.1.0)自动构建发布
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # PyPI trusted publishing (OIDC) 必需
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: '3.12'
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

boardctl-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+
+# 运行时数据目录(本地 TFTP 根目录,内容按需自建)
+tftpboot/
+
+# 工具缓存
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# 测试构建产物特意保留(tests/ 下的小体积固件,便于无工具链环境复现 verify_e2e)

boardctl-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: boardctl
+Version: 0.1.0
+Summary: 开发板控制工具:串口终端 / 电源控制 / 文件传输(TFTP、Ymodem) / 一键启动测试,插件化架构(设计参考 ostool)
+Requires-Python: >=3.11
+Requires-Dist: pyserial>=3.5
+Provides-Extra: mijia
+Requires-Dist: mijiaapi>=4; extra == 'mijia'
+Description-Content-Type: text/markdown
+
+# remote-serial / boardctl
+
+开发板控制工具(设计参考 [ostool](https://crates.io/crates/ostool)):每块开发板一个
+TOML 配置,**模块化 + 插件化**架构——加传输方式/执行方式只需在插件目录丢一个文件,
+改某块功能只需动对应模块。
+
+当前接入的板卡:**Sipeed LicheeRv Nano**(Sophgo SG2002 / CV181x,RISC-V 玄铁 C906,
+U-Boot 2021.10,提示符 `soph#`),串口经 TCP 桥(gem12)透传,电源为小米智能插座。
+
+## 快速上手
+
+```bash
+./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/`(推荐:用户自己的板放这里)** → 包内置示例。
+
+| 段 | 键 | 说明 |
+|---|---|---|
+| 顶层 | `ssh_host` | 命令执行位置:空 = 本机(power/exec 等);填 ssh 别名(如 `gem12`)= 经 ssh 在远端主机执行,别名/端口/用户走 `~/.ssh/config` |
+| `[serial]` | `url` / `timeout` | 串口桥 URL(本板为 `socket://...` 裸 TCP) |
+| `[uboot]` | `prompt` / `load_addr` | 提示符、默认加载地址 |
+| | `server_ip` / `ensure_server_ip` | TFTP 服务器地址;该 U-Boot 无 saveenv,连接时自动恢复 |
+| `[power]` | `method = "mijia"` + `[power.mijia]` dev_name/did | **方式一·电源插件**:进程内原生调用小米云(凭证复用 `~/.config/mijia-api/auth.json`,首次需 `mijiaAPI login` 扫码),不走 ssh_host |
+| | `method = "command"` + `on_cmd`/`off_cmd`/`status_cmd` | **方式二·命令插件**:任意开关机 shell 命令(经 ssh_host 决定本机/远端);method 未配置时默认即此。改 `method` 一行切换 |
+| | `off_on_exit = true` | console 退出时自动断电(覆盖所有退出路径:Ctrl-\、Ctrl-A x、kill、串口掉线) |
+| `[tftp]` | `method=remote` + `ssh_host`/`remote_dir` | scp 到远端 tftpd(gem12 的 tftpd-hpa) |
+| | `method=local` + `local_dir` | 本机临时拉起 `tftp_server.py`(UDP 69 需特权,退出自动回收) |
+| `[loady]` | `sender` | Ymodem 发送器(Arch 为 `lrzsz-sb`) |
+| `[run.<名字>]` | `file` / `exec` / `method` / `timeout` | 一键启动目标(exec/method 即插件名) |
+| | `addr` / `entry` | 加载地址 / 跳转执行地址(`go 0x...` 的目标);缺省都取 `uboot.load_addr`,加载与入口不同时分别指定 |
+| | `reset_before` | 开头冷启动:关→开→等提示符(从任意脏状态恢复) |
+| | `after = off/reset/none` | 收尾动作 |
+| | `expect = [..]` | 输出断言,全命中才 PASS(退出码 0/1) |
+
+## 端到端验收
+
+```bash
+./.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`。
+
+## 安装与发布
+
+```bash
+# 从 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://...`(零发布设施,适合私有/内网)。
+
+## 依赖

boardctl-0.1.0/README.md

@@ -0,0 +1,105 @@
+# remote-serial / boardctl
+
+开发板控制工具(设计参考 [ostool](https://crates.io/crates/ostool)):每块开发板一个
+TOML 配置,**模块化 + 插件化**架构——加传输方式/执行方式只需在插件目录丢一个文件,
+改某块功能只需动对应模块。
+
+当前接入的板卡:**Sipeed LicheeRv Nano**(Sophgo SG2002 / CV181x,RISC-V 玄铁 C906,
+U-Boot 2021.10,提示符 `soph#`),串口经 TCP 桥(gem12)透传,电源为小米智能插座。
+
+## 快速上手
+
+```bash
+./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/`(推荐:用户自己的板放这里)** → 包内置示例。
+
+| 段 | 键 | 说明 |
+|---|---|---|
+| 顶层 | `ssh_host` | 命令执行位置:空 = 本机(power/exec 等);填 ssh 别名(如 `gem12`)= 经 ssh 在远端主机执行,别名/端口/用户走 `~/.ssh/config` |
+| `[serial]` | `url` / `timeout` | 串口桥 URL(本板为 `socket://...` 裸 TCP) |
+| `[uboot]` | `prompt` / `load_addr` | 提示符、默认加载地址 |
+| | `server_ip` / `ensure_server_ip` | TFTP 服务器地址;该 U-Boot 无 saveenv,连接时自动恢复 |
+| `[power]` | `method = "mijia"` + `[power.mijia]` dev_name/did | **方式一·电源插件**:进程内原生调用小米云(凭证复用 `~/.config/mijia-api/auth.json`,首次需 `mijiaAPI login` 扫码),不走 ssh_host |
+| | `method = "command"` + `on_cmd`/`off_cmd`/`status_cmd` | **方式二·命令插件**:任意开关机 shell 命令(经 ssh_host 决定本机/远端);method 未配置时默认即此。改 `method` 一行切换 |
+| | `off_on_exit = true` | console 退出时自动断电(覆盖所有退出路径:Ctrl-\、Ctrl-A x、kill、串口掉线) |
+| `[tftp]` | `method=remote` + `ssh_host`/`remote_dir` | scp 到远端 tftpd(gem12 的 tftpd-hpa) |
+| | `method=local` + `local_dir` | 本机临时拉起 `tftp_server.py`(UDP 69 需特权,退出自动回收) |
+| `[loady]` | `sender` | Ymodem 发送器(Arch 为 `lrzsz-sb`) |
+| `[run.<名字>]` | `file` / `exec` / `method` / `timeout` | 一键启动目标(exec/method 即插件名) |
+| | `addr` / `entry` | 加载地址 / 跳转执行地址(`go 0x...` 的目标);缺省都取 `uboot.load_addr`,加载与入口不同时分别指定 |
+| | `reset_before` | 开头冷启动:关→开→等提示符(从任意脏状态恢复) |
+| | `after = off/reset/none` | 收尾动作 |
+| | `expect = [..]` | 输出断言,全命中才 PASS(退出码 0/1) |
+
+## 端到端验收
+
+```bash
+./.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`。
+
+## 安装与发布
+
+```bash
+# 从 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://...`(零发布设施,适合私有/内网)。
+
+## 依赖

boardctl-0.1.0/boardctl/__init__.py

@@ -0,0 +1,11 @@
+"""boardctl — 开发板控制工具包(设计参考 crates.io 上的 ostool)
+
+结构(松耦合,单向依赖):
+  config.py    板卡 TOML 加载(不依赖其他模块)
+  session.py   U-Boot 串口会话(依赖 config)
+  power.py     电源控制与冷启动(依赖 config, session)
+  console.py   交互终端(依赖 config, session, power)
+  runner.py    run/cmd 编排(依赖上述 + plugins)
+  cli.py       命令行入口,只做接线
+  plugins/     插件(按目录约定自动发现,见 plugins/__init__.py)
+"""

boardctl-0.1.0/boardctl/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == '__main__':
+    main()

boardctl-0.1.0/boardctl/boards/sg2002.toml

@@ -0,0 +1,67 @@
+# Sophgo SG2002 开发板(Cvitek / RISC-V 玄铁 C906 / U-Boot 2021.10)
+description = "Sophgo SG2002 (RISC-V C906, U-Boot 2021.10, soph# 提示符)"
+
+# 命令执行位置:留空 = power/exec 等命令在本机执行;
+# 填 ssh 别名(如 "gem12")= 这些命令经 ssh 在该主机上执行(别名/端口/用户走 ~/.ssh/config)
+ssh_host = ""
+
+[serial]
+url = "socket://172.16.0.7:5000"   # 串口桥(gem12 的 VPN 地址),裸 TCP 透传
+timeout = 0.2
+
+[uboot]
+prompt = "soph#"
+load_addr = "0x80080000"
+ip_addr = "192.168.1.201"          # 设备自身 IP(静态)
+server_ip = "192.168.1.9"          # TFTP 服务器 = gem12 的 wlan 口
+ensure_server_ip = true            # 该构建无 saveenv,每次连接自动恢复 serverip
+
+[power]
+# 两种方式二选一(改 method 一行切换):
+method = "mijia"              # 方式一:原生插件,进程内直连小米云(参数见 [power.mijia])
+# method = "command"              # 方式二:特制开关机命令(用下面的 on_cmd/off_cmd/status_cmd)
+reset_delay = 3                    # 断电到上电的间隔(秒)
+off_on_exit = true                 # console 退出时自动断电(任何退出路径)
+# 方式二的命令(method = "command" 时生效;经顶层 ssh_host 决定本机/远端执行):
+on_cmd = "./run.sh 1"              # 开机命令
+off_cmd = "./run.sh 0"             # 关机命令
+status_cmd = "mijiaAPI get --dev_name sg2002 --prop_name on"   # 查状态(可选)
+
+[power.mijia]                      # 方式一的参数:dev_name 或 did 二选一
+dev_name = "sg2002"                # 米家里的设备名(即插座命名)
+
+[tftp]
+method = "remote"                  # remote: scp 到远端 tftp 目录 | local: 本机起内置 tftp 服务器
+ssh_host = "gem12"
+remote_dir = "/srv/tftp"           # 需一次性: ssh -t gem12 'sudo chown $USER /srv/tftp'
+local_dir = "tftpboot"             # method=local 时的根目录
+
+[loady]
+sender = "/usr/bin/lrzsz-sb"       # Arch 的 lrzsz;Debian/Ubuntu 为 /usr/bin/sb
+
+# 一键启动目标:boardctl.py -b sg2002 run <名字>(省略名字列出全部)
+[run.hello]
+desc = "RISC-V 裸机测试(冷启动→go 跳转→5 行标记→断电收尾)"
+file = "tests/baremetal/hello.bin"
+addr = "0x80080000"                # 加载地址(send/run 默认取 uboot.load_addr,可省)
+# entry = "0x80080010"             # 跳转地址(go 的目标);缺省 = addr。加载和入口不同时用它
+exec = "go"                        # go / source / none(只加载不执行)
+method = "tftp"
+timeout = 8                        # 执行后收集输出的秒数
+reset_before = true                # 关 → 开 → 等 U-Boot 提示符,从确定状态开始
+after = "off"                      # 收尾:off 断电 | reset 重启回提示符 | none 保持
+expect = [                         # 输出必须全部包含这些标记才算 PASS(缺省则不判定)
+  "BM-TEST-START",
+  "BM-COUNTER-1",
+  "BM-COUNTER-2",
+  "BM-COUNTER-3",
+  "BM-TEST-DONE",
+]
+
+[run.script]
+desc = "U-Boot 脚本(source 执行,三标记后干净返回,设备保持开机)"
+file = "tests/script/test_uboot.scr"
+exec = "source"
+method = "tftp"
+timeout = 8
+expect = ["SCRIPT-START", "SCRIPT-MIDDLE", "SCRIPT-DONE"]

boardctl-0.1.0/boardctl/cli.py

@@ -0,0 +1,68 @@
+"""命令行入口:参数解析与子命令分发,只做接线不含业务逻辑"""
+import argparse
+import os
+import sys
+
+from . import power, runner, shell
+from .config import available_boards, load_board
+from .console import do_console
+from .plugins import TRANSPORT
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        prog='boardctl',
+        description='开发板控制工具(参考 ostool 设计,每板一个 boards/*.toml,插件化传输/执行)')
+    ap.add_argument('-b', '--board', default='sg2002', help='开发板名(boards/ 下的 TOML 文件名)')
+    sub = ap.add_subparsers(dest='op', required=True)
+
+    sub.add_parser('console', help='交互式串口终端')
+    p_power = sub.add_parser('power', help='电源控制')
+    p_power.add_argument('state', choices=['on', 'off', 'status'])
+    sub.add_parser('reset', help='断电重启')
+    p_cmd = sub.add_parser('cmd', help='在 U-Boot 提示符执行命令')
+    p_cmd.add_argument('commands', nargs='+')
+    p_send = sub.add_parser('send', help='向开发板传输文件')
+    p_send.add_argument('file')
+    p_send.add_argument('--method', choices=sorted(TRANSPORT) or ['loady'],
+                        default='loady', help='传输插件')
+    p_send.add_argument('--addr', help='加载地址(默认取板卡 uboot.load_addr)')
+    p_run = sub.add_parser('run', help='按板卡配置的 [run.<名字>] 一键启动')
+    p_run.add_argument('name', nargs='?', help='启动目标名(省略则列出可用目标)')
+    p_exec = sub.add_parser('exec', help='在板卡命令环境执行 shell 命令(配置 ssh_host 则经 ssh 远端执行)')
+    p_exec.add_argument('command', nargs='+')
+    sub.add_parser('boards', help='列出开发板')
+
+    args = ap.parse_args()
+    if args.op == 'boards':
+        boards = available_boards()
+        if not boards:
+            sys.exit('没有找到任何板卡配置(搜索:$BOARDCTL_BOARDS → ./boards → ~/.config/boardctl/boards → 包内置)')
+        for name in sorted(boards):
+            cfg = load_board(name)
+            desc = f' — {cfg["description"]}' if cfg['description'] else ''
+            print(f'{cfg["name"]}{desc}')
+        return
+
+    cfg = load_board(args.board)
+    if args.op == 'console':
+        do_console(cfg)
+    elif args.op == 'power':
+        power.do_power(cfg, args.state)
+    elif args.op == 'reset':
+        power.do_reset(cfg)
+    elif args.op == 'cmd':
+        runner.do_cmd(cfg, args.commands)
+    elif args.op == 'send':
+        if not os.path.isfile(args.file):
+            sys.exit(f'文件不存在: {args.file}')
+        addr = args.addr or cfg['uboot']['load_addr']
+        ok = TRANSPORT[args.method].send(cfg, args.file, addr)
+        sys.exit(0 if ok else 1)
+    elif args.op == 'run':
+        runner.do_run(cfg, args.name)
+    elif args.op == 'exec':
+        r = shell.run(cfg, ' '.join(args.command), check=False, capture=True)
+        sys.stdout.write(r.stdout or '')
+        sys.stderr.write(r.stderr or '')
+        sys.exit(r.returncode)

boardctl-0.1.0/boardctl/config.py

@@ -0,0 +1,77 @@
+"""板卡配置加载:boards/*.toml + 默认值合并(TOML 同名键覆盖)"""
+import os
+import sys
+import tomllib
+from pathlib import Path
+
+# 项目根目录(本包的上一级):开发运行时 boards/、run.sh 等在这里
+BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+# 全局默认值(仅真正跨模块的段;插件自己的默认值由插件模块的 DEFAULTS 提供)
+DEFAULTS = {
+    'serial': {'url': 'socket://localhost:5000', 'timeout': 0.2},
+    'uboot': {
+        'prompt': '=>',
+        'load_addr': '0x80080000',
+        'ip_addr': '',
+        'server_ip': '',
+        'ensure_server_ip': False,
+    },
+}
+
+
+def boards_dirs():
+    """板卡配置目录搜索顺序(去重,仅保留存在的):
+    $BOARDCTL_BOARDS → 当前目录 boards/ → ~/.config/boardctl/boards → 包内置示例
+    """
+    candidates = [
+        os.environ.get('BOARDCTL_BOARDS'),
+        os.path.join(os.getcwd(), 'boards'),
+        str(Path.home() / '.config' / 'boardctl' / 'boards'),
+        os.path.join(os.path.dirname(os.path.abspath(__file__)), 'boards'),
+    ]
+    seen, out = set(), []
+    for d in candidates:
+        if d:
+            d = os.path.abspath(d)
+            if d not in seen and os.path.isdir(d):
+                seen.add(d)
+                out.append(d)
+    return out
+
+
+def available_boards():
+    """全部可用板卡名(按目录优先级去重,先出现的优先)"""
+    names = {}
+    for d in boards_dirs():
+        for f in sorted(os.listdir(d)):
+            if f.endswith('.toml'):
+                names.setdefault(f[:-5], os.path.join(d, f))
+    return names
+
+
+def load_board(name):
+    boards = available_boards()
+    if name not in boards:
+        sys.exit(f"未知开发板 {name!r},可用: {' '.join(sorted(boards)) or '(没有任何 boards/ 目录里有配置)'}")
+    with open(boards[name], 'rb') as f:
+        data = tomllib.load(f)
+    cfg = {'name': name, 'description': data.get('description', ''),
+           'ssh_host': data.get('ssh_host', '')}
+    for section, defaults in DEFAULTS.items():
+        cfg[section] = {**defaults, **data.get(section, {})}
+    cfg['power'] = dict(data.get('power', {}))
+    cfg['tftp'] = dict(data.get('tftp', {}))
+    cfg['run'] = data.get('run', {})
+
+    # 插件自带默认值:按插件的 CFG_SECTION 声明合并(TOML 值优先)。
+    # 函数内 import,避免 config <-> plugins 模块级循环依赖
+    from .plugins import all_plugins
+    for mod in all_plugins():
+        section = getattr(mod, 'CFG_SECTION', None)
+        defaults = getattr(mod, 'DEFAULTS', None)
+        if section and isinstance(defaults, dict):
+            merged = dict(defaults)
+            merged.update(cfg.get(section, {}))
+            cfg[section] = merged
+    return cfg