# bmgr-toolchain-flow

**Repository Path**: genvex/bmgr-toolchain-flow

## Basic Information

- **Project Name**: bmgr-toolchain-flow
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-04
- **Last Updated**: 2026-07-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BMGR 工具链工作流 — 从 ESP-Claw YAML 到一键编译

## 概述

本仓库封装了一套完整的嵌入式板卡编译工作流：

```
ESP-Claw 板卡 YAML → BMGR 8/8 步配置 → idf.py build → .bin 固件
```

这套方法的核心思想：**用乐鑫官方工具链替代手动 BSP 维护**。你只需要提供板卡的 YAML 描述文件，工具链自动生成引脚配置、设备初始化代码、SDK 配置，然后编译出固件。

## 工作流全景

```
┌──────────────────────────────────────────────────────────┐
│  数据源                                                    │
│  ESP-Claw 仓库 (31板)  +  板卡基因总库 (168板)            │
│         │                                                  │
│         ▼                                                  │
│  选取目标板卡 → 复制 YAML 到项目                           │
│         │                                                  │
│         ▼                                                  │
│  Step 1: 创建 IDF 项目 + 添加 BMGR 依赖                   │
│  Step 2: 复制 managed_components (网络离线时)             │
│  Step 3: 放置板卡 YAML 数据                                │
│  Step 4: 添加 setup_device.c (按需)                       │
│  Step 5: idf.py bmgr -b BOARD_NAME  (8步配置)             │
│  Step 6: idf.py build  (编译固件)                         │
│  Step 7: idf.py flash monitor (刷机验证)                  │
└──────────────────────────────────────────────────────────┘
```

## 前置条件

| 工具 | 版本要求 | 获取方式 |
|------|---------|---------|
| ESP-IDF | ≥ 5.5 | `git clone https://github.com/espressif/esp-idf.git` |
| Python | ≥ 3.10 | IDF 自带 |
| BMGR 组件 | ≥ 0.6 | `idf.py add-dependency "espressif/esp_board_manager^0.6"` |

## 快速开始（5 分钟编译一块板）

### 第 1 步：提取板卡 YAML

从 ESP-Claw 仓库获取官方板卡数据：

```bash
git clone https://github.com/espressif/esp-claw.git
# 板卡 YAML 位于 application/edge_agent/boards/ 目录
ls esp-claw/application/edge_agent/boards/
# 选取一块板，例如 DFRobot K10
cp -r esp-claw/application/edge_agent/boards/dfrobot_k10 /tmp/my_board/
```

**支持的板卡列表（31 块，来自 ESP-Claw）：**

| 板卡名 | 芯片 | 厂商 | 关键设备 |
|--------|------|------|---------|
| esp_box_3 | ESP32-S3 | Espressif | ES8311+ES7210+ILI9341+GT911 |
| m5stack_cores3 | ESP32-S3 | M5Stack | AXP2101+ES8311+ILI9341 |
| m5stack_tab5 | ESP32-P4 | Espressif | ES8388+ES7210+ILI9881C(MIPI)+GT911 |
| dfrobot_k10 | ESP32-S3 | DFRobot | TCA9555+ES7243E+ILI9341+GC2145 |
| lilygo_t_display_s3 | ESP32-S3 | LilyGO | ST7789+FT6336G |
| waveshare_esp32_p4_nano | ESP32-P4 | Waveshare | ES8311+SD卡 |
| ... 共 31 块 | | | |

### 第 2 步：搭建编译环境

```bash
. ~/esp/esp-idf/export.sh
cd /tmp
idf.py create-project my_build && cd my_build
idf.py add-dependency "espressif/esp_board_manager^0.6"
```

### 第 3 步：处理网络依赖（墙内环境）

如果 `components.espressif.com` 无法访问，需要从已有的编译环境复制组件：

```bash
# 从已成功编译的项目复制
cp -r /path/to/working_project/managed_components/espressif__esp_board_manager \
      managed_components/
cp -r /path/to/working_project/managed_components/espressif__esp_boards \
      managed_components/
```

### 第 4 步：放置板卡 YAML

```bash
mkdir -p managed_components/espressif__esp_boards/boards
cp -r /path/to/board_data/YOUR_BOARD \
      managed_components/espressif__esp_boards/boards/
```

### 第 5 步：处理设备工厂函数

**为什么需要 setup_device.c？**

BMGR 需要板卡为某些设备提供工厂函数（factory entry）。当对应的驱动组件未安装时，需要提供占位函数。

**什么时候需要：**

| 设备类型 | 工厂函数名 | 触发条件 |
|---------|-----------|---------|
| display_lcd (SPI) | `lcd_panel_factory_entry_t` | 设备有 display_lcd |
| gpio_expander | `io_expander_factory_entry_t` | 设备有 gpio_expander |
| lcd_touch (I2C) | `lcd_touch_factory_entry_t` | 设备有 lcd_touch |
| audio_codec (I2C) | `codec_factory_entry_t` | 设备有 audio_codec |
| display_lcd (MIPI DSI) | `lcd_dsi_panel_factory_entry_t` | 设备有 dsi_display |

**模板：**

```bash
cp templates/setup_device.c \
   managed_components/espressif__esp_boards/boards/YOUR_BOARD/
```

### 第 6 步：编译

```bash
# BMGR 8 步配置
ESP_BMGR_ASSIST_PREFLIGHT=0 idf.py bmgr -b YOUR_BOARD

# 编译固件
ESP_BMGR_ASSIST_PREFLIGHT=0 idf.py build
```

### 第 7 步：刷机

```bash
idf.py -p /dev/ttyACM0 flash monitor
```

