ESP-IDF (Espressif IoT Development Framework) 是樂鑫的ESP32芯片的開發框架，在VSCode中使用。雖然很多基於ESP32的開發板已經在PlatformIO中支持，但是目前ESP-IDF好像還不是PlatformIO原生的。值得注意的是，ESP使用xtensa的架構（也是gcc），而不是avr/arm的架構，在移植的時候跟avr/arm多少還是有一點點區別。
詳細安裝步驟
請根據下方詳細步驟，完成安裝過程。
第一步：安裝準備
爲了在 ESP32 中使用 ESP-IDF，需要根據操作系統安裝一些軟件包。以下安裝指南可協助您安裝 Linux 和 macOS 的系統上所有需要的軟件包。
Linux 用戶
編譯 ESP-IDF 需要以下軟件包。請根據使用的 Linux 發行版本，選擇合適的安裝命令。
-
Ubuntu 和 Debian:
sudo apt-get install git wget flex bison gperf python3 python3-pip python3-setuptools cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0
CentOS 7 & 8:
sudo yum -y update && sudo yum install git wget flex bison gperf python3 python3-pip python3-setuptools cmake ninja-build ccache dfu-util libusbx
目前仍然支持 CentOS 7，但爲了更好的用戶體驗，建議使用 CentOS 8。
-
Arch:
sudo pacman -S --needed gcc git make flex bison gperf python-pip cmake ninja ccache dfu-util libusb
註解
-
使用 ESP-IDF 需要 CMake 3.5 或以上版本。較早的 Linux 發行版可能需要升級自身的軟件源倉庫，或開啓 backports 套件庫，或安裝 “cmake3” 軟件包（不是安裝 “cmake”）。
-
如果上述列表中沒有您使用的系統，請參考您所用系統的相關文檔，查看安裝軟件包所用的命令。
macOS 用戶
ESP-IDF 將使用 macOS 上默認安裝的 Python 版本。
-
安裝 pip:
sudo easy_install pip
安裝 CMake 和 Ninja 編譯工具：
若有 HomeBrew，您可以運行:
brew install cmake ninja dfu-util
若有 MacPorts，您可以運行:
sudo port install cmake ninja dfu-util
-
-
強烈建議同時安裝 ccache 以獲得更快的編譯速度。如有 HomeBrew，可通過 MacPorts 上的
brew install ccache或sudo port install ccache完成安裝。
註解
如您在上述任何步驟中遇到以下錯誤:
xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun
則必須安裝 XCode 命令行工具，可運行 xcode-select --install 命令進行安裝。
安裝 Python 3
Catalina 10.15 發佈說明 中表示不推薦使用 Python 2.7 版本，在未來的 macOS 版本中也不會默認包含 Python 2.7。執行以下命令來檢查您當前使用的 Python 版本:
python --version
如果輸出結果是 Python 2.7.17，則代表您的默認解析器是 Python 2.7。這時需要您運行以下命令檢查電腦上是否已經安裝過 Python 3:
python3 --version
如果運行上述命令出現錯誤，則代表電腦上沒有安裝 Python 3。
請根據以下步驟安裝 Python 3：
使用 HomeBrew 進行安裝的方法如下:
brew install python3
使用 MacPorts 進行安裝的方法如下:
sudo port install python38
第二步：獲取 ESP-IDF
在圍繞 ESP32 構建應用程序之前，請先獲取樂鑫提供的軟件庫文件 ESP-IDF 倉庫。
獲取 ESP-IDF 的本地副本：打開終端，切換到您要保存 ESP-IDF 的工作目錄，使用 git clone 命令克隆遠程倉庫。針對不同操作系統的詳細步驟，請見下文。
打開終端，運行以下命令：
mkdir -p ~/esp
cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.git
ESP-IDF 將下載至 ~/esp/esp-idf。
請前往 ESP-IDF 版本簡介，查看 ESP-IDF 不同版本的具體適用場景。
第三步：設置工具
除了 ESP-IDF 本身，您還需要爲支持 ESP32 的項目安裝 ESP-IDF 使用的各種工具，比如編譯器、調試器、Python 包等。
cd ~/esp/esp-idf
./install.sh esp32
或使用 Fish shell：
cd ~/esp/esp-idf
./install.fish esp32
上述命令僅僅爲 ESP32 安裝所需工具。如果需要爲多個目標芯片開發項目，則可以一次性指定多個目標，如下所示:
.. code-block:: bash
cd ~/esp/esp-idf ./install.sh esp32,esp32s2
或使用 Fish shell：
cd ~/esp/esp-idf
./install.fish esp32,esp32s2
如果需要一次性爲所有支持的目標芯片安裝工具，可以運行如下命令：
cd ~/esp/esp-idf
./install.sh all
或使用 Fish shell：
cd ~/esp/esp-idf
./install.fish all
下載工具備選方案
ESP-IDF 工具安裝器會下載 Github 發佈版本中附帶的一些工具，如果訪問 Github 較爲緩慢，可以設置一個環境變量，從而優先選擇 Espressif 的下載服務器進行 Github 資源下載。
註解
該設置隻影響從 Github 發佈版本中下載的單個工具，它並不會改變訪問任何 Git 倉庫的 URL。
要在安裝工具時優先選擇 Espressif 下載服務器，請在運行 install.sh 時使用以下命令：
cd ~/esp/esp-idf export IDF_GITHUB_ASSETS="dl.espressif.com/github_assets" ./install.sh
自定義工具安裝路徑
本步驟中介紹的腳本將 ESP-IDF 所需的編譯工具默認安裝在用戶的根目錄中，即 Linux 系統中的 $HOME/.espressif 目錄。您可以選擇將工具安裝到其他目錄中，但請在運行安裝腳本前，重新設置環境變量 IDF_TOOLS_PATH。注意，請確保您的用戶賬號已經具備了讀寫該路徑的權限。
如果修改了 IDF_TOOLS_PATH 變量，請確保該變量在每次執行安裝腳本 (install.bat、install.ps1 或 install.sh) 和導出腳本 (export.bat、export.ps1 或 export.sh) 均保持一致。
第四步：設置環境變量
此時，您剛剛安裝的工具尚未添加至 PATH 環境變量，無法通過“命令窗口”使用這些工具。因此，必須設置一些環境變量。這可以通過 ESP-IDF 提供的另一個腳本進行設置。
請在需要運行 ESP-IDF 的終端窗口運行以下命令：
. $HOME/esp/esp-idf/export.sh
對於 fish shell（僅支持 fish 3.0.0 及以上版本），請運行以下命令：
. $HOME/esp/esp-idf/export.fish
注意，命令開始的 “.” 與路徑之間應有一個空格！
如果您需要經常運行 ESP-IDF，您可以爲執行 export.sh 創建一個別名，具體步驟如下：
-
複製並粘貼以下命令到 shell 配置文件中（
.profile、.bashrc、.zprofile等）alias get_idf='. $HOME/esp/esp-idf/export.sh'
-
通過重啓終端窗口或運行
source [path to profile]，如source ~/.bashrc來刷新配置文件。
現在您可以在任何終端窗口中運行 get_idf 來設置或刷新 esp-idf 環境。
不建議直接將 export.sh 添加到 shell 的配置文件。這樣做會導致在每個終端會話中都激活 IDF 虛擬環境（包括無需使用 IDF 的會話）。這違背了使用虛擬環境的目的，還可能影響其他軟件的使用。
第五步：開始使用 ESP-IDF 吧
現在您已經具備了使用 ESP-IDF 的所有條件，接下來將介紹如何開始您的第一個工程。
本指南將幫助您完成使用 ESP-IDF 的第一步。按照本指南，您將能使用 ESP32 開始創建第一個工程，並構建、燒錄和監控設備輸出。
註解
如果您還沒有安裝 ESP-IDF，請前往 安裝 並按照說明操作，以獲得使用本指南所需的所有軟件。
開始創建工程
現在，您可以開始準備開發 ESP32 應用程序了。您可以從 ESP-IDF 中 examples 目錄下的 get-started/hello_world 工程開始。
重要
ESP-IDF 編譯系統不支持 ESP-IDF 路徑或其工程路徑中帶有空格。
將 get-started/hello_world 工程複製至您本地的 ~/esp 目錄下：
Windows 操作系統
cd %userprofile%\esp xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world
Linux 和 macOS 操作系統
cd ~/esp cp -r $IDF_PATH/examples/get-started/hello_world .
註解
ESP-IDF 的 examples 目錄下有一系列示例工程，您可以按照上述方法複製並運行其中的任何示例，也可以直接編譯示例，無需進行復制。
連接設備
現在，請將您的 ESP32 開發板連接到 PC，並查看開發板使用的串口。
通常，串口在不同操作系統下顯示的名稱有所不同：
-
Windows 操作系統：
COM1等 -
Linux 操作系統： 以
/dev/tty開始 -
macOS 操作系統： 以
/dev/cu.開始
有關如何查看串口名稱的詳細信息，請見 與 ESP32 創建串口連接。
註解
請記住串口名，您會在後續步驟中使用。
配置工程
請進入 hello_world 目錄，設置 ESP32 爲目標芯片，然後運行工程配置工具 menuconfig。
Windows 操作系統
cd %userprofile%\esp\hello_world idf.py set-target esp32 idf.py menuconfig
Linux 和 macOS 操作系統
cd ~/esp/hello_world
idf.py set-target esp32
idf.py menuconfig
打開一個新工程後，應首先使用 idf.py set-target esp32 設置“目標”芯片。注意，此操作將清除並初始化項目之前的編譯和配置（如有）。 您也可以直接將“目標”配置爲環境變量（此時可跳過該步驟）。更多信息，請見 選擇目標芯片。
如果之前的步驟都正確，則會顯示下面的菜單：
工程配置 — 主窗口
您可以通過此菜單設置項目的具體變量，包括 Wi-Fi 網絡名稱、密碼和處理器速度等。hello_world 示例項目會以默認配置運行，因此可以跳過使用 menuconfig 進行項目配置這一步驟。
注意
如果您使用的是 ESP32-DevKitC（板載 ESP32-SOLO-1 模組）或 ESP32-DevKitM-1（板載 ESP32-MINI-1(1U) 模組），請在燒寫示例程序前，前往 menuconfig 中使能單核模式（CONFIG_FREERTOS_UNICORE）。
註解
您終端窗口中顯示出的菜單顏色可能會與上圖不同。您可以通過選項 --style 來改變外觀。請運行 idf.py menuconfig --help 命令，獲取更多信息。
編譯工程
請使用以下命令，編譯燒錄工程：
idf.py build
運行以上命令可以編譯應用程序和所有 ESP-IDF 組件，接着生成引導加載程序、分區表和應用程序二進制文件。
$ idf.py build Running cmake in directory /path/to/hello_world/build Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"... Warn about uninitialized values. -- Found Git: /usr/bin/git (found version "2.17.0") -- Building empty aws_iot component due to configuration -- Component names: ... -- Component paths: ... ... (more lines of build system output) [527/527] Generating hello_world.bin esptool.py v2.3.1 Project build complete. To flash, run this command: ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello_world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin or run 'idf.py -p PORT flash'
如果一切正常，編譯完成後將生成 .bin 文件。
燒錄到設備
請使用以下命令，將剛剛生成的二進制文件 (bootloader.bin、partition-table.bin 和 hello_world.bin) 燒錄至您的 ESP32 開發板：
idf.py -p PORT [-b BAUD] flash
請將 PORT 替換爲 ESP32 開發板的串口名稱。
您還可以將 BAUD 替換爲您希望的燒錄波特率。默認波特率爲 460800。
更多有關 idf.py 參數的詳情，請見 idf.py。
註解
勾選 flash 選項將自動編譯並燒錄工程，因此無需再運行 idf.py build。
燒錄過程中可能遇到的問題
如果在運行給定命令時出現如“連接失敗”這樣的錯誤，造成該錯誤的原因之一可能是運行 esptool.py 時出現錯誤。esptool.py 是構建系統調用的程序，用於重置芯片、與 ROM 引導加載器交互以及燒錄固件的工具。可以按照以下步驟進行手動復位，輕鬆解決該問題。如果問題仍未解決，請參考 Troubleshooting. 獲取更多信息。
esptool.py 通過使 USB 轉串口轉接器芯片（如 FTDI 或 CP210x）的 DTR 和 RTS 控制線生效來自動復位 ESP32（請參考 與 ESP32 創建串口連接 獲取更多詳細信息)。DTR 和 RTS 控制線又連接到 ESP32 的 GPIO0 和 CHIP_PU (EN) 管腳上，因此 DTR 和 RTS 的電壓電平變化會使 ESP32 進入固件下載模式。相關示例可查看 ESP32 DevKitC 開發板的 原理圖。
一般來說，使用官方的 ESP-IDF 開發板不會出現問題。但是，esptool.py 在以下情況下不能自動重置硬件。
-
您的硬件沒有連接到
GPIO0和CIHP_PU的 DTR 和 RTS 控制線。 -
DTR 和 RTS 控制線的配置方式不同
-
根本沒有這樣的串行控制線路
根據您硬件的種類，也可以將您 ESP32 開發板手動設置成固件下載模式（復位）。
-
對於 Espressif 的開發板，您可以參考對應開發板的入門指南或用戶指南。例如，可以通過按住 Boot 按鈕 (
GPIO0) 再按住 EN 按鈕(CHIP_PU) 來手動復位 ESP-IDF 開發板。 -
對於其他類型的硬件，可以嘗試將
GPIO0拉低。
常規操作
在燒錄過程中，您會看到類似如下的輸出日誌：
... esptool.py --chip esp32 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode dio --flash_freq 40m --flash_size 2MB 0x8000 partition_table/partition-table.bin 0x1000 bootloader/bootloader.bin 0x10000 hello_world.bin esptool.py v3.0-dev Serial port /dev/ttyUSB0 Connecting........_ Chip is ESP32D0WDQ6 (revision 0) Features: WiFi, BT, Dual Core, Coding Scheme None Crystal is 40MHz MAC: 24:0a:c4:05:b9:14 Uploading stub... Running stub... Stub running... Changing baud rate to 460800 Changed. Configuring flash size... Compressed 3072 bytes to 103... Writing at 0x00008000... (100 %) Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (effective 5962.8 kbit/s)... Hash of data verified. Compressed 26096 bytes to 15408... Writing at 0x00001000... (100 %) Wrote 26096 bytes (15408 compressed) at 0x00001000 in 0.4 seconds (effective 546.7 kbit/s)... Hash of data verified. Compressed 147104 bytes to 77364... Writing at 0x00010000... (20 %) Writing at 0x00014000... (40 %) Writing at 0x00018000... (60 %) Writing at 0x0001c000... (80 %) Writing at 0x00020000... (100 %) Wrote 147104 bytes (77364 compressed) at 0x00010000 in 1.9 seconds (effective 615.5 kbit/s)... Hash of data verified. Leaving... Hard resetting via RTS pin... Done
如果一切順利，燒錄完成後，開發板將會復位，應用程序 “hello_world” 開始運行。
如果您希望使用 Eclipse 或是 VS Code IDE，而非 idf.py，請參考 Eclipse 指南，以及 VS Code 指南。
監視輸出
您可以使用 idf.py -p PORT monitor 命令，監視 “hello_world” 工程的運行情況。注意，不要忘記將 PORT 替換爲您的串口名稱。
運行該命令後，IDF 監視器 應用程序將啓動：:
$ idf.py -p <PORT> monitor Running idf_monitor in directory [...]/esp/hello_world/build Executing "python [...]/esp-idf/tools/idf_monitor.py -b 115200 [...]/esp/hello_world/build/hello_world.elf"... --- idf_monitor on <PORT> 115200 --- --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H --- ets Jun 8 2016 00:22:57 rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) ets Jun 8 2016 00:22:57 ...
此時，您就可以在啓動日誌和診斷日誌之後，看到打印的 “Hello world!” 了。
...
Hello world!
Restarting in 10 seconds...
This is esp32 chip with 2 CPU core(s), WiFi/BT/BLE, silicon revision 1, 2MB external flash
Minimum free heap size: 298968 bytes
Restarting in 9 seconds...
Restarting in 8 seconds...
Restarting in 7 seconds...
您可使用快捷鍵 Ctrl+]，退出 IDF 監視器。
如果 IDF 監視器在燒錄後很快發生錯誤，或打印信息全是亂碼（如下），很有可能是因爲您的開發板採用了 26 MHz 晶振，而 ESP-IDF 默認支持大多數開發板使用的 40 MHz 晶振。
此時，您可以：
-
退出監視器。
-
返回 menuconfig。
-
進入
Component config–>ESP32-specific–>Main XTAL frequency進行配置，將 CONFIG_ESP32_XTAL_FREQ_SEL 設置爲 26 MHz。 -
重新 編譯和燒錄 應用程序。
註解
您也可以運行以下命令，一次性執行構建、燒錄和監視過程：
idf.py -p PORT flash monitor
此外，
恭喜，您已完成 ESP32 的入門學習！
現在，您可以嘗試一些其他 examples，或者直接開發自己的應用程序。
重要
一些示例程序不支持 ESP32，因爲 ESP32 中不包含所需的硬件。
在編譯示例程序前請查看 README 文件中 Supported Targets 表格。如果表格中包含 ESP32， 或者不存在這個表格，那麼即表示 ESP32 支持這個示例程序。
其他提示
權限問題 /dev/ttyUSB0
使用某些 Linux 版本向 ESP32 燒錄固件時，可能會出現 Failed to open port /dev/ttyUSB0 錯誤消息。此時可以將用戶添加至 Linux Dialout 組。
建議：更新 ESP-IDF
樂鑫會不時推出新版本的 ESP-IDF，修復 bug 或提供新的功能。請注意，EESP-IDF 的每個主要版本和次要版本都有相應的支持期限。支持期限滿後，版本停止更新維護，用戶可將項目升級到最新的 ESP-IDF 版本。更多關於支持期限的信息，請參考 ESP-IDF 版本。
因此，您在使用時，也應注意更新您本地的版本。最簡單的方法是：直接刪除您本地的 esp-idf 文件夾，然後按照 第二步：獲取 ESP-IDF 中的指示，重新完成克隆。
另一種方法是僅更新變更的部分。具體方式，請前往 更新 ESP-IDF 章節查看。具體更新步驟會根據您使用的 ESP-IDF 版本有所不同。
注意，更新完成後，請再次運行安裝腳本，以防新版 ESP-IDF 所需的工具也有所更新。具體請參考 第三步：設置工具。
一旦重新安裝好工具，請使用導出腳本更新環境，具體請參考 第四步：設置環境變量。