Определения оборудования

  • Статья

В этом разделе описаны файлы определения оборудования и их создание для досок и модулей Azure Sphere.

Файлы определения оборудования

Определения оборудования служат для двух отдельных, но связанных целей:

Определения, относящиеся к плате, определяют конкретные периферийные устройства модуля или другой платы и позволяют приложению ссылаться на них с помощью релевантных и значимых идентификаторов. Например, приложение может использовать "Red_LED_1" вместо непрозрачного номера, такого как GPIO "13". Каталог HardwareDefinitions в пакете SDK для Azure Sphere содержит такие определения для распространенных досок Azure Sphere и используемых ими микросхем. Этот каталог находится в %ProgramFiles(x86)%\Microsoft Azure Sphere SDK\HardwareDefinitions Windows и /opt/azurespheresdk/HardwareDefinitions Linux.

Определения для конкретных приложений сопоставляют периферийные устройства, на которые ссылается код приложения, с определениями, зависящими от доски. Определения для конкретных приложений основаны на определениях, относящихся к плате, и определяют единый набор идентификаторов, которые можно использовать для ссылки на периферийные устройства на любой плате. Таким образом, приложение, работающее на нескольких платах, может иметь определение для каждого типа платы, но само приложение использует только один набор идентификаторов периферийных устройств. Сам код может выполняться совершенно без изменений на другом оборудовании; разработчику нужно только изменить ссылку, чтобы использовать соответствующее определение. Например, код приложения для кофеварки ссылается на светодиодный индикатор BrewingStatus. Доска управления кофеваркой подается двумя поставщиками, Contoso и Fabrikam. Благодаря использованию определений, характерных для каждого приложения, индикатор BrewingStatus можно сопоставить с индикатором 2 на панели управления, предоставляемой Contoso, и светодиодным индикатором 4 на панели управления, предоставляемой Fabrikam.

Если ваше приложение использует определения оборудования из пакета SDK или поставщика оборудования, а вы не создаете собственное определение для конкретного приложения, вы можете пропустить оставшуюся часть этого раздела и перейти к использованию зависимостей оборудования.

Файлы определения оборудования создаются в формате JSON. Затем вы создаете файлы заголовков C из файлов JSON.

Формат файла определения оборудования

Файл определения оборудования — это 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 содержит сведения, которые будут размещены в начале созданного файла заголовка.

В разделе Imports указывается путь к файлу определения оборудования для базовой аппаратной платформы (платы или модуля).

В разделе Периферийные устройства перечислены периферийные устройства, предоставляемые этой доской для использования в приложениях. Описание периферийного устройства имеет следующий формат:

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

Ниже приведены элементы раздела Периферийные устройства .

Имя — идентификатор, используемый для ссылки на периферийное устройство в коде приложения.

Type — тип периферийного устройства (например, Gpio, Uart, ADC). Сведения о типе см. в файле определения оборудования, указанном в разделе Импорт .

Сопоставление. Сопоставляет идентификатор в поле Имя с идентификатором, используемым для периферийного устройства в импортированном файле определения оборудования.

Примечания— содержит полезные сведения, которые будут отображаться в созданном файле заголовка. Например, назначение закреплений для периферийных устройств ISU* или сопоставление встроенных светодиодов с контактами GPIO базового MCU или модуля.

Пример: определение доски

В следующем примере показана часть файла определения оборудования, которая содержит определение, относящееся к плате, для вымышленной платы разработки MT3620 с именем MyBoard. Он задает определения периферийных контактов для MyBoard. Он импортирует определения ресурсов из файла определения оборудования для конкретной микросхемы (mt3620.json) для MCU MT3620. Сведения в разделе Периферийные устройства приводят к сопоставлению ресурсов, предоставляемых MyBoard, с ресурсами, предоставляемыми базовым MCU MT3620.

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

Дополнительные примеры файлов определений, относящихся к плате, можно просмотреть в каталоге HardwareDefinitions, который является частью установки пакета SDK для Azure Sphere.

Пример: определение для конкретного приложения

В следующем примере показана часть файла определения оборудования, которая содержит определение для конкретного приложения для вымышленной кофеварки (модуль).

Среди периферийных устройств, включенных в приложение, два индикатора и кнопка нажатия. На них ссылаются в коде приложения идентификаторы 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"},

    Name — содержит идентификатор, используемый для периферийного устройства в коде приложения.

    Сопоставление — содержит идентификатор, используемый для периферийного устройства в файле определения оборудования для платы или модуля.

Следующая версия кофеварки может быть создана на MyBoardV2. Он будет иметь новое определение с периферийными устройствами, такими как MY_BOARD_V2_LED_ORANGE. Это будет импортировано новой реализацией определения конкретного приложения кофеварки, которое сопоставляет COFFEEMAKER_STATUS_BREWING с этим новым оранжевым светодиодным индикатором. Фактический код приложения кофеварки останется неизменным.

Аналогичным образом, новая реализация определения "sample_appliance.json", используемого примерами приложений Azure Sphere, может позволить этим примерам приложений работать без изменений на 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-файл определения оборудования и сопутствующий файл заголовка, см. раздел Управление зависимостями целевого оборудования , чтобы узнать, как использовать его в приложении.