boardctl 0.1.0__py3-none-any.whl

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/__main__.py

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

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/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/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

boardctl/console.py

@@ -0,0 +1,207 @@
+"""交互式串口终端:raw 模式、按键本地命令、autoboot 自动拦截、退出自动断电"""
+import codecs
+import os
+import select
+import signal
+import sys
+import termios
+import threading
+import time
+import tty
+
+import serial
+
+from . import power
+
+CTRL_A = 0x01
+QUIT_BYTE = 0x1C              # Ctrl-\ 任意时刻直接退出
+QUIT_KEYS = (0x71, 0x78, 0x18)  # Ctrl-A q / Ctrl-A x(ostool 惯例) / Ctrl-A Ctrl-X
+
+BOOT_MARKERS = ('u-boot', 'hit any key', 'autoboot', 'arp retry')
+SERVER_ERROR = 'device open failure'
+INTERRUPT_INTERVAL = 0.1
+INTERRUPT_WINDOW = 15.0
+
+HELP = (
+    '\r\n[本地按键]\r\n'
+    '  Ctrl-\\      退出(任意时刻)\r\n'
+    '  Ctrl-A x/q  退出\r\n'
+    '  Ctrl-A b    手动开启一轮 autoboot 拦截\r\n'
+    '  Ctrl-A h    显示本帮助\r\n'
+    '  其他按键    原样转发到设备(包括 Ctrl-C)\r\n'
+)
+
+
+def cmsg(text):
+    print(f'\r\n{text}\r\n', end='', flush=True)
+
+
+def console_reader(ser, write_lock, manual_trigger, stop, quit_event, prompts):
+    decoder = codecs.getincrementaldecoder('utf-8')(errors='replace')
+    buf = ''
+    window_until = 0.0
+    last_sent = 0.0
+
+    while not stop.is_set() and not quit_event.is_set():
+        try:
+            data = ser.read(100)
+        except Exception:  # 关闭竞态:主线程 close() 后底层 socket 置 None
+            return
+        if data:
+            text = decoder.decode(data)
+            print(text, end='', flush=True)
+            low = text.lower()
+            if SERVER_ERROR in low:
+                cmsg('串口服务器打不开物理串口(服务器端设备不可用),稍后重连')
+                return
+            buf = (buf + low)[-160:]
+
+        now = time.monotonic()
+        if manual_trigger.is_set():
+            manual_trigger.clear()
+            window_until = now + INTERRUPT_WINDOW
+
+        if window_until == 0.0:
+            if any(m in buf for m in BOOT_MARKERS):
+                buf = ''
+                window_until = now + INTERRUPT_WINDOW
+                cmsg('检测到启动特征,发送按键打断 autoboot...')
+        elif now < window_until:
+            if any(p in buf for p in prompts):
+                buf = ''
+                window_until = 0.0  # 已停在提示符,停止发送
+            elif now - last_sent >= INTERRUPT_INTERVAL:
+                last_sent = now
+                try:
+                    with write_lock:
+                        ser.write(b'\r\x03')
+                except Exception:  # 同上,关闭竞态
+                    return
+        else:
+            buf = ''
+            window_until = 0.0
+
+
+def handle_stdin(data, ser, write_lock, manual_trigger, state):
+    for c in data:
+        if c == QUIT_BYTE:
+            return 'quit'
+        if state['prefix']:
+            state['prefix'] = False
+            if c in QUIT_KEYS:
+                return 'quit'
+            if c == ord('b'):
+                manual_trigger.set()
+                cmsg('手动触发拦截窗口')
+            elif c == ord('h'):
+                print(HELP, end='', flush=True)
+            elif c == CTRL_A:
+                with write_lock:
+                    ser.write(bytes([CTRL_A]))
+        elif c == CTRL_A:
+            state['prefix'] = True
+        else:
+            with write_lock:
+                ser.write(bytes([c]))
+    return None
+
+
+def console_session(ser, write_lock, manual_trigger, stop, quit_event, state, prompts):
+    reader = threading.Thread(
+        target=console_reader,
+        args=(ser, write_lock, manual_trigger, stop, quit_event, prompts),
+        daemon=True)
+    reader.start()
+
+    with write_lock:
+        ser.write(b'\r')
+    manual_trigger.set()
+
+    while True:
+        if quit_event.is_set():
+            return 'quit'
+        r, _, _ = select.select([sys.stdin], [], [], 0.2)
+        if r:
+            data = os.read(sys.stdin.fileno(), 1024)
+            if not data:
+                return 'quit'
+            try:
+                if handle_stdin(data, ser, write_lock, manual_trigger, state) == 'quit':
+                    return 'quit'
+            except Exception:  # 串口失效(含关闭竞态)
+                return 'reconnect'
+        if not reader.is_alive():
+            return 'reconnect'
+
+
+def console_wait_or_quit(seconds, state, quit_event):
+    end = time.monotonic() + seconds
+    while time.monotonic() < end:
+        if quit_event.is_set():
+            return False
+        r, _, _ = select.select([sys.stdin], [], [], 0.2)
+        if not r:
+            continue
+        data = os.read(sys.stdin.fileno(), 1024)
+        if not data:
+            return False
+        for c in data:
+            if c == QUIT_BYTE or (state['prefix'] and c in QUIT_KEYS):
+                return False
+            state['prefix'] = (c == CTRL_A)
+    return True
+
+
+def do_console(cfg):
+    prompts = list(dict.fromkeys([cfg['uboot']['prompt'], '=>']))
+    raw_mode = sys.stdin.isatty()
+    if raw_mode:
+        old_attrs = termios.tcgetattr(sys.stdin.fileno())
+        tty.setraw(sys.stdin.fileno())
+
+    write_lock = threading.Lock()
+    manual_trigger = threading.Event()
+    stop = threading.Event()
+    quit_event = threading.Event()
+    state = {'prefix': False}
+    signal.signal(signal.SIGTERM, lambda *_: quit_event.set())
+    signal.signal(signal.SIGINT, lambda *_: quit_event.set())
+
+    power_off = cfg['power'].get('off_on_exit') and cfg['power'].get('off_cmd')
+    banner = f'连接 {cfg["serial"]["url"]} | Ctrl-\\ 退出, Ctrl-A h 帮助'
+    if power_off:
+        banner += ',退出时自动断电'
+    cmsg(banner)
+    try:
+        while True:
+            try:
+                ser = serial.serial_for_url(
+                    cfg['serial']['url'], timeout=cfg['serial']['timeout'])
+            except serial.SerialException as e:
+                cmsg(f'连接失败: {e},3 秒后重试')
+                if not console_wait_or_quit(3, state, quit_event):
+                    return
+                continue
+            try:
+                result = console_session(
+                    ser, write_lock, manual_trigger, stop, quit_event, state, prompts)
+            finally:
+                try:
+                    ser.close()
+                except OSError:
+                    pass
+            if result == 'quit' or quit_event.is_set():
+                return
+            if not console_wait_or_quit(3, state, quit_event):
+                return
+    finally:
+        stop.set()
+        if raw_mode:
+            termios.tcdrain(sys.stdin.fileno())
+            termios.tcsetattr(sys.stdin.fileno(), termios.TCSADRAIN, old_attrs)
+        # 按配置在退出时断电(power.off_on_exit)
+        if power_off:
+            cmsg('退出:执行断电(power.off_on_exit)')
+            if not power.power_off(cfg, check=False):
+                cmsg('断电失败,请手动确认电源状态')
+        cmsg('已退出')

