Definizioni hardwareHardware definitions

In questa sezione vengono descritti i file di definizione hardware e come crearli per Azure Sphere lavagne e moduli.This section describes hardware definition files and how to create them for Azure Sphere boards and modules.

File di definizione dell'hardwareHardware definition files

Le definizioni hardware servono due scopi distinti ma correlati:Hardware definitions serve two separate but related purposes:

Le definizioni specifiche della lavagna definiscono le periferiche specifiche di un modulo o di un'altra lavagna e consentono a un'applicazione di farvi riferimento tramite identificatori rilevanti e significativi.Board-specific definitions define the specific peripherals of a module or other board and enable an application to reference them by using identifiers that are relevant and meaningful. Ad esempio, un'app può usare "Red_LED_1" invece di un numero opaco, ad esempio GPIO "13".For example, an app can use "Red_LED_1" instead of an opaque number such as GPIO "13". La directory HardwareDefinitions in Azure Sphere SDK contiene definizioni per le lavagne di Azure Sphere comuni e i chip utilizzati.The HardwareDefinitions directory in the Azure Sphere SDK contains such definitions for common Azure Sphere boards and the chips they use. Questa directory si trova Microsoft Azure Sphere SDK\HardwareDefinitions in Windows e /opt/azurespheresdk/HardwareDefinitions in Linux.This directory is Microsoft Azure Sphere SDK\HardwareDefinitions on Windows and /opt/azurespheresdk/HardwareDefinitions on Linux.

Le definizioni specifiche dell'applicazione eseguono il mapping delle periferiche a cui viene fatto riferimento nel codice dell'applicazione per le definizioni specifiche della lavagna.Application-specific definitions map peripherals that are referenced in application code to board-specific definitions. Le definizioni specifiche dell'applicazione sono compilate in base a definizioni specifiche della lavagna e definiscono un singolo set di identificatori che possono essere usati per fare riferimento alle periferiche in qualsiasi lavagna.Application-specific definitions are built on board-specific definitions, and define a single set of identifiers that can be used to reference peripherals on any board. Pertanto, un'applicazione eseguita su più lavagne potrebbe avere una definizione specifica dell'applicazione per ogni tipo di bacheca, ma l'applicazione stessa utilizza un solo set di identificatori di periferiche.Thus, an application that runs on multiple boards might have an application-specific definition for each type of board, but the application itself uses only one set of peripheral identifiers. Il codice può essere eseguito completamente senza modifiche su hardware diverso; uno sviluppatore deve solo modificare il riferimento in modo da usare la definizione appropriata.The code itself can run entirely unchanged on different hardware; a developer only needs to change the reference to use the appropriate definition. Ad esempio, il codice dell'applicazione per un creatore di caffè fa riferimento a un indicatore LED BrewingStatus.For example, the application code for a coffee maker references a BrewingStatus indicator LED. La lavagna di controllo caffettiera viene originata da due fornitori, Contoso e fabrikam.The coffee maker control board is sourced by two suppliers, Contoso and Fabrikam. Tramite l'utilizzo di definizioni specifiche dell'applicazione per ogni lavagna, è possibile eseguire il mapping dell'indicatore BrewingStatus a LED 2 sulla lavagna di controllo fornita da Contoso e LED 4 sulla lavagna di controllo fornita da Fabrikam.Through the use of application-specific definitions for each board, the BrewingStatus indicator can be mapped to LED 2 on the control board supplied by Contoso and LED 4 on the control board supplied by Fabrikam.

Se l'applicazione usa definizioni hardware dall'SDK o dal fornitore dell'hardware e non si crea una definizione specifica dell'applicazione, è possibile ignorare la parte rimanente di questo argomento per il momento e passare direttamente a usare le dipendenze hardware.If your application uses hardware definitions from the SDK or from your hardware supplier—and you aren't creating your own application-specific definition—then you can skip the remainder of this topic for now, and go straight to using hardware dependencies.

I file di definizione hardware vengono creati in formato JSON.You create your hardware definition files in JSON format. Quindi si generano i file di intestazione C dai file JSON.You then generate C header files from the JSON files.

Formato di un file di definizione hardwareFormat of a hardware definition file