## 一键编译脚本

```bash
# 单板编译
./scripts/compile_board.sh -b dfrobot_k10 -p /path/to/project

# 批量编译（全部 31 块 ESP-Claw 板卡）
./scripts/batch_compile.sh
```

## 固件产物说明

编译得到的 `.bin` 固件包含三层内容：

| 层级 | 内容 | 大小 | 说明 |
|------|------|------|------|
| BMGR 生成代码 | I2C/I2S/GPIO 配置结构体 | ~15KB | YAML 数据的 C 翻译 |
| BMGR 框架 | 外设初始化、设备链表 | ~50KB | 通用初始化逻辑 |
| ESP-IDF 基础库 | FreeRTOS、驱动、WiFi | ~100KB | 标准 IDF 组件 |

**DFRobot K10 已集成（其余板卡仍为占位版）：**
- ✅ I2C 总线初始化（引脚已配置）
- ✅ I2S 总线初始化（时钟已配置）
- ✅ GPIO 初始化（PA 使能等）
- ✅ **ILI9341 显示驱动**（`esp_lcd_ili9341` 组件 + 工厂函数）
- ✅ **ES7243E 音频 ADC + NS4168 音频 DAC**（`esp_codec_dev` 组件 + I2S 配置）
- ✅ TCA9555 GPIO 扩展器（I2C 地址 0x20）
- ⚠️ WS2812 LED 灯带（组件已加，init_skip 未启用）
- 🔲 GC2145 摄像头（组件已下载，应用层未调用）

**其他板卡当前能做什么（占位版）：**
- ✅ I2C 总线初始化（引脚已配置）
- ✅ I2S 总线初始化（时钟已配置）
- ✅ GPIO 初始化（PA 使能等）
- ❌ 显示驱动（需要 `esp_lcd_ili9341` 等组件）
- ❌ 音频驱动（需要 `esp_codec_dev` 组件）
- ❌ 触摸驱动（需要 `esp_lcd_touch` 组件）

**完整功能需要：**
1. 安装缺失的驱动组件：`idf.py add-dependency "espressif/esp_lcd_ili9341^1"`
2. 替换 `setup_device.c` 的占位函数为实际驱动调用
3. 编写应用层 `main.c`

## 项目结构

```
bmgr-toolchain-flow/
├── README.md                    # 本文件
├── docs/
│   ├── BMGR_8步编译流程.md       # 完整操作手册
│   ├── 公众号文章_BMGR工具链方法.md  # 背景故事
│   └── bmgr_flowchart.html      # 流程图（浏览器打开）
├── scripts/
│   ├── compile_board.sh         # 单板编译脚本
│   └── batch_compile.sh         # 批量编译脚本
├── templates/
│   └── setup_device.c           # 工厂函数模板
├── boards/                      # 板卡数据索引
│   └── ESP-CLAW_BOARDS.md       # 31板列表+芯片+设备
├── SKILL.md                     # Hermes Agent skill
└── .gitignore
```

## 已验证的板卡

| 板卡 | 芯片 | BMGR | 编译 | 固件大小 | 屏驱 | 音频 | 备注 |
|------|------|------|------|---------|------|------|------|
| anyboard | ESP32-S3 | ✅ 8/8 | ✅ | 461KB | - | - | 虚拟板，测试用 |
| **dfrobot_k10** | **ESP32-S3** | **✅ 8/8** | **✅** | **~445KB** | **✅ ILI9341** | **✅ ES7243E+NS4168** | **全驱动集成** |
| **waveshare_ESP32_S3_RLCD_4_2** | **ESP32-S3** | **✅ 8/8** | **✅** | **~208KB** | **✅ 反射式黑白** | **✅ ES8311+ES7210** | **全驱动集成** |
| m5stack_tab5 | ESP32-P4 | ✅ 8/8 | ✅ | 668KB | - | - | 未加驱动 |
| t_deck (our data) | ESP32-S3 | ✅ 8/8 | ✅ | 462KB | - | - | 未加驱动 |

## 一键编译（带驱动）

```bash
# DFRobot K10 — 包含完整屏幕+音频驱动
cd template_project
./compile_k10.sh

# Waveshare ESP32-S3-RLCD-4.2 — 反射式黑白屏 + 音频驱动
cd template_project
./compile_waveshare_rlcd.sh
```

## 常见问题

### Q: `idf.py bmgr -b` 报错 "Board not found"

**原因：** 板卡名只能包含字母、数字和下划线。连字符 `-` 不被支持。

**解决：** 将板卡目录名从 `t-deck` 改为 `t_deck`，并更新 `board_info.yaml` 中的 `board:` 字段。

### Q: CMake 报 403 Forbidden 下载组件

**原因：** 网络无法访问乐鑫组件仓库。

**解决：** 从已编译的项目复制 `managed_components/` 目录。

### Q: 链接错误 `undefined reference to xxx_factory_entry_t`

**原因：** 缺少 `setup_device.c` 或工厂函数名不正确。

**解决：** 根据错误信息中的函数名，在 `setup_device.c` 中添加对应的占位函数。

### Q: 需要分区表

**原因：** 板卡需要特定大小（16MB/8MB/4MB）的分区表文件。

**解决：** 根据 Flash 大小创建 `partitions_16MB.csv`（或相应大小）。

## 参考

- [ESP-Claw 仓库](https://github.com/espressif/esp-claw) — 31 块板卡 YAML 数据
- [ESP Board Manager 文档](https://docs.espressif.com/projects/esp-board-manager/) — BMGR 官方文档
- [ESP-IDF 编程指南](https://docs.espressif.com/projects/esp-idf/) — IDF 使用手册