硬件定义

项目
08/09/2023

本部分介绍硬件定义文件以及如何为 Azure Sphere 板和模块创建它们。

硬件定义文件

硬件定义有两个单独但相关的目的：

特定于板 的定义定义模块或其他板的特定外围设备，并使应用程序能够使用相关且有意义的标识符来引用它们。例如，应用可以使用“Red_LED_1”，而不是 GPIO“13”等不透明数字。 Azure Sphere SDK 中的 HardwareDefinitions 目录包含常见 Azure Sphere 板及其使用的芯片的此类定义。此目录位于 %ProgramFiles(x86)%\Microsoft Azure Sphere SDK\HardwareDefinitions Windows 和 /opt/azurespheresdk/HardwareDefinitions Linux 上。

特定于应用程序 的定义将应用程序代码中引用的外围设备映射到特定于板的定义。特定于应用程序的定义基于特定于板的定义，并定义了一组标识符，这些标识符可用于引用任何板上的外围设备。因此，在多个开发板上运行的应用程序对于每种类型的开发板可能有特定于应用程序的定义，但应用程序本身只使用一组外围标识符。代码本身可以在不同硬件上完全保持不变地运行;开发人员只需更改引用即可使用适当的定义。例如，咖啡机的应用程序代码引用 BrewingStatus 指示器 LED。咖啡机控制板由 Contoso 和 Fabrikam 两家供应商采购。通过对每个板使用特定于应用程序的定义，BrewingStatus 指示器可以映射到 Contoso 提供的控制板上的 LED 2 和 Fabrikam 提供的控制板上的 LED 4。

如果应用程序使用来自 SDK 或硬件供应商的硬件定义，并且你未创建自己的特定于应用程序的定义，则可以暂时跳过本主题的其余部分，直接转到使用硬件依赖项。

以 JSON 格式创建硬件定义文件。然后，从 JSON 文件生成 C 头文件。

硬件定义文件的格式

硬件定义文件是具有以下格式的 JSON 文件：

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

“元数据”部分包含有关文件的信息， (文件类型、版本等) 。

“ 说明 ”部分包含有关开发板或模块的信息。 “MainCoreHeaderFileTopContent”字段包含将放置在生成的头文件开头的信息。

“导入”部分指定基础硬件平台 (板或模块) 的硬件定义文件的路径名。

“ 外围设备 ”部分列出了此开发板公开供应用程序使用的外围设备。外围设备说明采用以下格式：

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

以下是 “外围设备 ”部分的元素：

名称 - 用于在应用程序代码中引用外围设备的标识符。

类型 - 外围 (的类型，例如 Gpio、Uart、Adc) 。请参阅导入部分中列出的硬件定义文件以获取类型信息。

映射 - 将“名称”字段中的标识符映射到导入的硬件定义文件中用于外围设备的标识符。

注释 - 提供在生成的头文件中显示的有用信息。例如，ISU* 外围设备的引脚分配，或将板载 LED 映射到基础 MCU 或模块的 GPIO 引脚。

示例：特定于板的定义

以下示例显示了硬件定义文件的一部分，该文件包含名为 MyBoard 的虚构 MT3620 开发板的特定于板的定义。它指定 MyBoard 的外围引脚定义。它从 MT3620 MCU 的特定于芯片的硬件定义文件 (mt3620.json) 导入资源定义。 外围设备部分中的信息导致 MyBoard 公开的资源到基础 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"},
                              .
                              .
                              .
    ]
}

可以在作为 Azure Sphere SDK 安装的一部分的 HardwareDefinitions 目录中查看特定于板的定义文件的其他示例。

示例：特定于应用程序的定义

以下示例演示硬件定义文件的一部分，该文件包含虚构咖啡机设备的特定于应用程序的定义。

应用程序中包含的外围设备包括两个指示灯 LED 和一个按钮。它们分别由标识符COFFEEMAKER_STATUS_BREWING、COFFEEMAKER_STATUS_READY和COFFEEMAKER_BUTTON_START在应用程序代码中引用。这些标识符映射到虚构 MT3620 板 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"},
                                             .
                                             .
                                             .
    ]
}

“导入”部分包含物理板或模块的硬件定义文件的路径。
```
"Imports" : [ {"Path": "... /MyHwDefs/my_board.json"} ],
```
“ 外围设备 ”部分将 CoffeeMaker 控制板外围设备映射到开发板或模块上的相应外围设备。
```
{"Name": "COFFEEMAKER_BUTTON_START", "Type": "Gpio", "Mapping": "MY_BOARD_BUTTON_A", "Comment": " Start button uses MyBoard Button A"},
```
名称 - 包含用于应用程序代码中外围设备的标识符。

映射 - 包含用于开发板或模块的硬件定义文件中外围设备的标识符。

下一版本的咖啡机可能基于 MyBoardV2 构建。它将具有特定于板的新定义，以及外围设备（例如MY_BOARD_V2_LED_ORANGE）。这将通过咖啡机应用程序特定定义的新实现导入，该定义将COFFEEMAKER_STATUS_BREWING映射到这种新的橙色 LED。实际的咖啡机应用程序代码将保持不变。

同样， Azure Sphere 示例应用使用的新“sample_appliance.json”定义实现可以使这些示例应用在 MyBoard 上保持不变地运行。

头文件

头文件是从包含硬件定义的 JSON 文件生成的。必须为特定于板的定义和特定于应用程序的定义创建头文件。

使用 azsphere hardware-definition generate-header 命令生成头文件。

若要创建头文件，请在 Azure Sphere 命令提示符处输入以下行。将替换为 <filename> JSON 文件的名称。

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

将创建头文件 filename.h 并将其放置在文件夹 inc/hw 中。

例如，输入以下行以从 JSON 文件生成头文件。

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

下面显示了 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
                   .
                   .
                   .

注意默认情况下，生成的头文件将放置在中 inc/hw，该文件必须是包含输入 JSON 文件的目录的子目录。如果此子目录不存在，则会创建它。

创建硬件定义 JSON 文件及其随附头文件后，请参阅管理目标硬件依赖项，了解在应用程序中使用它的步骤。

Share via

硬件定义

硬件定义文件

硬件定义文件的格式

示例：特定于板的定义

示例：特定于应用程序的定义

头文件

其他资源