Metadata-Version: 2.4
Name: firmwareloop
Version: 0.0.10
Summary: AI Agent Firmware Development and Lab Automation Platform (Dual-Tier MCP Server)
Author-email: WeilinZhang <19523330249@163.com>
License: MIT
Project-URL: Homepage, https://github.com/Jeffrey1799/FirmwareLoop
Project-URL: Repository, https://github.com/Jeffrey1799/FirmwareLoop.git
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyvisa>=1.14.0
Requires-Dist: pyvisa-py>=0.7.0
Requires-Dist: pyserial>=3.5
Requires-Dist: pytest>=8.0.0
Requires-Dist: pyocd>=0.36.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: agentic-hil>=0.14.0
Dynamic: license-file

# FirmwareLoop (`fwloop`)

> **面向 AI Agent 的嵌入式固件开发、硬件在环测试（HIL）与实验室自动化 MCP 工具集。**
> 赋能 Claude Code、Qoder、Antigravity、Cursor 等 AI 智能体直接操作物理硬件，打通从代码编译、探针烧录、芯片复位到串口交互、逻辑分析仪抓包与示波器测量的完整开发闭环。

![Windows](https://img.shields.io/badge/windows-10%20%7C%2011-blue)
![PowerShell](https://img.shields.io/badge/powershell-7+-4E8B8B)
![Python](https://img.shields.io/badge/python-3.10%2B-3776AB)
[![PyPI](https://img.shields.io/pypi/v/firmwareloop.svg)](https://pypi.org/project/firmwareloop/)
[![CI](https://github.com/Jeffrey1799/FirmwareLoop/actions/workflows/ci.yml/badge.svg)](https://github.com/Jeffrey1799/FirmwareLoop/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## 为什么需要 FirmwareLoop？（定位与作用）

传统的 AI 编程助手（LLM）通常只能停留在**“纯软件文本生成”**阶段。在单片机与嵌入式领域，AI 面临严重的断层：**看不到编译报错行列、无法操作物理烧录器、读取不到串口输出，更无法测量真实的电信号与总线波形**。

**FirmwareLoop 作为一个标准的 Model Context Protocol (MCP) 服务器，充当了 AI Agent 与物理硬件之间的桥梁**：
* **赋予 AI 动手能力**：让 Agent 自主调用 Keil5 / CMake 编译固件，并通过 ST-LINK / J-Link / DAPLink 烧录到目标 MCU 并硬件复位。
* **赋予 AI 观测能力**：让 Agent 能够监听 UART 串口会话、捕获并解码 I2C/SPI 总线数据，甚至读取示波器与程控电源的真实物理量。
* **软硬件自动排障闭环**：当硬件运行异常时，Agent 基于捕获到的真实证据（编译器诊断、I2C NACK、串口 Panic、示波器异常电压）自动定位并修改 C/C++ 源码，重新烧录验证，直到测试全绿。

---

## 核心功能与 MCP 工具矩阵

FirmwareLoop 为 AI Agent 暴露了开箱即用的 MCP 工具，涵盖 5 大核心领域：

| 领域 | 核心 MCP 工具 | 功能说明 |
|---|---|---|
| **构建与体检** | `fw_doctor` <br> `fw_build` | 环境工具链诊断；自动调度 Keil MDK 5 (`UV4.exe`)、CMake、Make、PlatformIO 等编译固件并提取精确定位到行列的诊断日志。 |
| **硬件与探针** | `fw_scan_hardware` <br> `fw_flash` <br> `fw_reset` | 自动扫描连接的 ST-LINK / J-Link / DAPLink 探针与串口；直连 SWD 接口执行固件烧录与芯片硬件复位。 |
| **总线与协议** | `fw_logic_capture` <br> `fw_logic_decode` | 驱动逻辑分析仪（Saleae / Sigrok）捕获数字信号；自动解码并断言 I2C 地址/ACK、SPI 帧与串口数据完整性。 |
| **测试与测量** | `fw_run_hil_test` <br> `fw_measure` <br> `fw_acceptance_scenario` | 一键运行 12 项 pytest 自动化硬件在环测试；安全读取 PyVISA 示波器（频率/Vpp）与程控电源（电流/电压）。 |
| **工程与脚手架** | `fw_init_project` <br> `fw_configure_lab` <br> `fw_get_evidence` | 一键生成 `AGENTS.md` / `CLAUDE.md` / `GEMINI.md` 多 Agent 指南；自然语言修改芯片型号与台架配置；提取全链路审计证据。 |

---

## 核心设计原则

1. **真实硬件优先与零伪造原则（Real-Hardware-First & Zero-Fake）**：
   开发过程中，若探针未插、MCU 未上电、COM 串口占用或编译器缺失，系统**严格抛出明确异常（Fail-Closed）并输出可操作的排查与安装指引**，绝不伪造假成功数据。
2. **安全沙盒保护（Safety Gate）**：
   所有物理仪器写操作强制受 [`lab/limits.yaml`](lab/limits.example.yaml) 限制，永久禁止超压超流与擦除安全密钥。
3. **全电脑全局通用（Zero Config per Project）**：
   通过 `uv tool install firmwareloop` 全局安装一次，所有 STM32 / Keil 项目均可直接由 Agent 唤起使用。

---

## 架构

```
┌────────────────────────────────────────────┐
│               AI Agent (Qoder / CLI)       │
│  Code / Planning / Diagnosis / Orchestration│
└────────────────────┬───────────────────────┘
         ┌───────────┼───────────────┐
         ▼           ▼               ▼
     Shell/CLI      MCP           pytest
         │           │               │
         ▼   ┌───────┴──────┐       ▼
       tools/  Agentic HIL  Saleae  HIL 测试
         │     │            │
         ▼     ▼            ▼
   Build  Flash UART CAN    Logic
   Adapter Reset Debug      Analyzer
         │
         └─────────┬───────────────┐
                   ▼               ▼
                  DUT         PyVISA / SCPI
                               Scope / PSU / DMM / AWG
```

细节见 [AI_DEV_GUIDE.md](AI_DEV_GUIDE.md)（Agent 强制规则，设计约束由此衍生；原始内部需求文档不随仓库发布）。

---

## 极速起步（3 步搞定）

无论你使用 **Google Antigravity**、**Claude Code**、**Qoder** 还是 **Cursor**，只需以下 3 步即可开始 AI 驱动的单片机自动化开发：

### 第一步：全局安装核心 CLI 工具

从 PyPI 官方源安装（全电脑仅需执行一次）：

```bash
uv tool install firmwareloop
uv tool install agentic-hil
```

---

### 第二步：全局注册到各大 AI Agent

按你日常使用的 Agent 执行对应的注册命令（全电脑仅需配置一次）：

1. **Google Antigravity / Gemini CLI（全自动配置，推荐）**：
```bash
fwloop setup
```
> **说明**：该命令会自动将双层 MCP 写入 Antigravity 全局配置（`~/.gemini/config/mcp_config.json`），并全自动将全套技能包同步到全局 Skill 目录。

2. **Claude Code CLI**：
```bash
claude mcp add --scope user fwloop -- fwloop
claude mcp add --scope user agentic-hil -- agentic-hil mcp-stdio
```

3. **Qoder IDE**：
```bash
qoder.cmd mcp add --global fwloop -- fwloop
```

4. **Cursor / 其他 IDE**（在工程根目录的 `.mcp.json` 中并联配置）：
```json
{
  "mcpServers": {
    "fwloop": {
      "command": "fwloop"
    },
    "agentic-hil": {
      "command": "agentic-hil",
      "args": ["mcp-stdio"]
    }
  }
}
```

---

### 第三步：在你的单片机工程中开启自动化

进入你的任意单片机工程根目录（如 STM32 Keil / CMake / IAR / PlatformIO 项目）：

1. 一键生成智能体规范、MCP 描述与台架模板：
```bash
fwloop init
```

2. 接入真实硬件（配置串口与探针）：
根据提示打开工程目录下的 `lab/lab.yaml`，填入你的串口号（如 `COM5`）、目标芯片型号（如 `STM32F103C8`）与编译器类型（如 `keil` 或 `cmake`）。

3. 打开 AI Agent 对话框，直接用自然语言调度：
- “*执行 `fw_doctor()` 检查我的硬件和编译器连接状态*”
- “*帮我编译当前单片机代码，并刷入开发板运行*”
- “*运行 HIL 自动化测试，抓取串口 Log 并验证开机状态*”

---

### 核心命令职责速查

| 命令 | 适用级别 | 核心作用 | 使用时机 |
|---|---|---|---|
| **`fwloop setup`** | **系统全局级** | 给各大 Agent（Antigravity / Claude Code）配置全局 MCP 与同步技能包 | **全电脑只需跑 1 次** |
| **`fwloop init`** | **工程项目级** | 在当前单片机代码目录下生成 `AGENTS.md`、`GEMINI.md`、`CLAUDE.md` 与台架配置 | **每个新单片机项目跑 1 次** |
| **`fwloop doctor`** | **环境诊断** | 检查编译器（Keil/GCC）、Python 环境、串口与探针连接健康度 | 随时排查环境时使用 |
| **`fwloop update`** | **自动更新** | 一键自动拉取最新代码并热重载依赖 | 升级工具版本时使用 |

---

### 进阶：免克隆即时运行模式（Zero-Clone Mode）

如果不想使用全局安装，也可配置 Agent 通过 `uvx` 临时拉取即时运行：

1. Claude Code CLI 注册：
```bash
claude mcp add fwloop -- uvx firmwareloop
claude mcp add agentic-hil -- uvx agentic-hil mcp-stdio
```

2. 工程 `.mcp.json` 配置：
```json
{
  "mcpServers": {
    "fwloop": {
      "command": "uvx",
      "args": ["firmwareloop"]
    },
    "agentic-hil": {
      "command": "uvx",
      "args": ["agentic-hil", "mcp-stdio"]
    }
  }
}
```

---

### 接入模式三：源码二次开发模式（本地 Git 克隆）

适合需要修改 FirmwareLoop 源码或离线开发的用户：

1. 克隆与环境初始化：
```powershell
git clone https://github.com/Jeffrey1799/FirmwareLoop.git D:\Tools\FirmwareLoop
cd D:\Tools\FirmwareLoop
uv pip install -e .
```

2. 注册到 Claude Code：
```bash
claude mcp add fwloop -- "D:\Tools\FirmwareLoop\.venv\Scripts\fwloop.exe"
claude mcp add agentic-hil -- "D:\Tools\FirmwareLoop\.venv\Scripts\agentic-hil.exe" mcp-stdio
```

---

### 常用 CLI 终端命令

本项目支持名称兼容，`fwloop` 与 `firmwareloop` 完全等价：

1. 在任意单片机工程根目录下一键初始化多 Agent 规范（AGENTS.md, CLAUDE.md, GEMINI.md）与台架配置：
```bash
fwloop init
```

2. 自动检查并更新至最新版本（自动拉取最新代码并热重载依赖）：
```bash
fwloop update
```

3. 环境健康体检与依赖诊断：
```bash
fwloop doctor
```

4. 查看或生成各大 Agent MCP 注册指令：
```bash
fwloop setup
```

5. 查看当前版本：
```bash
fwloop version
```

---

### 卸载与清理

如果需要从系统中卸载 FirmwareLoop：

1. 一键卸载全局 CLI 工具（干净彻底，不残留垃圾文件）：
```bash
uv tool uninstall firmwareloop
uv tool uninstall agentic-hil
```

2. 从 Claude Code 中移除全局 MCP 注册：
```bash
claude mcp remove --scope user fwloop
claude mcp remove --scope user agentic-hil
```

---

### 在任意工程中纯对话开发

在你的任意单片机工程目录下启动 Agent，直接通过自然语言交互：
* “*帮我将当前单片机工程初始化为 FirmwareLoop 项目*” → Agent 自动调用 `fw_init_project` 生成 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 与 `lab/lab.yaml`
* “*帮我将当前工程设为 Keil5 编译，目标芯片是 STM32F103C8T6，串口为 COM5*” → Agent 自动调用 `fw_configure_lab`
* “*扫描已连接的 ST-LINK / J-Link 调试器*” → Agent 自动调用 `fw_scan_hardware`
* “*编译当前 Keil 工程并刷入板子，复位后读取串口输出*” → Agent 自动闭环调用 `fw_build`、`fw_flash`、`fw_reset`

---

## 特性

- **多 Agent 规范体系**：自动生成 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 与 `skills/firmwareloop/SKILL.md`，支持主流 Agent 无缝协同
- **Build 适配**：自动探测 Keil (UV4.exe) / CMake / Make / IAR / PlatformIO 等已有构建系统，只做包装不重造；输出结构化 `firmware-build-result/v1`（含 file/line/col 诊断）
- **pytest HIL**：12 项开箱测试（boot / UART / 协议 / 电源 / PWM / 逻辑分析），无硬件自动 skip，产物 JUnit + `firmware-hil-result/v1` + evidence
- **逻辑分析**：`capture → decode → assert` 全链路（I2C / SPI / UART），Saleae MCP 或 sigrok fallback
- **仪器层**：PyVISA/SCPI，每一次写入都受 `lab/limits.yaml` 安全限制保护，超限返回 `SAFETY_LIMIT`（`raw_scpi` 刻意未实现）
- **硬件门（Agentic HIL）**：probe → 身份校验 → 动作；目标不符立即 STOP；CAN TX 默认需人工授权；Mass Erase / OTP / RDP 等永久禁止
- **仿真模式**：无硬件也能完整验收——模拟 DUT 是真实编译产物（stdio 即 UART），仪器/逻辑分析有确定性 simulator 后端
- **审计闭环**：每次运行保存 run_id / git commit / modified files / artifact sha256 / uart.log / measurements / 报告

---

## 与同类项目定位

| | FirmwareLoop | pytest-embedded | PlatformIO Test | Labgrid |
|---|---|---|---|---|
| 编排主体 | AI Agent | pytest | pytest | 资源调度 |
| 测量证据 | 逻辑分析 + VISA 仪器 | 串口/日志 | 基础 | 弱 |
| 安全策略 | limits.yaml + 权限模型 | 无 | 无 | 弱 |
| 迭代闭环 | build→测→改→重测（<=3 次） | 无 | 部分 | 无 |

---

## 目录结构

```
├── tools/            fw_mcp_server / setup-agent-mcp / doctor / build / test /
│                     flash / reset / can / logic_* / instrument_cli / acceptance-scenario
├── tests/            unit/ (mcp_server) / hil/ / plans/ / safety/ / backend/
├── lab/              lab.example.yaml / limits.example.yaml / protocol-decode.yaml
├── test-plans/       smoke.yaml / real-smoke.yaml / regression.yaml
├── demo-firmware/    示例固件（CMake；宿主编译模拟 MCU，闭环验证载体）
├── demo-make/        示例固件（Make；构建测试载体）
├── docs/             DEPENDENCY_MATRIX / REUSE_PLAN / V0.0.2_GAP_VERIFICATION
├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.0.10)
├── .mcp.example.json 双层 MCP 配置模板（firmwareloop + agentic-hil）
├── AGENTS.md         通用智能体规范（Antigravity / Qoder / Cursor 等）
├── CLAUDE.md         Claude Code CLI 指南
├── GEMINI.md         Antigravity / Gemini CLI 指南
└── AI_DEV_GUIDE.md   AGENT 强制规则
```

---

## 能力验证状态（v0.0.10）

> 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
> `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`

| 能力 | 状态 |
|---|---|
| 双层 MCP 服务（13 个工作流与硬件工具） | Implemented + Protocol Validated（31/31 测试通过） |
| 一键多 Agent 脚手架（fwloop init / fw_init_project） | Implemented + Multi-Agent Validated |
| 自定义/私有调试工具接入 Skill（fwloop-adapter） | Implemented + Multi-Skill Validated |
| 一键终端更新（fwloop update） | Implemented + Auto-updater Validated |
| uvx 免克隆即时运行（Zero-Clone Mode） | Implemented + PEP 517/621 Validated |
| Build：keil (UV4.exe) / cmake / make / platformio / iar / zephyr / esp-idf | Implemented + Multi-backend Validated |
| pytest HIL（12 项，simulator） | Implemented + Simulator Validated |
| pytest HIL（real UART） | Implemented（Agentic HIL 插件已就绪）-> Real Hardware Validated 待 DUT |
| Agentic HIL MCP（42 硬件工具） | Implemented + discovery 验证 -> 真机待 DUT |
| 逻辑分析 capture/decode/assert（I2C/SPI/UART） | Simulator Validated -> Real Hardware Validated 待 LA |
| VISA 仪器（simulator） | Simulator Validated -> Real Hardware Validated 待仪器 |
| Safety Policy（limits.yaml） | Implemented（simulator 校验）-> 外置权威配置 |
| 自动修复闭环（M6 载体） | Simulator Validated -> Real Hardware Validated 待 DUT |

---

## 接入真实硬件

1. `Copy-Item lab\lab.example.yaml lab\lab.yaml`，填入 **COM 口 / 目标身份 / 探针序列号 / 仪器 resource**（真实值永不入库）
2. `agentic-hil adopt-hardware` 载入探针（CLI 已含于 venv）
3. `.\tools\doctor.ps1 -Json` 复核
4. `probe_target` 确认目标身份后，`.\tools\acceptance-scenario.ps1 -Hardware agentic-hil -Json`

---

## 贡献

见 [CONTRIBUTING.md](CONTRIBUTING.md)。版本记录见 [CHANGELOG.md](CHANGELOG.md)，安全相关见 [SECURITY.md](SECURITY.md)。

---

## License

[MIT](LICENSE) © Jeffrey1799。第三方组件（Agentic HIL / Logic 2 / PyVISA / pytest / CMake / Ninja / MinGW）归各自作者所有；本项目只做薄适配层。
