# FlashKey **Repository Path**: jdi058/FlashKey ## Basic Information - **Project Name**: FlashKey - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-25 - **Last Updated**: 2026-08-25 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

FlashKey FK-01

> FlashKey FK-01 — 专为 AI Agent 设计的嵌入式 USB 烧录调试工具。 [![English|README](https://img.shields.io/badge/English-README-blue)](README.md) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![build](https://github.com/Ai-Thinker-Open/FlashKey/actions/workflows/build.yml/badge.svg)](https://github.com/Ai-Thinker-Open/FlashKey/actions/workflows/build.yml) --- ## 项目简介 FlashKey FK-01 是安信可（Ai-Thinker）推出的嵌入式 USB 烧录调试器，从设计之初就面向 **AI Agent**：AI 无需手动按键，即可通过 USB 控制 BOOT/RST 引脚与电源，自动完成 Ai-WB2（BL602）、Ai-M62（BL616/BL618）等模组的固件烧录与调试。 > **J-Link 是给人类用的调试器，FlashKey 是给 AI Agent 用的烧录员。** - 🔌 **USB CDC 控制通道** — BOOT / RST 引脚控制、5V / 3.3V 电源开关 - ⚡ **UART 桥接** — USART2 ↔ USB CDC 透传，最高 2Mbps，满足烧录波特率 - 🔐 **Challenge-Response 认证** — 插上即自动 HELLO 握手，无需手动认证 - 🤖 **MCP 支持** — 通过 [`flashkey-mcp`](flashkey-mcp/) 让 Cline、Hermes Agent、OpenCode、Codex 等 AI 工具直接调用 ### 双芯片架构 FK-01 内置 WCH-LinkE 调试器（CH32V305）+ CH32V203 控制芯片： | 芯片 | 职责 | | --- | --- | | WCH-LinkE（CH32V305） | DAPLink 调试器（SWD） | | CH32V203 | 控制芯片 — 验证/认证 + USB CDC ↔ UART 桥接 + GPIO / 电源控制 | > 源码仓库：[Ai-Thinker-Open/FlashKey](https://github.com/Ai-Thinker-Open/FlashKey) --- ## 安装 / 编译 ### 克隆仓库（含子模块） ```bash git clone --recurse-submodules git@github.com:Ai-Thinker-Open/FlashKey.git cd FlashKey ``` 如果已经克隆但未拉取子模块： ```bash git submodule update --init --recursive ``` ### 工具链 RISC-V 工具链（xPack RISC-V GCC 12.5.0）以子模块方式固定版本： ```bash tools/toolchain/bin/riscv-none-elf-gcc --version ``` 如果使用其他工具链路径或前缀，请修改 `firmware/ch32v203/CMakeLists.txt` 顶部的 `TOOLCHAIN_FOLDER` / `TOOLCHAIN_PREFIX`。 ### 编译固件 ```bash cd firmware/ch32v203 cmake -B build -G "Unix Makefiles" cmake --build build -j$(nproc) ``` 产物（`flashkey_ch32v203.elf` / `.hex` / `.map`）生成在 `build/` 下，已通过 .gitignore 排除，不入库。 ### MCP 插件（给 AI 用） ```bash pip install flashkey-mcp ``` 完整的安装与 AI 工具配置说明见 [`flashkey-mcp`](flashkey-mcp/) 子模块 README。 --- ## 使用说明 ### 1. Windows 驱动（可选） 安装 `driver/windows/flashkey-fk01.inf`，让设备在设备管理器中显示为 **“FlashKey FK-01”**： ```powershell pnputil /add-driver driver/windows/flashkey-fk01.inf ``` 设备标识：VID `1A86` / PID `FE0D`（USB CDC ACM）。 ### 2. 烧录 FK-01 自身固件（CH32V203 #2） 将 FK-01 自带的 WCH-LinkE SWD 接口接到 CH32V203 #2，使用 OpenOCD： ```bash cd tools openocd -f flashkey-erase-program.cfg # 全片擦除 + 烧录 + 校验 openocd -f flashkey-debug.cfg # 调试 / 复位 ``` 也可直接使用现成脚本：`tools/flash-fk01.sh`（Linux/WSL）、`tools/flash-burn.cmd`（Windows）。 ### 3. 通过 AI 工具（MCP）控制设备 flashkey-mcp 提供 `status()`、`flash()`、`enter_bootloader()`、`rst_pulse()`、`log_open()`、`firmware_check()` 等工具 — 详见 [flashkey-mcp README](flashkey-mcp/)。 ### 4. UART1 调试串口 固件启动时在 USART1（**115200 8N1**）打印启动横幅：产品名 / 版本 / 编译 commit / 密钥状态。 --- ## 示例 ### 查看设备状态 ``` status() ``` 返回认证状态、固件版本、引脚状态与模组信息。 ### 一键烧录（Ai-WB2） ``` flash(firmware_path="/path/to/firmware.bin", chip="ai-wb2", flash_port="ttyACM1") ``` ### 手动引脚控制 ``` rst_pulse(50) # 50ms 复位脉冲 boot_set(true) # BOOT 拉高 v5v_set(true) # 开启 5V 电源 ``` --- ## 工作原理 ``` ┌──────────────────────────────────────────┐ │ USB Type-C │ └────────────────┬─────────────────────────┘ │ ┌────┴────┐ │ FE1.1s │ USB Hub (1→4) └────┬────┘ ┌───────┴────────┐ ▼ ▼ ┌────────────────┐ ┌──────────────────┐ │ CH32V305 #1 │ │ CH32V203 #2 │ │ WCH-LinkE │ │ 验证 + USB CDC │ │ DAPLink SWD │ │ GPIO + 电源控制 │ └────────────────┘ └──────────────────┘ ``` ### 仓库结构 ``` FlashKey/ ├── firmware/ │ ├── ch32v203/ # #2 控制芯片固件（USB CDC ↔ UART + GPIO） │ ├── wch-linke/ # #1 WCH-LinkE DAPLink 调试器固件 │ └── baseline/ # WCH 基线固件（参考） ├── flashkey-mcp/ # MCP 服务器插件（子模块） ├── driver/windows/ # Windows INF 驱动 ├── docs/ # 架构 / API / 开发文档 ├── tools/ # OpenOCD 配置、烧录脚本、工具链 └── LICENSE # MIT ``` ### 固件功能状态（v0.1.5） | 模块 | 状态 | 说明 | | --- | :---: | --- | | USB CDC 设备栈 | ✅ | EP1 OUT + EP2 IN（64B）+ EP3 IN 通知（8B） | | USB ↔ UART 桥接 | ✅ | USART2 DMA，256 字节环形缓冲，最高 2Mbps | | 帧协议 | ✅ | `0x7E SOF \| LEN \| CMD \| DATA \| CRC-8/MAXIM \| 0x7F EOF` | | GPIO 控制 | ✅ | PB3 BOOT / PB4 RST / PB1 5V_EN / PB0 3.3V_EN | | RST 脉冲 | ✅ | 50~250ms 精确脉宽 | | Challenge-Response 认证 | ✅ | SBOX + XOR + ROTL1，8 字节密钥，自动 HELLO | | 设备身份 | ✅ | VID 1A86 / PID FE0D，"Ai-Thinker FlashKey-FK01" | | UID 读取 / 密钥烧录 | ✅ | `GET_UID`、`SET_KEY`（Flash 持久化，v0.1.3） | | 心跳保持 | ✅ | ~6s 超时清除认证，PB11 LED 指示 | | 扩展模组桥接 | ✅ | I2C 清单轮询 + USART2 透传 | ### 文档 | 文档 | 说明 | | --- | --- | | [QUICKSTART](docs/QUICKSTART.md) | 30 秒快速入门 | | [PROJECT_OVERVIEW](docs/PROJECT_OVERVIEW.md) | 项目总览与硬件 | | [ARCHITECTURE](docs/ARCHITECTURE.md) | 架构设计 | | [DEVELOPMENT_GUIDE](docs/DEVELOPMENT_GUIDE.md) | 开发环境与流程 | | [API_REFERENCE](docs/API_REFERENCE.md) | API 参考 | | [CONTRIBUTING](docs/CONTRIBUTING.md) | 贡献指南 | --- ## 常见问题 / 故障排查 **设备无法识别？** - Windows：安装 `driver/windows/flashkey-fk01.inf` 后重新插拔。 - 用 `lsusb`（Linux）或设备管理器（Windows）确认设备标识为 `1A86:FE0D`。 **WSL 中看不到设备？** 需要先把 USB 设备附加到 WSL：`usbip attach -r 127.0.0.1 -b `（Windows 端：`usbipd.exe attach --wsl --busid `）。 **如何确认当前固件版本？** 通过 MCP 调用 `get_version()`，或查看 USART1 启动横幅（115200 8N1）。 **烧录报读保护/写保护错误？** Windows 下可用 WCH-LinkUtility 解锁；flashkey-mcp 的 `firmware_flash()` 也会自动重试解锁后烧录。 --- ## 贡献指南 欢迎提交 Issue 和 PR： 1. Fork 本仓库并创建功能分支； 2. 提交信息遵循 Conventional Commits（`feat:`、`fix:`、`docs:` 等）； 3. 行为变更时同步更新 `docs/`； 4. 在 PR 中说明目的与验证方式。 详见 [CONTRIBUTING.md](docs/CONTRIBUTING.md)。 --- ## 许可证 [MIT](LICENSE) © 2026 Ai-Thinker Open