《ESP32-S3使用指南—IDF版 V1.6》第四章 開發環境搭建（下）

4.2 IDF前端工具
idf.py 是 ESP-IDF 開發環境中的一個重要命令行工具，用於提供前端界面，幫助開發者輕鬆管理工程的配置、構建、燒錄以及調試等操作。它結合了CMake、Niunja和esptool.py等工具，使開發流程更加便捷和高效。
idf.py 主要工具作用：
1）CMake工具用於配置工程的構建流程，管理構建依賴和生成構建文件。
2）Ninja工具用於實際執行構建操作，快速高效地編譯項目。
3）esptool.py工具用於燒錄程序到目標芯片，並進行芯片的基本管理操作，如擦除閃存、復位和下載等。
下圖為idf.py主要工具操作流程圖。

圖4.2.1 項目工程的構建、編譯和燒錄流程
在開發過程中，源代碼通常依賴多個庫或模塊，而 CMake 可以自動分析並管理這些依賴關係。它根據開發者提供的 CMakeLists.txt 配置文件，確定哪些源文件需要編譯、哪些庫需要鏈接，確保所有依賴關係正確處理。在 ESP32 開發中，項目可能包含許多組件，CMake 能夠智能地處理這些組件的構建順序。通過 CMake 配置後，CMake 會生成構建文件（如 build.ninja），這些文件定義瞭如何構建項目。接下來，Ninja 工具執行具體的編譯工作，生成最終的可執行文件或二進制等文件。最後，使用 esptool.py 工具將生成的二進制文件燒錄到 ESP32 開發板上，確保程序能夠運行。
4.2.1 IDF常用命令
1，創建新的工程

idf.py create-project --path <project name>

該命令用於創建一個新的項目目錄結構，並將必要的文件和模板複製到指定目錄中。其目的是幫助開發者快速設置一個新的 IoT 項目，而無需手動創建所有必要的文件和目錄，從而加快項目初始化過程。
下面是這個命令的解析和使用方法。
1）命令解析
①：idf.py：是 ESP-IDF 工具鏈的主要命令行工具。
②：create-project：操作功能為創建工程。
③：--path：工程創建在哪個位置（可選）。
④：<project_name>：創建工程的名稱。
2）使用方法
首先，在桌面新建一個名為 test 的文件夾，用來保存新建的工程。然後，打開 ESP-IDF CMD 或 PowerShell 終端，輸入以下命令來創建項目工程。

圖4.2.1.1 指定路徑創建工程
從上圖可以看到，在桌面上的test文件夾下創建了一個名為“atk_project”的工程。

2，創建新的組件

idf.py create-component <component name>

該命令用於在當前項目中創建一個新的組件（component）。它會自動生成該組件所需的基本目錄結構和文件，包括CMakeLists.txt文件，以及默認的源代碼文件和頭文件。組件是ESP-IDF項目中重要的模塊化單元，通常包含相關功能代碼，便於代碼的複用和管理。
注意：新的組件一般放置在componen文件夾下。因此，我們需要在項目的根目錄下新建一個名為 “components”的文件夾，用來保存我們創建的組件。
下面是這個命令的解析和使用方法。
1）命令解析
①：idf.py：是 ESP-IDF 工具鏈的主要命令行工具。
②：create-component：操作功能為創建新的組件，如LED、KEY等驅動組件。
③： ：創建組件的名稱。
2）使用方法
首先，在test項目的根目錄下新建一個components文件夾。接着，打開命令終端，進入components文件夾路徑，並在該路徑下輸入以下命令來創建組件，如下圖所示。

圖4.2.1.2 創建新的組件
在上圖中，我們首先利用“cd”命令進入到指定的項目工程路徑。隨後，在該路徑下輸入創建組件的命令，即可成功創建組件。led組件的文件結構如圖所示。

圖4.2.1.3 led組件文件結構
上圖中的 led.c 和 led.h 是典型的源代碼文件和頭文件，分別用於實現和聲明與 LED 控制相關的功能。而 CMakeLists.txt 文件的作用是將 led 組件添加到構建系統中，使其能夠參與項目的編譯和構建。這也是前面筆者講解的構建文件。

3，選擇目標芯片

idf.py set-target <target>