boardctl/plugins/__init__.py

@@ -0,0 +1,42 @@
+"""插件注册表:按目录约定自动发现,无需注册代码。
+
+- plugins/transport/<mod>.py   传输插件
+- plugins/executors/<mod>.py   执行插件
+- plugins/power/<mod>.py       电源插件
+
+新建插件 = 在对应目录加一个模块文件,自动生效。
+"""
+import importlib
+import pkgutil
+
+from . import executors, power, transport
+
+#: 传输插件注册表 {NAME: module},接口见 transport/__init__.py
+TRANSPORT = {}
+
+#: 执行插件注册表 {NAME: module},接口见 executors/__init__.py
+EXECUTORS = {}
+
+#: 电源插件注册表 {NAME: module},接口见 power/__init__.py
+POWER = {}
+
+
+def _scan(package, registry):
+    for m in pkgutil.iter_modules(package.__path__):
+        module = importlib.import_module(f'{package.__name__}.{m.name}')
+        name = getattr(module, 'NAME', None)
+        if name:
+            registry[name] = module
+
+
+_scan(transport, TRANSPORT)
+_scan(executors, EXECUTORS)
+_scan(power, POWER)
+
+
+def all_plugins():
+    """全部已注册插件模块的列表(config 合并插件自带 DEFAULTS 用)"""
+    mods = []
+    for registry in (TRANSPORT, EXECUTORS, POWER):
+        mods.extend(registry.values())
+    return mods

