Partage via

Définitions du matériel

  • Article

Important

Il s’agit de la documentation Azure Sphere (héritée). Azure Sphere (hérité) prend sa retraite le 27 septembre 2027 et les utilisateurs doivent migrer vers Azure Sphere (intégré) pour l’instant. Utilisez le sélecteur de version situé au-dessus du TOC pour afficher la documentation Azure Sphere (intégrée).

Cette section décrit les fichiers de définition matérielle et comment les créer pour les cartes et modules Azure Sphere.

Fichiers de définition de matériel

Les définitions matérielles servent deux objectifs distincts mais connexes :

Les définitions spécifiques à la carte définissent les périphériques spécifiques d’un module ou d’un autre tableau et permettent à une application de les référencer à l’aide d’identificateurs pertinents et significatifs. Par exemple, une application peut utiliser « Red_LED_1 » au lieu d’un nombre opaque tel que GPIO « 13 ». Le répertoire HardwareDefinitions du Kit de développement logiciel (SDK) Azure Sphere contient de telles définitions pour les cartes Azure Sphere courantes et les puces qu’ils utilisent. Ce répertoire se trouve %ProgramFiles(x86)%\Microsoft Azure Sphere SDK\HardwareDefinitions sur Windows et /opt/azurespheresdk/HardwareDefinitions sur Linux.

Les définitions spécifiques à l’application mappent les périphériques référencés dans le code de l’application aux définitions spécifiques à la carte. Les définitions spécifiques à l’application sont basées sur des définitions spécifiques à la carte et définissent un ensemble unique d’identificateurs qui peuvent être utilisés pour référencer des périphériques sur n’importe quelle carte. Par conséquent, une application qui s’exécute sur plusieurs cartes peut avoir une définition spécifique à l’application pour chaque type de carte, mais l’application elle-même n’utilise qu’un seul ensemble d’identificateurs périphériques. Le code lui-même peut s’exécuter entièrement inchangé sur différents matériels ; un développeur doit uniquement modifier la référence pour utiliser la définition appropriée. Par exemple, le code d’application d’une machine à café fait référence à une LED d’indicateur BrewingStatus. La carte de contrôle de la machine à café est source par deux fournisseurs, Contoso et Fabrikam. Grâce à l’utilisation de définitions spécifiques à l’application pour chaque carte, l’indicateur BrewingStatus peut être mappé à LED 2 sur la carte de contrôle fournie par Contoso et LED 4 sur la carte de contrôle fournie par Fabrikam.

Si votre application utilise des définitions matérielles à partir du Kit de développement logiciel (SDK) ou de votre fournisseur matériel et que vous ne créez pas votre propre définition spécifique à l’application, vous pouvez ignorer le reste de cette rubrique pour l’instant et passer directement à l’utilisation de dépendances matérielles.

Vous créez vos fichiers de définition matérielle au format JSON. Vous générez ensuite des fichiers d’en-tête C à partir des fichiers JSON.

Format d’un fichier de définition matérielle

Un fichier de définition matérielle est un fichier JSON au format suivant :

{
    "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": " "},
   ]
}

La section Métadonnées contient des informations sur le fichier (type de fichier, version, etc.).

La section Description contient des informations sur la carte ou le module. Le champ « MainCoreHeaderFileTopContent » contient des informations qui sont placées au début du fichier d’en-tête généré.

La section Imports spécifie le chemin d’accès du fichier de définition de matériel pour la plateforme matérielle sous-jacente (carte ou module).

La section Peripherals liste les périphériques que cette carte expose pour une utilisation dans les applications. Une description périphérique a le format suivant :

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

Voici les éléments de la section Périphériques :

Name : identificateur utilisé pour référencer le périphérique dans le code de votre application.

Type : type de périphérique (par exemple, Gpio, Uart, Adc). Reportez-vous au fichier de définition de matériel listé dans la section Imports pour obtenir les informations sur le type.

Mapping : mappe l’identificateur dans le champ Name à l’identificateur utilisé pour le périphérique dans le fichier de définition de matériel importé.

