kevincoooool/ksdiy_c5_sdio_flasher

Readme

# ksdiy_c5_sdio_flasher

ESP32-P4 通过 **SDIO** 给板载 **ESP32-C5** 烧录 ESP-Hosted 从机固件。

- 空白 C5：首次启动自动 serial-flash merge-bin  
- 已烧录且版本 ≥ 目标：跳过烧录，**保持 ESP-Hosted 连接**（不影响后续 WiFi）  
- NVS 标记：避免重复全量烧录  

## 快速开始（示例工程）

```powershell
cd components/ksdiy_c5_sdio_flasher/examples/c5_flasher
powershell -File copy_c5_firmware.ps1
idf.py set-target esp32p4
idf.py build flash monitor
```

详见 [examples/c5_flasher/README.md](examples/c5_flasher/README.md)。

## 集成到现有工程

### 1. 分区表

```csv
c5_fw,    data, 0x82,    ,  2M,
```

### 2. 打包固件

`main/CMakeLists.txt`：

```cmake
littlefs_create_partition_image(c5_fw ../c5_fw FLASH_IN_PROJECT)
```

将 C5 merge-bin 放入 `c5_fw/ESP32C5_V2.12.13_0X0.bin`（esp-hosted 从机 `idf.py merge-bin`）。

### 3. 组件依赖

`main/idf_component.yml`：

```yaml
kevincoooool/ksdiy_c5_sdio_flasher:
  version: "^1.1.0"
  override_path: "../../components/ksdiy_c5_sdio_flasher"
```

`main/CMakeLists.txt`：`REQUIRES ksdiy_c5_sdio_flasher`

### 4. sdkconfig

```ini
CONFIG_SLAVE_IDF_TARGET_ESP32C5=y
CONFIG_ESP_HOSTED_CP_TARGET_ESP32C5=y
CONFIG_SERIAL_FLASHER_PORT_SDIO=y
```

引脚：`Component config → KSDIY C5 SDIO Flasher`

| 信号 | 默认 GPIO | 说明 |
|------|-----------|------|
| RESET | 54 | C5 EN，高电平运行 |
| BOOT | 2 | 下载模式 strap |
| SDIO D0–D3 | 14–17 | 4-bit 数据 |
| CLK / CMD | 18 / 19 | 时钟 / 命令 |

### 5. 代码

```c
#include "ksdiy_c5_sdio_flasher.h"

void app_main(void)
{
    nvs_flash_init();
    // P4C5：GPIO20 升压、电源时序 ...

    // 最简：menuconfig 默认 + NVS 标记
    ESP_ERROR_CHECK(ksdiy_c5_sdio_flasher_ensure());

    // 带进度回调
    ksdiy_c5_sdio_flasher_config_t cfg;
    ksdiy_c5_sdio_flasher_config_defaults(&cfg);
    cfg.on_progress = my_progress_cb;
    cfg.on_log = my_log_cb;
    ksdiy_c5_sdio_flasher_ensure_with_opts(&(ksdiy_c5_sdio_flasher_ensure_opts_t){
        .config = &cfg,
    });

    // 之后可 esp_wifi_init() / LVGL 等
}
```

**调用顺序：** 必须在 `esp_wifi_init()`、LVGL、其他 SDIO 用户 **之前** 调用 `ensure()`。

## API 参考

| 函数 | 说明 |
|------|------|
| `ksdiy_c5_sdio_flasher_config_defaults()` | 填充 menuconfig 默认配置 |
| `ksdiy_c5_sdio_flasher_apply_hw()` | 应用引脚到 flasher 底层 |
| `ksdiy_c5_sdio_flasher_run()` | 执行一次烧录/版本检查 |
| `ksdiy_c5_sdio_flasher_ensure()` | 便捷封装（NVS + 默认配置） |
| `ksdiy_c5_sdio_flasher_ensure_with_opts()` | 可指定 NVS 命名空间与 config |
| `ksdiy_c5_sdio_flasher_is_marked_done()` | 查询 NVS 是否已标记完成 |
| `ksdiy_c5_sdio_flasher_clear_mark()` | 清除 NVS 标记（开发/重烧） |
| `ksdiy_c5_sdio_flasher_default_firmware_path()` | 默认 VFS 固件路径 |
| `ksdiy_c5_sdio_flasher_partition_label()` | LittleFS 分区 label |

## 工作流程

```
app_main
  └─ ensure()
       ├─ skip_if_version_ok?
       │    ├─ Hosted 连接 C5 → 读 FW 版本
       │    ├─ 版本 OK → 保持 Hosted，return（~3s）
       │    └─ 需升级/无固件 → release Hosted → SDIO serial flash
       ├─ 读 LittleFS merge-bin → 写入 C5
       ├─ 复位 C5 → Hosted 验证
       └─ NVS mark done
```

## 故障排查

| 现象 | 原因 / 处理 |
|------|-------------|
| `Read file failed` | `c5_fw/` 未放入 merge-bin 或未打包进 flash |
| `SDIO init failed` | 未开启 `CONFIG_SERIAL_FLASHER_PORT_SDIO` |
| `GPIO54 conflict` | 旧版在 skip 前 pulse reset；请用 ≥1.1.0 |
| `esp_wifi_init failed` | ensure 在 WiFi 之后调用，或 Hosted 被错误 deinit |
| `Need full C5 image` | 使用了 app-only bin，需 merge-bin |

## 依赖

- `espressif/esp-serial-flasher` (SDIO)
- `joltwallet/littlefs`
- `espressif/esp_hosted` / `espressif/esp_wifi_remote`

## 上传到 ESP 组件注册库

```bash
cd components/ksdiy_c5_sdio_flasher
compote registry login
compote component upload --namespace kevincoooool --name ksdiy_c5_sdio_flasher --version 1.1.0
```

注册库页面：<https://components.espressif.com/components/kevincoooool/ksdiy_c5_sdio_flasher>

**发布前请勿提交：** `build/`、`sdkconfig`、`dependencies.lock`、`c5_fw/*.bin`（见 `.gitignore`）。

## 许可

Apache-2.0 · [Kevincoooool](https://github.com/kevincoooool/ESP32P4_KSDIY)