一、环境与硬件说明

1. 开发环境

• ESP-IDF 版本：v5.5.4，路径 C:\esp\v5.5.4

• 开发终端：ESP-IDF PowerShell

• 编译工具链：riscv32-esp-elf-gcc 14.2.0

2. 硬件信息

• 主控：ESP32-P4 v1.3（芯片版本低于 3.0，需特殊配置 bootloader）

• 屏幕：5 寸 MIPI DSI 1280×720 LCD + GT911 电容触摸

• 外设：32MB Octal PSRAM、16MB Flash、SC2356 MIPI-CSI 摄像头

• WiFi：外挂 ESP32-C6 SDIO 无线模块

二、工程目录搭建

1. 基础工程创建

hello_world/
├─ CMakeLists.txt          # 工程根目录编译配置
├─ sdkconfig               # menuconfig生成硬件配置
├─ build/                  # 编译输出缓存（fullclean可删除）
├─ components/             # 第三方组件存放目录
│  ├─ M5GFX/
│  └─ M5Unified/
└─ main/
   ├─ CMakeLists.txt       # 主程序编译配置
   └─ hello_world_main.cpp # C++主程序（M5库仅支持C++）

2. 拉取 M5 官方依赖组件

进入工程components目录执行 Git 克隆，两个组件缺一不可：

cd D:\esp\app\hello_world\components
# 绘图底层库
git clone https://github.com/m5stack/M5GFX.git
# 板卡硬件封装库（屏幕/触摸/电源/摄像头）
git clone https://github.com/m5stack/M5Unified.git
cd ..

三、CMake 编译文件配置

1. 工程根目录 CMakeLists.txt

禁止在根目录写idf_component_register，该指令仅用于 main 子目录

cmake_minimum_required(VERSION 3.16)
# 声明第三方组件扫描目录
set(EXTRA_COMPONENT_DIRS ${CMAKE_SOURCE_DIR}/components)
# 引入ESP-IDF工程模板（固定顺序，必须在project前）
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
# 定义工程名称
project(hello_world)

2. main 目录 main/CMakeLists.txt

原文件基于 spi_flash 改造，新增 M5Unified 依赖，使用PRIV_REQUIRES私有依赖：

idf_component_register(SRCS "hello_world_main.cpp"
                    PRIV_REQUIRES spi_flash M5Unified
                    INCLUDE_DIRS "")

注意：源码后缀必须为.cpp，.c纯 C 文件无法编译 M5Unified C++ 库

四、menuconfig 全局硬件关键配置

执行命令打开配置界面：

idf.py menuconfig

配置 1：ESP32-P4 芯片版本兼容（解决 bootloader 烧录报错）

路径：Component config → Hardware Settings → Chip revision

勾选：Select ESP32-P4 revisions <3.0（适配 v1.3 老芯片）

配置 2：PSRAM 完整开启（解决报错 M5Tab5 need PSRAM enabled）

顶层开关：Component config → ESP-PSRAM

勾选 Support external SPI RAM (PSRAM)

进入 PSRAM config 子菜单参数设置：

配置 3：Flash 大小消除开机警告

路径：Serial flasher config → Flash size

选择：16MB（硬件板载 16MB Flash，解决 spi_flash 大小不匹配警告）

配置完成按 S 保存，Q 退出配置界面。

五、主程序代码（hello_world_main.cpp）

完整可运行代码

// FreeRTOS延时头文件，修复vTaskDelay/pdMS_TO_TICKS未定义
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"

// 【强制要求】板卡宏定义必须放在M5Unified头文件最前方
#define M5BOARD_M5TAB5
#include "M5Unified.h"

// extern "C" 包裹入口函数，解决链接报错 undefined reference to app_main
extern "C"
{
void app_main(void)
{
    // 一键初始化Tab5全部硬件：MIPI屏幕、背光、触摸、电源
    M5.begin();
    M5GFX& lcd = M5.Display;

    // 开启屏幕背光（0~255，默认0熄屏，必须设置）
    lcd.setBrightness(180);
    // 填充黑色背景
    lcd.fillScreen(TFT_BLACK);
    // 文字样式配置
    lcd.setTextSize(3);
    lcd.setTextColor(TFT_GREEN);
    lcd.setCursor(100, 300);
    lcd.println("M5 Tab5 LCD Test OK");

    while (1)
    {
        M5.update(); // 轮询触摸输入，必须保留
        vTaskDelay(pdMS_TO_TICKS(100));
    }
}
}

关键代码说明

#define M5BOARD_M5TAB5：强制指定板卡，新版 M5Unified 无 Kconfig 菜单，必须代码定义

extern "C"：C++ 文件入口函数标准写法，避免链接器找不到app_main

lcd.setBrightness()：屏幕背光默认关闭，不调用会黑屏

必须引入 FreeRTOS 头文件，否则延时函数编译报错

六、编译、清理、烧录流程

1. 全量清理旧缓存（修改 menuconfig/CMake 后必须执行）

idf.py fullclean

2. 编译工程

idf.py build

3. 烧录并打开串口监视器（COM23 替换为实际设备端口）

idf.py -p COM23 flash monitor

七、效果展示：