共用方式為


硬體定義

重要

這是 Azure Sphere (舊版) 檔。 Azure Sphere(舊版)將於 2027 年 9 月 27 日淘汰,且使用者此時必須移轉至 Azure Sphere(整合式)。 使用位於 TOC 上方的版本選取器來檢視 Azure Sphere (整合式) 檔。

本節說明硬體定義檔案,以及如何為 Azure Sphere 面板和模組建立它們。

硬體定義檔案

硬體定義提供兩個不同的但相關的用途:

面板特定 定義會定義模組或其他面板的特定周邊,並讓應用程式使用相關且有意義的標識符來參考它們。 例如,應用程式可以使用 「Red_LED_1」,而不是不透明的數位,例如 GPIO “13” Azure Sphere SDK 中的 HardwareDefinitions 目錄包含一般 Azure Sphere 面板及其使用的晶片這類定義。 此目錄位於 %ProgramFiles(x86)%\Microsoft Azure Sphere SDK\HardwareDefinitions Windows 和 /opt/azurespheresdk/HardwareDefinitions Linux 上。

應用程式特定 定義會將應用程式程式代碼中所參考的周邊對應至面板特定定義。 應用程式特定定義建置在面板特定定義上,並定義一組標識符,可用來參考任何面板上的周邊。 因此,在多個面板上執行的應用程式,對於每種面板類型,可能會有一個應用程式特定的定義,但應用程式本身只會使用一組周邊標識符。 程序代碼本身可以在不同的硬體上完全不變地執行;開發人員只需要變更參考,才能使用適當的定義。 例如,咖啡機的應用程式程式代碼會參考 BrewingStatus 指標 LED。 咖啡機控制板由兩家供應商 Contoso 和 Fabrikam 提供。 透過針對每個面板使用應用程式特定定義,BrewingStatus 指標可以對應至 Contoso 提供的控制板上的 LED 2,以及 Fabrikam 所提供的控制板上的 LED 4。

如果您的應用程式使用來自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 針腳。

範例:面板特定定義

下列範例顯示硬體定義檔的一部分,其中包含名為 MyBoard 之虛構 MT3620 開發面板的面板特定定義。 它會指定 MyBoard 的周邊針腳定義。 它會從 MT3620 MCU 的晶片特定硬體定義檔 (mt3620.json) 匯入資源定義。 [周邊] 區段中的資訊會導致 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 Sphere 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 Sphere 範例應用程式所使用的 「sample_appliance.json」定義的新實作,可讓這些範例應用程式在 MyBoard 上保持不變執行。

標頭檔

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

使用 azsphere hardware-definition generate-header 命令來產生頭檔。

若要建立頭檔,請在 Azure Sphere 命令提示字元中輸入下列這一行。 將取代 <filename> 為 JSON 檔案的名稱。

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

頭檔 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 檔案及其隨附頭檔,請參閱 管理目標硬體相依性 ,以取得在應用程式中使用它的步驟。