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