Définitions matérielles

Article
08/09/2023

Cette section décrit les fichiers de définition de matériel et comment les créer pour les tableaux 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 ces définitions pour les cartes Azure Sphere courantes et les puces qu’elles 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 à des définitions spécifiques à la carte. Les définitions spécifiques à l’application reposent 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 tableaux peut avoir une définition spécifique à l’application pour chaque type de carte, mais l’application elle-même utilise un seul ensemble d’identificateurs périphériques. Le code lui-même peut s’exécuter entièrement sur un matériel différent ; 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é provient de 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é à la LED 2 sur la carte de contrôle fournie par Contoso et à la LED 4 sur la carte de contrôle fournie par Fabrikam.

Si votre application utilise des définitions matérielles du SDK ou de votre fournisseur de 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 des dépendances matérielles.

Vous créez vos fichiers de définition de matériel 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 seront 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 Périphériques répertorie les périphériques que cette carte expose pour une utilisation dans les applications. Une description de 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 :

Nom : 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 matérielle répertorié dans la section Imports pour obtenir des informations de type.

Mappage : mappe l’identificateur du champ Nom à l’identificateur utilisé pour le périphérique dans le fichier de définition matérielle importé.

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

Exemple : définition spécifique au tableau

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 d’épinglage 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 d’autres exemples 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 machine à café fictive Appliance.

Parmi les périphériques inclus dans l’application figurent deux voyants LED et un bouton pousseur. 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 à des périphériques définis dans la définition spécifique à la carte importée pour la carte fictive 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"},
                                             .
                                             .
                                             .
    ]
}

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 la 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"},
```
Name : 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 basée 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 cafetière qui mappe COFFEEMAKER_STATUS_BREWING à cette nouvelle LED orange. Le code de l’application de machine à café réel 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, pourrait permettre à ces exemples d’applications de s’exécuter sans modification 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 au tableau et à 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 par <filename> 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
                   .
                   .
                   .

Note Par défaut, 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 est créé.

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