firmwareloop 0.1.6__tar.gz → 0.1.8__tar.gz

{firmwareloop-0.1.6 → firmwareloop-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firmwareloop
-Version: 0.1.6
+Version: 0.1.8
 Summary: AI Agent Firmware Development and Lab Automation Platform (Dual-Tier MCP Server)
 Author-email: WeilinZhang <19523330249@163.com>
 License: MIT
@@ -134,7 +134,8 @@ fwloop ndtdebugtool "C:/Users/weilin.zhang/Desktop/zwl/NdtDebugTool-v1.0.19"
 > 完成以上两步后，Agent 侧即可直接调用 NdtBox 相关工具：
 > `fw_ndtdbg_status`（版本/连通性/模组通断）、`fw_ndtdbg_measure`（数据轮询采集）、
 > `fw_ndtdbg_read_reg` / `fw_ndtdbg_write_reg`（任意寄存器读写，写需 `write_allowed` + `confirm` 双门控）、
-> `fw_ndtdbg_capture_seq`（寄存器序列 + Saleae 波形同窗口取证）。
+> `fw_ndtdbg_capture_seq`（寄存器序列 + Saleae 波形同窗口取证）、
+> `fw_ndtdbg_flash`（.bin/.nfw 整片擦写烧录，需 `write_allowed` + `confirm` 双门控，默认拒绝）。
 > 前置硬件要求：NdtBox 已装 CH341 驱动；如需 Saleae 波形证据，另装 sigrok-cli 并配置
 > `libusb-win32` 驱动（详见 `docs/` 交付说明）。测试时请退出 STDataCollection.exe 上位机（USB 独占）。
 
@@ -362,7 +363,7 @@ claude mcp remove --scope user agentic-hil
 ├── demo-firmware/    示例固件（CMake；宿主编译模拟 MCU，闭环验证载体）
 ├── demo-make/        示例固件（Make；构建测试载体）
 ├── docs/             DEPENDENCY_MATRIX / REUSE_PLAN / V0.0.2_GAP_VERIFICATION
-├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.1.6)
+├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.1.8)
 ├── .mcp.example.json 双层 MCP 配置模板（firmwareloop + agentic-hil）
 ├── AGENTS.md         通用智能体规范（Antigravity / Qoder / Cursor 等）
 ├── CLAUDE.md         Claude Code CLI 指南
@@ -372,7 +373,7 @@ claude mcp remove --scope user agentic-hil
 
 ---
 
-## 能力验证状态（v0.1.6）
+## 能力验证状态（v0.1.8）
 
 > 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
 > `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`
@@ -393,6 +394,7 @@ claude mcp remove --scope user agentic-hil
 | Safety Policy（limits.yaml） | Implemented（simulator 校验）-> 外置权威配置 |
 | 自动修复闭环（M6 载体） | Simulator Validated -> Real Hardware Validated 待 DUT |
 | NdtBox 数据采集/调试（fw_ndtdbg_status / fw_ndtdbg_measure, ChipSea Fxx IIC） | Implemented（无硬件 Fail-Closed 已验证）-> Real Hardware Validated 待 NdtBox |
+| NdtBox IIC 固件烧录（fw_ndtdbg_flash, .bin/.nfw 整片擦写, 芯海 Fxx） | Real Hardware Validated（84.87.1.1 / 84.87.1.2 真机整片擦写 verify pass, ~22s；双闸门 Fail-Closed） |
 
 ---
 

{firmwareloop-0.1.6 → firmwareloop-0.1.8}/README.md

@@ -106,7 +106,8 @@ fwloop ndtdebugtool "C:/Users/weilin.zhang/Desktop/zwl/NdtDebugTool-v1.0.19"
 > 完成以上两步后，Agent 侧即可直接调用 NdtBox 相关工具：
 > `fw_ndtdbg_status`（版本/连通性/模组通断）、`fw_ndtdbg_measure`（数据轮询采集）、
 > `fw_ndtdbg_read_reg` / `fw_ndtdbg_write_reg`（任意寄存器读写，写需 `write_allowed` + `confirm` 双门控）、