Un file di definizione hardware è un file JSON con il formato seguente:A hardware definition file is a JSON file with the following 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": " "},
   ]
}

La sezione Metadata contiene informazioni sul file, ovvero il tipo di file, la versione e così via.The Metadata section contains information about the file (file type, version, etc.).

La sezione Description contiene informazioni sulla scheda o sul modulo.The Description section contains information about the board or module. Il campo "MainCoreHeaderFileTopContent" contiene le informazioni che verranno inserite all'inizio del file di intestazione generato.The "MainCoreHeaderFileTopContent" field contains information that will be placed at the beginning of the generated header file.

Nella sezione Imports viene specificato il percorso del file di definizione hardware per la piattaforma hardware sottostante (lavagna o modulo).The Imports section specifies the pathname of the hardware definition file for the underlying hardware platform (board or module).

La sezione Peripherals include l'elenco delle periferiche esposte da questa scheda per l'uso nelle applicazioni.The Peripherals section lists the peripherals that this board exposes for use in applications. Una descrizione della periferica presenta il formato seguente:A peripheral description has the following format:

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

Di seguito sono riportati gli elementi della sezione periferiche :The following are the elements of the Peripherals section:

Name: l'identificatore usato per fare riferimento alla periferica nel codice dell'applicazione.Name - The identifier used to reference the peripheral in your application code.

Type: il tipo di periferica, ad esempio GPIO, UART, ADC.Type - The type of peripheral (for example, Gpio, Uart, Adc). Per informazioni sul tipo, vedere il file di definizione dell'hardware indicato nella sezione Imports.Refer to the hardware definition file listed in the Imports section to obtain type information.

Mapping: associa l'identificatore del campo Name all'identificatore usato per la periferica nel file di definizione dell'hardware importato.Mapping - Maps the identifier in the Name field to the identifier used for the peripheral in the imported hardware definition file.

Comments: fornisce informazioni utili da visualizzare nel file di intestazione generato.Comments - Provides helpful information to appear in the generated header file. Ad esempio, le assegnazioni di pin per le periferiche ISU * o il mapping dei LED incorporati ai pin GPIO del microcontroller o del modulo sottostante.For example, pin assignments for ISU* peripherals, or mapping on-board LEDs to GPIO pins of the underlying MCU or Module.

Esempio: definizione specifica della lavagnaExample: board-specific definition

Nell'esempio seguente viene illustrata una parte del file di definizione dell'hardware che contiene una definizione specifica della lavagna per una lavagna di sviluppo MT3620 fittizia denominata lavagna.The following example shows a portion of the hardware definition file that contains a board-specific definition for a fictional MT3620 development board called MyBoard. Specifica le definizioni di piedinatura periferiche per la lavagna.It specifies the peripheral pinout definitions for MyBoard. Importa le definizioni delle risorse dal file di definizione dell'hardware specifico del chip (mt3620.json) per la MCU MT3620.It imports resource definitions from the chip-specific hardware definition file (mt3620.json) for the MT3620 MCU. Le informazioni nella sezione periferiche generano un mapping pin-to-pin delle risorse esposte da lavagna alle risorse fornite dalla MCU MT3620 sottostante.The information in the Peripherals section results in a pin-to-pin mapping of the resources exposed by MyBoard to the resources provided by the underlying MT3620 MCU.

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

È possibile visualizzare altri esempi di file di definizione specifici della lavagna nella directory HardwareDefinitions che fa parte dell'installazione di Azure Sphere SDK.You can see additional examples of board-specific definition files in the HardwareDefinitions directory that is part of the Azure Sphere SDK installation.

Esempio: definizione specifica dell'applicazioneExample: application-specific definition

Nell'esempio seguente viene illustrata una parte di un file di definizione dell'hardware che contiene una definizione specifica dell'applicazione per un appliance per Coffee Maker fittizio.The following example shows a portion of a hardware definition file that contains an application-specific definition for a fictional coffee maker appliance.