boardctl/plugins/executors/__init__.py

@@ -0,0 +1,8 @@
+"""执行插件接口约定(文件加载后如何启动):
+
+每个插件模块需要提供:
+  NAME: str                      # 名字,对应 [run.*].exec
+  build_cmd(addr) -> str | None  # 返回要在 U-Boot 执行的命令;None = 只加载不执行
+
+在此目录新建 .py 文件即自动注册。
+"""

boardctl/plugins/executors/go.py

@@ -0,0 +1,7 @@
+"""go 执行插件:跳转到加载地址执行裸机代码(不保证返回,程序常以死循环结束)"""
+
+NAME = 'go'
+
+
+def build_cmd(addr):
+    return f'go {addr}'

boardctl/plugins/executors/none.py

@@ -0,0 +1,7 @@
+"""none 执行插件:只把文件加载到内存,不执行(配合后续手动操作)"""
+
+NAME = 'none'
+
+
+def build_cmd(addr):
+    return None

boardctl/plugins/executors/source.py

@@ -0,0 +1,7 @@
+"""source 执行插件:把加载的 uImage 脚本当 U-Boot 命令序列执行,结束回提示符"""
+
+NAME = 'source'
+
+
+def build_cmd(addr):
+    return f'source {addr}'

boardctl/plugins/power/__init__.py

@@ -0,0 +1,10 @@
+"""电源插件接口约定:
+
+每个插件模块需要提供:
+  NAME: str                       # 名字,对应 [power].method
+  set_power(cfg, on: bool)        # 开/关设备电源
+  get_power(cfg) -> bool          # 查询电源状态
+
+插件在 boardctl 进程内原生执行(不经过 ssh_host)。
+在此目录新建 .py 文件即自动注册。
+"""

boardctl/plugins/power/command.py

@@ -0,0 +1,31 @@
+"""command 电源插件:执行 [power] 里配置的 on_cmd / off_cmd / status_cmd 命令
+
+"特制开关机命令"方式:任意 shell 命令,经顶层 ssh_host 决定本机/远端执行。
+status_cmd 可缺省;命令输出无法可靠解析时 get_power 返回 None(上层原样打印)。
+method 未配置时默认即本插件。
+"""
+import sys
+
+from ...shell import run as run_shell
+
+NAME = 'command'
+CFG_SECTION = 'power'
+DEFAULTS = {'on_cmd': None, 'off_cmd': None, 'status_cmd': None}
+
+
+def _cmd(cfg, key):
+    command = cfg['power'].get(key)
+    if not command:
+        sys.exit(f'[power] 缺少 {key}(command 电源插件需要 on_cmd/off_cmd)')
+    return command
+
+
+def set_power(cfg, on):
+    run_shell(cfg, _cmd(cfg, 'on_cmd' if on else 'off_cmd'), check=True)
+
+
+def get_power(cfg):
+    status = cfg['power'].get('status_cmd')
+    if status:
+        run_shell(cfg, status, check=False)
+    return None  # 任意命令的输出无法可靠解析为 bool

boardctl/plugins/power/mijia.py

@@ -0,0 +1,37 @@
+"""mijia 电源插件:原生调用 mijiaapi 包,经小米云控制智能插座
+
+凭证复用 mijiaAPI CLI 的登录态(~/.config/mijia-api/auth.json),
+首次使用前需先执行一次 `mijiaAPI login` 扫码。
+"""
+import threading
+
+NAME = 'mijia'
+
+_lock = threading.Lock()
+_dev_cache = {}   # (did, dev_name) -> mijiaDevice,避免每次操作都拉设备列表
+
+
+def _device(cfg):
+    with _lock:
+        p = cfg['power'].get('mijia', {})
+        key = (p.get('did'), p.get('dev_name'))
+        if key not in _dev_cache:
+            from mijiaAPI.apis import mijiaAPI
+            from mijiaAPI.devices import mijiaDevice
+            kwargs = {}
+            if p.get('did'):
+                kwargs['did'] = p['did']
+            elif p.get('dev_name'):
+                kwargs['dev_name'] = p['dev_name']
+            else:
+                raise ValueError('[power.mijia] 需要 dev_name 或 did')
+            _dev_cache[key] = mijiaDevice(mijiaAPI(), **kwargs)
+        return _dev_cache[key]
+
+
+def set_power(cfg, on):
+    _device(cfg).set('on', bool(on))
+
+
+def get_power(cfg):
+    return bool(_device(cfg).get('on'))

