# k10-bmgr-full

**Repository Path**: genvex/k10-bmgr-full

## Basic Information

- **Project Name**: k10-bmgr-full
- **Description**: dianjixz/lvgl@85aa60d1
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-07-05
- **Last Updated**: 2026-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# K10 BMGR Full — DFRobot K10 完整固件

基于乐鑫官方 **BMGR (Board Manager)** 工具链构建的 DFRobot K10（行空板）ESP-IDF 项目。

集成 BMGR 硬件初始化 + Brookesia UI 框架 + **10 个内置应用**（时钟/表盘/电子宠物/格言/硬件信息/摄像头/传感器/频谱/水平仪/音乐）。

## 硬件

| 设备 | 芯片 | 接口 |
|:-----|:-----|:-----|
| 主控 | ESP32-S3 | 240 MHz |
| Flash | 16 MB | QIO @ 80 MHz |
| PSRAM | 8 MB | Octal @ 80 MHz |
| GPIO 扩展器 | TCA9555 | I2C (0x20) |
| 麦克风 ADC | ES7243E | I2S0 RX TDM + I2C (0x23) |
| 功放 | NS4168 | I2S0 TX 标准模式（Class-D） |
| 摄像头 | GC2145 | DVP 8-bit |
| LCD | ILI9341 320×240 | SPI3 |
| LED 灯带 | WS2812 ×3 | RMT (GPIO46) |
| SD 卡槽 | — | SPI2 |
| 温湿度 | AHT20 | I2C (0x38) |
| 光照 | LTR329 | I2C (0x29) |
| 加速度计 | SC7A20H | I2C (0x1E) |

> 音频由 `main/audio/k10_audio.cpp` 直管 I2S0（NS4168 功放 + ES7243E 麦克风），不由 BMGR 管理。

---

## 编译指南

### 环境要求

| 组件 | 版本 |
|------|------|
| ESP-IDF | **v6.0.2**（路径示例 `E:/idf_home/.espressif/v6.0.2/esp-idf`） |
| xtensa-esp-elf | esp-15.2.0_20251204 |
| Python venv | `C:/Espressif/tools/python/v6.0.2/venv`（含 IDF 依赖） |
| IDF_TOOLS_PATH | `C:/Espressif/tools` |

### ⚠️ 必须先跑 bmgr（关键）

`components/gen_bmgr_codes/` 是 **gitignore** 的板级代码，由 `idf.py bmgr` 生成。
**每次全新检出/清空后，必须先执行 bmgr 步骤**，否则 `dev_display_lcd.h` 等头文件无法解析。

### 编译步骤（Windows / 通用）

```bash
# 设置 IDF 环境（以你的安装为准）
set IDF_PATH=E:/idf_home/.espressif/v6.0.2/esp-idf
set IDF_TOOLS_PATH=C:/Espressif/tools
set IDF_PYTHON_ENV_PATH=C:/Espressif/tools/python/v6.0.2/venv

# Step 1: 生成 BMGR 板卡代码（每次 clean 后必须）
python run_idf.py bmgr -c boards -b dfrobot_k10

# Step 2: 编译
python run_idf.py build
```

### 编译步骤（Linux / Jetson）

```bash
export IDF_PATH=.../esp-idf
source $IDF_PYTHON_ENV_PATH/bin/activate
idf.py bmgr -c boards -b dfrobot_k10
idf.py build
```

> 也可直接运行仓库内的 `compile_k10_full.sh`（自动执行 bmgr + build）。

### 清除重来

```bash
rm -rf build managed_components components/gen_bmgr_codes sdkconfig sdkconfig.old
# 然后重复上面的 Step 1/2
```

### 编译验证

成功时输出：

```
k10_complete.bin ...  Project build complete.
```

构建产物：`build/k10_complete.bin`（约 2.1 MB，factory 分区 14 MB 富余 77%）。

### 烧录

