Manage target hardware dependencies

Azure Sphere hardware is available from multiple vendors, and each vendor may expose features of the underlying chip in different ways. Azure Sphere applications manage hardware dependencies by using hardware definition files, which define the features that a particular Azure Sphere-compatible chip, board, or module exposes. The Azure Sphere samples repository on GitHub includes hardware definition files for most current Azure Sphere hardware. Check with your hardware manufacturer if you need more information.

This topic describes how to set the target hardware for your high-level application and provides general information about hardware definition files. It also explains how to develop a hardware abstraction for your own products.

Note

The information in this topic applies only to high-level applications.

Set the hardware target for an application

To set the target hardware for an application, you need to set the project properties to use the corresponding hardware definition and include the appropriate header file. You can use the hardware definition files that are supplied with the samples or other files supplied by your hardware vendor.

The Azure Sphere samples use an abstraction that enables them to run on any hardware. When you build a sample application, you can use the sample hardware abstraction files. If you're creating a new application that targets specific hardware, you need to follow these steps:

  1. Copy the JSON and .h files for your hardware and add them to your project. A hardware platform may involve a board, a module, and a chip, so be sure to copy them all. For example, if you're using the MT 3620 reference development board (RDB), copy the files from the mt3620_rdb and mt3620 folders in the samples repository. Do not copy sample_hardware.json or sample_hardware.h.

  2. Set the Target Hardware Definition Directory and the Target Hardware Definition for your hardware.

    The Target Hardware Definition Directory identifies the folder that contains the hardware definition files for the target hardware. This path is relative to the workspace of the project. The Target Hardware Definition identifies the JSON file in the Target Hardware Definition Directory that defines the mappings from the sample application code to the target hardware.

    • For a Visual Studio project, use Project Properties to set the Target Hardware Definition Directory and the Target Hardware Definition for your hardware. For example:

       ![Target Hardware Definition properties](../media/targethardwareproperties.png)
      
       In the example, the ..\Hardware\mt3620_rdb folder contains the mt3620_rdb.json file, which maps peripherals on an MT3620 reference design board, such as the Seeed MT3620 Development Kit, to features of the underlying MT3620 chip.
      
    • For a CMake project, edit the AzureSphereTargetHardwareDefinitionDirectory and AzureSphereTargetHardwareDefinition fields in the CMakeSettings.json file. For example:

       ```json
       "AzureSphereTargetHardwareDefinitionDirectory": "..\\..\\..\\Hardware\\mt3620_rdb",
       "AzureSphereTargetHardwareDefinition": "mt3620_rdb.json"
       ```
      
  3. In your application code, include the header file for your target hardware. The following includes the header for the MT3620 RDB hardware, assuming a folder structure that is similar to the one used in the Azure Sphere samples:

    #include <hw/mt3620_rdb.h>
    
  4. In the JSON file for your board or module, find the name of each peripheral that you plan to use in the application. Use these names in your application code for the corresponding hardware. For example, for MT3620 RDB hardware, your application would use MT3620_RDB_LED1_RED to identify the red channel for LED 1, which maps to GPIO 8. For example:

    // Open red channel for LED1 on MT3620 RDB
    err = GPIO_OpenAsInput (MT3620_RDB_LED1_RED);
    

    To target the Avnet MT3620 Starter Kit, the application would specify AVNET_MT3620_SK_USER_LED_RED:

    // // Open red channel for LED1 on Avnet MT3620 Starter Kit
    err = GPIO_OpenAsInput (AVNET_MT3620_SK_USER_LED_RED);
    
  5. In the app_manifest.json file, use $name-in-code to represent the identifiers for the peripherals. The following example shows how to target LED 1 on MT3620 RDB hardware:

    "Gpio": [ "$MT3620_RDB_LED1_RED" ]
    

    The next example shows how to specify this GPIO for an application that targets the Avnet MT3620 Starter Kit:

    "Gpio": [ "$AVNET_MT3620_SK_USER_LED_RED" ]
    

Hardware definition files

A physical hardware definition file defines the features that a particular chip or Azure Sphere-compatible board or module exposes.

