《ESP32-P4开发指南— V1.0》第三章 初识ESP-IDF开发框架

正点原子运营

第三章 初识ESP-IDF开发框架

1）实验平台：正点原子DNESP32P4开发板

2）章节摘自【正点原子】ESP32-P4开发指南— V1.0

3）购买链接：https://detail.tmall.com/item.htm?id=873309579825

4）全套实验源码+手册+视频下载地址：http://www.openedv.com/docs/boards/esp32/ATK-DNESP32P4.html

5）正点原子官方B站：https://space.bilibili.com/394620890

6）正点原子DNESP32S3开发板技术交流群：132780729





ESP-IDF，全称为Espressif IoT Development Framework，是乐鑫科技专为ESP32系列芯片设计的开发框架。此框架的核心用途在于开发、构建以及部署基于ESP32的物联网（IoT）应用。对于开发者而言，编写程序以控制ESP32芯片，本质上是对其内部寄存器进行操作，从而确保芯片按照我们的需求工作。为了简化这一复杂的底层操作过程，ESP-IDF将大部分寄存器的操作细节封装成了易于使用的函数。这意味着，我们无需深入了解每一个寄存器的具体设置方法，只需熟悉并掌握ESP-IDF库所提供的函数接口，即可高效地驱动ESP32芯片进行工作。这种封装方式不仅提高了开发效率，还显著降低了出错率，使得开发者能够更专注于应用层的逻辑设计，从而节省宝贵的开发时间。
本章将分为如下几个小节：
3.1 ESP-IDF概述
3.2 ESP-IDF目录总览
3.3 ESP-IDF架构解析

3.1 ESP-IDF概述
ESP-IDF（Espressif IoT Development Framework）是乐鑫信息科技（Espressif Systems）官方的物联网开发框架，专为ESP32、ESP32-S、ESP32-C、ESP32-H及ESP32-P系列SoC设计。该框架以C/C++为主要开发语言，支持在Windows、Linux和Mac等主流操作系统下进行交叉编译，便于用户在这些平台上开发通用物联网应用程序。本书提供的示例程序均基于Windows系统下ESP-IDF搭建的，具有以下特性：
1，系统级驱动支持：包含针对ESP32、ESP32-S、ESP32-C、ESP32-H和ESP32-P系列SoC的系统级驱动。这些驱动主要包括外设底层LL（Low Level）库和HAL（Hardware Abstraction Layer）库、RTOS（实时操作系统）支持以及上层驱动软件等。
2，物联网基础组件：集成了物联网开发所需的基础组件，涵盖HTTP、MQTT等多种网络协议栈，支持动态调频的电源管理框架，以及Flash加密和Secure Boot等安全方案。
3，构建、烧录与调试工具：提供了开发和量产过程中常用的工具（见图3.1.1），如基于CMake的构建系统、基于GCC的交叉编译工具链、以及基于OpenOCD的JTAG调试工具等。
值得注意的是，ESP-IDF代码主要遵循Apache 2.0开源协议。在遵守该开源协议的前提下，用户可以自由地进行个人或商业软件开发，无需开源修改后的源代码，并享有永久的专利许可。

图3.1.1在开发和量产过程中常用的构建、烧录和调试工具

在上图中，ESP-IDF（Espressif IoT Development Framework）、Toolchain（工具链）和Project（项目）之间的关系可以通过以下几个方面来理解：
1，ESP-IDF
ESP-IDF 是由 Espressif 提供的开发框架，专门用于开发基于 ESP32 系列芯片的应用。它包含了许多开发所需的库、API 和示例代码，使得开发者可以方便地进行物联网应用的开发。
2，Toolchain
Toolchain 是指用于编译和构建代码的工具集。在 ESP-IDF 中，Toolchain 通常包括编译器（如 GCC）、构建工具（如 CMake 或 Make）和其他工具（如 Python、Git 等）。Toolchain 的作用是将你编写的源代码转换为可以在 ESP32 芯片上运行的二进制文件。
3，Project
Project 是开发者创建的具体应用或程序，它由一组源代码文件、配置文件和可能的资源文件组成。在 ESP-IDF 中，项目通常会利用 ESP-IDF 提供的库和功能来实现特定的功能。
Project就像是一份菜单，列出了用户想要的“菜品”（组件）和怎么烹饪（应用），而ESP-IDF则是厨房，提供各种必要的“食材”（核心组件）。通过Toolchain（工具链），这些“食材”根据菜单的需求被组合、加工，最终烹饪成一份可执行的程序。
这种架构的设计使得开发过程更加模块化和高效，开发者只需关注自己需要的功能，而不必担心底层的细节。