Comments : fournit des informations utiles à afficher dans le fichier d’en-tête généré. Par exemple, les assignations de broches pour les périphériques ISU* ou le mappage des LED intégrés aux broches GPIO du module ou MCU sous-jacent.

Exemple : définition spécifique à la carte

L’exemple suivant montre une partie du fichier de définition matérielle qui contient une définition spécifique à la carte pour une carte de développement MT3620 fictive appelée MyBoard. Il spécifie les définitions de broche périphérique pour MyBoard. Il importe les définitions de ressources à partir du fichier de définition matérielle spécifique à la puce (mt3620.json) pour le MCU MT3620. Les informations de la section Périphériques entraînent un mappage de broche à épingle des ressources exposées par MyBoard aux ressources fournies par le MCU MT3620 sous-jacent.

{
    "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"},
                              .
                              .
                              .
    ]
}

Vous pouvez voir des exemples supplémentaires de fichiers de définition spécifiques à la carte dans le répertoire HardwareDefinitions qui fait partie de l’installation du Kit de développement logiciel (SDK) Azure Sphere.

Exemple : définition spécifique à l’application

L’exemple suivant montre une partie d’un fichier de définition matérielle qui contient une définition spécifique à l’application pour une appliance de machine à café fictive.

Parmi les périphériques inclus dans l’application figurent deux LED d’indicateur et un bouton push. Ils sont référencés dans le code de l’application par les identificateurs COFFEEMAKER_STATUS_BREWING, COFFEEMAKER_STATUS_READY et COFFEEMAKER_BUTTON_START respectivement. Ces identificateurs sont mappés aux périphériques définis dans la définition spécifique à la carte importée pour la carte MT3620 fictive 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"},
                                             .
                                             .
                                             .
    ]
}

  • La section Imports contient le chemin d’accès au fichier de définition matérielle pour la carte physique ou le module.

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

  • La section Périphériques mappe les périphériques de carte de contrôle CoffeeMaker aux périphériques correspondants d’une carte ou d’un module.

    {"Name": "COFFEEMAKER_BUTTON_START", "Type": "Gpio", "Mapping": "MY_BOARD_BUTTON_A", "Comment": " Start button uses MyBoard Button A"},

    Nom : contient l’identificateur utilisé pour le périphérique dans le code de l’application.

    Mappage : contient l’identificateur utilisé pour le périphérique dans le fichier de définition matérielle d’une carte ou d’un module.

La prochaine version de la machine à café peut être construite sur MyBoardV2. Il aurait une nouvelle définition spécifique à la carte avec des périphériques tels que MY_BOARD_V2_LED_ORANGE. Cela serait importé par une nouvelle implémentation de la définition propre à l’application de la machine à café qui mappe COFFEEMAKER_STATUS_BREWING à cette nouvelle LED orange. Le code réel de l’application de la machine à café reste inchangé.

De même, une nouvelle implémentation de la définition « sample_appliance.json », utilisée par les exemples d’applications Azure Sphere, peut permettre à ces exemples d’applications d’exécuter inchangés sur MyBoard.

Fichiers d’en-tête

Les fichiers d’en-tête sont générés à partir des fichiers JSON qui contiennent les définitions matérielles. Vous devez créer des fichiers d’en-tête pour les définitions spécifiques à la carte et propres à l’application.

Utilisez la commande azsphere hardware-definition generate-header pour générer un fichier d’en-tête.

Pour créer le fichier d’en-tête, entrez la ligne suivante à l’invite de commandes Azure Sphere. Remplacez <filename> par le nom du fichier JSON.

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

Le fichier d’en-tête filename.h est créé et placé dans le dossier inc/hw.

Par exemple, entrez la ligne suivante pour générer un fichier d’en-tête à partir du fichier JSON.

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

Voici une partie du fichier d’en-tête 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
                   .
                   .
                   .

Notez par défaut que le fichier d’en-tête généré est placé dans inc/hw, qui doit être un sous-répertoire du répertoire qui contient le fichier JSON d’entrée. Si ce sous-répertoire n’existe pas, il sera créé.

Maintenant que vous avez créé votre fichier JSON de définition matérielle et son fichier d’en-tête associé, consultez Gérer les dépendances matérielles cibles pour connaître les étapes à suivre dans votre application.