171 lines
5.8 KiB
Markdown
171 lines
5.8 KiB
Markdown
# ESP-IDF v6.0 编译适配记录
|
||
|
||
> 日期：2026-03-31
|
||
> 目标芯片：ESP32-S3
|
||
> ESP-IDF 版本：v6.0
|
||
> 问题：从旧版本迁移到 ESP-IDF v6.0 后编译失败，存在多处头文件缺失、配置错误、CMakeLists 遗漏
|
||
|
||
---
|
||
|
||
## 问题清单与修复
|
||
|
||
### 1. Flash 大小配置错误
|
||
|
||
**错误信息：**
|
||
```
|
||
Partitions tables occupies 16.0MB of flash which does not fit in configured flash size 2MB
|
||
```
|
||
|
||
**修复：** `sdkconfig` 中 flash 大小从 2MB 改为 16MB
|
||
- `CONFIG_ESPTOOLPY_FLASHSIZE_2MB=y` → `CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y`
|
||
- `CONFIG_ESPTOOLPY_FLASHSIZE="2MB"` → `CONFIG_ESPTOOLPY_FLASHSIZE="16MB"`
|
||
|
||
### 2. WiFi 断开原因码未定义
|
||
|
||
**错误信息：**
|
||
```
|
||
error: 'WIFI_REASON_ASSOC_EXPIRE' undeclared
|
||
```
|
||
|
||
**修复：** `main/wifi/wifi_manager.c` — 为所有 reason code 添加 `#ifdef` 保护（ESP-IDF v6.0 移除了部分原因码）
|
||
|
||
### 3. CMakeLists.txt 缺少源文件
|
||
|
||
**修复：** `main/CMakeLists.txt`
|
||
- 添加 `"ota/ota_manager.c"` 到 SRCS 列表
|
||
|
||
### 4. 头文件缺失（共修复 16 处）
|
||
|
||
| 文件 | 缺失头文件 | 使用符号 |
|
||
|------|-----------|---------|
|
||
| `main/cli/serial_cli.c` | `llm/llm_provider.h` | `llm_provider_set_api_key` |
|
||
| `main/llm/llm_provider.c` | `esp_http_client.h` | `esp_http_client_set_header` |
|
||
| `main/bus/message_bus.c` | `freertos/FreeRTOS.h`, `freertos/queue.h` | `xQueueCreate`, `QueueHandle_t` |
|
||
| `main/wifi/wifi_manager.c` | `esp_event.h` | `esp_event_handler_instance_register` |
|
||
| `main/wifi/wifi_manager.c` | `freertos/FreeRTOS.h`, `freertos/task.h`, `freertos/event_groups.h` | `xEventGroupCreate`, `vTaskDelay` |
|
||
| `main/ota/ota_manager.c` | `esp_system.h` | `esp_restart` |
|
||
| `main/channels/telegram/telegram_bot.c` | `freertos/FreeRTOS.h`, `freertos/task.h` | `xTaskCreatePinnedToCore`, `vTaskDelay` |
|
||
| `main/channels/telegram/telegram_bot.c` | `esp_err.h` | `esp_err_to_name` |
|
||
| `main/tools/tool_registry.c` | `<stdlib.h>` | `free()` |
|
||
| `main/proxy/http_proxy.c` | `<sys/time.h>` | `struct timeval` |
|
||
| `main/gateway/ws_server.c` | `<stdint.h>` | `uint8_t` |
|
||
|
||
---
|
||
|
||
## ESP-IDF v6.0 API 兼容性验证
|
||
|
||
以下 API 在 v6.0 中**仍然可用**，无需修改：
|
||
|
||
| API | 位置 | 状态 |
|
||
|-----|------|------|
|
||
| `esp_spiffs_info()` | `esp_spiffs.h` | ✅ 存在 |
|
||
| `esp_websocket_client_send_bin()` | `esp_websocket_client.h` | ✅ 存在 |
|
||
| `esp_tls_set_conn_sockfd()` | `esp_tls.h` | ✅ 存在 |
|
||
| `esp_tls_set_conn_state()` | `esp_tls.h` | ✅ 存在 |
|
||
| `esp_console_new_repl_uart()` | `esp_console.h` | ✅ 存在 |
|
||
| `esp_console_new_repl_usb_serial_jtag()` | `esp_console.h` | ✅ 存在 |
|
||
| `esp_console_new_repl_usb_cdc()` | `esp_console.h` | ✅ 存在 |
|
||
| `esp_https_ota()` + `esp_https_ota_config_t` | `esp_https_ota.h` | ✅ 存在 |
|
||
| `esp_wifi_set_config()` | `esp_wifi.h` | ✅ 存在 |
|
||
|
||
---
|
||
|
||
## 烧录说明
|
||
|
||
ESP32-S3 烧录使用 **USB 口**（内置 USB Serial/JTAG 控制器）：
|
||
|
||
```powershell
|
||
idf.py -p COMx flash monitor
|
||
```
|
||
|
||
- 插 **USB 口**（标记为 `USB`），不是 UART 口
|
||
- 如遇连接失败，按住 **BOOT** 键再插线进入下载模式
|
||
|
||
---
|
||
|
||
## ESP-IDF v6.0 API 变更与修复（2026-04-01）
|
||
|
||
### 5. SNTP API 弃用问题
|
||
|
||
**错误信息：**
|
||
```
|
||
warning: 'sntp_setoperatingmode' is deprecated: use esp_sntp_setoperatingmode() instead
|
||
warning: 'sntp_setservername' is deprecated: use esp_sntp_setservername() instead
|
||
warning: 'sntp_init' is deprecated: use esp_sntp_init() instead
|
||
```
|
||
|
||
**修复：** `main/time_sync/time_sync.c`
|
||
- 将所有 `sntp_*` 函数调用替换为 `esp_sntp_*` 函数
|
||
- 示例：`sntp_init()` → `esp_sntp_init()`
|
||
|
||
**注意：** `esp_sntp` 组件在 v6.0 中不存在，`esp_sntp_*` 函数属于 `lwip` 组件，会被 `esp_netif` 和 `esp_wifi` 自动包含。
|
||
|
||
### 6. NVS API 兼容性变化
|
||
|
||
**错误信息：**
|
||
```
|
||
error: too few arguments to function 'nvs_entry_find'; expected 4, have 3
|
||
error: passing argument 1 of 'nvs_entry_next' from incompatible pointer type
|
||
```
|
||
|
||
**修复：** `main/nvs_safety/nvs_safety.c`
|
||
- `nvs_entry_find()` 现在需要 4 个参数：`nvs_entry_find(part_name, namespace, type, &iterator)`
|
||
- `nvs_entry_next()` 需要指向迭代器的指针：`nvs_entry_next(&iterator)`
|
||
- 新增 `nvs_release_iterator()` 调用释放迭代器
|
||
|
||
**建议：** 使用 `nvs_entry_find_in_handle()` 替代 `nvs_entry_find()`，更简洁。
|
||
|
||
### 7. 结构体类型错误
|
||
|
||
**错误信息：**
|
||
```
|
||
error: expected specifier-qualifier-list before 'arg_str1'
|
||
```
|
||
|
||
**修复：** `main/cli/serial_cli.c`
|
||
- `arg_str1 *server;` → `struct arg_str *server;`
|
||
- `arg_end *end;` → `struct arg_end *end;`
|
||
|
||
**原因：** `arg_str1` 是函数名，不是类型。结构体成员应使用 `struct arg_str` 类型。
|
||
|
||
### 8. 未使用的函数警告
|
||
|
||
**错误信息：**
|
||
```
|
||
warning: 'provider_is_openai' defined but not used
|
||
```
|
||
|
||
**修复：** `main/llm/llm_proxy.c`
|
||
- 删除未使用的 `provider_is_openai()` 函数
|
||
- 该函数只是调用 `llm_provider_is_openai_compatible()`，可直接使用原函数
|
||
|
||
### 9. 组件依赖问题
|
||
|
||
**错误信息：**
|
||
```
|
||
Failed to resolve component 'esp_sntp' required by component 'main': unknown name.
|
||
```
|
||
|
||
**修复：** `main/CMakeLists.txt`
|
||
- 从 `REQUIRES` 列表中移除 `esp_sntp` 组件
|
||
- `esp_sntp_*` 函数属于 `lwip` 组件，会被其他网络组件自动包含
|
||
|
||
---
|
||
|
||
## API 兼容性总结
|
||
|
||
### 已验证的 API（v6.0 中仍然可用）
|
||
| API | 状态 |
|
||
|-----|------|
|
||
| `esp_http_client_set_header()` | ✅ 未弃用 |
|
||
| `esp_crt_bundle_attach()` | ✅ 未弃用 |
|
||
| `esp_netif_create_default_wifi_sta()` | ✅ 未弃用 |
|
||
| `WIFI_INIT_CONFIG_DEFAULT()` | ✅ 未弃用 |
|
||
|
||
### 已弃用的 API（需要替换）
|
||
| 旧 API | 新 API | 文件 |
|
||
|--------|--------|------|
|
||
| `sntp_*()` | `esp_sntp_*()` | `time_sync.c` |
|
||
| `nvs_entry_find(part, ns, type)` | `nvs_entry_find(part, ns, type, &it)` | `nvs_safety.c` |
|
||
| `nvs_entry_next(it)` | `nvs_entry_next(&it)` | `nvs_safety.c` |
|