該命令的作用是設置當前項目的目標芯片。默認情況下，新建的項目工程是以 ESP32 系列芯片為模板的。如果你使用的不是 ESP32 系列芯片，而是其他樂鑫系列的芯片（如 ESP32-S3、ESP32-P4 等），則需要通過該命令切換到你所使用的目標芯片。
下面是這個命令的解析和使用方法。
1）命令解析
①：idf.py：是 ESP-IDF 工具鏈的主要命令行工具。
②：set-target：操作功能為設置目標芯片。可使用（idf.py --list-targets 命令查看當前 ESP-IDF 版本支持的所有目標芯片）。
③： ：切換目標芯片。
2）使用方法
首先，在 PowerShell 終端中切換到項目工程的根目錄。然後，輸入下圖命令切換目標芯片。

圖4.2.1.4 切換目標芯片
執行上述命令後，test 工程下將會編譯出 build 文件夾和 sdkconfig 文件。其中，sdkconfig 是 ESP-IDF 項目中的配置文件，用於定義項目的編譯和運行參數。它包含各種配置選項，如目標芯片型號、外設啓用情況、內存管理、網絡協議棧配置等。該文件的主要作用是根據用户的需求調整項目的功能和性能。

4，啓動圖形配置工具

idf.py menuconfig

該命令是啓動 ESP-IDF 提供的圖形化配置工具，用於方便地設置和管理項目的配置選項。
下面是這個命令的解析和使用方法。
1）命令解析
①：idf.py：是 ESP-IDF 工具鏈的主要命令行工具。
②：menuconfig：操作功能為開啓圖形化配置界面。
2）使用方法
首先，在 PowerShell 終端中切換到項目工程的根目錄。然後，輸入下圖命令開啓圖形化配置界面，如下圖所示。

圖4.2.1.4 進入圖形配置工具
menuconfig界面是ESP-IDF的圖形化配置工具，供開發者直觀地設置項目參數；當通過該界面修改配置並保存後，這些更改會被寫入sdkconfig文件中。sdkconfig文件則記錄了所有配置選項，確保在項目編譯時應用這些設置。因此，menuconfi是配置的操作界面，sdkconfig是配置的存儲文件，兩者共同作用於項目的配置管理。
在以後的章節中，筆者將詳細講解menuconfig圖形化配置工具中常用選項的作用，幫助大家更好地理解和學習它。

5，構建工程

idf.py build

此命令將構建當前目錄下的工程，具體步驟包括：創建用於保存構建輸出文件的build目錄（可使用-B選項更改路徑），運行CMake以配置工程並生成構建文件，最後通過主要構建工具（Ninja或GNU Make）進行編譯。默認情況下，構建工具會自動檢測，也可以通過-G選項手動設置。相關構建流程請參見 圖4.2.1流程圖。
下面是這個命令的解析和使用方法。
1）命令解析
①：idf.py：是 ESP-IDF 工具鏈的主要命令行工具。
②：build：操作功能為構建項目。
2）使用方法
首先，在 PowerShell 終端中切換到項目工程的根目錄。然後，輸入下圖命令構建項目，如下圖所示。

圖4.2.1.5 構建工程
編譯成功後，系統會將生成的目標文件（.obj）、可執行文件（.elf）和二進制文件（.bin）等保存到 build 文件夾中。

6，清除構建輸出

idf.py clean

該命令可清除build目錄中的構建輸出文件，確保下次構建時工程會完全重新構建。需要注意的是，使用該命令不會刪除build文件夾內的CMake配置輸出。
下面是這個命令的解析和使用方法。
1）命令解析
①：idf.py：是 ESP-IDF 工具鏈的主要命令行工具。
②：clean：操作功能為清除構建輸出。
2）使用方法
首先，在 PowerShell 終端中切換到項目工程的根目錄。然後，輸入下圖命令清除構建輸出文件，如下圖所示。

圖4.2.1.6 清除構建輸出的文件
注意：這個命令清除了由Ninja構建工具生成的文件，但不會清除CMake編譯輸出的文件。

7，刪除所有構建內容

idf.py fullclean

此命令將刪除build目錄下的所有內容，包括CMake配置輸出。下次構建時，CMake會重新配置其輸出。需要注意的是，該命令會遞歸刪除build目錄下的所有文件（工程配置將保留），因此請謹慎使用。
下面是這個命令的解析和使用方法。

1）命令解析
①：idf.py：是 ESP-IDF 工具鏈的主要命令行工具。
②：fullclean：操作功能為清除所有構建輸出文件。

2）使用方法
首先，在 PowerShell 終端中切換到項目工程的根目錄。然後，輸入下圖命令清除所有構建輸出文件，如下圖所示。

圖4.2.1.7 清除所有構建輸出文件

8，燒錄工程

idf.py -p COMx flash

