Hardware definitions

Article
08/08/2023

This section describes hardware definition files and how to create them for Azure Sphere boards and modules.

Hardware definition files

Hardware definitions serve two separate but related purposes:

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. For example, an app can use "Red_LED_1" instead of an opaque number such as GPIO "13". The HardwareDefinitions directory in the Azure Sphere SDK contains such definitions for common Azure Sphere boards and the chips they use. This directory is %ProgramFiles(x86)%\Microsoft Azure Sphere SDK\HardwareDefinitions on Windows and /opt/azurespheresdk/HardwareDefinitions on Linux.

Application-specific definitions map peripherals that are referenced in application code to board-specific definitions. 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. 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. The code itself can run entirely unchanged on different hardware; a developer only needs to change the reference to use the appropriate definition. For example, the application code for a coffee maker references a BrewingStatus indicator LED. The coffee maker control board is sourced by two suppliers, Contoso and 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.

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.

You create your hardware definition files in JSON format. You then generate C header files from the JSON files.

Format of a hardware definition file

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

The Metadata section contains information about the file (file type, version, and so on).

The Description section contains information about the board or module. The "MainCoreHeaderFileTopContent" field contains information that will be placed at the beginning of the generated header file.

The Imports section specifies the pathname of the hardware definition file for the underlying hardware platform (board or module).

The Peripherals section lists the peripherals that this board exposes for use in applications. A peripheral description has the following format:

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

The following are the elements of the Peripherals section:

Name - The identifier used to reference the peripheral in your application code.

Type - The type of peripheral (for example, Gpio, Uart, Adc). Refer to the hardware definition file listed in the Imports section to obtain type information.

Mapping - Maps the identifier in the Name field to the identifier used for the peripheral in the imported hardware definition file.

Comments - Provides helpful information to appear in the generated header file. For example, pin assignments for ISU* peripherals, or mapping on-board LEDs to GPIO pins of the underlying MCU or Module.

Example: board-specific definition

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. It specifies the peripheral pinout definitions for MyBoard. It imports resource definitions from the chip-specific hardware definition file (mt3620.json) for the MT3620 MCU. 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"},
                              .
                              .
                              .
    ]
}

You can see additional examples of board-specific definition files in the HardwareDefinitions directory that is part of the Azure Sphere SDK installation.

Example: application-specific definition

The following example shows a portion of a hardware definition file that contains an application-specific definition for a fictional coffee maker appliance.

Among the peripherals included in the application are two indicator LEDs and a push button. They are referenced in the application code by the identifiers COFFEEMAKER_STATUS_BREWING, COFFEEMAKER_STATUS_READY, and COFFEEMAKER_BUTTON_START respectively. 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"},
                                             .
                                             .
                                             .
    ]
}

The Imports section contains the path to the hardware definition file for the physical board or module.
```
"Imports" : [ {"Path": "... /MyHwDefs/my_board.json"} ],
```
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"},
```
Name - contains the identifier used for the peripheral in the application code.

Mapping - contains the identifier used for the peripheral in the hardware definition file for a board or module.

The next version of the coffee maker might be built on MyBoardV2. It would have a new board-specific definition with peripherals such as MY_BOARD_V2_LED_ORANGE. 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. The actual coffee maker application code would remain unchanged.

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.

Header files

Header files are generated from the JSON files that contain the hardware definitions. You must create header files for both board-specific and application-specific definitions.

Use the azsphere hardware-definition generate-header command to generate a header file.

To create the header file, enter the following line at the Azure Sphere Command Prompt. Replace <filename> with the name of the JSON file.

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

The header file filename.h will be created and placed in the folder inc/hw.

For example, enter the following line to generate a header file from the JSON file.

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

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
                   .
                   .
                   .

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. If this subdirectory doesn't exist it will be created.

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.