-> `fw_ndtdbg_capture_seq`（寄存器序列 + Saleae 波形同窗口取证）。
+> `fw_ndtdbg_capture_seq`（寄存器序列 + Saleae 波形同窗口取证）、
+> `fw_ndtdbg_flash`（.bin/.nfw 整片擦写烧录，需 `write_allowed` + `confirm` 双门控，默认拒绝）。
 > 前置硬件要求：NdtBox 已装 CH341 驱动；如需 Saleae 波形证据，另装 sigrok-cli 并配置
 > `libusb-win32` 驱动（详见 `docs/` 交付说明）。测试时请退出 STDataCollection.exe 上位机（USB 独占）。
 
@@ -334,7 +335,7 @@ claude mcp remove --scope user agentic-hil
 ├── demo-firmware/    示例固件（CMake；宿主编译模拟 MCU，闭环验证载体）
 ├── demo-make/        示例固件（Make；构建测试载体）
 ├── docs/             DEPENDENCY_MATRIX / REUSE_PLAN / V0.0.2_GAP_VERIFICATION
-├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.1.6)
+├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.1.8)
 ├── .mcp.example.json 双层 MCP 配置模板（firmwareloop + agentic-hil）
 ├── AGENTS.md         通用智能体规范（Antigravity / Qoder / Cursor 等）
 ├── CLAUDE.md         Claude Code CLI 指南
@@ -344,7 +345,7 @@ claude mcp remove --scope user agentic-hil
 
 ---
 
-## 能力验证状态（v0.1.6）
+## 能力验证状态（v0.1.8）
 
 > 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
 > `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`
@@ -365,6 +366,7 @@ claude mcp remove --scope user agentic-hil
 | Safety Policy（limits.yaml） | Implemented（simulator 校验）-> 外置权威配置 |
 | 自动修复闭环（M6 载体） | Simulator Validated -> Real Hardware Validated 待 DUT |
 | NdtBox 数据采集/调试（fw_ndtdbg_status / fw_ndtdbg_measure, ChipSea Fxx IIC） | Implemented（无硬件 Fail-Closed 已验证）-> Real Hardware Validated 待 NdtBox |
+| NdtBox IIC 固件烧录（fw_ndtdbg_flash, .bin/.nfw 整片擦写, 芯海 Fxx） | Real Hardware Validated（84.87.1.1 / 84.87.1.2 真机整片擦写 verify pass, ~22s；双闸门 Fail-Closed） |
 
 ---
 

{firmwareloop-0.1.6 → firmwareloop-0.1.8}/firmwareloop.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firmwareloop
-Version: 0.1.6
+Version: 0.1.8
 Summary: AI Agent Firmware Development and Lab Automation Platform (Dual-Tier MCP Server)
 Author-email: WeilinZhang <19523330249@163.com>
 License: MIT
@@ -134,7 +134,8 @@ fwloop ndtdebugtool "C:/Users/weilin.zhang/Desktop/zwl/NdtDebugTool-v1.0.19"
 > 完成以上两步后，Agent 侧即可直接调用 NdtBox 相关工具：
 > `fw_ndtdbg_status`（版本/连通性/模组通断）、`fw_ndtdbg_measure`（数据轮询采集）、
 > `fw_ndtdbg_read_reg` / `fw_ndtdbg_write_reg`（任意寄存器读写，写需 `write_allowed` + `confirm` 双门控）、
-> `fw_ndtdbg_capture_seq`（寄存器序列 + Saleae 波形同窗口取证）。
+> `fw_ndtdbg_capture_seq`（寄存器序列 + Saleae 波形同窗口取证）、
+> `fw_ndtdbg_flash`（.bin/.nfw 整片擦写烧录，需 `write_allowed` + `confirm` 双门控，默认拒绝）。
 > 前置硬件要求：NdtBox 已装 CH341 驱动；如需 Saleae 波形证据，另装 sigrok-cli 并配置
 > `libusb-win32` 驱动（详见 `docs/` 交付说明）。测试时请退出 STDataCollection.exe 上位机（USB 独占）。
 
@@ -362,7 +363,7 @@ claude mcp remove --scope user agentic-hil
 ├── demo-firmware/    示例固件（CMake；宿主编译模拟 MCU，闭环验证载体）
 ├── demo-make/        示例固件（Make；构建测试载体）
 ├── docs/             DEPENDENCY_MATRIX / REUSE_PLAN / V0.0.2_GAP_VERIFICATION
-├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.1.6)
+├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.1.8)
 ├── .mcp.example.json 双层 MCP 配置模板（firmwareloop + agentic-hil）
 ├── AGENTS.md         通用智能体规范（Antigravity / Qoder / Cursor 等）
 ├── CLAUDE.md         Claude Code CLI 指南