該命令將在需要時自動構建工程，隨後將其燒錄到目標芯片。使用-p和-b選項可分別設置串口端口號和燒錄程序的波特率。
下面是這個命令的解析和使用方法。
1）命令解析
①：idf.py：是 ESP-IDF 工具鏈的主要命令行工具。
②：-p：設置串口的端口號。
③：COMx：串口的端口號。
④：flash：操作功能為程序下載。

2）使用方法
首先，在 PowerShell 終端中切換到項目工程的根目錄。然後，輸入下圖命令下載程序，如下圖所示。

圖4.2.1.8 燒錄固件

9，啓動監視器

idf.py monitor

命令用於監控當前項目的運行狀態。在監控之前，必須確保已安裝 USB 虛擬串口驅動，或使用開發板上的 USB 串口/JTAG 接口連接設備，以便查看項目的調試輸出和日誌信息。
下面是這個命令的解析和使用方法。

1）命令解析
①：idf.py：是 ESP-IDF 工具鏈的主要命令行工具。
②：monitor：操作功能為啓動監視器。

2）使用方法
首先，在 PowerShell 終端中切換到項目工程的根目錄。然後，輸入下圖命令啓動監視器，如下圖所示。

圖4.2.1.9 啓動監視器

10，合併二進制文件

idf.py merge-bin -o <my-merged-binary>.bin/.hex -f raw

在某些情況下（例如將文件傳輸到另一台機器，且不借ESP-IDF進行燒錄），只燒錄一個文件比燒錄idf.py build生成的多個文件更為便捷。idf.py merge-bin命令會根據項目配置，合併引導加載程序、分區表、應用程序本身以及其他分區（如果存在），並在build文件夾中生成一個二進制文件merged-binary.[bin|hex]，之後可對其進行燒錄。
下面是這個命令的解析和使用方法。

1）命令解析
①：idf.py：是 ESP-IDF 工具鏈的主要命令行工具。
②：merge-bin：操作功能為合併二進制。
③：-o：輸出文件
④： .bin/.hex：輸出文件名稱
⑤：-f raw：輸出二進制。合併後的文件的輸出格式可以是二進制（raw），IntelHex（hex）以及 UF2（uf2）

2）使用方法
首先，在 PowerShell 終端中切換到項目工程的根目錄。然後，輸入下圖命令啓動監視器，如下圖所示。

圖4.2.1.10 輸出合併二進制文件

4.2.2 高級命令
1，打開目標芯片在線ESP-IDF編程文檔

idf.py docs

該命令將在瀏覽器中打開與工程目標芯片和 ESP-IDF 版本對應的官方文檔，方便用户查看相關的開發資料和參考信息。
下面是這個命令的解析和使用方法。

1）命令解析
①：idf.py：是 ESP-IDF 工具鏈的主要命令行工具。
②：docs：操作功能為打開文檔。
2）使用方法
首先，在 PowerShell 終端中切換到項目工程的根目錄。然後，輸入下圖命令打開在線文檔，如下圖所示。

圖4.2.2.1 打開在線文檔

2，顯示應用程序大小

idf.py size

該命令將顯示應用程序大小，包括佔用的RAM和flash 及各部分（如 .bss）的大小。
下面是這個命令的解析和使用方法。
1）命令解析
①：idf.py：是 ESP-IDF 工具鏈的主要命令行工具。
②：size：操作功能為查看應用程序大小。

2）使用方法
首先，在 PowerShell 終端中切換到項目工程的根目錄。然後，輸入下圖命令查看程序大小，如下圖所示。

圖4.2.2.2 查看程序相關大小

3，查看組件應用程序大小

idf.py size-components

該命令將顯示工程中各個組件的應用程序大小，幫助開發者瞭解每個組件在應用中的存儲佔用情況。
下面是這個命令的解析和使用方法。
1）命令解析
①：idf.py：是 ESP-IDF 工具鏈的主要命令行工具。
②：size-components：操作功能為查詢各組件的大小。
2）使用方法
首先，在 PowerShell 終端中切換到項目工程的根目錄。然後，輸入下圖命令查看各組件的大小，如下圖所示。

圖4.2.2.3 各組件的應用程序大小（部分截圖）
4，查看每個源文件大小

idf.py size-files

該命令將顯示工程中每個源文件的大小，並支持通過--format選項指定輸出格式（支持text、csv、json，默認格式為text）。此外，還可以使用--output-file參數指定輸出文件的文件名，而不是將結果輸出到標準輸出。
下面是這個命令的解析和使用方法。
1）命令解析
①：idf.py：是 ESP-IDF 工具鏈的主要命令行工具。
②：size-files：操作功能為查詢g工程每個源文件大小。
2）使用方法
首先，在 PowerShell 終端中切換到項目工程的根目錄。然後，輸入下圖命令查看工程每個源文件的大小，如下圖所示。