3.1.1 ESP-IDF版本介绍
ESP-IDF（Espressif IoT Development Framework）的源代码在GitHub平台上开源发布，至今已推出了v3、v4、v5三个主要版本系列，每个主要版本下通常又包含多个子版本，例如5.0、5.1、5.2和5.3等。乐鑫科技（Espressif Systems）为每个已发布的版本提供长达30个月的bug修复和安全更新支持。在此期间，乐鑫还可能会发布子版本的修订版本，如5.2.1、5.2.2等，以进一步优化和修复问题。
不同v5版本的ESP-IDF对乐鑫芯片的支持状态如下表所示。

表3.1.1.1 不同v5版本的ESP-IDF对乐鑫芯片的支持状态

上表中“预览”表示提供预览版本的支持，预览版本可能缺少关键功能或文档，“支持”表示提供正式版本的支持。

3.1.2 如何选择合适的IDF版本
根据上表所示，ESP-IDF从5.4版本开始正式支持ESP32-P4。在撰写本书时，v5.4版本尚未正式发布，但我们已经获取到了v5.4版本的发布版。
关于版本选择的建议：
1，对于入门开发者，我们推荐选择稳定的v5.4正式发布版本及其修订版本，以确保与本书中的示例版本保持一致，从而降低学习难度。
2，如果您的项目有量产需求，我们建议使用最新的稳定版本，因为这样可以获得最及时的技术支持和更新，有助于确保产品的稳定性和可靠性。
3，如果您需要尝试新芯片或预研产品的新功能，那么可以选择master分支。虽然master分支包含了所有的最新特性，但请注意，其中可能包含已知或未知的bug，因此在使用时需要谨慎评估风险。

3.2 ESP-IDF目录总览
在ESP-IDF安装成功后，包含以下两个主要目录：
1）esp-idf（安装路径/ frameworks）：这个目录主要包含ESP-IDF仓库的源代码文件和编译脚本。这些文件是开发ESP系列芯片应用程序的基础，包含各种库、示例代码和工具。
2）espressif（安装路径/ Espressif）：这个目录主要保存编译工具链和其他相关软件。这些工具对于编译和调试ESP-IDF项目至关重要。
熟悉这两个目录的结构和内容，有助于开发者更好地利用已有的资源，从而加快开发过程。ESP-IDF的目录结构如下所述。

1，ESP-IDF仓库代码目录，如下图所示。

图3.2.1 ESP-IDF仓库代码目录（部分截图）

1）组件目录：components。该目录是ESP-IDF（Espressif IoT Development Framework）的核心组成部分，集成了大量的核心软件组件。任何一个基于ESP-IDF的工程代码都无法完全脱离该目录中的组件进行编译。该目录包含对多款乐鑫（Espressif）芯片的驱动支持，从外设底层的LL（Low-Level）库、HAL（Hardware Abstraction Layer）库接口，到上层的Driver（驱动程序）、VFS（Virtual File System）层支持，都能找到相应的组件，以便开发者进行不同层级的开发。此外，ESP-IDF还适配了多种标准的网络协议栈，如TCP/IP、HTTP、MQTT等。开发者可以使用Socket等自己熟悉的接口来完成网络应用的开发。组件作为一个功能完整的模块，可以方便地集成到应用程序中，使开发者能够专注于业务逻辑的实现。常用的组件如下：
①：Driver：包含乐鑫各系列芯片的外设驱动程序，如GPIO、I2C、SPI、UART、LEDC（PWM等）。该组件中的外设驱动程序为用户提供了与芯片无关的抽象接口，每一个外设均有一个通用的头文件（如gpio.h），用户无需再特别处理不同芯片支持的问题。
②：Freertos：包含了完整的FreeRTOS代码，乐鑫除了对该操作系统提供了完成支持，还扩展了该操作系统对双核芯片的支持，对于ESP32、ESP32-S3和ESP32-P4等双核芯片，用户可以将任务创建在指定的内核上。

