硬體定義

發行項
08/09/2023

本節說明硬體定義檔案，以及如何為 Azure 球體版面和模組建立這些檔案。

硬體定義檔案

硬體定義有兩個不同但相關的用途：

面板特定 定義定義定義模組或其他面板的特定周邊，並讓應用程式使用相關且有意義的識別碼來參照這些定義。例如，應用程式可以使用「Red_LED_1」來取代不透明的數位，例如 GPIO 「13」。 Azure 球體 SDK 中的 HardwareDefinitions 目錄包含常見 Azure 球體板及其使用的晶片的定義。此目錄位於 %ProgramFiles(x86)%\Microsoft Azure Sphere SDK\HardwareDefinitions Windows 和 /opt/azurespheresdk/HardwareDefinitions Linux 上。

應用程式特定 定義會將應用程式程式碼中參照的周邊設備對應至面板特定定義。應用程式特定定義是內建在白板特定定義上，並定義單一識別碼集，可用來參照任何白板上的周邊。因此，在多個面板上執行的應用程式可能具有每種版面類型的應用程式特定定義，但應用程式本身只會使用一組周邊識別碼。程式碼本身可以在不同的硬體上完全保持不變;開發人員只需要變更參照，才能使用適當的定義。例如，咖啡製造商的應用程式代碼會參照一個加注統計指示器 LED。咖啡製造商控制台是由兩個供應商 Contoso 和 Fabrikam 所採購。透過針對每個白板使用應用程式特定定義，在 Fabrikam 提供的控制台上，利用 Contoso 和 LED 4 所提供的控制台，對應到 LED 2。

如果您的應用程式使用來自 SDK 或硬體供應商的硬體定義，而您並未建立自己的應用程式特定定義，那麼您目前可以略過本主題的其餘部分，直接使用硬體相依性。

您可以使用 JSON 格式建立硬體定義檔案。接著，您會從 JSON 檔案產生 C 頁首檔案。

硬體定義檔的格式

硬體定義檔案是具有下列格式的 JSON 檔案：

{
    "Metadata":
    {
        "Type": "Azure Sphere Hardware Definition",
        "Version": 1
    },
    "Description":
    {
        "Name": "<name of board or module>",
        "MainCoreHeaderFileTopContent": [
            "/* Copyright (c) <vendor name> All rights reserved.",
            "   <vendor licensing information, if any> */",
            "",
            "// This header contains the peripheral pinout definitions for the",
            "// <name of board or module>"
        ]
    },
    "Imports" : [ {"Path": "<path to underlying hardware definition file>"} ],
    "Peripherals": [
       {"Name": "", "Type": " ", "Mapping": " ", "Comment": " "},
   ]
}

[ 中繼資料] 區 段包含檔案 (檔案類型、版本等) 的相關資訊。

[ 描述] 區段包含白板或模組的相關資訊。 [MainCoreHeaderFileTopContent] 欄位包含將放在產生標題檔案開頭的資訊。

[ 匯入 ] 區段指定基礎硬體平臺的硬體定義檔路徑名稱 (面板或模組) 。

[ 周邊設備] 區段列出此面板公開供應用程式使用的周邊設備。周邊描述具有下列格式：

{"   Name": "<name-in-code>", "Type": "<type>", "Mapping": "<name-in-imported-definition>", "Comment": "<helpful info>"}

以下是 [ 介面設備] 區段的元素：

名稱 - 用來在應用程式程式碼中參照周邊設備的識別碼。

類型 - 周邊 (的類型，例如 Gpio、Uart、Adc) 。請參閱匯入 一節中 列出的硬體定義檔案，以取得類型資訊。

對應 - 將 [名稱] 欄位中的識別碼對應到匯入的硬體定義檔中周邊所用的識別碼。

批註 - 提供實用資訊以顯示在產生的頁首檔案中。例如，將 ISU* 周邊設備指派釘選，或將內部 LED 對應到基礎 MCU 或模組的 GPIO PIN 碼。

範例：面板特定定義

下列範例顯示部分硬體定義檔案，其中包含名為 MyBoard 的虛構 MT3620 開發面板的面板特定定義。它會指定 MyBoard 的周邊釘選定義。它會從晶片專用硬體定義檔匯入資源定義檔， (mt3620.json) 的 MT3620 MCU。 [ 介面設備] 區段中的資訊會對應 MyBoard 提供給基礎 MT3620 MCU 所提供的資源之資源的釘選對應。

{
    "Metadata":
    {
        "Type": "Azure Sphere Hardware Definition",
        "Version": 1
    },
    "Description":
    {
        "Name": "MyBoard",
        "MainCoreHeaderFileTopContent": [
            "// This header contains the peripheral pinout definitions for ",
            "// MyBoard"
        ]
    },
    "Imports" : [ {"Path": "... /mt3620/mt3620.json"} ],
    "Peripherals": [
        {"Name": "MY_BOARD_LED_RED", "Type": "Gpio", "Mapping": "MT3620_GPIO8", "Comment": "LED 1 Red channel uses GPIO8."},
        {"Name": "MY_BOARD_LED_GREEN", "Type": "Gpio", "Mapping": "MT3620_GPIO16", "Comment": "LED 2 Green channel uses GPIO16"},
        {"Name": "MY_BOARD_BUTTON_A", "Type": "Gpio", "Mapping": "MT3620_GPIO12", "Comment": "Button A uses GPIO12"},
                              .
                              .
                              .
    ]
}