圖4.2.2.4 查看工程每個源文件的大小（部分截圖）
比較常用的高級命令就講解到這裏了。如果讀者想了解更多高級命令，可以參考樂鑫官方在線文檔中的“IDF前端工具”章節，裏面對各個命令的使用和功能有非常詳細的介紹。

4.3 搭建集成開發環境
在上一小節中，筆者詳細闡述了命令式開發的常用命令。然而，對於初學者來説，他們往往更傾向於使用圖形界面式的開發方式，因為圖形界面能更直觀地展示整個開發過程。因此，作者在此推薦使用VS Code IDE作為開發工具。VS Code 支持下載ESP-IDF插件，方便開發者進行項目開發和調試。該插件集成了編輯、編譯、燒錄和調試等基礎功能，還提供工具安裝SDK配置和CMake編輯器等附加功能，簡化並增強了開發人員在VS Code中開發基於ESP32的IoT應用程序的體驗。

4.3.1 VS Code環境安裝
鑑於我們使用的是VS Code IDE搭配樂鑫ESP-IDF進行開發，接下來將介紹VS Code的安裝過程。首先，訪問VS Code的官方（https://code.visualstudio.com/Download）下載頁面，根據系統需求選擇相應的安裝包進行下載。此外，也可以在A盤 6 ，軟件資料 1 ， 軟件 1 ，IDF開發工具路徑下找到VS Code的安裝包。下圖為VS Code的官方下載頁面。

圖4.3.1.1 VS Code官網下載界面
在此，我們選擇下載Windows版本的VS Code，因為我們是在Windows環境下進行開發。雖然其他版本的下載方式應該類似，但這裏我們將重點介紹Windows版本的下載步驟。下載完成後，按照以下步驟進行安裝即可：
1，以<管理員身份>運行VSCodeUserSetup-x64-1.94.2.exe安裝包，如下圖所示。

圖4.3.1.2 以管理員身份運行VSCode安裝包
2，此時，進入安裝的許可協議頁面，如下圖所示。

圖4.3.1.3 安裝許可協議
3，選擇“我同意此協議”，然後點擊“下一步”進入選擇目標位置頁面，如下圖所示。

圖4.3.1.4 設置安裝路徑
用户可以自行填寫安裝位置，但需注意，安裝路徑最好使用全英文字符，以避免可能出現的路徑識別問題。
4，設置安裝路徑完成後，可點擊“下一步”進入選擇開始菜單文件夾，如下圖所示。

圖4.3.1.5 選擇開始菜單文件夾
5，這裏我們保持默認配置，接着，點擊“下一步”進入選擇附加任務頁面，如下圖所示。

圖4.3.1.6 選擇附加任務
6，請把附加任務全部勾選，然後點擊“下一步”進入準備安裝頁面，如下圖所示。

圖4.3.1.7 準備安裝頁面
7，點擊“安裝”按鈕即可開始安裝VS Code集成開發環境。安裝成功後，界面將如圖所示。

圖4.3.1.8 VSCode 安裝成功
值得注意的是，第一次安裝的VS Code軟件為英文版本。如果讀者希望將VS Code設置為中文漢化，則需要安裝簡體中文插件。安裝方式如下。
在VS Code集成開發環境中，可以通過點擊左側的“擴展”圖標或使用快捷鍵“Ctrl + Shift + X”直接進入擴展頁面。在搜索欄中輸入“Chinese”，然後選擇安裝“Chinese (Simplified) Language Pack for Visual Studio Code”插件，如下圖所示。安裝完成後，必須重啓VS Code才能切換為簡體中文界面。

圖4.3.1.9 安裝簡體中文插件
至此，VS Code的安裝過程就完成了。

4.3.2 ESP-IDF插件安裝與配置
ESP-IDF插件在安裝後會調用之前安裝的ESP-IDF提供的各種工具和功能，為開發者提供一個集成的開發環境。具體而言，插件利用ESP-IDF的構建系統，使開發者能夠輕鬆編譯項目，並集成燒錄工具，以便直接將固件燒錄到目標設備。此外，插件還調用ESP-IDF監控功能，實時查看設備輸出，幫助進行調試。同時，它提供圖形化界面，簡化了項目參數的配置過程。簡單來説ESP-IDF插件通過圖形化方式結合ESP-IDF和ESP-IDF Tools，對項目進行構建，從而提升開發效率和用户體驗。
下圖是ESP-IDF插件、ESP-IDF Tools、ESP-IDF、ESP Component Registry和Project關係圖。