```bash
python -m esptool --chip esp32s3 -b 460800 \
  --before default_reset --after hard_reset \
  write_flash --flash_mode qio --flash_size 16MB --flash_freq 80m \
  0x0 build/bootloader/bootloader.bin \
  0x8000 build/partition_table/partition-table.bin \
  0x10000 build/k10_complete.bin
```

---

## WiFi 配置

WiFi 账号密码填写在 `sdkconfig.defaults`：

```
CONFIG_K10_WIFI_SSID="你的WiFi名称"
CONFIG_K10_WIFI_PASS="你的WiFi密码"
```

改完编译即生效；也可在运行后 `menuconfig` 修改。

---

## 配置说明

所有配置仅通过 **sdkconfig** 管理，不修改任何第三方组件。

### 配置分层

| 层级 | 文件 | 内容 |
|------|------|------|
| 项目级 | `sdkconfig.defaults` | **必须条件固化**：分区表/Flash/PSRAM/WDT/Camera/LVGL 字体/WiFi，plain `idf.py build` 直接生效 |
| 板卡级 | `boards/dfrobot/dfrobot_k10/sdkconfig.defaults.board` | CPU/Flash/PSRAM/Camera/USB + 字体 + 分区表（BMGR 流程引用） |
| 应用级 | `sdkconfig.dfrobot_k10` | WiFi/天气等 K10 特有配置记录 |
| 生成级 | `components/gen_bmgr_codes/` | `idf.py bmgr` 生成的板级代码 + `board_manager.defaults`（gitignore，编译前必须先生成） |
| 运行时 | `sdkconfig` | 实际生效配置（由 sdkconfig.defaults + bmgr 合并生成） |

### 分区表

`partitions.csv` 自定义分区表，factory = 14 MB（0xE00000）：

```csv
# Name,   Type, SubType, Offset,  Size,      Flags
nvs,      data, nvs,     0x9000,  0x4000,
phy_init, data, phy,     0xf000,  0x1000,
factory,  app,  factory, 0x10000, 0xE00000,
```

> ⚠️ BMGR Step 7 会重置分区表为 SINGLE_APP（factory=1MB），由 `sdkconfig.defaults`/board defaults 自动覆盖。

### 字体配置（必需，勿删）

| 配置 | 用途 |
|------|------|
| `CONFIG_LV_FONT_FMT_TXT_LARGE=y` | xiaozhi-fonts 必需（FONT_PUHUI 等 bitmap_index > 1MB），否则 "Too large font or glyphs" |
| `CONFIG_LV_USE_IMGFONT=y` | xiaozhi-fonts 必需（emoji 经 `lv_imgfont_create()` 加载），否则 "implicit declaration" |
| `CONFIG_LV_FONT_MONTSERRAT_24/36/48=y` | watch_face 表盘应用必需，否则链接失败 |
| `CONFIG_LV_FONT_UNSCII_16=y` | Buddy ASCII-art sprite 等宽字体 |

---

## 内置应用

项目使用 Brookesia UI 框架，共 **10 个应用**，通过按键 A/B 翻页切换。

| # | 应用 | 功能 |
|---|------|------|
| 0 | **Clock** | 数字时钟，含天气信息（城市代码由 IP 定位确定，兜底上海 101020100） |
| 1 | **WatchFace** | 表盘，三种样式：经典/大字体/数字面板（Montserrat 24/36/48） |
| 2 | **Buddy** | 电子宠物，ASCII-art sprite 动画，按键 A 喂食/互动 |
| 3 | **Quote** | 每日格言/名人名言，随机显示 |
| 4 | **Hardware** | 硬件信息仪表盘：PSRAM 使用率、FreeRTOS tick、CPU 频率等 |
| 5 | **Camera** | 摄像头预览（GC2145 DVP，实时取景） |
| 6 | **Sensor** | 传感器读数：AHT20 温湿度、LTR329 光照、SC7A20H 加速度（超时 15s 显示过期） |
| 7 | **Spectrum** | 音频频谱可视化（I2S0 读取音频数据绘制实时频谱条） |
| 8 | **Accel** | 水平仪（SC7A20H 三轴倾斜指示） |
| 9 | **Music** | 音乐播放器（SD 卡 MP3，开机后台预扫描，按键控制播放/暂停/切歌） |