The base for all hardware definition files is a pair of JSON and header files that identify the features that a particular Azure Sphere chip exposes. The JSON file lists the peripherals that are available on the chip along with the identifiers and application manifest values that are required to use each peripheral. For example, the mt3620.json file associates the name MT3620_GPIO8 with pin 8 on the header and GPIO 8 in the application manifest. In turn, the mt3620.h header file defines this pin as follows:

// MT3620 GPIO 8
#define MT3620_GPIO8 (8)

For each type of board or module, a board-specific JSON file maps the features exposed by that board to the features of the underlying chip. Thus, the MT3620 reference board design exposes the red channel on LED1 via GPIO 8, so mt3620_rdb.json defines MT3620_RDB_LED1_RED as follows:

{"Name": "MT3620_RDB_LED1_RED", "Type": "Gpio", "Mapping": "MT3620_GPIO8", "Comment": "LED 1 Red channel uses GPIO8."}

This mapping associates the identifier MT3620_RDB_LED1_RED with MT3620_GPIO8, which mt3620.json associates with pin 8. In the resulting mt3620_rdb.h file, MT3620_RDB_LED1_RED is defined as follows:

// LED 1 Red channel uses GPIO8.
#define MT3620_RDB_LED1_RED MT3620_GPIO8

As a result, applications that run on an MT3620 RDB can use MT3620_RDB_LED1_RED, and the name will resolve to MT3620_GPIO8 at run time and to 8 when the code is compiled, the application manifest is processed, and the image package is generated.

Develop a custom hardware abstraction for your product

You can develop a custom hardware abstraction for your product by using a pattern similar to the one used in the Azure Sphere samples repository. Use the abstraction across the different hardware options supported in your product line.

A hardware abstraction requires an abstract hardware definition file, which maps the hardware and corresponding identifiers used by an application to the definitions in one or more physical hardware definition files. The following diagram shows the relationships among these files:

Relationships of hardware definition files

The sample_hardware.json files in the samples repository are abstract hardware definition files for the sample applications. These files map the identifiers used in the sample code to the same peripherals, abstracting how they are exposed differently on each board or module.

Create the abstraction files

To create a hardware abstraction, follow these steps:

  1. Identify the peripherals that your applications use. For example, COFFEE_MAKER_STATUS_LED indicates that the application requires an LED; DISHWASHER_WASHING_SPI_MOTOR indicates that the application requires an SPI.

  2. Create a JSON file for each hardware platform that your application targets. Use the files in the Azure Sphere samples repository as a guide. In the Imports section of the JSON file, specify the path to the hardware definition file for the hardware platform. For example, the following imports the definitions from mt3620_rdb.json:

    "Imports" : [ {"Path": "../mt3620_rdb/mt3620_rdb.json"} ],
    
  3. For each common peripheral, the Peripherals section of the JSON file should contain a line in the following form:

    {"Name": "<name-in-code>", "Type": "<type>", "Mapping": "<name-in-imported-definition>", "Comment": "<helpful info"}
    
    • Replace name-in-code and name-in-imported-definition with the identifiers used for the peripheral in your application and in the imported physical hardware definition file, respectively
    • Replace type with the type of peripheral. See the hardware definition files for examples.
    • Replace helpful-info with information to appear in the generated header file

    For example, the following line in a JSON file maps COFFEE_MAKER_STATUS_LED to the red channel of LED 1 on an MT3620 RDB:

    {"Name": "COFFEE_MAKER_STATUS_LED", "Type": "Gpio", "Mapping": "MT3620_RDB_LED1_RED", "Comment": "MT3620 RDB: LED 1 (red channel)"}`  
    
  4. Generate a header file from each JSON file. In an Azure Sphere Developer Command Prompt, run azsphere hardware-definition generate-header, and supply the JSON file as the --input parameter. For example:

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

    This example generates the CoffeeMaker.h file and places it in the inc\hw subdirectory of the folder that contains the input file.

Add abstraction support to your application

After you create a hardware abstraction, follow these steps to use it in your application:

  1. In your application code, include the header file for the hardware abstraction, such as CoffeeMaker.h.
  2. In the Project Properties, set the hardware target for the application.