Definice hardwaru

Článek
03/01/2025

Důležité

Toto je dokumentace k Azure Sphere (starší verze). Azure Sphere (starší verze) se vyřazuje 27. září 2027 a uživatelé musí do této doby migrovat do Azure Sphere (integrované). K zobrazení dokumentace k Azure Sphere (integrované) použijte selektor verzí umístěný nad obsahem.

Tato část popisuje soubory definic hardwaru a způsob jejich vytvoření pro panely a moduly Azure Sphere.

Soubory definic hardwaru

Definice hardwaru slouží ke dvěma samostatným, ale souvisejícím účelům:

Definice specifické pro desku definují konkrétní periferní zařízení modulu nebo jiné desky a umožňují aplikaci odkazovat na ně pomocí identifikátorů, které jsou relevantní a smysluplné. Aplikace může například místo neprůhleného čísla, jako je GPIO 13, použít "Red_LED_1". Adresář HardwareDefinitions v sadě Azure Sphere SDK obsahuje takové definice pro běžné desky Azure Sphere a čipy, které používají. Tento adresář je %ProgramFiles(x86)%\Microsoft Azure Sphere SDK\HardwareDefinitions ve Windows a /opt/azurespheresdk/HardwareDefinitions v Linuxu.

Definice specifické pro aplikace mapují periferní zařízení odkazovaná v kódu aplikace na definice specifické pro konkrétní desky. Definice specifické pro aplikaci jsou založené na definicích specifických pro desku a definují jednu sadu identifikátorů, které lze použít k odkazování na periferní zařízení na libovolné desce. Aplikace, která běží na více panelech, tedy může mít pro každý typ desky definici specifickou pro aplikaci, ale samotná aplikace používá pouze jednu sadu identifikátorů periferních zařízení. Samotný kód může běžet zcela beze změny na jiném hardwaru; Vývojář potřebuje změnit odkaz jenom tak, aby používal příslušnou definici. Kód aplikace pro kávovar například odkazuje na led indikátor BrewingStatus. Řídicí deska kávovaru je zdrojem dvou dodavatelů, Contoso a Fabrikam. Pomocí definic specifických pro aplikaci pro každou desku lze indikátor BrewingStatus mapovat na LED 2 na řídicí desce dodané společností Contoso a LED 4 na řídicí desce dodané společností Fabrikam.

Pokud vaše aplikace používá definice hardwaru ze sady SDK nebo od dodavatele hardwaru a nevytváčíte vlastní definici specifickou pro aplikaci, můžete prozatím zbývající část tohoto tématu přeskočit a přejít přímo k používání závislostí hardwaru.

Soubory definic hardwaru vytvoříte ve formátu JSON. Pak ze souborů JSON vygenerujete soubory hlaviček jazyka C.

Formát souboru definice hardwaru

Soubor definice hardwaru je soubor JSON s následujícím formátem:

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

Část Metadata obsahuje informace o souboru (typ souboru, verze atd.).

Část Popis obsahuje informace o panelu nebo modulu. Pole MainCoreHeaderFileTopContent obsahuje informace, které budou umístěny na začátku vygenerovaného souboru hlaviček.

Část Import určuje cestu k souboru definice hardwaru pro základní hardwarovou platformu (desku nebo modul).

V části Periferní zařízení jsou uvedena periferní zařízení, která tato deska zveřejňuje pro použití v aplikacích. Popis periferního zařízení má následující formát:

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

V části Periferní zařízení jsou následující prvky:

Název – identifikátor použitý k odkazu na periferní zařízení v kódu aplikace.

Typ – typ periferního zařízení (například Gpio, Uart, Adc). Informace o typu najdete v souboru definice hardwaru uvedeného v části Import .

Mapování – Mapuje identifikátor v poli Název na identifikátor použitý pro periferní zařízení v importovaném souboru definice hardwaru.

Komentáře – poskytuje užitečné informace, které se zobrazí v vygenerovaném souboru hlaviček. Můžete například připnout přiřazení periferních zařízení ISU* nebo namapovat indikátory LED na piny GPIO podkladového MCU nebo modulu.