### 启动流程

```
app_main()
  ├─ NVS 初始化
  ├─ BMGR 硬件初始化（TCA9555/GC2145/ILI9341 等）
  ├─ 传感器初始化 + 启动 sensor_task（后台读取）
  ├─ LVGL 显示初始化
  ├─ SD 卡挂载（无卡则跳过）
  ├─ MP3 后台预扫描（不阻塞 UI）
  ├─ WiFi 初始化 + SNTP 时钟同步
  ├─ 输入初始化（A/B 按键 + TCA9555 扩展器）
  ├─ 注册 10 个 App 到 Brookesia Kernel
  ├─ 启动 Kernel（LVGL 渲染）
  └─ 主循环任务（50ms 轮询按键 + globalTick + render）
```

---

## 实用操作说明

### 按键操作

| 按键 | 物理位置 | 短按（松手时触发） | 长按（>1000ms） |
|------|----------|-------------------|----------------|
| **A**（左） | TCA9555 pin 2 | 上一页 / 当前 App 消费（如音乐切歌） | 强制上一页（绕过 App 拦截） |
| **B**（右） | TCA9555 pin 12 | 下一页 / 当前 App 消费（如音乐切歌） | 强制下一页（绕过 App 拦截） |

> 按键事件通过 TCA9555 GPIO 扩展器读取，中断回调入队（互斥锁保护），主循环（50ms）出队处理。

### 音乐 App

| 操作 | 效果 |
|------|------|
| 进入 App | 显示 SD 卡 MP3 列表（开机已后台预扫描） |
| 短按 A | 上一首 |
| 短按 B | 下一首 |
| 长按 A/B | 强制翻页离开 App |

### SD 卡音乐

- 支持 FAT32 格式的 SD 卡，挂载点 `/sdcard`
- 开机后台异步扫描 MP3，不阻塞 UI 启动
- 扫描完成后，进入 Music App 即可直接播放
- 无卡时优雅跳过，不报错

### 天气功能

- Clock App 显示实时天气
- 城市代码根据 IP 定位自动确定
- 定位失败时兜底为上海（101020100）
- 需要 WiFi 连接，SNTP 同步时间后生效

### 传感器数据

- **AHT20**：温度/湿度，每 2 秒刷新
- **LTR329**：环境光（Lux），每 2 秒刷新
- **SC7A20H**：三轴加速度，每 2 秒刷新
- 数据超时 15 秒显示为"过期"（传感器故障或 I2C 冲突时）

---

## 项目结构