@@ -372,7 +373,7 @@ claude mcp remove --scope user agentic-hil
 
 ---
 
-## 能力验证状态（v0.1.6）
+## 能力验证状态（v0.1.8）
 
 > 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
 > `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`
@@ -393,6 +394,7 @@ claude mcp remove --scope user agentic-hil
 | Safety Policy（limits.yaml） | Implemented（simulator 校验）-> 外置权威配置 |
 | 自动修复闭环（M6 载体） | Simulator Validated -> Real Hardware Validated 待 DUT |
 | NdtBox 数据采集/调试（fw_ndtdbg_status / fw_ndtdbg_measure, ChipSea Fxx IIC） | Implemented（无硬件 Fail-Closed 已验证）-> Real Hardware Validated 待 NdtBox |
+| NdtBox IIC 固件烧录（fw_ndtdbg_flash, .bin/.nfw 整片擦写, 芯海 Fxx） | Real Hardware Validated（84.87.1.1 / 84.87.1.2 真机整片擦写 verify pass, ~22s；双闸门 Fail-Closed） |
 
 ---
 

{firmwareloop-0.1.6 → firmwareloop-0.1.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "firmwareloop"
-version = "0.1.6"
+version = "0.1.8"
 description = "AI Agent Firmware Development and Lab Automation Platform (Dual-Tier MCP Server)"
 readme = "README.md"
 authors = [

{firmwareloop-0.1.6 → firmwareloop-0.1.8}/tools/__init__.py

@@ -2,4 +2,4 @@
 FirmwareLoop - AI Agent Firmware Development and Lab Automation Platform.
 """
 
-__version__ = "0.1.6"
+__version__ = "0.1.8"

{firmwareloop-0.1.6 → firmwareloop-0.1.8}/tools/fw_mcp_server.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-fw_mcp_server.py - FirmwareLoop High-Level Workflow & Device MCP Server (v0.1.6).
+fw_mcp_server.py - FirmwareLoop High-Level Workflow & Device MCP Server (v0.1.8).
 
 Exposes high-level firmware engineering and hardware management tools to AI Coding
 Agents (Antigravity CLI, Claude Code CLI, Qoder IDE, CodeBuddy IDE, Cursor) via the Model Context
@@ -19,6 +19,7 @@ Tools provided:
   - fw_ndtdbg_read_reg: NdtBox IIC register read (ndtdbg_cli.py)
   - fw_ndtdbg_write_reg: NdtBox IIC register write, double-gated (ndtdbg_cli.py)
   - fw_ndtdbg_capture_seq: NdtBox register sequence + concurrent I2C capture for waveform evidence (ndtdbg_cli.py)
+  - fw_ndtdbg_flash: NdtBox IIC firmware flash (.bin/.nfw, full-chip erase, double-gated) (ndtdbg_cli.py)
   - fw_logic_capture: Logic analyzer protocol capture (logic_capture.ps1)
   - fw_logic_decode: Logic analyzer protocol decoding & assertion (logic_decode.ps1)
   - fw_get_evidence: Read structured audit run evidence (artifacts/runs/)
@@ -306,6 +307,18 @@ def handle_fw_ndtdbg_write_reg(args: Dict[str, Any]) -> Dict[str, Any]:
     return res
 
 
+def handle_fw_ndtdbg_flash(args: Dict[str, Any]) -> Dict[str, Any]:
+    """Erase + flash a .bin/.nfw image onto the NdtBox target chip (ChipSea Fxx) over IIC."""
+    cli_script = os.path.join(REPO_ROOT, "tools", "ndtdbg_cli.py")
+    cmd = [PYTHON_EXE, cli_script, "flash-bin", "--file", str(args.get("file_path")),
+           "--erase-ms", str(int(args.get("erase_ms", 2000)))]
+    if args.get("confirm"):
+        cmd.append("--confirm")
+    _ndtdbg_reg_args(args, cmd)
+    timeout_s = min(max(int(args.get("timeout_seconds", 300)), 30), 900)
+    return run_process(cmd, timeout=timeout_s)
+
+
 def handle_fw_ndtdbg_capture_seq(args: Dict[str, Any]) -> Dict[str, Any]:
     """单次调用内并发: 逻辑分析仪抓取与 NdtBox 寄存器序列同时进行。
 
@@ -1265,6 +1278,47 @@ TOOLS_REGISTRY = {
         },
         "handler": handle_fw_ndtdbg_write_reg,
     },
+    "fw_ndtdbg_flash": {
+        "description": "Erase and flash a .bin/.nfw firmware image onto the NdtBox target chip (ChipSea Fxx) over IIC via NdtDebugTool (power-cycle reset into boot -> erase magic AA 55 A5 5A -> 128B page writes -> 256B read-back verify -> finish 'PASs'). DESTRUCTIVE full-chip erase: requires lab.yaml ndtdbg.write_allowed: true AND confirm: true, otherwise PERMISSION_DENIED.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "file_path": {
+                    "type": "string",
+                    "description": "Firmware image path (.bin auto-padded to 128-byte alignment with 0xFF; .nfw stripped of its 256-byte header)",
+                },
+                "confirm": {
+                    "type": "boolean",
+                    "description": "Acknowledge the destructive full-chip erase (double-gated with lab.yaml ndtdbg.write_allowed)",
+                    "default": False,
+                },
+                "erase_ms": {
+                    "type": "integer",
+                    "description": "Erase wait in ms (align with factory UpdateFW: 2000)",
+                    "default": 2000,
+                },
+                "timeout_seconds": {
+                    "type": "integer",
+                    "description": "CLI process timeout; budget ~30s per 64KB image (page writes paced at 30ms)",
+                    "default": 300,
+                },
+                "dll_dir": {
+                    "type": "string",
+                    "description": "NdtDebugTool lib directory containing USBIOX.DLL and usb2io.dll; default from lab.yaml ndtdbg.dll_dir",
+                },
+                "slave_addr": {
+                    "type": "string",
+                    "description": "IIC slave address (e.g. 0xA0); default from lab.yaml ndtdbg.slave_addr",
+                },
+                "speed": {
+                    "type": "integer",
+                    "description": "IIC speed 0=20kHz 1=100kHz; default from lab.yaml ndtdbg.iic_speed",
+                },
+            },
+            "required": ["file_path"],
+        },
+        "handler": handle_fw_ndtdbg_flash,
+    },
     "fw_ndtdbg_capture_seq": {
         "description": "One-call protocol evidence: concurrently runs a NdtBox register write sequence (default 0xBE=01, 0x01=BE 42, poll 0x01, readback 0xBE) and a 3s Saleae/sigrok I2C capture, returning the capture path for fw_logic_decode.",
         "inputSchema": {
@@ -1433,7 +1487,7 @@ def process_request(req: Dict[str, Any]) -> Optional[Dict[str, Any]]:
                 },
                 "serverInfo": {
                     "name": "firmwareloop",
-                    "version": "0.1.6"
+                    "version": "0.1.8"
                 }
             }
         }
