ESP-IDF

本章节包含以下部分，请按需阅读：

• ESP-IDF 入门教程
• 配置 ESP-IDF 开发环境
• 示例程序

ESP-IDF 入门教程

初次接触 ESP32 ESP-IDF 开发，想要快速上手？我们为您准备了一套通用的 入门教程。

• 第0节 认识 ESP32
• 第1节 搭建环境
• 第2节 运行实例
• 第3节 创建项目
• 第4节 使用组件
• 第5节 调试程序
• 第6节 FreeRTOS
• 第7节 驱动外设
• 第8节 Wi-Fi 编程
• 第9节 BLE 编程

请注意：该教程使用 ESP32-S3-Zero 作为教学示例，所有硬件代码均基于其引脚布局。在动手实践前，建议您对照手中的开发板引脚图，确认引脚配置无误。

配置 ESP-IDF 开发环境

备注

以下内容以 Windows 系统为例，使用 VS Code + ESP-IDF 扩展 的方式进行开发。Mac/Linux 用户请参考 官方说明。

版本选择

此部分图示以安装 ESP-IDF V5.5.2 为例示范，安装时请选用与您开发板示例匹配的 ESP-IDF 版本。

安装 ESP-IDF 开发环境

1. 前往 ESP-IDF Installation Manager 下载 ESP-IDF 安装管理器。这是乐鑫最新推出的跨平台安装工具，下文将演示如何使用其离线安装功能。

   在页面中点击 Offline Installer 标签，然后在筛选栏中选择 Windows 操作系统和你需要的 ESP-IDF 版本（图示仅为参考，请以实际为准）。

   

   确认选择无误后，点击下载按钮。浏览器将自动同时下载两个文件：一个是 ESP-IDF 离线整合包(.zst)，另一个是 ESP-IDF 安装器(.exe)。

   

   请耐心等待两个文件下载完成。

2. 下载完成后，双击运行 ESP-IDF 安装器(eim-gui-windows-x64.exe)。

   启动后，可在右上角将界面语言切换为中文。

   

   安装工具会自动检测同一目录下是否存在离线整合包。点击 从存档安装。

   

   接下来，选择安装路径。建议使用默认路径；若需自定义，请确保路径中不包含中文或空格。确认无误后，点击 开始安装。

   

3. 当看到如下界面时，表示 ESP-IDF 已安装成功。

   

4. 建议同时安装驱动程序。点击 完成安装，然后点击 安装驱动程序。

   

安装 Visual Studio Code 与 ESP-IDF 扩展

1. 下载并安装 Visual Studio Code。

2. 安装时建议勾选 通过 Code 打开操作添加到 Windows 资源管理器文件上下文菜单,以便快速打开项目文件夹。

3. 在 VS Code 中,点击侧边活动栏中的 扩展图标(或使用快捷键 Ctrl + Shift + X)打开 扩展 视图。

4. 在搜索框中输入 ESP-IDF,找到 ESP-IDF 扩展并点击安装。

   

5. 当 ESP-IDF 扩展版本 ≥ 2.0 时,扩展会自动检测并识别上述步骤中安装的 ESP-IDF 环境,无需手动配置。

示例程序

Transparent_Test

程序说明

• 本示例使用 ESP32-C5-Pico-M，通过四线 SPI 接口驱动分辨率为 128 × 64 的 SSD1312 OLED。工程当前目标芯片为 esp32c5，sdkconfig 由 ESP-IDF 6.0.2 生成。
• 驱动使用 SPI2，工作在 SPI 模式 0，时钟频率为 4 MHz。屏幕只接收数据，无需连接 MISO。
• SSD1312 驱动提供清屏、刷新、点、线、矩形、圆、英文字符、中文点阵字符和 BMP 点阵图等显示接口。显存采用 128 列 × 8 页的组织方式，每页对应 8 行像素。
• 默认运行 oled_demo_run()，依次演示英文字符串、中文点阵字符、BMP 点阵图、线条场景和仪表盘点阵图。工程还提供旋转线框立方体示例，可在 main/main.c 中切换。

硬件连接

接线前断开电源

OLED 的工作电压为 3.3 V。请勿将 VCC 接入 5 V 电源。

0.96inch Transparent OLED	ESP32-C5-Pico-M
VCC	3.3 V
GND	GND
DIN	GPIO8
CLK	GPIO7
CS	GPIO9
DC	GPIO10
RST	GPIO11
EN	不连接

模块的 EN 引脚默认开启，本示例未使用该引脚。完成接线后，将 ESP32-C5-Pico-M 通过 USB 数据线连接到电脑。

本示例按模块默认的四线 SPI 接口编写。如果已将模块焊点切换为 I2C 接口，需要先恢复为四线 SPI，或修改 main/BSP/OLED/ssd1312.h 中的接口配置和引脚定义后重新构建。

代码分析

• app_main()：调用 oled_init() 初始化屏幕。初始化成功后运行当前选择的演示程序；初始化失败时输出错误码并停止执行。
• oled_init()：配置 GPIO 和 SPI2 总线，复位 OLED，发送 SSD1312 初始化命令，清除显示 RAM 后开启显示。
• oled_refresh()：将 128 × 64 帧缓冲区按 8 个页写入 OLED。SPI 模式下每页使用一次 128 字节数据传输。
• oled_demo_run()：循环显示英文 Waveshare、中文“微雪”、BMP 点阵图、夜景线稿和仪表盘点阵图。
• cube_ui_run()：对立方体的 8 个顶点进行旋转和透视投影，再使用 12 条边绘制连续旋转的线框立方体。

oled_demo_run() 和 cube_ui_run() 内部均为持续运行的循环，因此每次只能选择其中一个。在 main/main.c 中保留需要运行的函数，并注释另一个函数：

// cube_ui_run();
oled_demo_run();

如需运行旋转立方体示例，修改为：

cube_ui_run();
// oled_demo_run();

编译和运行

在已初始化 ESP-IDF 6.0.2 环境的终端中进入示例工程目录，执行以下命令：

idf.py build
idf.py -p COMx flash monitor

将 COMx 替换为 ESP32-C5-Pico-M 的实际串口号。烧录完成后，串口监视器显示以下初始化成功信息：

SSD1312 initialization successful!

退出串口监视器请按 Ctrl-]。

运行效果

默认程序启动后，OLED 按以下顺序循环显示：

顺序	显示内容	保持时间
1	英文 Waveshare	2 秒
2	中文“微雪”	2 秒
3	内置 128 × 64 BMP 点阵图	2 秒
4	星星、月牙、山峰和松树线稿	3 秒
5	内置 128 × 64 仪表盘点阵图	5 秒

切换为 cube_ui_run() 后，OLED 持续显示绕竖直方向旋转的线框立方体，程序每 20 ms 绘制并刷新一帧。