Use hardware definitions

This topic describes how to use hardware definitions in your high-level application. See Hardware definitions for more detailed information about hardware definitions, including how to create your own hardware definition files.

Note

The directory containing the JSON hardware definitions also contains an inc/hw sub-directory for the equivalent header file definitions.

Use a hardware definition from the SDK

The HardwareDefinitions directory in the Azure Sphere SDK contains 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.

1. In CMakelists.txt search for the function azsphere_target_hardware_definition and set the TARGET_DEFINITION parameter to the hardware definition JSON file for the target board. The following example shows how to set the TARGET_DEFINITION parameter if your application uses the MT3620 Reference Development Board (RDB):

   azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DEFINITION "mt3620_rdb.json")

2. In main.c, include the corresponding hardware definition header file for the target board:

   #include  "hw/mt3620_rdb.h"
   

3. See the header file or the JSON file to get information about the identifier and the type of peripherals used in your application. Create or modify your application code accordingly.

   For example, an application that targets the MT3620 Reference Development Board (RDB) uses an on-board LED. The constant used to identify the LED is defined in the header file mt3620_rdb.h as follows:

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

   The following line initializes the LED using the information provided in the hardware definition.

   int fd = GPIO_OpenAsOutput(MT3620_RDB_LED1_RED, GPIO_OutputMode_PushPull, GPIO_Value_High);
   

4. Update the application manifest to enable the peripherals that the app is now using:

   "Capabilities": {  "Gpio": [ "MT3620_RDB_LED1_RED" ]},
   

5. Compile and package the application.

Use a hardware definition that is not installed with the SDK

1. In CMakelists.txt search for the azsphere_target_hardware_definition function .

2. Set the TARGET_DIRECTORY parameter with the relative or absolute path or paths to the directory or directories containing the hardware definition files you want to use.

3. Set the TARGET_DEFINITION parameter to the name of the hardware definition JSON file. The build process searches for this file, and any files that it imports, in the target directories in the order listed, and then in the SDK itself.

   azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "<path>/my_app/contoso_hardware_definitions" TARGET_DEFINITION "contoso_board.json")

   Specify each target directory in double quotation marks, and separate directory names with spaces. In the example, <path> represents the path to the my_app folder.

4. In main.c include the hardware definition header file for the target board. The build process will search for this file, and those files that it includes, in the 'inc' subdirectory of the target directories in the order listed, and then in the SDK itself. Hence, following convention, the following will find contoso_board.h in inc/hw sub-directory of the target directories:

   #include   "hw/contoso_board.h"
   

5. See the header file or the JSON file to get information about the identifier and the type of peripherals used in your application. Create or modify your application code accordingly.

   int fd = GPIO_OpenAsOutput(CONTOSO_BOARD_LED_RED, GPIO_OutputMode_PushPull, GPIO_Value_High);
   

6. Update the application manifest (app_manifest.json) to enable the peripherals that the app is now using:

   "Capabilities": {  "Gpio": [ "CONTOSO_BOARD_LED_RED" ]},
   

7. Compile and package the application.