@@ -1525,7 +1579,7 @@ def process_request(req: Dict[str, Any]) -> Optional[Dict[str, Any]]:
 def handle_cli_update() -> int:
     """Handle `firmwareloop update` command."""
     print("============================================================")
-    print("  FirmwareLoop Auto-Updater (v0.1.6)")
+    print("  FirmwareLoop Auto-Updater (v0.1.8)")
     print("============================================================")
 
     is_git_repo = os.path.exists(os.path.join(REPO_ROOT, ".git"))
@@ -1795,7 +1849,7 @@ def set_ndtdbg_dlldir(dll_path: str) -> str:
 def handle_cli_setup() -> int:
     """Handle `firmwareloop setup` command: simultaneously configure Antigravity CLI, Claude Code CLI, Qoder IDE, and CodeBuddy IDE."""
     print("============================================================")
-    print("  FirmwareLoop Multi-Agent Global Setup Helper (v0.1.6)")
+    print("  FirmwareLoop Multi-Agent Global Setup Helper (v0.1.8)")
     print("============================================================")
     print("")
 
@@ -1920,7 +1974,7 @@ def handle_cli_setup() -> int:
 def handle_cli_init() -> int:
     """Handle `firmwareloop init` command."""
     print("============================================================")
-    print("  FirmwareLoop Multi-Agent Project Initializer (v0.1.6)")
+    print("  FirmwareLoop Multi-Agent Project Initializer (v0.1.8)")
     print("============================================================")
     cwd = os.getcwd()
     print(f"[*] Initializing multi-agent guidelines & bench config in:\n    {cwd}\n")