您可以在包含 Azure 球體 SDK 安裝的 HardwareDefinitions 目錄中，看到其他白板特定定義檔案的範例。

範例：應用程式特定定義

下列範例顯示部分硬體定義檔案，其中包含虛構咖啡製造商設備的應用程式特定定義。

應用程式中包含的周邊設備有兩個指示器 LED 和一個推播按鈕。它們會在應用程式代碼中分別由識別碼COFFEEMAKER_STATUS_BREWING、COFFEEMAKER_STATUS_READY和COFFEEMAKER_BUTTON_START參照。這些識別碼會對應到匯入的 MT3620 面板 MyBoard 白板定義中定義的周邊設備。

{
    "Metadata": {
        "Type": "Azure Sphere Hardware Definition",
        "Version": 1
    },
    "Description":
    {
        "Name": "Coffee Maker Application",
        "MainCoreHeaderFileTopContent": [
            "// This file implements the Coffee Maker application-specific definition on MyBoard",
        ]
    },
    "Imports" : [ {"Path": "... /MyHwDefs/my_board.json"} ],
    "Peripherals": [
         {"Name": "COFFEEMAKER_STATUS_BREWING", "Type": "Gpio", "Mapping": "MY_BOARD_LED_RED", "Comment": "Brewing status indicator uses MyBoard RED LED"},
         {"Name": "COFFEEMAKER_STATUS_READY", "Type": "Gpio", "Mapping": "MY_BOARD_LED_GREEN", "Comment": "Ready status indicator uses MyBoard GREEN LED"},
         {"Name": "COFFEEMAKER_BUTTON_START", "Type": "Gpio", "Mapping": "MY_BOARD_BUTTON_A", "Comment": "Start button uses MyBoard Button A"},
                                             .
                                             .
                                             .
    ]
}

[ 匯入 ] 區段包含實體面板或模組的硬體定義檔路徑。
```
"Imports" : [ {"Path": "... /MyHwDefs/my_board.json"} ],
```
[ 周邊設備] 區段會將 CoffeeMaker 控制項面板周邊設備對應到面板或模組上的對應周邊設備。
```
{"Name": "COFFEEMAKER_BUTTON_START", "Type": "Gpio", "Mapping": "MY_BOARD_BUTTON_A", "Comment": " Start button uses MyBoard Button A"},
```
名稱 - 包含應用程式代碼中周邊設備所用的識別碼。

對應 - 包含面板或模組硬體定義檔中周邊所用的識別碼。

下一版的咖啡製作程式可能建置在 MyBoardV2 上。它會有新的面板特定定義與周邊設備，例如MY_BOARD_V2_LED_ORANGE。這將會由咖啡製造商應用程式特定定義的新實作匯入，該定義會將COFFEEMAKER_STATUS_BREWING對應到這個新的橘色 LED。實際的咖啡製造商應用程式代碼將保持不變。

同樣地， Azure 球體範例應用程式所使用的「sample_appliance.json」定義的新實作，可能會讓這些範例應用程式在 MyBoard 上執行時得以保持不變。

頁首檔案

頁首檔案是從包含硬體定義的 JSON 檔案中產生。您必須為面板特定定義和應用程式特定定義建立頁首檔案。

使用 azsphere 硬體定義產生標題 命令來產生頁首檔案。

若要建立頁首檔案，請在 Azure 球體命令提示字元中輸入下列行。以 JSON 檔案的名稱取代 <filename> 。

azsphere hardware-definition generate-header --hardware-definition-file <filename>

頁首檔案名。h 會建立並放置在資料夾 inc/hw中。

例如，輸入下列行以從 JSON 檔案產生頁首檔案。

azsphere hardware-definition generate-header --hardware-definition-file my_board.json

下列顯示my_board.h 頁首檔案的一部分：

#pragma once
#include "... /mt3620/inc/hw/mt3620.h"

// LED Red channel uses GPIO8.
#define MY_BOARD_LED_RED MT3620_GPIO8

// LED Green channel uses GPIO16
#define MY_BOARD_LED_GREEN MT3620_GPIO16

// Button A uses GPIO12
#define MY_BOARD_BUTTON_A MT3620_GPIO12
                   .
                   .
                   .

注意根據預設，系統會將產生的頁首檔案放在 inc/hw 中，而該檔案必須是包含輸入 JSON 檔案之目錄的子導向。如果這個子導向不存在，將會建立它。

現在您已建立硬體定義 JSON 檔案及其隨附的頁首檔案，請參閱管理目標硬體相依性以瞭解在應用程式中使用的步驟。

共用方式為