2）文档目录 docs 。包含了与 ESP-IDF 相关的开发文档，包括快速入门手册、API 参考手册和开发指南等。

3）脚本工具目录 tools 。包含了常用的编译前端 idf.py 和监视器终端工具 idf_monitor.py 等。其子目录 cmake 中还包含了编译系统的核心脚本文件，这些文件是实现 ESP-IDF 编译规则的基础。在环境变量配置时，tools 目录中的内容会被添加到系统环境变量中，因此可以在项目路径下直接执行 idf.py。

4）示例程序目录examples。该目录中包含了大量的ESP-IDF示例程序，以便尽可能多地展示组件API的使用方法。按照示例的类别，目录esamples的子目录可分为以下几类：
①：get-started：入门示例子目录，包含hello world、blink等基础示例，便于读者入门学习。
②：bluetooth：蓝牙示例子目录，包含Bluetooth LE Mesh、Bluetooth LE HD等示例程序。
③：wifi：Wi-Fi示例子目录，包含 Wi-Fi SofAP、Wi-Fi Station 等基础的示例程序，espnow等乐鑫科技专有的通信协议示例程序，以及基于Wi-Fi的多个应用层示例程序（如Iperf、Sniffer、Smart Config等）。
④：peripherals：外设示例子目录，这是一个比较大的文件夹，按照外设名称又分为数十个子文件夹，主要包含乐鑫系列芯片的外设驱动示例程序，每个示例程序均包含若于个示例例如，子目录gpio中包含了GPIO和GPIO矩阵键盘两个示例。需要注意的是，这里的示例未必都适用于ESP32-P4，例如usb/host中的示例仅适用于包含 USB Host 硬件的外设（如ESP32-P4），而ESP32- P4不具有该外设，对于这类示例，在设置目标时编译系统一般输出相应的提示。每个示例的README文件中会列出已经适配的芯片。
⑤：protocols：通信协议示例子目录，该子目录包含了数十种通信协议的示例程序，包括MOTT、HTTP、HTTP Server、PPPoS、Modbus、mDNS、SNTP 等，几乎涵盖了所有物联网开发所需的通信协议示例。
⑥：provisioning：配网示例子目录,该子目录包含了多种配网方式,如 Wi-Fi配网、Bluetooth LE 配网等。
⑦：system：系统示例子目录，该子目录包含了系统调试示例(如堆追踪、运行追踪、任务监控等)，与电源管理相关的示例（如各种休眠模式、协处理器等），以及控制台终端、事件循环、系统定时器等常用系统组件的示例。
⑧：storage：存储示例子目录，该子目录包含了ESP-IDF支持的所有文件系统和存储机制示例（如Flash、SD卡等存储媒介的读写），以及非易失存储（NVS）、FatFS、SPIFFS等文件系统操作示例。
⑨：security：安全示例子目录，该子目录包含了与Flash加密相关的示例程序。

2，ESP-IDF编译工具链的目录（安装路径/ Espressif），如下图所示：

图3.2.2 ESP-IDF编译工具链目录

1）软件分发目录dist。该目录用于存放以压缩包形式分发的ESP-IDF工具链和相关软件。安装工具在安装过程中会先下载压缩包到 dist 目录，然后将其解压到指定目录。安装完成后，可以清空 dist 目录中的内容。
2）python虚拟环境目录python_env。ESP-IDF依赖于不同版本的Python软件包，直接在同一台主机上安装可能导致版本冲突。为了解决这一问题，ESP-IDF采用Python虚拟环境来隔离不同的软件包版本。开发者可以在主机上同时安装多个版本的ESP-IDF，只需在使用时导入相应的环境变量。
3）编译工具链目录tools。该目录包含编译ESP-IDF工程所需的交叉编译工具，如CMake和Ninja构建工具，以及生成最终可执行程序的GCC工具链。此外，该目录还包含C/C++语言的标准库和对应的头文件。当程序引用系统头文件（如 #include <stdio.h>）时，编译工具链将会在此目录中查找所需的头文件。

