第三章 初識ESP-IDF開發框架

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映射和相關操作函數。
這些文件幫助開發者在不同層次上抽象和操作硬件，使得代碼更加模塊化和易維護。