Příklad: definice specifická pro desku

Následující příklad ukazuje část souboru definice hardwaru, která obsahuje definici specifickou pro desku pro fiktivní vývojovou desku MT3620 s názvem MyBoard. Určuje definice periferních pinoutů pro MyBoard. Importuje definice prostředků ze souboru definice hardwaru specifického pro čip (mt3620.json) pro MT3620 MCU. Informace v části Periferní zařízení mají za následek mapování prostředků vystavených nástrojem MyBoard k prostředkům, které poskytuje základní 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"},
                              .
                              .
                              .
    ]
}

Další příklady definičních souborů specifických pro desku najdete v adresáři HardwareDefinitions, který je součástí instalace sady Azure Sphere SDK.

Příklad: definice specifická pro aplikaci

Následující příklad ukazuje část souboru definice hardwaru, která obsahuje definici specifickou pro aplikaci pro fiktivní kávovar zařízení.

Mezi periferní zařízení, která jsou součástí aplikace, jsou dvě indikátory LED a tlačítko. Odkazují se v kódu aplikace identifikátory COFFEEMAKER_STATUS_BREWING, COFFEEMAKER_STATUS_READY a COFFEEMAKER_BUTTON_START. Tyto identifikátory se mapují na periferní zařízení definovaná v importované definici desky specifické pro fiktivní desku 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"},
                                             .
                                             .
                                             .
    ]
}

Část Import obsahuje cestu k souboru definice hardwaru pro fyzickou desku nebo modul.
```
"Imports" : [ {"Path": "... /MyHwDefs/my_board.json"} ],
```
Oddíl Periferní zařízení mapuje periferní zařízení kávovaru na odpovídající periferní zařízení na desce nebo modulu.
```
{"Name": "COFFEEMAKER_BUTTON_START", "Type": "Gpio", "Mapping": "MY_BOARD_BUTTON_A", "Comment": " Start button uses MyBoard Button A"},
```
Název – obsahuje identifikátor použitý pro periferní zařízení v kódu aplikace.

Mapování – obsahuje identifikátor použitý pro periferní zařízení v definičním souboru hardwaru pro desku nebo modul.

Další verze kávovaru může být postavena na MyBoardV2. Měla by novou definici specifickou pro desku s periferními zařízeními, jako je MY_BOARD_V2_LED_ORANGE. To by bylo importováno novou implementací definice specifické pro kávovar, která mapuje COFFEEMAKER_STATUS_BREWING na tuto novou oranžovou LED. Skutečný kód aplikace kávovaru by zůstal beze změny.

Podobně by nová implementace definice "sample_appliance.json" používaná ukázkovými aplikacemi Azure Sphere mohla těmto ukázkovým aplikacím umožnit, aby se na MyBoardu spouštěly beze změny.

Soubory hlaviček

Soubory hlaviček se generují ze souborů JSON, které obsahují definice hardwaru. Soubory hlaviček je nutné vytvořit pro definice specifické pro desku i pro konkrétní aplikaci.

K vygenerování souboru hlavičky použijte příkaz azsphere hardware-definition generate-header .

Pokud chcete vytvořit soubor hlaviček, zadejte na příkazovém řádku Azure Sphere následující řádek. Nahraďte <filename> názvem souboru JSON.

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

Název souboru hlavičky.h se vytvoří a umístí do složky inc/hw.

Zadejte například následující řádek pro vygenerování souboru hlavičky ze souboru JSON.

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

Následuje část souboru záhlaví 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
                   .
                   .
                   .

Poznámka: Ve výchozím nastavení bude vygenerovaný hlavičkový soubor umístěn do inc/hw, což musí být podadresář adresáře, který obsahuje vstupní soubor JSON. Pokud tento podadresář neexistuje, vytvoří se.

Teď, když jste vytvořili soubor JSON definice hardwaru a jeho doprovodný hlavičkový soubor, najdete v tématu Správa cílových závislostí hardwaru pro postup jeho použití ve vaší aplikaci.

Sdílet prostřednictvím