Definicje sprzętu

W tej sekcji opisano pliki definicji sprzętu oraz sposoby ich tworzenia dla tablic i modułów Azure Sphere.

Pliki definicji sprzętu

Definicje sprzętu służą dwóm odrębnym, ale powiązanym celom:

Definicje specyficzne dla zarządu definiują określone urządzenia peryferyjne modułu lub innej tablicy i umożliwiają aplikacji odwoływanie się do nich przy użyciu odpowiednich i znaczących identyfikatorów. Na przykład aplikacja może używać ciągu "Red_LED_1" zamiast nieprzezroczystego numeru, takiego jak GPIO "13". Katalog HardwareDefinitions w zestawie SDK Azure Sphere zawiera takie definicje typowych płytek Azure Sphere i używanych mikroukładów. Ten katalog znajduje się %ProgramFiles(x86)%\Microsoft Azure Sphere SDK\HardwareDefinitions w systemie Windows i /opt/azurespheresdk/HardwareDefinitions systemie Linux.

Definicje specyficzne dla aplikacji mapują urządzenia peryferyjne, do których odwołuje się kod aplikacji, do definicji specyficznych dla tablicy. Definicje specyficzne dla aplikacji są oparte na definicjach specyficznych dla tablic i definiują pojedynczy zestaw identyfikatorów, których można używać do odwoływania się do urządzeń peryferyjnych na dowolnej tablicy. Z tego powodu aplikacja działająca na wielu tablicach może mieć określoną definicję dla każdego typu tablicy, ale sama aplikacja używa tylko jednego zestawu identyfikatorów peryferyjnych. Sam kod może działać całkowicie bez zmian na innym sprzęcie; deweloper musi tylko zmienić odwołanie, aby użyć odpowiedniej definicji. Na przykład kod aplikacji dla ekspresu do kawy odwołuje się do diody LED wskaźnika BrewingStatus. Tablica kontrolna ekspresu do kawy jest pozyskiowana przez dwóch dostawców: Contoso i Fabrikam. Dzięki zastosowaniu definicji specyficznych dla poszczególnych tablic wskaźnik BrewingStatus można zamapować na diodę LED 2 na tablicy kontrolnej dostarczonej przez Contoso i LED 4 na płycie kontrolnej dostarczonej przez Fabrikama.

Jeśli aplikacja używa definicji sprzętu z zestawu SDK lub od dostawcy sprzętu — i nie tworzysz własnej definicji specyficznej dla aplikacji — możesz na razie pominąć pozostałą część tego tematu i przejść bezpośrednio do korzystania ze współzależności sprzętu.

Pliki definicji sprzętu tworzy się w formacie JSON. Następnie generujesz pliki nagłówków C z plików JSON.

Format pliku definicji sprzętu

Plik definicji sprzętu to plik JSON o następującym formacie:

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

Sekcja Metadane zawiera informacje o pliku (typ pliku, wersja itd.).

Sekcja Opis zawiera informacje o tablicy lub module. Pole "MainCoreHeaderFileTopContent" zawiera informacje, które zostaną umieszczone na początku wygenerowanego pliku nagłówka.

Sekcja Importowanie określa nazwę ścieżki pliku definicji sprzętu dla platformy sprzętowej (tablicy lub modułu).

Sekcja Urządzenia peryferyjne zawiera listę urządzeń peryferyjnych udostępnianych przez tę tablicę do użytku w aplikacjach. Opis urządzenia peryferyjnego ma następujący format:

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

Poniżej przedstawiono elementy sekcji Urządzenia peryferyjne :

Nazwa — identyfikator używany do odwoływania się do urządzenia peryferyjnego w kodzie aplikacji.

Typ — typ urządzenia peryferyjnego (na przykład Gpio, Uart, Adc). Aby uzyskać informacje o typach, zapoznaj się z plikiem definicji sprzętu wymienionym w sekcji Importowanie .

Mapowanie — mapuje identyfikator w polu Nazwa na identyfikator używany dla urządzenia peryferyjnego w importowanym pliku definicji sprzętu.

Komentarze — zawiera przydatne informacje wyświetlane w wygenerowanym pliku nagłówka. Na przykład przypinaj przypisania dla urządzeń peryferyjnych ISU* lub mapowanie wbudowanych diod LED na piny GPIO podstawowego mcu lub modułu.

Przykład: definicja specyficzna dla tablicy

