Definizioni hardware

Questa sezione descrive i file di definizione hardware e come crearli per le schede e i moduli Azure Sphere.

File di definizione hardware

Le definizioni hardware servono a due scopi separati ma correlati:

Le definizioni specifiche della scheda definiscono le periferiche specifiche di un modulo o di un'altra scheda e consentono a un'applicazione di farvi riferimento utilizzando identificatori rilevanti e significativi. Ad esempio, un'app può usare "Red_LED_1" invece di un numero opaco come GPIO "13". La directory HardwareDefinitions in Azure Sphere SDK contiene tali definizioni per le comuni schede Azure Sphere e i chip che usano. Questa directory è %ProgramFiles(x86)%\Microsoft Azure Sphere SDK\HardwareDefinitions in Windows e /opt/azurespheresdk/HardwareDefinitions su Linux.

Le definizioni specifiche dell'applicazione mappano le periferiche a cui viene fatto riferimento nel codice dell'applicazione a definizioni specifiche della scheda. Le definizioni specifiche dell'applicazione sono basate su definizioni specifiche della scheda e definiscono un singolo set di identificatori che può essere utilizzato per fare riferimento alle periferiche su qualsiasi scheda. Pertanto, un'applicazione eseguita su più schede potrebbe avere una definizione specifica dell'applicazione per ogni tipo di scheda, ma l'applicazione stessa utilizza un solo set di identificatori periferici. Il codice stesso può essere eseguito completamente invariato su hardware diverso; uno sviluppatore deve solo modificare il riferimento per utilizzare la definizione appropriata. Ad esempio, il codice dell'applicazione per un produttore di caffè fa riferimento a un LED indicatore BrewingStatus. La bacheca di controllo del produttore del caffè proviene da due fornitori, Contoso e Fabrikam. Attraverso l'uso di definizioni specifiche dell'applicazione per ogni scheda, l'indicatore BrewingStatus può essere mappato a LED 2 sulla scheda di controllo fornita da Contoso e LED 4 sulla scheda di controllo fornita da Fabrikam.

Se l'applicazione usa le definizioni hardware dell'SDK o del fornitore dell'hardware e non si sta creando una definizione specifica dell'applicazione, per il momento è possibile ignorare il resto di questo argomento e passare direttamente all'uso delle dipendenze hardware.

Creare i file di definizione hardware in formato JSON. È quindi possibile generare i file di intestazione C dai file JSON.

Formato di un file di definizione hardware

Un file di definizione hardware è un file JSON con il formato seguente:

{
    "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 sezione Metadati contiene informazioni sul file (tipo di file, versione e così via).

La sezione Descrizione contiene informazioni sulla bacheca o sul modulo. Il campo "MainCoreHeaderFileTopContent" contiene informazioni che verranno inserite all'inizio del file di intestazione generato.

La sezione Imports specifica il percorso del file di definizione hardware per la piattaforma hardware sottostante (scheda o modulo).

La sezione Periferiche elenca le periferiche esposte da questa scheda per l'uso nelle applicazioni. La descrizione di una periferica ha il formato seguente:

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

Di seguito sono riportati gli elementi della sezione Peripherals :

Name: identificatore utilizzato per fare riferimento alla periferica nel codice dell'applicazione.

Tipo: tipo di periferica, ad esempio Gpio, Uart, Adc. Fare riferimento al file di definizione hardware elencato nella sezione Imports per ottenere informazioni sul tipo.

Mapping: esegue il mapping dell'identificatore nel campo Nome all'identificatore utilizzato per la periferica nel file di definizione hardware importato.

Commenti: fornisce informazioni utili da visualizzare nel file di intestazione generato. Ad esempio, aggiungi le assegnazioni per le periferiche ISU* o il mapping dei LED incorporati ai pin GPIO del MCU o modulo sottostante.

Esempio: definizione specifica della scheda

L'esempio seguente mostra una parte del file di definizione hardware che contiene una definizione specifica della bacheca per una scheda di sviluppo fittizia di MT3620 denominata MyBoard. Specifica le definizioni di pinout periferiche per MyBoard. Importa le definizioni delle risorse dal file di definizione hardware specifico del chip (mt3620.json) per MT3620 MCU. Le informazioni nella sezione Periferiche portano a una mappatura pin-to-pin delle risorse esposte da MyBoard alle risorse fornite dalla MCU MT3620 sottostante.

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

Puoi vedere altri esempi di file di definizione specifici della bacheca nella directory HardwareDefinitions che fa parte dell'installazione di Azure Sphere SDK.

Esempio: definizione specifica dell'applicazione

L'esempio seguente mostra una parte di un file di definizione hardware che contiene una definizione specifica dell'applicazione per un accessorio fittizio per la creazione di caffè.

Tra le periferiche incluse nell'applicazione ci sono due LED di indicatore e un pulsante di pressione. Nel codice dell'applicazione viene fatto riferimento dagli identificatori COFFEEMAKER_STATUS_BREWING, COFFEEMAKER_STATUS_READY e COFFEEMAKER_BUTTON_START rispettivamente. Questi identificatori vengono mappati alle periferiche definite nella definizione specifica della bacheca importata per la scheda MyBoard fittizia di MT3620.

{
    "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 sezione Imports contiene il percorso del file di definizione hardware per la scheda fisica o il modulo.

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

• La sezione Periferiche associa le periferiche del pannello di controllo CoffeeMaker alle periferiche corrispondenti di una scheda o di un modulo.

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

  Name: contiene l'identificatore utilizzato per la periferica nel codice dell'applicazione.

  Mapping: contiene l'identificatore utilizzato per la periferica nel file di definizione hardware per una scheda o un modulo.

La versione successiva del produttore di caffè potrebbe essere costruita su MyBoardV2. Avrebbe una nuova definizione specifica della scheda con periferiche come MY_BOARD_V2_LED_ORANGE. Ciò verrebbe importato da una nuova implementazione della definizione specifica dell'applicazione del produttore di caffè che associa COFFEEMAKER_STATUS_BREWING a questo nuovo LED arancione. Il codice effettivo dell'applicazione coffee maker rimane invariato.

Analogamente, una nuova implementazione della definizione "sample_appliance.json", usata dalle app di esempio Azure Sphere, potrebbe consentire l'esecuzione invariata di queste app di esempio in MyBoard.

File di intestazione

I file di intestazione vengono generati dai file JSON che contengono le definizioni hardware. È necessario creare file di intestazione per definizioni specifiche della bacheca e specifiche dell'applicazione.

Usare il comando azsfera hardware-definition generate-header per generare un file di intestazione.

Per creare il file di intestazione, immettere la riga seguente al prompt dei comandi di Azure Sphere. Sostituire <filename> con il nome del file JSON.

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

Il file di intestazione nomefile.h verrà creato e inserito nella cartella inc/hw.

Ad esempio, immettere la riga seguente per generare un file di intestazione dal file JSON.

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

Di seguito è illustrata una parte del file di intestazione 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
                   .
                   .
                   .

Nota Per impostazione predefinita, il file di intestazione generato verrà inserito in inc/hw, che deve essere una sottodirectory della directory che contiene il file JSON di input. Se questa sottodirectory non esiste, verrà creata.

Ora che hai creato il file JSON delle definizioni hardware e il relativo file di intestazione, vedi Gestire le dipendenze dell'hardware di destinazione per i passaggi da usare nell'applicazione.