Freigeben über

Hardwaredefinitionen

  • Artikel

Wichtig

Dies ist die Dokumentation zu Azure Sphere (Legacy). Azure Sphere (Legacy) wird am 27. September 2027 eingestellt, und Benutzer müssen bis zu diesem Zeitpunkt zu Azure Sphere (integriert) migrieren. Verwenden Sie die Versionsauswahl oberhalb des Inhaltsverzeichniss, um die Dokumentation zu Azure Sphere (Integriert) anzuzeigen.

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 Tafel und ermöglichen es einer Anwendung, mithilfe von Bezeichnern, die relevant und aussagekräftig sind, darauf zu verweisen. Beispielsweise kann eine App "Red_LED_1" anstelle einer undurchsichtigen Zahl wie GPIO "13" verwenden. Das HardwareDefinitions-Verzeichnis im Azure Sphere SDK enthält solche Definitionen für allgemeine 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 zu, auf die im Anwendungscode verwiesen wird, zu boardspezifischen Definitionen. Anwendungsspezifische Definitionen basieren auf boardspezifischen Definitionen und definieren einen einzelnen Satz von Bezeichnern, die verwendet werden können, um auf Peripheriegeräte auf jeder Tafel zu verweisen. Daher kann eine Anwendung, die auf mehreren Boards ausgeführt wird, eine anwendungsspezifische Definition für jeden Boardtyp aufweisen, die Anwendung selbst verwendet jedoch nur einen Satz von Peripheriebezeichnern. Der Code selbst kann auf unterschiedlicher Hardware vollständig unverändert ausgeführt werden. Ein Entwickler muss den Verweis nur ändern, um die entsprechende Definition zu verwenden. Beispielsweise verweist der Anwendungscode für eine Kaffeemaschine auf eine BrewingStatus-Indikator-LED. Die Coffee Maker Control Board wird von zwei Lieferanten, Contoso und Fabrikam, stammen. Durch die Verwendung anwendungsspezifischer Definitionen für jede Tafel kann der BrewingStatus-Indikator led 2 auf der von Contoso und LED 4 auf der von Fabrikam bereitgestellten Steuertafel 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 zur Verwendung von Hardwareabhängigkeiten wechseln.

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 mit dem 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 Description (Beschreibung) enthält Informationen zum Board oder Modul. Das Feld „MainCoreHeaderFileTopContent“ enthält Informationen, die am Anfang der generierten Headerdatei angeordnet werden.

Der Abschnitt "Imports" gibt den Pfadnamen der Hardwaredefinitionsdatei für die zugrunde liegende Hardwareplattform (Board oder Modul) an.

Im Abschnitt Peripherals (Peripheriegeräte) sind die Peripheriegeräte aufgeführt, die von diesem Board für die Verwendung in Anwendungen verfügbar gemacht werden. Eine Peripheriebeschreibung weist das folgende Format auf:

{"   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 zum Verweisen auf das Peripheriegerät in Ihrem Anwendungscode.

Type (Typ): Der Typ des Peripheriegeräts (z. B. Gpio, Uart, Adc). Informationen zum Typ finden Sie in der Hardwaredefinitionsdatei unter Imports (Importe).

Mapping (Zuordnung): Ordnet den Bezeichner im Feld „Name“ dem Bezeichner zu, der in der importierten Hardwaredefinitionsdatei für das Peripheriegerät verwendet wird.

Comments (Kommentare): Stellt hilfreiche Informationen bereit, die in der generierten Headerdatei angezeigt werden. Beispiele hierfür sind Pinzuweisungen für ISU*-Peripheriegeräte oder die Zuordnung von Onboard-LEDs zu den GPIO-Pins der zugrunde liegenden MCU bzw. des Moduls.

Beispiel: Boardspezifische Definition

Das folgende Beispiel zeigt einen Teil der Hardwaredefinitionsdatei, der eine boardspezifische Definition für ein fiktives MT3620-Entwicklungs board mit dem Namen 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-to-Pin-Zuordnung der Ressourcen, die von MyBoard verfügbar gemacht werden, 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 Board-spezifische Definitionsdateien finden Sie im HardwareDefinitions-Verzeichnis, das Teil der Azure Sphere SDK-Installation ist.

Beispiel: anwendungsspezifische Definition

Das folgende Beispiel zeigt einen Teil einer Hardwaredefinitionsdatei, die eine anwendungsspezifische Definition für eine fiktive Kaffeemaschine enthält.

Zu den in der Anwendung enthaltenen Peripheriegeräten gehören zwei Indikator-LEDs und ein Knopfdruck. Sie werden 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 Boardspezifischen 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 "Imports" enthält den Pfad zur Hardwaredefinitionsdatei für das physische Board oder Modul.

    "Imports" : [ {"Path": "... /MyHwDefs/my_board.json"} ],

  • Der Abschnitt "Peripheriegeräte " ordnet die CoffeeMaker-Steuerbrett-Peripheriegeräte den entsprechenden Peripheriegeräten auf einem Board oder Modul zu.

    {"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 ein Board oder Modul verwendet wird.

Die nächste Version der Kaffeemaschine kann auf MyBoardV2 gebaut werden. Es wäre 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 zugeordnet. Der tatsächliche Code der Kaffeemaschine würde unverändert bleiben.

Ebenso könnte eine neue Implementierung der definition "sample_appliance.json", die von den Azure Sphere-Beispiel-Apps verwendet wird, die Ausführung dieser Beispiel-Apps auf MyBoard ermöglichen.

Headerdateien

Headerdateien werden aus den JSON-Dateien generiert, die die Hardwaredefinitionen enthalten. Sie müssen Headerdateien für boardspezifische und 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 den <filename> 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 sehen Sie einen Teil der Headerdatei 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
                   .
                   .
                   .

Hinweis : Standardmäßig wird die generierte Headerdatei eingefügt inc/hw, die ein Unterverzeichnis des Verzeichnisses sein muss, das die EINGABE-JSON-Datei enthält. Wenn dieses Unterverzeichnis nicht vorhanden ist, wird es erstellt.

Nachdem Sie ihre JSON-Datei für die Hardwaredefinition und die zugehörige Headerdatei erstellt haben, lesen Sie " Verwalten von Zielhardwareabhängigkeiten für die Schritte zur Verwendung in Ihrer Anwendung".