本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Espressif ESP32-DevKitC 和 ESP-WROVER-KIT 入門
<a name="getting_started_espressif"></a>

**重要**  <a name="deprecation-message"></a>
此參考整合託管在已棄用的 Amazon-FreeRTOS 儲存庫上。我們建議您在建立新專案時從[這裡開始](freertos-getting-started-modular.md)。如果您已經有以現在已棄用的 Amazon-FreeRTOS 儲存庫為基礎的現有 FreeRTOS 專案，請參閱 [Amazon-FreeRTOS Github 儲存庫遷移指南](github-repo-migration.md)。 FreeRTOS 

**注意**  
若要探索如何在您自己的 Espressif IDF 專案中整合 FreeRTOS 模組化程式庫和示範，請參閱我們的 [ ESP32-C3 平台特色參考整合](https://www.freertos.org/featured-freertos-iot-integration-targeting-an-espressif-esp32-c3-risc-v-mcu/)。

遵循本教學課程，開始使用配備 ESP32-WROOM-32、ESP32-SOLO-1 或 ESP-WROVER 模組的 Espressif ESP32-DevKitC，以及 ESP-WROVER-KIT-VB。 ESP32-WROOM-32 ESP32-SOLO-1 若要從合作夥伴裝置目錄上的 AWS 合作夥伴購買，請使用以下連結：
+ [ESP32-WROOM-32 DevKitC](https://devices.amazonaws.com/detail/a3G0L00000AANtjUAH/ESP32-DevKitC)
+ [ESP32-SOLO-1](https://devices.amazonaws.com/detail/a3G0h0000076lSMEAY)
+ [ ESP32-WROVER-KIT](https://devices.amazonaws.com/detail/a3G0L00000AANtlUAH/ESP-WROVER-KIT)

FreeRTOS 支援這些版本的開發板。

如需這些主機板最新版本的詳細資訊，請參閱 Espressif 網站上的 [ ESP32-DevKitC V4](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/hw-reference/modules-and-boards.html#esp32-devkitc-v4) 或 [ ESP-WROVER-KIT v4.1。](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/hw-reference/modules-and-boards.html#esp-wrover-kit-v4-1)

**注意**  
目前，ESP32-WROVER-KIT 和 ESP DevKitC 的 FreeRTOS 連接埠不支援對稱多處理 (SMP) 功能。

## 概觀
<a name="getting_started_espressif-overview"></a>

本教學課程將指引您完成下列步驟：

1. 將主機板連線到主機機器。

1. 在主機機器上安裝軟體以對微控制器主機板的內嵌應用程式進行開發和除錯。

1. 將 FreeRTOS 示範應用程式跨編譯至二進位映像。

1. 將應用程式二進位映像載入主機板，然後執行應用程式。

1. 透過序列連線與在開發板上執行的應用程式互動，以便進行監控和除錯。

## 先決條件
<a name="setup-espressif-prereqs"></a>

在 Espressif 電路板上開始使用 FreeRTOS 之前，您必須設定 AWS 您的帳戶和許可。

### 註冊 AWS 帳戶
<a name="sign-up-for-aws"></a>

若要開始使用 AWS，您需要 AWS 帳戶。如需建立 的相關資訊 AWS 帳戶，請參閱《 *AWS 帳戶管理 參考指南*》中的 [入門 AWS 帳戶](https://docs.aws.amazon.com//accounts/latest/reference/getting-started.html)。

若要提供存取權，請新增權限至您的使用者、群組或角色：
+ 中的使用者和群組 AWS IAM Identity Center：

  建立權限合集。請按照《*AWS IAM Identity Center 使用者指南*》中的[建立權限合集](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html)說明進行操作。
+ 透過身分提供者在 IAM 中管理的使用者：

  建立聯合身分的角色。遵循《*IAM 使用者指南*》的[為第三方身分提供者 (聯合) 建立角色](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html)中的指示。
+ IAM 使用者：
  + 建立您的使用者可擔任的角色。請按照《*IAM 使用者指南*》的[為 IAM 使用者建立角色](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html)中的指示。
  + (不建議) 將政策直接附加至使用者，或將使用者新增至使用者群組。請遵循《*IAM 使用者指南*》的[新增許可到使用者 (主控台)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) 中的指示。

## 開始使用
<a name="setup-espressif-idf42"></a>

**注意**  
本教學課程中的 Linux 命令要求您使用 Bash shell。

1. **設定 Espressif 硬體。**
   + 如需有關設定 ESP32-DevKitC 開發板硬體的資訊，請參閱 [ ESP32-DevKitC V4 入門指南](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/hw-reference/esp32/get-started-devkitc.html)。
   + 如需有關設定 ESP-WROVER-KIT 開發板硬體的資訊，請參閱 [ ESP-WROVER-KIT V4.1 入門指南。](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/hw-reference/esp32/get-started-wrover-kit.html)
**重要**  
當您到達 Espressif 指南的**入門**區段時，請停止，然後返回此頁面的指示。

1. 從 [GitHub](https://github.com/aws/amazon-freertos) 下載 Amazon FreeRTOS。（如需說明，請參閱 [README.md](https://github.com/aws/amazon-freertos/blob/main/README.md) 檔案。)

1. **設定您的開發環境**。

   若要與您的主機板通訊，您必須安裝工具鏈。Espressif 提供 ESP-IDF 來為其主機板開發軟體。由於 ESP-IDF 有自己的 FreeRTOS 核心版本整合為元件，因此 Amazon FreeRTOS 包含已移除 FreeRTOS 核心的 ESP-IDF v4.2 自訂版本。這可以修正編譯時重複檔案的問題。若要使用 Amazon FreeRTOS 隨附的 ESP-IDF 4.2 版自訂版本，請遵循下列適用於主機機器作業系統的說明。

   **Windows**

   1. 下載 ESP-IDF 的 [ Universal Online Installer](https://dl.espressif.com/dl/esp-idf/?idf=4.2) for Windows。

   1. 執行 **Universal Online Installer**。

   1. 當您前往步驟**下載或使用 ESP-IDF** 時，請選取**使用現有的 ESP-IDF 目錄**，並將**選擇現有的 ESP-IDF 目錄**設定為 `{{freertos}}/vendors/espressif/esp-idf`。

   1. 完成安裝。

   **macOS **

   1. 請遵循 [ macOS 的工具鏈先決條件標準設定 (ESP-IDF v4.2) ](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/get-started/macos-setup.html)中的指示。
**重要**  
當您達到**後續步驟**下的「取得 ESP-IDF」指示時，請停止，然後返回此頁面的指示。

   1. 開啟命令列視窗。

   1. 導覽至 FreeRTOS 下載目錄，然後執行下列指令碼，為您的平台下載並安裝 espressif 工具鏈。

      ```
      vendors/espressif/esp-idf/install.sh
      ```

   1. 使用下列命令，將 ESP-IDF 工具鏈工具新增至終端機的路徑。

      ```
      source vendors/espressif/esp-idf/export.sh
      ```

   **Linux**

   1. 請遵循適用於 [ Linux 的工具鏈先決條件標準設定 (ESP-IDF v4.2)](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/get-started/linux-setup.html) 中的指示。
**重要**  
當您達到**後續步驟**下的「取得 ESP-IDF」指示時，請停止，然後返回此頁面的指示。

   1. 開啟命令列視窗。

   1. 導覽至 FreeRTOS 下載目錄，然後執行下列指令碼，為您的平台下載並安裝 Espressif 工具鏈。

      ```
      vendors/espressif/esp-idf/install.sh
      ```

   1. 使用下列命令，將 ESP-IDF 工具鏈工具新增至終端機的路徑。

      ```
      source vendors/espressif/esp-idf/export.sh
      ```

1. **建立序列連線。**

   1. 若要在主機機器與 ESP32-DevKitC 之間建立序列連線，您必須安裝 CP210x USB 至 UART Bridge VCP 驅動程式。您可以從 [Silicon Labs](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers) 下載這些驅動程式。

      若要在主機機器與 ESP32-WROVER-KIT 之間建立序列連線，您必須安裝 FTDI 虛擬 COM 連接埠驅動程式。您可以從 [FTDI](https://www.ftdichip.com/Drivers/VCP.htm) 下載此驅動程式。

   1. 依照步驟[建立與 ESP32 的序列連線](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/get-started/establish-serial-connection.html)。

   1. 在您建立序連接之後，請記下開發板連接的序列連接埠。您需要它來刷新示範。

### 設定 FreeRTOS 示範應用程式
<a name="configure-demos-espressif-idf42"></a>

在本教學課程中，FreeRTOS 組態檔案位於 `{{freertos}}/vendors/espressif/boards/{{board-name}}/aws_demos/config_files/FreeRTOSConfig.h`。（例如，如果選擇 `AFR_BOARD espressif.esp32_devkitc` ，則組態檔案位於 `{{freertos}}/vendors/espressif/boards/esp32/aws_demos/config_files/FreeRTOSConfig.h`。) 

1. 如果您正在執行 macOS 或 Linux，請開啟終端機提示。如果您正在執行 Windows，請開啟「ESP-IDF 4.x CMD」應用程式 （如果您在安裝 ESP-IDF 工具鏈時包含此選項），否則請開啟「命令提示」應用程式。

1. 若要確認您已安裝 Python3，請執行 

   ```
   python --version
   ```

   安裝的版本即會顯示。如果您沒有安裝 Python 3.0.1 或更新版本，您可以從 [Python](https://www.python.org/downloads/) 網站安裝。

1. 您需要 AWS 命令列界面 (CLI) 才能執行 AWS IoT 命令。如果您執行 Windows，請使用 AWS `easy_install awscli`命令在「命令」或「ESP-IDF 4.x CMD」應用程式中安裝 CLI。

   如果您正在執行 macOS 或 Linux，請參閱[安裝 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/installing.html)。

1. 執行

   ```
   aws configure
   ```

   並使用您的 AWS 存取金鑰 ID、私密存取金鑰和預設 AWS 區域來設定 AWS CLI。如需詳細資訊，請參閱[設定 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)。

1. 使用下列命令來安裝適用於 Python (boto3) 的 AWS SDK：
   + 在 Windows 的「命令」或「ESP-IDF 4.x CMD」應用程式中，執行

     ```
     pip install boto3 --user
     ```
**注意**  
如需詳細資訊，請參閱 [Boto3 文件](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html)。
   + 在 macOS 或 Linux 上執行

     ```
     pip install tornado nose --user
     ```

     然後執行

     ```
     pip install boto3 --user
     ```

   FreeRTOS 包含`SetupAWS.py`指令碼，可讓您更輕鬆地設定要連線的 Espressif 電路板 AWS IoT。若要設定此指令碼，請開啟 `{{freertos}}/tools/aws_config_quick_start/configure.json` 並設定下列屬性：  
**`afr_source_dir`**  
您電腦上 `{{freertos}}` 目錄的完整路徑。請確定您使用斜線來指定此路徑。  
**`thing_name`**  
您要指派給代表電路板之 AWS IoT 物件的名稱。  
**`wifi_ssid`**  
您的 Wi-Fi 網路 SSID。  
**`wifi_password`**  
您 Wi-Fi 網路的密碼。  
**`wifi_security`**  
您 Wi-Fi 網路的安全類型。  
以下是有效的安全類型：  
   + `eWiFiSecurityOpen` (開放，不具安全性)
   + `eWiFiSecurityWEP` (WEP 安全性)
   + `eWiFiSecurityWPA` (WPA 安全性)
   + `eWiFiSecurityWPA2` (WPA2 安全性)

1. 執行組態指令碼。

   1. 如果您正在執行 macOS 或 Linux，請開啟終端機提示。如果您執行 Windows，請開啟「ESP-IDF 4.x CMD」或「命令」應用程式。

   1. 導覽至 `{{freertos}}/tools/aws_config_quick_start`目錄並執行 

      ```
      python SetupAWS.py setup
      ```

       指令碼會執行以下操作：
      + 建立 IoT 物件、憑證和政策。
      + 將 IoT 政策連接至憑證，並將憑證連接至 AWS IoT 物件。
      + 使用端點 AWS IoT 、Wi-Fi SSID 和登入資料填入`aws_clientcredential.h`檔案。
      + 格式化您的憑證和私有金鑰，並將其寫入`aws_clientcredential_keys.h`標頭檔案。
**注意**  
憑證為硬式編碼，僅供示範之用。生產層級應用程式必須將這些檔案存放在安全的位置。

      如需 的詳細資訊`SetupAWS.py`，請參閱 `README.md` `{{freertos}}/tools/aws_config_quick_start`目錄中的 。

### 監控雲端的 MQTT 訊息
<a name="gsg-espressif-monitor-mqtt"></a>

在執行 FreeRTOS 示範專案之前，您可以在 AWS IoT 主控台中設定 MQTT 用戶端，以監控裝置傳送至 AWS 雲端的訊息。

**使用 MQTT 用戶端訂閱 AWS IoT MQTT 主題**

1. 導覽至 [AWS IoT 主控台](https://console.aws.amazon.com/iotv2/)。

1. 在導覽窗格中，選擇**測試**，然後選擇 **MQTT 測試用戶端**。

1. 在**訂閱主題**中輸入 `{{your-thing-name}}/example/topic`，然後選擇**訂閱主題**。

當示範專案在您的裝置上成功執行時，您會看到「Hello World！」 多次傳送到您訂閱的主題。

### 使用 idf.py 指令碼建置、刷新和執行 FreeRTOS 示範專案
<a name="build-and-run-example-espressif-idf42"></a>

您可以使用 Espressif 的 IDF 公用程式 (`idf.py`) 來建置專案，並將二進位檔刷入您的裝置。

**注意**  
有些設定可能需要搭配 使用連接埠選項`"-p port-name"``idf.py`來指定正確的連接埠，如下列範例所示。  

```
idf.py -p /dev/cu.usbserial-00101301B flash
```

**在 Windows、Linux 和 macOS (ESP-IDF v4.2) 上建置和刷新 FreeRTOS macOS**

1. 導覽至 FreeRTOS 下載目錄的根目錄。

1. 在命令列視窗中，輸入下列命令，將 ESP-IDF 工具新增至終端機的 PATH。  
**Windows (「命令」應用程式）**  

   ```
   vendors\espressif\esp-idf\export.bat
   ```  
**Windows ("ESP-IDF 4.x CMD" 應用程式）**  
（這已經在您開啟應用程式時完成。)  
**Linux/macOS**  

   ```
   source vendors/espressif/esp-idf/export.sh
   ```

1. 在 `build`目錄中設定 cmake，並使用下列命令建置韌體映像。

   ```
   idf.py -DVENDOR=espressif -DBOARD=esp32_wrover_kit -DCOMPILER=xtensa-esp32 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 檔案。

1. 使用以下命令清除開發板的快閃記憶體。

   ```
   idf.py erase_flash
   ```

1. 使用`idf.py`指令碼將應用程式二進位檔刷新到您的主機板。

   ```
   idf.py flash
   ```

1. 使用下列命令來監控主機板序列埠的輸出。

   ```
   idf.py monitor
   ```
**注意**  
您可以在下列範例中結合這些命令，例如 。  

   ```
   idf.py erase_flash flash monitor
   ```

   對於某些主機機器設定，您必須在刷新主機板時指定連接埠，如下列範例所示。

   ```
   idf.py erase_flash flash monitor -p /dev/ttyUSB1
   ```

### 使用 CMake 建置和 Flash FreeRTOS
<a name="flash-espressif-cmake-idf42"></a>

除了 IDF 開發套件提供的`idf.py`指令碼來建置和執行程式碼之外，您也可以使用 CMake 建置專案。目前，它支援 Unix Makefiles 或 Ninja 組建系統。

**建置和刷新專案**

1. 在命令列視窗中，導覽至 FreeRTOS 下載目錄的根目錄。

1. 執行下列指令碼，將 ESP-IDF 工具新增至 shell 的 PATH。  
**Windows**  

   ```
   vendors\espressif\esp-idf\export.bat
   ```  
**Linux/macOS**  

   ```
   source vendors/espressif/esp-idf/export.sh
   ```

1. 輸入下列命令以產生建置檔案。  
**使用 Unix Makefiles**  

   ```
   cmake -DVENDOR=espressif -DBOARD=esp32_wrover_kit -DCOMPILER=xtensa-esp32 -S . -B ./YOUR_BUILD_DIRECTORY -DAFR_ENABLE_ALL_MODULES=1 -DAFR_ENABLE_TESTS=0
   ```  
**使用 Ninja**  

   ```
   cmake -DVENDOR=espressif -DBOARD=esp32_wrover_kit -DCOMPILER=xtensa-esp32 -S . -B ./YOUR_BUILD_DIRECTORY -DAFR_ENABLE_ALL_MODULES=1 -DAFR_ENABLE_TESTS=0 -GNinja
   ```

1. 建置專案。  
**使用 Unix Makefiles**  

   ```
   make -C ./YOUR_BUILD_DIRECTORY -j8 
   ```  
**使用 Ninja**  

   ```
   ninja -C ./YOUR_BUILD_DIRECTORY -j8
   ```

1. 清除快閃記憶體，然後刷新電路板。  
**使用 Unix Makefiles**  

   ```
   make -C ./YOUR_BUILD_DIRECTORY erase_flash
   ```

   ```
   make -C ./YOUR_BUILD_DIRECTORY flash
   ```  
**使用 Ninja**  

   ```
   ninja -C ./YOUR_BUILD_DIRECTORY erase_flash
   ```

   ```
   ninja -C ./YOUR_BUILD_DIRECTORY flash
   ```

## 執行低功耗藍牙示範
<a name="espressif-run-ble"></a>

FreeRTOS 支援[低功耗藍牙程式庫](freertos-ble-library.md)連線。

若要跨低功耗藍牙執行 FreeRTOS 示範專案，您必須在 iOS 或 Android 行動裝置上執行 FreeRTOS 低功耗藍牙行動開發套件示範應用程式。

**設定 FreeRTOS 低功耗藍牙行動 SDK 示範應用程式**

1. 按照 [適用於 FreeRTOS 藍牙裝置的 Mobile SDKs](freertos-ble-mobile.md)中的指示，在您的主機電腦上下載並安裝適用於行動平台的軟體開發套件。

1. 按照 [FreeRTOS 低功耗藍牙行動 SDK 示範應用程式](ble-demo.md#ble-sdk-app) 中的指示，來在您的行動裝置上設定示範行動應用程式。

如需如何在主機板上執行 MQTT over Bluetooth 低功耗示範的說明，請參閱 [透過低功耗藍牙執行的 MQTT](ble-demo.md#ble-demo-mqtt)。

如需如何在主機板上執行 Wi-Fi 佈建示範的說明，請參閱 [Wi-Fi 佈建](ble-demo.md#ble-demo-wifi)。

## 在 ESP32 的 CMake 專案中使用 FreeRTOS
<a name="getting_started_espressif_cmake_project"></a>

如果您想要在自己的 CMake 專案中使用 FreeRTOS，您可以將它設定為子目錄，並與應用程式一起建置。首先，從 [GitHub](https://github.com/aws/amazon-freertos) 取得 FreeRTOS 的副本。您也可以使用下列命令將其設定為 Git 子模組，以便在未來更容易更新。

```
git submodule add -b release https://github.com/aws/amazon-freertos.git freertos
```

如果發行更新版本，您可以使用這些命令更新本機複本。

```
# Pull the latest changes from the remote tracking branch.
git submodule update --remote -- freertos
```

```
# Commit the submodule change because it is pointing to a different revision now.
git add freertos
```

```
git commit -m "Update FreeRTOS to a new release"
```

如果您的專案具有下列目錄結構：

```
- freertos (the copy that you obtained from GitHub or the AWS IoT console)
- src
  - main.c (your application code)
- CMakeLists.txt
```

然後，以下是最上層`CMakeLists.txt`檔案的範例，可用於與 FreeRTOS 一起建置您的應用程式。

```
cmake_minimum_required(VERSION 3.13)

project(freertos_examples)

# Tell IDF build to link against this target.
set(IDF_EXECUTABLE_SRCS "<complete_path>/src/main.c")
set(IDF_PROJECT_EXECUTABLE my_app)

# Add FreeRTOS as a subdirectory. AFR_BOARD tells which board to target.
set(AFR_BOARD espressif.esp32_devkitc CACHE INTERNAL "")
add_subdirectory(freertos)

# Link against the mqtt library so that we can use it. Dependencies are transitively
# linked.
target_link_libraries(my_app PRIVATE AFR::core_mqtt)
```

若要建置專案，請執行以下 CMake 命令。確保 ESP32 編譯器位於 PATH 環境變數中。

```
cmake -S . -B build-directory -DCMAKE_TOOLCHAIN_FILE=freertos/tools/cmake/toolchains/xtensa-esp32.cmake -GNinja 
```

```
cmake --build build-directory 
```

若要將應用程式刷新到您的主機板，請執行下列命令。

```
cmake --build build-directory --target flash 
```

### 使用 FreeRTOS 中的元件
<a name="getting_started_espressif_cmake_project_components"></a>

執行 CMake 之後，您可以在摘要輸出中找到所有可用的元件。它看起來應該類似下列範例。

```
====================Configuration for FreeRTOS====================
  Version:                 202107.00
  Git version:             202107.00-g79ad6defb

Target microcontroller:
  vendor:                  Espressif
  board:                   ESP32-DevKitC
  description:             Development board produced by Espressif that comes in two
                           variants either with ESP-WROOM-32 or ESP32-WROVER module
  family:                  ESP32
  data ram size:           520KB
  program memory size:     4MB

Host platform:
  OS:                      Linux-4.15.0-66-generic
  Toolchain:               xtensa-esp32
  Toolchain path:          /opt/xtensa-esp32-elf
  CMake generator:         Ninja

FreeRTOS modules:
  Modules to build:        backoff_algorithm, common, common_io, core_http,
                           core_http_demo_dependencies, core_json, core_mqtt,
                           core_mqtt_agent, core_mqtt_agent_demo_dependencies,
                           core_mqtt_demo_dependencies, crypto, defender, dev_mode_key_
                           provisioning, device_defender, device_defender_demo_
                           dependencies, device_shadow, device_shadow_demo_dependencies,
                           freertos_cli_plus_uart, freertos_plus_cli, greengrass,
                           http_demo_helpers, https, jobs, jobs_demo_dependencies,
                           kernel, logging, mqtt, mqtt_agent_interface, mqtt_demo_
                           helpers, mqtt_subscription_manager, ota, ota_demo_
                           dependencies, ota_demo_version, pkcs11, pkcs11_helpers,
                           pkcs11_implementation, pkcs11_utils, platform, secure_sockets,
                           serializer, shadow, tls, transport_interface_secure_sockets,
                           wifi
  Enabled by user:         common_io, core_http_demo_dependencies, core_json,
                           core_mqtt_agent_demo_dependencies, core_mqtt_demo_
                           dependencies, defender, device_defender, device_defender_demo_
                           dependencies, device_shadow, device_shadow_demo_dependencies,
                           freertos_cli_plus_uart, freertos_plus_cli, greengrass, https,
                           jobs, jobs_demo_dependencies, logging, ota_demo_dependencies,
                           pkcs11, pkcs11_helpers, pkcs11_implementation, pkcs11_utils,
                           platform, secure_sockets, shadow, wifi
  Enabled by dependency:   backoff_algorithm, common, core_http, core_mqtt,
                           core_mqtt_agent, crypto, demo_base, dev_mode_key_provisioning,
                           freertos, http_demo_helpers, kernel, mqtt, mqtt_agent_
                           interface, mqtt_demo_helpers, mqtt_subscription_manager, ota,
                           ota_demo_version, pkcs11_mbedtls, serializer, tls,
                           transport_interface_secure_sockets, utils
  3rdparty dependencies:   jsmn, mbedtls, pkcs11, tinycbor
  Available demos:         demo_cli_uart, demo_core_http, demo_core_mqtt, demo_core_mqtt_
                           agent, demo_device_defender, demo_device_shadow,
                           demo_greengrass_connectivity, demo_jobs, demo_ota_core_http,
                           demo_ota_core_mqtt, demo_tcp
  Available tests:
=========================================================================
```

您可以從`Modules to build`清單中參考任何元件。若要將它們連結到您的應用程式，請將`AFR::`命名空間放在名稱前面，例如 `AFR::core_mqtt`、 `AFR::ota`等。

### 使用 ESP-IDF 新增自訂元件
<a name="getting_started_espressif_cmake_project_espidf"></a>

您可以在使用 ESP-IDF 時新增更多元件。例如，假設你想要新增一個名為 `example_component` 的元件，並且你的專案看起來像這樣：

```
- freertos
- components
  - example_component
    - include
      - example_component.h
    - src
      - example_component.c
    - CMakeLists.txt
- src
  - main.c
- CMakeLists.txt
```

以下是 元件的 `CMakeLists.txt` 檔案範例。

```
add_library({{example_component}} {{src/example_component.c}})
target_include_directories({{example_component}} PUBLIC include)
```

然後，在最上層`CMakeLists.txt`檔案中，在 後面插入以下行來新增元件`add_subdirectory(freertos)`。

```
add_subdirectory({{component/example_component}}) 
```

然後，修改 `target_link_libraries`以包含您的元件。

```
target_link_libraries(my_app PRIVATE AFR::core_mqtt PRIVATE {{example_component}}) 
```

根據預設，此元件現在會自動連結至您的應用程式碼。您現在可以包含其標頭檔案，並呼叫其定義的函數。

### 覆寫 FreeRTOS 的組態
<a name="getting_started_espressif_cmake_project_override"></a>

目前沒有明確定義的方法來重新定義 FreeRTOS 來源樹狀目錄以外的組態。依預設，CMake 將尋找 `{{freertos}}/vendors/espressif/boards/esp32/aws_demos/config_files/` 和 `{{freertos}}/demos/include/` 目錄。不過，您可以使用因應措施，告訴編譯器首先搜尋其他目錄。例如，您可以為 FreeRTOS 組態新增另一個資料夾。

```
- freertos
- freertos-configs
  - aws_clientcredential.h
  - aws_clientcredential_keys.h
  - iot_mqtt_agent_config.h
  - iot_config.h
- components
- src
- CMakeLists.txt
```

`freertos-configs` 下的檔案是複製自 `{{freertos}}/vendors/espressif/boards/esp32/aws_demos/config_files/` 和 `{{freertos}}/demos/include/` 目錄。然後，在您的頂層`CMakeLists.txt`檔案中，在 之前新增此行，`add_subdirectory(freertos)`以便編譯器首先搜尋此目錄。

```
include_directories(BEFORE freertos-configs)
```

### 為 ESP-IDF 提供您自己的 sdkconfig
<a name="getting_started_espressif_providing_sdkconfig"></a>

如果你想要提供自己的 `sdkconfig.default`，則可以從命令行設定 CMake 變數 `IDF_SDKCONFIG_DEFAULTS`：

```
cmake -S . -B build-directory -DIDF_SDKCONFIG_DEFAULTS=path_to_your_sdkconfig_defaults -DCMAKE_TOOLCHAIN_FILE=freertos/tools/cmake/toolchains/xtensa-esp32.cmake -GNinja 
```

如果您未為自己的`sdkconfig.default`檔案指定位置，FreeRTOS 會使用位於 的預設檔案`{{freertos}}/vendors/espressif/boards/esp32/aws_demos/sdkconfig.defaults`。

如需詳細資訊，請參閱 Espressif *API 參考*中的[專案組態](https://docs.espressif.com/projects/esp-idf/en/v4.2-beta1/esp32s2/api-reference/kconfig.html)，如果您在成功編譯之後遇到問題，請參閱該頁面上[已棄用選項及其取代](https://docs.espressif.com/projects/esp-idf/en/v4.2-beta1/esp32s2/api-reference/kconfig.html#deprecated-options-and-their-replacements)的章節。

### 摘要
<a name="getting_started_espressif_cmake_project_summary"></a>

如果你有一個專案具有名為 `example_component` 的元件，而且你想要覆寫一些組態，則以下是頂層 `CMakeLists.txt` 檔案的完整範例。

```
cmake_minimum_required(VERSION 3.13)

project(freertos_examples)

set(IDF_PROJECT_EXECUTABLE my_app)
set(IDF_EXECUTABLE_SRCS "src/main.c")

# Tell IDF build to link against this target.
set(IDF_PROJECT_EXECUTABLE my_app)

# Add some extra components. IDF_EXTRA_COMPONENT_DIRS is a variable used by ESP-IDF
# to collect extra components.
get_filename_component(
    EXTRA_COMPONENT_DIRS
    "components/example_component" ABSOLUTE
)
list(APPEND IDF_EXTRA_COMPONENT_DIRS ${EXTRA_COMPONENT_DIRS})

# Override the configurations for FreeRTOS.
include_directories(BEFORE freertos-configs)

# Add FreeRTOS as a subdirectory. AFR_BOARD tells which board to target.
set(AFR_BOARD espressif.esp32_devkitc CACHE INTERNAL "")
add_subdirectory(freertos)

# Link against the mqtt library so that we can use it. Dependencies are transitively
# linked.
target_link_libraries(my_app PRIVATE AFR::core_mqtt)
```

## 疑難排解
<a name="getting_started_espressif_troubleshooting"></a>
+ 如果您正在執行 macOS 且作業系統無法辨識 ESP-WROVER-KIT，請確定您未安裝 D2XX 驅動程式。若要解除安裝這些驅動程式，請遵循 [FTDI Drivers Installation Guide for macOS X](http://www.ftdichip.com/Support/Documents/AppNotes/AN_134_FTDI_Drivers_Installation_Guide_for_MAC_OSX.pdf) 中的說明。
+ ESP-IDF 提供的監視器公用程式 （並使用 make monitor 叫用） 可協助您解碼地址。因此，它可協助您在應用程式停止運作時取得一些有意義的回溯。如需詳細資訊，請參閱 Espressif 網站上的[自動地址解碼](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/api-guides/tools/idf-monitor.html#automatic-address-decoding)。
+ 您也可以啟用 GDBstub 與 gdb 通訊，而不需要任何特殊的 JTAG 硬體。如需詳細資訊，請參閱 Espressif [ 網站上的使用 GDBStub 啟動 GDB](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/api-guides/tools/idf-monitor.html#launching-gdb-with-gdbstub)。
+ 如需在需要 JTAG 硬體型偵錯時設定 OpenOCD 型環境的相關資訊，請參閱 Espressif 網站上的 [ JTAG Debugging](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html)。
+ 如果`pyserial`無法在 macOS `pip` 上使用 安裝 ，請從 [pyserial 網站](https://pypi.org/simple/pyserial)下載。
+ 如果電路板持續重設，請嘗試在終端機上輸入下列命令來清除快閃記憶體。

  ```
  make erase_flash
  ```
+ 如果您在執行 `idf_monitor.py` 時看到錯誤，請使用 Python 2.7。
+ 從 ESP-IDF 取得的必要程式庫包含在 FreeRTOS 中，因此不需要從外部下載。如果已設定`IDF_PATH`環境變數，建議您在建置 FreeRTOS 之前將其清除。
+ 在 Windows 上，系統可能需要 3-4 分鐘來建置專案。若要縮短建置時間，您可以在 make 命令上使用 `-j4` 開關。

  ```
  make flash monitor -j4
  ```
+ 如果您的裝置無法連線至 AWS IoT，請開啟 `aws_clientcredential.h` 檔案，並確認檔案中已正確定義組態變數。 `clientcredentialMQTT_BROKER_ENDPOINT[]`看起來應該像 `1234567890123-ats.iot.us-east-1.amazonaws.com`。
+ 如果您遵循 [在 ESP32 的 CMake 專案中使用 FreeRTOS](#getting_started_espressif_cmake_project) 中的步驟，並且從連結器中看到未定義的參照錯誤，這通常是因為缺少相依程式庫或示範導致。若要新增這些項目，請使用標準 CMake 函數 `target_link_libraries` 更新 `CMakeLists.txt` 檔案 (在根目錄下)。
+ ESP-IDF v4.2 支援使用 *xtensa\\-esp32\\-elf\\-gcc 8\\.2\\.0\\. *工具鏈。如果您使用的是舊版 Xtensa 工具鏈，請下載必要的版本。
+ 如果您看到有關 ESP-IDF v4.2 未滿足的 Python 相依性的錯誤日誌，如下所示：

  ```
  The following Python requirements are not satisfied:
    click>=5.0
    pyserial>=3.0
    future>=0.15.2
    pyparsing>=2.0.3,<2.4.0
    pyelftools>=0.22
    gdbgui==0.13.2.0
    pygdbmi<=0.9.0.2
    reedsolo>=1.5.3,<=1.5.4
    bitstring>=3.1.6
    ecdsa>=0.16.0
    Please follow the instructions found in the "Set up the tools" section of ESP-IDF Getting Started Guide
  ```

  使用下列 Python 命令在您的平台上安裝 python 相依性：

  ```
  root/vendors/espressif/esp-idf/requirements.txt
  ```

如需更多故障診斷資訊，請參閱 [故障診斷入門](gsg-troubleshooting.md)。

## 除錯
<a name="getting_started_espressif_debugging"></a>

### Espressif ESP32-DevKitC 和 ESP-WROVER-KIT (ESP-IDF v4.2) 上的偵錯程式碼
<a name="debugging-espressif-idf42"></a>

本節說明如何使用 ESP-IDF v4.2 偵錯 Espressif 硬體。您需要 JTAG 對 USB 纜線。我們使用 USB 轉 MPSSE 纜線 （例如 [FTDI C232HM-DDHSL-0](http://www.ftdichip.com/Products/Cables/USBMPSSE.htm))。

**ESP-DevKitC JTAG 設定**  
對於 FTDI C232HM-DDHSL-0 纜線，這些是 ESP32 DevkitC 的連線。  

```
| C232HM-DDHSL-0 Wire Color | ESP32 GPIO Pin | JTAG Signal Name |
| ------------------------- | -------------- | ---------------- |
|  Brown (pin 5)            |  IO14          |  TMS             |
|  Yellow (pin 3)           |  IO12          |  TDI             |
|  Black (pin 10)           |  GND           |  GND             |
|  Orange (pin 2)           |  IO13          |  TCK             |
|  Green (pin 4)            |  IO15          |  TDO             |
```

**ESP-WROVER-KIT JTAG 設定**  
對於 FTDI C232HM-DDHSL-0 纜線，這些是 ESP32-WROVER-KIT 的連線。  

```
| C232HM-DDHSL-0 Wire Color | ESP32 GPIO Pin | JTAG Signal Name |
| ------------------------- | -------------- | ---------------- |
|  Brown (pin 5)            |  IO14          |  TMS             |
|  Yellow (pin 3)           |  IO12          |  TDI             |
|  Orange (pin 2)           |  IO13          |  TCK             |
|  Green (pin 4)            |  IO15          |  TDO             |
```
這些資料表是從 [FTDI C232HM-DDHSL-0 datasheet](https://www.ftdichip.com/Support/Documents/DataSheets/Cables/DS_C232HM_MPSSE_CABLE.pdf) 開發而來。如需詳細資訊，請參閱資料表中的「C232HM MPSSE 纜線連接和機械詳細資訊」一節。  
若要在 ESP-WROVER-KIT 上啟用 JTAG，請在 TMS、TDO、TDI、TCK 和 S\_TDI 接腳上放置跳線，如下所示。  

![跳接器置放](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/JP8-jumpers.png)


**Windows 上的偵錯 (ESP-IDF v4.2)**  

**在 Windows 中進行除錯設定**

1. 將 FTDI C232HM-DDHSL-0 的 USB 一端接到您的電腦，而另一端則按[Espressif ESP32-DevKitC 和 ESP-WROVER-KIT (ESP-IDF v4.2) 上的偵錯程式碼](#debugging-espressif-idf42)中所述進行。FTDI C232HM-DDHSL-0 裝置應該會出現在 **Universal Serial Bus Controllers (通用序列匯流排控制器)** 下方的 **Device Manager (裝置管理員)** 中。

1. 在通用序列匯流排裝置清單中，在 **C232HM-DDHSL-0** 裝置上按一下滑鼠右鍵，然後選擇**屬性**。
**注意**  
裝置可能會列為 **USB Serial Port (USB 序列連接埠)**。

   若要查看裝置的屬性，請在屬性視窗中，選擇**詳細資訊**索引標籤。如果未列出裝置，請安裝 [FTDI C232HM-DDHSL-0 的 Windows 驅動程式](http://www.ftdichip.com/Drivers/D2XX.htm)。

1. 在 **Details (詳細資訊)** 索引標籤中，選擇 **Property (屬性)**，然後選擇 **Hardware IDs (硬體 ID)**。您應該會在 **值** 欄位中看到類似的情況。

   ```
   FTDIBUS\COMPORT&VID_0403&PID_6014
   ```

   在此範例中，廠商 ID 為 0403，產品 ID 為 6014。

   確認這些 ID 符合 `projects/espressif/esp32/make/aws_demos/esp32_devkitj_v1.cfg` 中的 ID。IDs 是在以 開頭的行中指定，`ftdi_vid_pid`後面接著廠商 ID 和產品 ID。

   ```
   ftdi_vid_pid 0x0403 0x6014
   ```

1. 下載 [OpenOCD for Windows](https://github.com/espressif/openocd-esp32/releases)。

1. 將檔案解壓縮至 `C:\`，並新增 `C:\openocd-esp32\bin` 到您的系統路徑。

1. OpenOCD 需要 libusb，但預設不會在 Windows 中安裝。安裝 libusb：

   1. 請下載 [zadig.exe](https://zadig.akeo.ie)。

   1. 執行 `zadig.exe`。從 **Options (選項)** 功能表中，選擇 **List All Devices (列出所有裝置)**。

   1. 從下拉式選單中，選擇 **C232HM-DDHSL-0**。

   1. 在目標驅動程式欄位中，選擇綠色箭頭右側的 **WinUSB (WinUSB)**。

   1. 針對目標驅動程式欄位下的清單，選擇箭頭，然後選擇**安裝驅動程式**。選擇 **Replace Driver (取代驅動程式)**。

1. 開啟命令提示字元，導覽至 FreeRTOS 下載目錄的根目錄，然後執行下列命令。

   ```
   idf.py openocd
   ```

   將此命令提示保持開啟。

1. 開啟新的命令提示字元，導覽至 FreeRTOS 下載目錄的根目錄，然後執行

   ```
   idf.py flash monitor
   ```

1. 開啟另一個命令提示字元，導覽至 FreeRTOS 下載目錄的根目錄，並等待示範開始在您的電路板上執行。執行時，請執行

   ```
   idf.py gdb
   ```

   程式應該會在 `main` 函數中停止。
**注意**  
ESP32 支援最多兩個中斷點。

**在 macOS 上偵錯 (ESP-IDF v4.2)**  

1. 下載[適用於 macOS 的 FTDI 驅動程式](http://www.ftdichip.com/Drivers/VCP.htm)。

1. 下載 [OpenOCD](https://github.com/espressif/openocd-esp32/releases)。

1. 解壓縮已下載的 .tar 檔案，並將路徑設在 `.bash_profile` 到 `OCD_INSTALL_DIR/openocd-esp32/bin` 中。

1. 使用下列命令在 macOS `libusb`上安裝 。

   ```
   brew install libusb
   ```

1. 使用下列命令卸載序列連接埠驅動程式。

   ```
   sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver
   ```

1. 使用下列命令卸載序列連接埠驅動程式。

   ```
   sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver
   ```

1. 如果您執行的 macOS 版本高於 10.9，請使用下列命令來卸載 Apple FTDI 驅動程式。

   ```
   sudo kextunload -b com.apple.driver.AppleUSBFTDI
   ```

1. 使用下列命令來取得 FTDI 纜線的產品 ID 和廠商 ID。它列出連接的 USB 裝置。

   ```
   system_profiler SPUSBDataType
   ```

   的輸出`system_profiler`應如下所示。

   ```
      DEVICE:
   
      Product ID: product-ID
      Vendor ID: vendor-ID (Future Technology Devices International Limited)
   ```

1. 開啟 `projects/espressif/esp32/make/aws_demos/esp32_devkitj_v1.cfg` 檔案。裝置的廠商 ID 和產品 ID 是指定在開頭為 `ftdi_vid_pid` 的一行中。變更 ID 以符合來自前一個步驟中 `system_profiler` 輸出的 ID。

1. 開啟終端機視窗，導覽至 FreeRTOS 下載目錄的根目錄，然後使用下列命令來執行 OpenOCD。

   ```
   idf.py openocd
   ```

   保持此終端機視窗開啟。

1. 開啟新的終端機，並使用下列命令載入 FTDI 序列連接埠驅動程式。

   ```
   sudo kextload -b com.FTDI.driver.FTDIUSBSerialDriver
   ```

1. 導覽至 FreeRTOS 下載目錄的根目錄，然後執行 

   ```
   idf.py flash monitor
   ```

1. 開啟另一個新的終端機，導覽至 FreeRTOS 下載目錄的根目錄，然後執行

   ```
   idf.py gdb
   ```

   程式應該會在 `main` 停止。

**Linux 上的偵錯 (ESP-IDF v4.2)**  

1. 下載 [OpenOCD](https://github.com/espressif/openocd-esp32/releases)。解壓縮 tarball 並遵循讀我檔中的安裝指示。

1. 使用下列命令在 Linux 上安裝 libusb。

   ```
   sudo apt-get install libusb-1.0
   ```

1. 開啟終端機，並輸入 **ls -l /dev/ttyUSB\*** 以列出所有連接到您電腦的 USB 裝置。這可協助您檢查作業系統是否辨識電路板的 USB 連接埠。您應該會看到類似以下的輸出。

   ```
      $ls -l /dev/ttyUSB*
      crw-rw----    1    root    dialout    188,    0    Jul    10    19:04    /dev/ttyUSB0
      crw-rw----    1    root    dialout    188,    1    Jul    10    19:04    /dev/ttyUSB1
   ```

1. 登出再登入，並重新啟動電路板的電源，以讓變更生效。在終端機提示中，列出 USB 裝置。確定群組擁有者已從 變更為 `dialout` `plugdev`。

   ```
      $ls -l /dev/ttyUSB*
      crw-rw----    1    root    plugdev    188,    0    Jul    10    19:04    /dev/ttyUSB0
      crw-rw----    1    root    plugdev    188,    1    Jul    10    19:04    /dev/ttyUSB1
   ```

   數字小的 `/dev/ttyUSBn` 界面用於 JTAG 通訊。另一個界面會路由至 ESP32 的序列連接埠 (UART)，並用於將程式碼上傳至 ESP32 的快閃記憶體。

1. 在終端機視窗中，導覽至 FreeRTOS 下載目錄的根目錄，然後使用下列命令來執行 OpenOCD。

   ```
   idf.py openocd 
   ```

1. 開啟另一個終端機，導覽至 FreeRTOS 下載目錄的根目錄，然後執行下列命令。

   ```
   idf.py flash monitor 
   ```

1. 開啟另一個終端機，導覽 FreeRTOS 下載目錄的根目錄，然後執行下列命令：

   ```
   idf.py gdb
   ```

   程式應該會在 `main()` 中停止。