boardctl/plugins/transport/__init__.py

@@ -0,0 +1,9 @@
+"""传输插件接口约定:
+
+每个插件模块需要提供:
+  NAME: str                     # 名字,对应 --method / [run.*].method
+  send(cfg, path, addr) -> bool  # 把文件传到设备的 addr,成功返回 True
+
+可用的依赖:boardctl.config(BASE_DIR 等)、boardctl.session(UbootSession)。
+插件之间禁止互相 import。在此目录新建 .py 文件即自动注册。
+"""

boardctl/plugins/transport/loady.py

@@ -0,0 +1,70 @@
+"""loady 传输插件:设备端 loady(Ymodem)+ 本机 lrzsz 发送器,走串口,零网络依赖"""
+import fcntl
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+
+from ...session import UbootSession
+
+NAME = 'loady'
+CFG_SECTION = 'loady'
+DEFAULTS = {'sender': ''}   # Ymodem 发送器;空则自动找 lrzsz-sb / sb
+
+
+def find_sender(cfg):
+    sender = cfg['loady'].get('sender')
+    if sender and os.path.isfile(sender):
+        return sender
+    return shutil.which('lrzsz-sb') or shutil.which('sb')
+
+
+def send(cfg, path, addr):
+    sender = find_sender(cfg)
+    if not sender:
+        sys.exit('找不到 Ymodem 发送器(Arch: lrzsz 包的 lrzsz-sb;Debian: lrzsz 的 sb)')
+    with UbootSession(cfg) as s:
+        ok, _ = s.wait_prompt()
+        if not ok:
+            sys.exit('等待 U-Boot 提示符超时,设备可能不在 U-Boot 命令行')
+        s.ser.write(f'loady {addr}\r'.encode())
+        time.sleep(1.5)  # 等设备进入 Ymodem 接收态
+
+        # socket:// 的 pyserial 对象没有 fileno(),用底层 socket
+        raw = getattr(s.ser, 'sock', None)
+        fd = raw.fileno() if raw is not None else None
+        if fd is None:
+            try:
+                fd = s.ser.fileno()
+            except Exception:
+                fd = None
+        if fd is None:
+            sys.exit('该串口 URL 不支持把 fd 交给 Ymodem 发送器')
+        # 关键: 清掉 settimeout() 设置的 O_NONBLOCK,否则子进程 read 得到 EAGAIN 被当成超时
+        flags = fcntl.fcntl(fd, fcntl.F_GETFL)
+        fcntl.fcntl(fd, fcntl.F_SETFL, flags & ~os.O_NONBLOCK)
+
+        p = subprocess.Popen([sender, os.path.abspath(path)],
+                             stdin=fd, stdout=fd, stderr=subprocess.PIPE)
+        try:
+            _, err = p.communicate(timeout=180)
+        except subprocess.TimeoutExpired:
+            p.kill()
+            p.communicate()
+            print('Ymodem 发送器超时(180s),已终止')
+            return False
+        tail, _ = s.read_until(s.cfg['uboot']['prompt'], 10)
+        print(err.decode('utf-8', 'replace').strip())
+        print(tail.strip('\r\n'))
+        m = re.search(r'Total Size\s*=\s*(0x[0-9a-fA-F]+|\d+)', tail)
+        if m:
+            size = int(m.group(1), 0)
+            actual = os.path.getsize(path)
+            ok = size == actual
+            print(f'loady {"OK" if ok else "大小不符"}: {size} 字节 -> {addr}'
+                  + ('' if ok else f'(本地 {actual})'))
+            return ok
+        print('loady 传输失败(未见 Total Size 报告)')
+        return False