Tra le periferiche incluse nell'applicazione sono presenti due indicatori LED e un pulsante di push.Among the peripherals included in the application are two indicator LEDs and a push button. Viene fatto riferimento nel codice dell'applicazione dagli identificatori COFFEEMAKER_STATUS_BREWING, COFFEEMAKER_STATUS_READY e COFFEEMAKER_BUTTON_START rispettivamente.They are referenced in the application code by the identifiers COFFEEMAKER_STATUS_BREWING, COFFEEMAKER_STATUS_READY, and COFFEEMAKER_BUTTON_START respectively. Questi identificatori vengono mappati alle periferiche definite nella definizione specifica della lavagna importata per la lavagna MT3620 immaginaria.These identifiers are mapped to peripherals defined in the imported board-specific definition for the fictional MT3620 board 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 sezione Imports contiene il percorso del file di definizione hardware per la lavagna fisica o il modulo.The Imports section contains the path to the hardware definition file for the physical board or module.

    "Imports" : [ {"Path": "... /MyHwDefs/my_board.json"} ],
    
  • La sezione periferiche esegue il mapping delle periferiche della lavagna di controllo della caffettiera alle periferiche corrispondenti in una lavagna o in un modulo.The Peripherals section maps the CoffeeMaker control board peripherals to the corresponding peripherals on a board or module.

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

    Nome: contiene l'identificatore usato per la periferica nel codice dell'applicazione.Name - contains the identifier used for the peripheral in the application code.

    Mapping: contiene l'identificatore usato per la periferica nel file di definizione hardware per una lavagna o un modulo.Mapping - contains the identifier used for the peripheral in the hardware definition file for a board or module.

La versione successiva del creatore del caffè potrebbe essere basata su MyBoardV2.The next version of the coffee maker might be built on MyBoardV2. Avrebbe una nuova definizione specifica della lavagna con periferiche come MY_BOARD_V2_LED_ORANGE.It would have a new board-specific definition with peripherals such as MY_BOARD_V2_LED_ORANGE. Questa operazione verrebbe importata da una nuova implementazione della definizione specifica dell'applicazione del creatore del caffè che esegue il mapping COFFEEMAKER_STATUS_BREWING al nuovo LED arancione.This would be imported by a new implementation of the coffee maker's application-specific definition that maps COFFEEMAKER_STATUS_BREWING to this new orange LED. Il codice dell'applicazione Coffee Maker effettivo rimarrà invariato.The actual coffee maker application code would remain unchanged.

Analogamente, una nuova implementazione della definizione "sample_appliance.json", usata dalle app di esempio di Azure Sphere, potrebbe consentire l'esecuzione di queste app di esempio senza modifiche nella lavagna.Similarly, a new implementation of the "sample_appliance.json" definition, used by the Azure Sphere sample apps, could enable these sample apps to run unchanged on MyBoard.

File di intestazioneHeader files

I file di intestazione vengono generati dai file JSON che contengono le definizioni hardware.Header files are generated from the JSON files that contain the hardware definitions. È necessario creare i file di intestazione per le definizioni specifiche della lavagna e specifiche dell'applicazione.You must create header files for both board-specific and application-specific definitions.

Per generare un file di intestazione, usare il comando azsphere hardware-definition generate-header.Use the azsphere hardware-definition generate-header command to generate a header file.

Per creare il file di intestazione, immettere la riga seguente al prompt dei comandi Azure Sphere.To create the header file, enter the following line at the Azure Sphere command prompt. Sostituire <filename> con il nome del file JSON.Replace <filename> with the name of the JSON file.

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

Il file di intestazione filename.h verrà creato e inserito nella cartella inc/hw.The header file filename.h will be created and placed in the folder inc/hw.

Ad esempio, immettere la riga seguente per generare un file di intestazione dal file JSON.For example, enter the following line to generate a header file from the JSON file.

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

Di seguito viene illustrata una parte del file di intestazione my_board. h:The following shows a portion of the my_board.h header file:

#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.Note By default, the generated header file will be placed in inc/hw, which must be a subdirectory of the directory that contains the input JSON file. Se questa sottodirectory non esiste, verrà creata.If this subdirectory doesn't exist it will be created.

Ora che è stato creato il file JSON di definizione hardware e il file di intestazione associato, vedere gestire le dipendenze hardware di destinazione per i passaggi da usare nell'applicazione.Now that you've created your hardware definition JSON file and its accompanying header file, see Manage target hardware dependencies for the steps to use it in your application.