圖4.3.2.1 項目工程編譯關係圖
在項目開發過程中，ESP-IDF插件、ESP-IDF Tools、ESP-IDF（SDK）和ESP Component Registry協同工作，形成一個集成的開發流程。ESP-IDF插件提供了用户友好的圖形界面，允許開發者提交編譯、燒錄等命令，並接收調試反饋。ESP-IDF Tools負責處理項目需求和執行編譯、構建工作。ESP-IDF作為核心開發平台，提供了必要的核心組件，如BSP和RTOS，而ESP Component Registry則為開發者提供大量開源組件。最終，項目通過這些工具和組件庫完成構建，輸出最終的結果。
接下來，筆者將詳細介紹如何在VS Code集成開發環境下安裝ESP-IDF插件的具體步驟。
首先，打開VS Code軟件，按下快捷鍵“Ctrl + Shift + X”進入擴展頁面。在搜索欄中輸入“ESP-IDF”進行搜索，然後點擊“安裝”按鈕進行插件安裝。下圖展示了具體操作步驟。

圖4.3.2.2 下載與安裝ESP-IDF插件
按下快捷鍵“F1”或“Ctrl + Shift + P”打開“顯示所有命令”界面。然後，在搜索框中輸入“Configure ESP-IDF”，並從下拉菜單中選擇此選項，進入 ESP-IDF 配置界面，如下圖所示。

圖4.3.2.3 配置ESP-IDF擴展
回車後，將進入配置 ESP-IDF 插件的界面，如下圖所示。

圖4.3.2.4 進入ESP-IDF插件配置界面
在上圖中，點擊“USE EXISTING SETUP”使用現有的ESP-IDF，如下圖所示。

圖4.3.2.5 搜索當前系統的ESP-IDF
如果在“Search ESP-IDF in System”下看到你想要安裝的版本（例如上圖的v5.3），可以直接點擊該版本進行安裝。如果沒有找到所需版本，則點擊“Search ESP-IDF in System”選項進入手動配置，通過指定路徑來完成安裝，如下圖所示。

圖4.3.2.6 手動安裝ESP-IDF
在上圖中，首先選擇“Select download server”和“Select ESP-IDF version”選項，確保與上圖中的配置一致。接着，在“Enter ESP-IDF directory (IDF_PATH):”選項中設置為我們之前安裝ESP-IDF（SDK）的路徑，並在“Enter ESP-IDF Tools directory (IDF_TOOLS_PATH)”選項中設置為IDF_TOOLS_PATH/tools路徑（IDF_TOOLS_PATH路徑請看系統環境變量）。確保所有設置完成後，點擊上圖中的“install”按鈕，開始安裝ESP-IDF。
當出現下圖的所示，表示我們的ESP-IDF安裝成功。

圖4.3.2.7 ESP-IDF插件配置成功
至此，我們已經成功配置了ESP-IDF插件，並且完成了與ESP-IDF（SDK）和ESP-IDF Tools的集成。這使我們可以在VSCode集成開發環境下，順利進行項目的編譯、燒錄和調試工作，實現高效的開發流程。

4.3.3 VSCode的個性化配置（可選）
在Visual Studio Code（VS Code）中，settings.json文件用於存儲用户的個性化配置和工作環境設置。它控制了編輯器的外觀、代碼格式化風格、自動補全行為、調試配置等，配置可以分為用户設置（全局設置）和工作區設置（針對特定項目）。以下是配置settings.json文件的流程：
1，打開設置界面
菜單欄中選擇 文件 > 首選項 > 設置，進入 VS Code 的設置頁。
2，添加個性化配置和工作環境設置參數
添加內容如下：

{
    /* 上面的部分是我自己創建的一些設置 */ 
    "editor.insertSpaces": true,
    /* 自動插入空格禁用*/ 
    "editor.detectIndentation": true,
    /* 啓用時根據文件內容進行重寫*/ 
    "editor.renderControlCharacters": true,
    /* 是否顯示控制字符：啓用*/ 
    "editor.renderWhitespace": "all",
    /* 顯示4個空格是.... */ 
    "editor.tabSize": 4,
    /* tab 設置為4個空格*/ 
    "editor.fontSize": 18,
}

至此，我們已成功完成VS Code集成開發環境中ESP-IDF插件的安裝，並配置好了VS Code的工作環境。在接下來的章節中，筆者將詳細講解如何在VS Code IDE中新建一個ESP-IDF項目工程，並進一步探討工程的調試工具及相關配置的使用，以幫助大家更好地進行項目開發。