通过

硬件定义

  • 项目

重要

这是 Azure Sphere（旧版）文档。 Azure Sphere（旧版）将于 2027 年 9 月 27 日停用，用户此时必须迁移到 Azure Sphere（集成）。 使用位于 TOC 上方的版本选择器查看 Azure Sphere（集成）文档。

本部分介绍硬件定义文件以及如何为 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": " "},
   ]
}

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

Description 节包含有关开发板或模块的信息。 “MainCoreHeaderFileTopContent”字段包含将放在生成的头文件开头的信息。

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

Peripherals 节列出了此开发板公开的可在应用程序中使用的外设。 外围设备说明具有以下格式：

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

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

Name - 用于在应用程序代码中引用外设的标识符。

Type - 外设类型（例如 Gpio、Uart、Adc）。 若要获取类型信息，请参阅 Imports 节中列出的硬件定义文件。

Mapping - 将 Name 字段中的标识符映射到导入的硬件定义文件中用于外设的标识符。

Comments - 提供要显示在生成的头文件中的有用信息。 例如，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 文件及其随附的头文件后，请参阅管理目标硬件依赖项，了解在应用程序中使用它的步骤。