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

# Microchip Curiosity PIC32MZ EF 入門
<a name="getting_started_mch"></a>

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

**注意**  
根據與 Microchip 的協議，我們將從 FreeRTOS 參考整合儲存庫主分支中移除 Curiosity PIC32MZEF (DM320104)，並且不會再將其帶入新版本。Microchip 已發出[正式通知](https://www.microchip.com/DevelopmentTools/ProductDetails/PartNO/DM320104)，指出不再建議將 PIC32MZEF (DM320104) 用於新設計。PIC32MZEF 專案和原始程式碼仍然可以透過先前的版本標籤存取。Microchip 建議客戶使用 Curiosity [ PIC32MZ-EF-2.0 開發板 (DM320209)](https://devices.amazonaws.com/detail/a3G0h0000077I69EAE/Curiosity-PIC32MZ-EF-2-0-Development-Board) 進行新設計。PIC32MZv1 平台仍然可以在 FreeRTOS 參考整合儲存庫的 [v202012.00](https://github.com/aws/amazon-freertos/tree/202012.00) 中找到。不過，FreeRTOS 參考的 [v202107.00](https://github.com/aws/amazon-freertos/tree/202107.00) 不再支援平台。

本教學課程提供 Microchip Curiosity PIC32MZ EF 入門指示。如果您沒有 Microchip Curiosity PIC32MZ EF 套件，請造訪 AWS Partner Device Catalog 向[我們的合作夥伴](https://devices.amazonaws.com/detail/a3G0L00000AANscUAH/Curiosity-PIC32MZ-EF-Amazon-FreeRTOS-Bundle)購買。

套件包含下列項目：
+ [Curiosity PIC32MZ EF 開發板](https://www.microchip.com/Developmenttools/ProductDetails/DM320104)
+ [MikroElectronika USB UART click 電路板](https://www.mikroe.com/usb-uart-click)
+ [MikroElectronika WiFi 7 click 電路板](https://www.mikroe.com/wifi-7-click) 
+ [PIC32 LAN8720 PHY 子板](http://www.microchip.com/DevelopmentTools/ProductDetails.aspx?PartNO=ac320004-3)

您也需要使用以下項目進行偵錯：
+ [MPLAB Snap 電路內除錯器](https://www.microchip.com/Developmenttools/ProductDetails/PG164100)
+ (選用) [PICkit 3 Programming Cable Kit ](https://www.microchip.com/TPROG001)

開始之前，您必須設定 AWS IoT 和 FreeRTOS 下載，將您的裝置連線至 AWS 雲端。如需說明，請參閱 [首要步驟](freertos-prereqs.md)。

**重要**  
在本主題中，FreeRTOS 下載目錄的路徑稱為 `freertos`。
`freertos` 路徑中的空格字元可能會導致建置失敗。當您複製或拷貝儲存庫時，請確定您建立的路徑不包含空格字元。
Microsoft Windows 的檔案路徑長度上限為 260 個字元。長 FreeRTOS 下載目錄路徑可能會導致建置失敗。
由於原始碼可能包含符號連結，如果您使用 Windows 擷取封存，您可能需要：  
啟用[開發人員模式](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development)或 
使用提升為管理員的主控台。
透過這種方式，Windows 可以在擷取封存時正確建立符號連結。否則，符號連結會寫入為一般檔案，其中包含符號連結的路徑為文字或空白。如需詳細資訊，請參閱 [ Windows 10！ 中的部落格項目 Symlinks](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/)。  
如果您在 Windows 下使用 Git，則必須啟用開發人員模式，或者您必須：  
使用下列命令將 `core.symlinks`設為 true：  

    ```
    git config --global core.symlinks true
    ```
每當您使用寫入系統的 git 命令 （例如 **git pull**、 **git clone**和 ) 時，請使用提升為管理員的主控台**git submodule update --init --recursive**。

## 概觀
<a name="getting_started_mch_overview"></a>

本教學課程包含以下入門步驟的指示：

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

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

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

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

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

## 設定 Microchip Curiosity PIC32MZ EF 硬體
<a name="setup-hw-mch"></a>

1. 將 MikroElectronika USB UART Click 電路板接到 Microchip Curiosity PIC32MZ EF 的 microBUS 1 連接器。

1. 將 PIC32 LAN8720 PHY 子板接到 Microchip Curiosity PIC32MZ EF 的 J18 接頭。

1. 使用 USB A 對 USB mini-B 纜線，將 MikroElectronika USB UART click 電路板接到您的電腦。

1. 若要將電路板連接至網際網路，請使用下列其中一個選項：
   + 若要使用 **Wi-Fi**，請將 MikroElectronika Wi-Fi 7 Click 電路板接到 Microchip Curiosity PIC32MZ EF 的 microBUS 2 連接器 請參閱 [設定 FreeRTOS 示範](freertos-prereqs.md#freertos-configure)。
   + 若要使用**乙太網路**來將 Microchip Curiosity PIC32MZ EF 電路板連接至網際網路，請將 PIC32 LAN8720 PHY 子板連接至 Microchip Curiosity PIC32MZ EF 上的 J18 標頭。將乙太網路纜線一端接到 LAN8720 PHY 子板上。將另一端接到您的路由器或其他網際網路連接埠。您還必須定義預處理器巨集 `PIC32_USE_ETHERNET`。

1. 請將轉角聯接器 (angle connector) 焊接至 Microchip Curiosity PIC32MZ EF 的 ICSP 頂蓋 (若發現未焊接)。

1. 將 PICkit 3 Programming Cable Kit 的 ICSP 纜線一端連接至 Microchip Curiosity PIC32MZ EF。

   若您沒有 PICkit 3 Programming Cable Kit，可改為使用 M-F Dupont 跳線做連接。請注意，白色圓形表示接腳 1 (Pin 1) 的位置。

1. 將 ICSP 纜線 (或跳線) 的另一端連接到 MPLAB Snap Debugger。電路板右下方黑色三角形的標示為 8 針腳 SIL Programming Connector 的接腳 1。

   請確認連接至 Microchip Curiosity PIC32MZ EF 接腳 1 (標示為白色) 的線路與 MPLAB Snap Debugger 的接腳 1 對齊。

   如需 MPLAB Snap Debugger 的詳細資訊，請參閱 [ MPLAB Snap In-Circuit Debugger 資訊表](http://ww1.microchip.com/downloads/en/DeviceDoc/MPLAB%20Snap%20In-Circuit%20Debugger%20IS%20DS50002787A.pdf)。

## 使用 PICkit On Board (PKOB) 設定 Microchip Curiosity PIC32MZ EF 硬體
<a name="setup-env_mch-pkob"></a>

建議您遵循上一節的設定程序。不過，您可以依照下列步驟，使用整合式 PICkit On Board (PKOB) 程式設計人員/偵錯工具，透過基本偵錯來評估和執行 FreeRTOS 示範。

1. 將 MikroElectronika USB UART Click 電路板接到 Microchip Curiosity PIC32MZ EF 的 microBUS 1 連接器。

1. 若要將電路板連接至網際網路，請執行下列其中一項操作：
   + 若要使用 **Wi-Fi**，請將 MikroElectronika Wi-Fi 7 Click 電路板接到 Microchip Curiosity PIC32MZ EF 的 microBUS 2 連接器 (按照[設定 FreeRTOS 示範](freertos-prereqs.md#freertos-configure)中的 「設定 Wi-Fi」步驟進行)。
   + 若要使用**乙太網路**來將 Microchip Curiosity PIC32MZ EF 電路板連接至網際網路，請將 PIC32 LAN8720 PHY 子板連接至 Microchip Curiosity PIC32MZ EF 上的 J18 標頭。將乙太網路纜線一端接到 LAN8720 PHY 子板上。將另一端接到您的路由器或其他網際網路連接埠。您還必須定義預處理器巨集 `PIC32_USE_ETHERNET`。

1. 使用 USB type A 轉 USB micro-B 纜線，將 Microchip Curiosity PIC32MZ EF 電路板上名為「USB DEBUG」(USB 偵錯) 的 USB micro-B 連接埠連接至電腦。

1. 使用 USB A 對 USB mini-B 纜線，將 MikroElectronika USB UART click 電路板接到您的電腦。

## 設定開發環境
<a name="setup-env_mch"></a>

**注意**  
此裝置的 FreeRTOS 專案是以 MPLAB Harmony v2 為基礎。若要建置專案，您需要使用與 Harmony v2 相容的 MPLAB 工具，例如 MPLAB XC32 的 v2.10 版和 MPLAB Harmony Configurator (MHC) 的 2.X.X 版。

1. 安裝 [Python 3.x 版](https://www.python.org/downloads/)或更新版本。

1. 安裝 MPLAB X IDE：
**注意**  
FreeRTOS AWS 參考整合 v202007.00 目前僅支援 MPLabv5.35。MPLabv5.40 支援舊版 FreeRTOS AWS 參考整合。 MPLabv5.40.

**MPLabv5.35 下載**
   + [ 適用於 Windows 的 MPLAB X 整合式開發環境](http://ww1.microchip.com/downloads/en/DeviceDoc/MPLABX-v5.35-windows-installer.exe)
   + [ 適用於 macOS 的 MPLAB X 整合式開發環境](http://ww1.microchip.com/downloads/en/DeviceDoc/MPLABX-v5.35-osx-installer.dmg)
   + [ 適用於 Linux 的 MPLAB X 整合式開發環境](http://ww1.microchip.com/downloads/en/DeviceDoc/MPLABX-v5.35-linux-installer.tar)

**最新的 MPLab 下載 (MPLabv5.40)**
   + [適用於 Windows 的 MPLAB X 整合開發環境](http://www.microchip.com/mplabx-ide-windows-installer)
   + [適用於 macOS 的 MPLAB X 整合開發環境](http://www.microchip.com/mplabx-ide-osx-installer)
   + [適用於 Linux 的 MPLAB X 整合開發環境](http://www.microchip.com/mplabx-ide-linux-installer)

1. 安裝 MPLAB XC32 編譯器：
   + [適用於 Windows 的 MPLAB XC32/32\$1\$1 編譯器](http://www.microchip.com/mplabxc32windows)
   + [適用於 macOS 的 MPLAB XC32/32\$1\$1 編譯器](http://www.microchip.com/mplabxc32osx)
   + [適用於 Linux 的 MPLAB XC32/32\$1\$1 編譯器](http://www.microchip.com/mplabxc32linux)

1. 啟動 UART 終端機模擬器，並使用以下設定開啟連線：
   + 傳輸速率：115200
   + 資料：8 位元
   + 同位：無
   + 停止位元：1
   + 流量控制：無

## 在雲端監控 MQTT 訊息
<a name="getting_started_mch_monitor_mqtt"></a>

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

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

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

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

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

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

## 建置並執行 FreeRTOS 示範專案
<a name="mch-build-and-run-example"></a>

### 在 MPLAB IDE 中開啟 FreeRTOS 示範
<a name="mch-freertos-import-project"></a><a name="mch-load-project"></a>

1. 開啟 MPLAB IDE。如果您已安裝多個版本的編譯器，您需要選擇想在 IDE 內使用的編譯器。

1. 從 **File (檔案)** 選單中，選擇 **Open Project (開啟專案)**。

1. 瀏覽至 `projects/microchip/curiosity_pic32mzef/mplab/aws_demos` 並將它開啟。

1. 選擇 **Open project (開啟專案)**。

**注意**  
在您首次開啟專案時，您可能會收到有關編譯器的錯誤訊息。在 IDE 中，導覽至 **Tools (工具)**、**Options (選項)**、**Embedded (內嵌)**，然後選擇您要用於專案的編譯器。

若要使用乙太網路進行連線，您必須定義前置處理器巨集 `PIC32_USE_ETHERNET`。

**使用乙太網路透過 MPLAB IDE 進行連線**

1. 在 MPLAB IDE 中，在專案上按一下滑鼠右鍵，然後選擇**屬性**。

1. 在**專案屬性**對話方塊中，選擇 ***compiler-name* （全域選項）** 將其展開，然後選取 ***compiler-name*-gcc**。

1. 針對**選項類別**，選擇**預先處理和訊息**，然後將`PIC32_USE_ETHERNET`字串新增至**預先處理器巨集**。

### 執行 FreeRTOS 示範專案
<a name="mch-run-example"></a>

1. 重新組建專案。

1. 在 **Projects (專案)** 標籤中，以滑鼠右鍵按一下 `aws_demos` 最上層資料夾，然後選擇 **Debug (除錯)**。

1. 當除錯器停在 `main()` 中斷點時，請從 **Run (執行)** 功能表，選擇 **Resume (繼續)**。

### 使用 CMake 建置 FreeRTOS 示範
<a name="microchip-cmake"></a>

如果您不想使用 IDE 進行 FreeRTOS 開發，您也可以使用 CMake 來建置和執行您使用第三方程式碼編輯器和偵錯工具開發的示範應用程式或應用程式。

**使用 CMake 建置 FreeRTOS 示範**

1. 建立目錄以包含產生的建置檔案，例如 *build-directory*。

1. 使用下列命令從原始程式碼產生建置檔案。

   ```
   cmake -DVENDOR=microchip -DBOARD=curiosity_pic32mzef -DCOMPILER=xc32 -DMCHP_HEXMATE_PATH=path/microchip/mplabx/version/mplab_platform/bin  -DAFR_TOOLCHAIN_PATH=path/microchip/xc32/version/bin -S freertos -B build-folder
   ```
**注意**  
您必須指定 Hexmate 和工具鏈二進位檔的正確路徑，例如 `C:\Program Files (x86)\Microchip\MPLABX\v5.35\mplab_platform\bin`和 `C:\Program Files\Microchip\xc32\v2.40\bin` 路徑。

1. 將目錄變更為建置目錄 (*build-directory*)，然後從`make`該目錄執行。

如需詳細資訊，請參閱[搭配 FreeRTOS 使用 CMake](getting-started-cmake.md)。

若要使用乙太網路進行連線，您必須定義前置處理器巨集 `PIC32_USE_ETHERNET`。

## 疑難排解
<a name="getting_started_mch_troubleshooting"></a>

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