3.3 ESP-IDF架构解析
ESP-IDF（SDK）架构可分为三个主要层级，分别是低级层（LL）、硬件抽象层（HAL）和驱动层。这一结构旨在提供灵活、高效的外设控制接口，支持不同抽象级别的操作，确保用户在不同复杂度需求下可以选择合适的开发方式。下图为ESP-IDF项目开发架构总图。

图3.3.1 ESP-IDF项目开发架构

根据图中架构中，每一层次负责不同的功能和抽象：
1，应用层
这是用户开发的应用程序代码所在的层次。用户的程序通过调用驱动层或操作系统内核提供的API，与底层硬件交互。
2，操作系统内核
ESP-IDF通常使用FreeRTOS作为其操作系统内核。FreeRTOS为应用程序提供任务调度、信号量、队列等常用的RTOS功能。
3，驱动层
驱动层封装了对硬件外设的高级控制接口，应用程序通过调用驱动层API来操作硬件设备。驱动层的API通常是与具体的硬件设备相关的，例如GPIO、I2C、SPI、UART等。
4，硬件抽象层（HAL）
硬件抽象层为上层驱动提供了更加通用的接口，它将硬件外设的操作步骤抽象为一系列可复用的函数。HAL层的设计目标是为了跨不同的硬件平台，保持代码的兼容性和可移植性。
5，低级层（LL层）
LL层直接操作硬件寄存器，它是对硬件最直接的抽象。与HAL不同，LL层更靠近硬件，它将寄存器的操作封装为简洁的函数，方便用户直接控制硬件寄存器。
6，硬件平台
硬件平台是ESP32芯片本身及其外设。这是所有抽象层的基础，它提供了底层硬件的具体实现，包括CPU、存储、外设（如UART、I2C、SPI等）。
在这个架构中，ESP-IDF（SDK）包含了驱动层、操作系统内核层、硬件抽象层（HAL）和最底层的LL层，这四层组合成了完整的ESP-IDF软件工具包，帮助开发者高效地开发基于ESP32的应用。
当打开ESP-IDF的软件工具包时，可以看到components文件夹下分类存放着各个层次的抽象文件，见下图所示：
1）freertos文件夹：保存的是操作系统内核层文件，主要包括FreeRTOS内核相关的代码和任务调度、信号量等操作系统功能。
2）hal文件夹：包含了硬件抽象层（HAL）和低级层（LL层）的文件。HAL提供跨平台的硬件操作接口，而LL层负责更底层的寄存器控制，使硬件操作更贴近实际。
3）driver文件夹或其他设备相关文件夹：这些文件夹属于驱动层，封装了ESP32常用外设（如GPIO、UART、I2C、SPI等）的高级操作API，应用层可通过这些驱动与硬件设备交互。

图3.3.2 ESP-IDF（SDK）下的components文件夹部分截图

在ESP-IDF架构中，soc文件夹（上图soc文件夹）保存着与硬件相关的抽象文件，这些文件分为不同类型，负责具体的硬件描述和操作。常见的文件类型及其作用如下：
①：xxx_reg.h：定义了与硬件相关的寄存器，提供对硬件寄存器的直接访问。
②：xxx_struct.h：以C语言的struct形式描述硬件，便于通过结构体访问硬件的不同部分。
③：xxx_channel.h：为拥有多个通道的硬件设备定义通道相关的配置和操作。
④：xxx_caps.h：描述硬件的特性或能力，例如支持的最大频率、数据宽度等，方便跨平台兼容。
⑤：xxx_pins.h：定义了硬件的引脚配置，帮助开发者更好地控制设备的IO映射。
⑥：xxx_periph.h/*.c：包含与某个外设相关的所有头文件，声明和定义了该外设的IO映射和相关操作函数。
这些文件帮助开发者在不同层次上抽象和操作硬件，使得代码更加模块化和易维护。