Hardwaredefinitionen
In diesem Abschnitt werden Hardwaredefinitionsdateien und deren Erstellung für Azure Sphere-Boards und -Module beschrieben.
Hardwaredefinitionsdateien
Hardwaredefinitionen dienen zwei separate, aber verwandte Zwecke:
Boardspezifische Definitionen definieren die spezifischen Peripheriegeräte eines Moduls oder einer anderen Platine und ermöglichen es einer Anwendung, auf diese zu verweisen, indem sie relevante und aussagekräftige Bezeichner verwendet. Beispielsweise kann eine App "Red_LED_1" anstelle einer nicht transparenten Zahl wie GPIO "13" verwenden. Das Verzeichnis HardwareDefinitions im Azure Sphere SDK enthält solche Definitionen für gängige Azure Sphere-Boards und die verwendeten Chips. Dieses Verzeichnis befindet sich %ProgramFiles(x86)%\Microsoft Azure Sphere SDK\HardwareDefinitions unter Windows und /opt/azurespheresdk/HardwareDefinitions unter Linux.
Anwendungsspezifische Definitionen ordnen Peripheriegeräte, auf die im Anwendungscode verwiesen wird, boardspezifischen Definitionen zu. Anwendungsspezifische Definitionen basieren auf boardspezifischen Definitionen und definieren einen einzelnen Satz von Bezeichnern, die verwendet werden können, um auf Peripheriegeräte auf einer beliebigen Platine zu verweisen. Daher kann eine Anwendung, die auf mehreren Boards ausgeführt wird, über eine anwendungsspezifische Definition für jeden Boardtyp verfügen, aber die Anwendung selbst verwendet nur einen Satz von Peripheriebezeichnern. Der Code selbst kann vollständig unverändert auf unterschiedlicher Hardware ausgeführt werden. Ein Entwickler muss nur den Verweis ändern, um die entsprechende Definition zu verwenden. Beispielsweise verweist der Anwendungscode für eine Kaffeemaschine auf eine BrewingStatus-Indikator-LED. Das Kontrollboard der Kaffeemaschine wird von zwei Lieferanten, Contoso und Fabrikam, bezogen. Durch die Verwendung anwendungsspezifischer Definitionen für jede Platine kann der BrewingStatus-Indikator led 2 auf der von Contoso bereitgestellten Steuerplatine und LED 4 auf der von Fabrikam bereitgestellten Steuerplatine zugeordnet werden.
Wenn Ihre Anwendung Hardwaredefinitionen aus dem SDK oder von Ihrem Hardwareanbieter verwendet und Sie keine eigene anwendungsspezifische Definition erstellen, können Sie den Rest dieses Themas vorerst überspringen und direkt mit der Verwendung von Hardwareabhängigkeiten fortfahren.
Sie erstellen Ihre Hardwaredefinitionsdateien im JSON-Format. Anschließend generieren Sie C-Headerdateien aus den JSON-Dateien.
Format einer Hardwaredefinitionsdatei
Eine Hardwaredefinitionsdatei ist eine JSON-Datei im folgenden Format:
{
"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": " "},
]
}
Der Abschnitt Metadaten enthält Informationen zur Datei (Dateityp, Version usw.).
Der Abschnitt Beschreibung enthält Informationen zum Board oder Modul. Das Feld "MainCoreHeaderFileTopContent" enthält Informationen, die am Anfang der generierten Headerdatei platziert werden.
Im Abschnitt Importe wird der Pfadname der Hardwaredefinitionsdatei für die zugrunde liegende Hardwareplattform (Board oder Modul) angegeben.
Im Abschnitt Peripheriegeräte werden die Peripheriegeräte aufgelistet, die dieses Board für die Verwendung in Anwendungen verfügbar macht. Eine Beschreibung des Peripheriegeräts hat das folgende Format:
{" Name": "<name-in-code>", "Type": "<type>", "Mapping": "<name-in-imported-definition>", "Comment": "<helpful info>"}
Im Folgenden sind die Elemente des Abschnitts Peripheriegeräte aufgeführt :
Name: Der Bezeichner, der verwendet wird, um auf das Peripheriegerät in Ihrem Anwendungscode zu verweisen.
Typ: Der Typ des Peripheriegeräts (z. B. Gpio, Uart, Adc). Informationen zum Abrufen von Typinformationen finden Sie in der Hardwaredefinitionsdatei, die im Abschnitt Importe aufgeführt ist.
Zuordnung: Ordnet den Bezeichner im Feld Name dem Bezeichner zu, der für das Peripheriegerät in der importierten Hardwaredefinitionsdatei verwendet wird.
Kommentare: Stellt hilfreiche Informationen bereit, die in der generierten Headerdatei angezeigt werden sollen. Beispiel: Pinzuweisungen für ISU*-Peripheriegeräte oder Zuordnen von onboard-LEDs zu GPIO-Pins der zugrunde liegenden MCU oder des zugrunde liegenden Moduls.
Beispiel: Board-spezifische Definition
Das folgende Beispiel zeigt einen Teil der Hardwaredefinitionsdatei, der eine boardspezifische Definition für ein fiktives MT3620-Entwicklungsboard namens MyBoard enthält. Es gibt die Peripherie-Pinoutdefinitionen für MyBoard an. Es importiert Ressourcendefinitionen aus der chipspezifischen Hardwaredefinitionsdatei (mt3620.json) für die MT3620-MCU. Die Informationen im Abschnitt Peripheriegeräte führen zu einer Pin-zu-Pin-Zuordnung der Von MyBoard verfügbar gemachten Ressourcen zu den Ressourcen, die von der zugrunde liegenden MT3620-MCU bereitgestellt werden.
{
"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"},
.
.
.
]
}
Weitere Beispiele für boardspezifische Definitionsdateien finden Sie im Verzeichnis HardwareDefinitions, das Teil der Azure Sphere SDK-Installation ist.
Beispiel: anwendungsspezifische Definition
Das folgende Beispiel zeigt einen Teil einer Hardwaredefinitionsdatei, der eine anwendungsspezifische Definition für eine fiktive Kaffeemaschine Anwendung enthält.
Zu den in der Anwendung enthaltenen Peripheriegeräten gehören zwei Indikator-LEDs und ein Knopfdruck. Auf sie wird im Anwendungscode durch die Bezeichner COFFEEMAKER_STATUS_BREWING, COFFEEMAKER_STATUS_READY und COFFEEMAKER_BUTTON_START verwiesen. Diese Bezeichner werden Peripheriegeräten zugeordnet, die in der importierten Board-spezifischen Definition für das fiktive MT3620-Board MyBoard definiert sind.
{
"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"},
.
.
.
]
}
Der Abschnitt Importe enthält den Pfad zur Hardwaredefinitionsdatei für die physische Platine oder das modul.
"Imports" : [ {"Path": "... /MyHwDefs/my_board.json"} ],Im Abschnitt Peripheriegeräte werden die Peripheriegeräte der CoffeeMaker-Steuerung den entsprechenden Peripheriegeräten auf einer Platine oder einem Modul zugeordnet.
{"Name": "COFFEEMAKER_BUTTON_START", "Type": "Gpio", "Mapping": "MY_BOARD_BUTTON_A", "Comment": " Start button uses MyBoard Button A"},Name: Enthält den Bezeichner, der für das Peripheriegerät im Anwendungscode verwendet wird.
Zuordnung: Enthält den Bezeichner, der für das Peripheriegerät in der Hardwaredefinitionsdatei für eine Platine oder ein Modul verwendet wird.
Die nächste Version der Kaffeemaschine wird möglicherweise auf MyBoardV2 erstellt. Es würde eine neue Board-spezifische Definition mit Peripheriegeräten wie MY_BOARD_V2_LED_ORANGE. Dies würde durch eine neue Implementierung der anwendungsspezifischen Definition der Kaffeemaschine importiert werden, die COFFEEMAKER_STATUS_BREWING dieser neuen orangefarbenen LED zuordnet. Der tatsächliche Code der Kaffeemaschinenanwendung bleibt unverändert.
Ebenso könnte eine neue Implementierung der Definition "sample_appliance.json", die von den Azure Sphere-Beispiel-Apps verwendet wird, ermöglichen, dass diese Beispiel-Apps unverändert auf MyBoard ausgeführt werden.
Headerdateien
Headerdateien werden aus den JSON-Dateien generiert, die die Hardwaredefinitionen enthalten. Sie müssen Headerdateien sowohl für boardspezifische als auch für anwendungsspezifische Definitionen erstellen.
Verwenden Sie den Befehl azsphere hardware-definition generate-header , um eine Headerdatei zu generieren.
Um die Headerdatei zu erstellen, geben Sie die folgende Zeile an der Azure Sphere-Eingabeaufforderung ein. Ersetzen Sie durch <filename> den Namen der JSON-Datei.
azsphere hardware-definition generate-header --hardware-definition-file <filename>
Die Headerdatei filename.h wird erstellt und im Ordner inc/hw abgelegt.
Geben Sie beispielsweise die folgende Zeile ein, um eine Headerdatei aus der JSON-Datei zu generieren.
azsphere hardware-definition generate-header --hardware-definition-file my_board.json
Im Folgenden wird ein Teil der Headerdatei my_board.h gezeigt:
#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
.
.
.
Hinweis Standardmäßig wird die generierte Headerdatei in inc/hwplatziert. Dabei muss es sich um ein Unterverzeichnis des Verzeichnisses handeln, das die JSON-Eingabedatei enthält. Wenn dieses Unterverzeichnis nicht vorhanden ist, wird es erstellt.
Nachdem Sie ihre JSON-Datei mit Hardwaredefinition und die zugehörige Headerdatei erstellt haben, finden Sie unter Verwalten von Zielhardwareabhängigkeiten die Schritte zur Verwendung in Ihrer Anwendung.