```
k10-bmgr-full/
├── CMakeLists.txt                        # IDF 项目入口
├── partitions.csv                        # 自定义分区表（factory = 14 MB）
├── sdkconfig.defaults                    # 项目级必须配置固化（plain build 生效）
├── sdkconfig.dfrobot_k10                 # 应用级配置记录（WiFi/天气/字体）
├── compile_k10_full.sh                   # Linux 一键编译脚本（bmgr + build）
├── boards/dfrobot/dfrobot_k10/
│   ├── board_info.yaml                   # 板卡元信息
│   ├── board_devices.yaml                # BMGR 设备配置（6 设备）
│   ├── board_peripherals.yaml            # BMGR 外设引脚（3 总线）
│   ├── sdkconfig.defaults.board          # 板卡级硬件 + 字体 + 分区表配置
│   └── setup_device.c                    # BMGR 工厂函数 + I2C 总线捕获
├── components/gen_bmgr_codes/            # BMGR 生成的板级代码（gitignore，编译前先 bmgr）
├── managed_components/                   # 组件管理器下载的第三方组件
└── main/
    ├── CMakeLists.txt                    # main 组件构建配置
    ├── Kconfig.projbuild                 # WiFi/天气等 Kconfig
    ├── main.cpp                          # 应用入口：WiFi/LVGL/SD/App 注册/主循环
    ├── audio/
    │   └── k10_audio.h / k10_audio.cpp   # I2S0 音频驱动（直管，非 BMGR）
    ├── music/
    │   ├── k10_music.h / k10_music.cpp   # MP3 播放控制
    │   └── k10_music_fs.h / k10_music_fs.cpp  # SD 卡 MP3 文件扫描
    ├── sensors/
    │   ├── aht20.h / aht20.c             # AHT20 温湿度驱动
    │   ├── ltr3xxx.h / ltr3xxx.c         # LTR329 光照驱动
    │   ├── sc7a20h.h / sc7a20h.c         # SC7A20H 加速度计驱动
    │   └── sensor_task.h / sensor_task.c # 传感器后台读取任务
    ├── apps/
    │   ├── block_clock/                  # 数字时钟 LVGL 组件
    │   ├── buddy/                        # 电子宠物 LVGL 组件（ASCII sprite）
    │   ├── daily_quote/                  # 每日格言 LVGL 组件
    │   └── watch_face/                   # 表盘 LVGL 组件（三种样式）
    ├── brookesia/
    │   ├── core/kernel.hpp               # Brookesia 内核（App 管理/渲染/事件）
    │   ├── core/router.hpp               # 10 App 路由表
    │   ├── page_context.hpp              # 页面上下文
    │   └── apps/
    │       ├── clock_app.hpp             # 时钟应用
    │       ├── watch_face_app.hpp        # 表盘应用
    │       ├── buddy_app.hpp             # 电子宠物应用
    │       ├── quote_app.hpp             # 格言应用
    │       ├── hardware_app.hpp          # 硬件信息应用
    │       ├── camera_app.hpp            # 摄像头应用
    │       ├── sensor_app.hpp            # 传感器应用
    │       ├── spectrum_app.hpp          # 频谱可视化应用
    │       ├── accel_app.hpp             # 水平仪应用
    │       └── music_app.hpp             # 音乐播放器应用
    └── test/
        └── audio_test.h / audio_test.c   # 音频测试（默认关闭）
```

---

## 常见错误

| 错误 | 原因 | 解决 |
|------|------|------|
| `Failed to resolve component 'json'` | IDF v6.0 移除了内置 json 组件 | 用 `espressif/cjson`（见 `main/idf_component.yml`） |
| `dev_display_lcd.h: No such file or directory` | 未先执行 bmgr | 先 `idf.py bmgr -c boards -b dfrobot_k10` |
| `lv_imgfont_create: implicit declaration` | `LV_USE_IMGFONT` 未启用 | 检查 `sdkconfig.defaults` |
| `Too large font or glyphs` | `LV_FONT_FMT_TXT_LARGE` 未启用 | 检查 `sdkconfig.defaults` |
| `app partition is too small` | 分区表退化为 1 MB | 检查 `CONFIG_PARTITION_TABLE_CUSTOM=y` |
| `undefined reference to lv_font_montserrat_*` | Montserrat 字体未启用 | 检查 `sdkconfig.defaults` |
| `hex escape sequence out of range` | `\x` 后接十六进制字符（如 `\xB0C`）被贪婪解析 | 拆字符串字面量 |
| `missing initializer for member ...` | IDF v6.0 结构体新增字段 | 改为零初始化 `= {}` 后逐字段赋值 |

---

## 相关资源

- [ESP-Claw 仓库](https://github.com/espressif/esp-claw) — 硬件 YAML 数据源
- [ESP Board Manager](https://components.espressif.com/components/espressif/esp_board_manager) — BMGR 核心组件
- [LVGL](https://lvgl.io/) — GUI 库
- [xiaozhi-fonts](https://github.com/espressif/xiaozhi-fonts) — 中文字体/emoji

## License

MIT