@@ -1941,7 +1995,7 @@ def handle_cli_init() -> int:
 
 
 def print_cli_help() -> None:
-    print("""FirmwareLoop (fwloop) — AI Agent Firmware Engineering & Lab Automation Platform (v0.1.6)
+    print("""FirmwareLoop (fwloop) — AI Agent Firmware Engineering & Lab Automation Platform (v0.1.8)
 
 Usage:
   fwloop [command]   (or: firmwareloop [command])
@@ -1981,7 +2035,7 @@ def main() -> None:
                 sys.exit(2)
             sys.exit(handle_cli_ndtdebugtool(args[1]))
         elif cmd in ["version", "-v", "--version"]:
-            print("FirmwareLoop v0.1.6")
+            print("FirmwareLoop v0.1.8")
             sys.exit(0)
         elif cmd in ["help", "-h", "--help"]:
             print_cli_help()

{firmwareloop-0.1.6 → firmwareloop-0.1.8}/tools/lib/ndtdbg.py

@@ -92,6 +92,53 @@ def pad_bin_128(file_bytes: bytes) -> bytes:
     return file_bytes + b"\xFF" * pad
 
 
+# ---------------------------------------------------------------------------
+# 固件烧录 (对齐 ChipSea.cs UpdateFW: 断电复位 -> 整片擦除 -> 页写 -> 回读校验 -> 完成魔数)
+# ---------------------------------------------------------------------------
+
+FLASH_WRITE_PAGE = 128     # WriteFw 每事务 128 字节负载 (IIC 写共 130B = 2B 页地址 + 负载)
+FLASH_READ_WINDOW = 256    # ReadFwAndCheck 每窗回读 256 字节
+ERASE_MAGIC = b"\xAA\x55\xA5\x5A"    # EreaseChipCmd 写 @0x0000
+FINISH_MAGIC = b"\x50\x41\x53\x73"   # UpgradeFinishCmd "PASs" 写 @0x0000
+BOOT_READY_MS = 100        # VBRTOFF 上电后到发擦除命令的等待 (UpdateFW Thread.Sleep(100))
+PAGE_WRITE_GAP_MS = 30     # 页写间隔 (WriteFw Thread.Sleep(30))
+PAGE_READ_GAP_MS = 10      # 回读窗口间隔 (ReadFwAndCheck Thread.Sleep(10))
+
+
+def load_firmware(file_path: str) -> tuple[str, bytes]:
+    """读取固件: .nfw 去 256 头 / .bin 128 对齐 0xFF 补齐 (ChipSea.cs LoadFile)。返回 (类型, 载荷)。"""
+    if not os.path.isfile(file_path):
+        raise NdtBoxError("CONFIG_ERROR", "固件文件不存在", file_path)
+    ext = os.path.splitext(file_path)[1].lower()
+    try:
+        with open(file_path, "rb") as fh:
+            raw = fh.read()
+    except OSError as exc:
+        raise NdtBoxError("CONFIG_ERROR", "固件文件读取失败", str(exc)) from exc
+    if ext == ".nfw":
+        return "nfw", strip_nfw(raw)
+    if ext == ".bin":
+        if not raw:
+            raise NdtBoxError("CONFIG_ERROR", ".bin 固件为空", file_path)
+        return "bin", pad_bin_128(raw)
+    raise NdtBoxError("CONFIG_ERROR", "仅支持 .bin / .nfw 固件文件", ext or "(无后缀)")
+
+
+def build_page_write_frame(offset: int, page: bytes) -> bytes:
+    """页写帧: 页地址大端 2 字节 + <=128 字节负载 (ChipSea.cs WriteFw 逐页自 0x0000 递增)。"""
+    if len(page) > FLASH_WRITE_PAGE:
+        raise NdtBoxError("CONFIG_ERROR", "页负载超过 128 字节", str(len(page)))
+    if not 0 <= offset <= 0xFFFF:
+        raise NdtBoxError("CONFIG_ERROR", "页地址越界 (0..0xFFFF)", hex(offset))
+    return offset.to_bytes(2, "big") + page
+
+
+def expected_read_window(fw: bytes, offset: int) -> bytes:
+    """回读期望窗口: 256 字节, 末窗不足部分 0xFF 补齐 (ChipSea.cs ReadFwAndCheck)。"""
+    window = fw[offset:offset + FLASH_READ_WINDOW]
+    return window + b"\xFF" * (FLASH_READ_WINDOW - len(window))
+
+
 # ---------------------------------------------------------------------------
 # 桥调用层
 # ---------------------------------------------------------------------------
@@ -156,6 +203,82 @@ class NdtBoxIo:
             raise NdtBoxError("CONFIG_ERROR", "写入数据过长 (<=128)", str(len(data)))
         self._bridge("write", RegAddr=reg, Data=data.hex())
 
+    def raw_write_read(self, write: bytes, read_len: int = 0) -> bytes | None:
+        """原始 IIC 事务 (对齐 IIC.WriteRead): 写 write 字节(不含从机地址) 再读 read_len 字节。
+
+        覆盖 ChipSea 烧录的多字节地址形态 (页写 130B / 页读 [hi,lo]+256)。
+        """
+        if not write:
+            raise NdtBoxError("CONFIG_ERROR", "raw 写字节为空", None)
+        if 1 + len(write) > 256:
+            raise NdtBoxError("CONFIG_ERROR", "raw 写事务过长 (含从机地址须 <=256)", str(len(write)))
+        if not 0 <= read_len <= 256:
+            raise NdtBoxError("CONFIG_ERROR", "raw 读长度越界 (0..256)", str(read_len))
+        data = self._bridge("raw", WriteHex=write.hex(), ReadLen=read_len)
+        return bytes.fromhex(data["hex"].replace(" ", "")) if read_len > 0 else None
+
+    def _bridge_pipe(self, action: str, payload_text: str, timeout_ms: int | None) -> dict:
+        """把 JSON 文本经 stdin 送入桥的批量 action, 单进程执行。
+
+        #progress 进度行由桥写 stdout (非 JSON), 本方法转发到本进程 stderr。
+        末行为 JSON: {ok:false,...} -> 转 NdtBoxError (Fail-Closed); 成功返回 data。
+        """
+        import sys
+        args = [PS32, "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
+                "-File", self.bridge_ps1, "-Action", action,
+                "-DllDir", self.dll_dir, "-SlaveAddr", str(self.slave_addr),
+                "-Speed", str(self.speed)]
+        to = self.timeout_ms if timeout_ms is None else timeout_ms
+        try:
+            proc = subprocess.run(args, input=payload_text.encode("utf-8"), capture_output=True,
+                                  timeout=to / 1000.0, check=False)
+        except subprocess.TimeoutExpired:
+            raise NdtBoxError("INSTRUMENT_TIMEOUT", f"桥 {action} 执行超时 >{to}ms", None)
+        out = (proc.stdout or b"").decode("utf-8", errors="replace")
+        lines = [ln for ln in out.splitlines() if ln]
+        for ln in lines[:-1]:
+            if ln.startswith("#progress"):
+                print(ln, file=sys.stderr, flush=True)
+        if not lines:
+            tail = (proc.stderr or b"").decode("utf-8", errors="replace").strip()[-400:]
+            raise NdtBoxError("UNKNOWN_ERROR", f"桥 {action} 无输出 (exit={proc.returncode})", tail or None)
+        try:
+            result = json.loads(lines[-1])
+        except json.JSONDecodeError as exc:
+            raise NdtBoxError("UNKNOWN_ERROR", f"桥 {action} 输出非 JSON", out[-400:]) from exc
+        if not result.get("ok"):
+            raise NdtBoxError(result.get("error_class", "UNKNOWN_ERROR"),
+                              result.get("error", f"桥 {action} 返回失败"),
+                              result.get("detail"))
+        return result.get("data", {})
+
+    def run_ops(self, ops: list[dict], timeout_ms: int | None = None) -> dict:
+        """在单个 32 位 PS 进程内顺序执行 ops——批量路径避免逐帧 spawn 进程开销。
+
+        ops item: {"op":"sleep","ms":N} | {"op":"w","hex":"<帧 hex>"} |
+                  {"op":"r","hex":"<2B 地址 hex>","len":N}
+        桥自动为 w/r 前置从机地址; r 的读回按序进入返回 read_hexes (无空格 hex, 每窗一条)。
+        """
+        if not ops:
+            raise NdtBoxError("CONFIG_ERROR", "run_ops 空序列", None)
+        return self._bridge_pipe("run", json.dumps(ops, separators=(",", ":")), timeout_ms)
+
+    def flash_exec(self, plan: dict, timeout_ms: int | None = None) -> dict:
+        """单进程完整固件烧录 (bridge "flash"), 复刻原厂 GUI 进程模型:
+        usb2io(IO10) 断电复位进 boot + USBIOX IIC 全序列在**同一进程同一会话**内连续执行,
+        消除跨进程的"断电->擦除"间隔。校验 (逐窗 vs expect_hex) 在桥内完成, 失败即
+        {ok:false, TARGET_MISMATCH} -> 本方法转 NdtBoxError (Fail-Closed)。
+
+        plan: {"off_ms":200,"erase_ms":2000,"page_gap_ms":30,"read_gap_ms":10,
+               "writes":["<2B 地址+128B 数据帧 hex>",...],
+               "windows":[{"off":0,"expect_hex":"<256B hex>"},...]}
+        """
+        return self._bridge_pipe("flash", json.dumps(plan, separators=(",", ":")), timeout_ms)
+
+    def vbrt_reset(self, off_ms: int = 200) -> dict:
+        """模组断电 off_ms 后恢复上电 (usb2io.dll IO10)——复位进入 IIC boot (IOoperation.VBRTOFF)。"""
+        return self._bridge("vbrt", OffMs=off_ms)
+
     def close(self) -> dict:
         return self._bridge("close")
 
@@ -220,3 +343,48 @@ class ChipSeaFxx:
             raise NdtBoxError("CONFIG_ERROR", "poll 时长必须 > 0", str(duration_ms))
         return self._io._bridge("poll", DurationMs=int(duration_ms), IntervalMs=int(interval_ms),
                                 ReadyTimeoutMs=int(ready_timeout_ms))
+
+    # -- 固件烧录 (对齐 ChipSea.cs UpdateFW: 仅芯海 Fxx, 整片擦写) --
+
+    def flash_bin(self, file_path: str, erase_ms: int = 2000,
+                  progress=None) -> dict:
+        """经 NdtBox IIC 烧录 .bin/.nfw 固件到芯海 Fxx (单进程 flash action)。
+
+        时序逐行对齐 ChipSea.cs UpdateFW, 进程模型对齐原厂 STDataCollection GUI:
+          VBRTOFF(200) 断电复位进 boot -> 100ms -> 擦除魔数 -> erase_ms ->
+          逐 128B 页写(30ms) -> 200ms -> 逐 256B 窗回读校验(10ms, 桥内逐窗比对) ->
+          完成魔数 "PASs" -> VBRTOFF(200) 复位加载。
+        整条序列在**一个 32 位 PS 进程**内连续执行 (usb2io + USBIOX 句柄同持),
+        消除跨进程"断电->擦除"间隔, ~15s 量级。帧组装在本层 (可单测),
+        校验失败由桥 {ok:false, TARGET_MISMATCH} -> flash_exec 抛 NdtBoxError (Fail-Closed)。
+
+        progress(phase, done, total) 在 verify 阶段末回调 (逐帧 #progress 由桥转发到 stderr)。
+        """
+        import time
+        fw_type, fw = load_firmware(file_path)
+        started = time.monotonic()
+        pages = list(range(0, len(fw), FLASH_WRITE_PAGE))
+        windows = list(range(0, len(fw), FLASH_READ_WINDOW))
+        plan = {
+            "off_ms": 200,
+            "erase_ms": int(erase_ms),
+            "page_gap_ms": PAGE_WRITE_GAP_MS,
+            "read_gap_ms": PAGE_READ_GAP_MS,
+            "writes": [build_page_write_frame(off, fw[off:off + FLASH_WRITE_PAGE]).hex()
+                       for off in pages],
+            "windows": [{"off": off, "expect_hex": expected_read_window(fw, off).hex()}
+                        for off in windows],
+        }
+        res = self._io.flash_exec(plan)
+        if progress:
+            progress("verify", len(windows), len(windows))
+        return {
+            "file": file_path,
+            "file_type": fw_type,
+            "fw_len": len(fw),
+            "pages_written": len(pages),
+            "read_windows": len(windows),
+            "erase_ms": int(erase_ms),
+            "verify": res.get("verify", "pass"),
+            "duration_ms": int((time.monotonic() - started) * 1000),
+        }