W poniższym przykładzie przedstawiono część pliku definicji sprzętu zawierającą definicję specyficzną dla tablicy dla fikcyjnej tablicy deweloperów MT3620 o nazwie MyBoard. Określa on definicje wypinania urządzeń peryferyjnych dla aplikacji MyBoard. Importuje definicje zasobów z pliku definicji sprzętu specyficznego dla chipów (mt3620.json) dla MCU MT3620. Informacje w sekcji Urządzenia peryferyjne skutkują mapowaniem przypinania do pinezki zasobów udostępnionych przez aplikację MyBoard zasobom dostarczonym przez podstawową jednostkę 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"},
                              .
                              .
                              .
    ]
}

Dodatkowe przykłady plików definicji specyficznych dla tablicy można zobaczyć w katalogu HardwareDefinitions, który jest częścią instalacji azure Sphere SDK.

Przykład: definicja specyficzna dla aplikacji

W poniższym przykładzie przedstawiono fragment pliku definicji sprzętu, który zawiera specyficzną dla aplikacji definicję fikcyjnego urządzenia do kawy.

Wśród urządzeń peryferyjnych zawartych w aplikacji są dwie diody LED wskaźnika i przycisk. Do tych danych odwołuje się kod aplikacji, podając identyfikatory odpowiednio COFFEEMAKER_STATUS_BREWING, COFFEEMAKER_STATUS_READY i COFFEEMAKER_BUTTON_START. Te identyfikatory są mapowane na urządzenia peryferyjne zdefiniowane w definicji specyficznej dla zaimportowanej tablicy dla fikcyjnej tablicy 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"},
                                             .
                                             .
                                             .
    ]
}

• Sekcja Importowanie zawiera ścieżkę do pliku definicji sprzętu dla tablicy fizycznej lub modułu.

  "Imports" : [ {"Path": "... /MyHwDefs/my_board.json"} ],
  

• Sekcja Urządzenia peryferyjne mapuje urządzenia peryferyjne programu CoffeeMaker na odpowiednie urządzenia peryferyjne na tablicy lub module.

  {"Name": "COFFEEMAKER_BUTTON_START", "Type": "Gpio", "Mapping": "MY_BOARD_BUTTON_A", "Comment": " Start button uses MyBoard Button A"},
  

  Nazwa — zawiera identyfikator używany dla urządzenia peryferyjnego w kodzie aplikacji.

  Mapowanie — zawiera identyfikator używany dla urządzenia peryferyjnego w pliku definicji sprzętu dla tablicy lub modułu.

Następna wersja ekspresu do kawy może być zbudowana na MyBoardV2. Miałby nową definicję specyficzną dla tablicy z urządzeniami peryferyjnymi, takimi jak MY_BOARD_V2_LED_ORANGE. Zostanie to zaimportowane przez nową implementację definicji specyficznej dla aplikacji ekspresów do kawy, która mapuje COFFEEMAKER_STATUS_BREWING na tę nową pomarańczową diodę LED. Rzeczywisty kod aplikacji ekspresu do kawy pozostanie niezmieniony.

Podobnie nowa implementacja definicji "sample_appliance.json", używanej przez przykładowe aplikacje Azure Sphere, może umożliwić działanie tych przykładowych aplikacji na platformie MyBoard bez zmian.

Pliki nagłówków

Pliki nagłówków są generowane z plików JSON zawierających definicje sprzętu. Musisz utworzyć pliki nagłówków dla definicji specyficznych dla tablicy i specyficznych dla aplikacji.

Użyj polecenia azsphere hardware-definition generate-header , aby wygenerować plik nagłówka.

Aby utworzyć plik nagłówka, wprowadź następujący wiersz w wierszu polecenia Azure Sphere. Zamień <filename> na nazwę pliku JSON.

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

Plik nagłówka nazwa.h zostanie utworzony i umieszczony w folderze inc/hw.

Na przykład wprowadź następujący wiersz, aby wygenerować plik nagłówka z pliku JSON.

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

Poniżej przedstawiono część pliku nagłówka 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
                   .
                   .
                   .

Uwaga Domyślnie wygenerowany plik nagłówka zostanie umieszczony w inc/hwfolderze , który musi być podkatalogiem katalogu zawierającego wejściowy plik JSON. Jeśli ten podkatalog nie istnieje, zostanie utworzony.

Po utworzeniu pliku JSON definicji sprzętu i towarzyszącego mu pliku nagłówka zobacz Zarządzanie docelowymi zależnościami sprzętu , aby zapoznać się z instrukcjami dotyczącymi używania go w aplikacji.