ハードウェア定義

[アーティクル]
08/09/2023

このセクションでは、ハードウェア定義ファイルと、それらを Azure Sphere ボードとモジュール用に作成する方法について説明します。

ハードウェア定義ファイル

ハードウェア定義は、次の 2 つの独立した関連する目的で機能します。

ボード固有の 定義は、モジュールまたはその他のボードの特定の周辺機器を定義し、関連する意味のある識別子を使用してアプリケーションがそれらを参照できるようにします。たとえば、アプリでは、GPIO "13" などの不透明な数値の代わりに "Red_LED_1" を使用できます。 Azure Sphere SDK の HardwareDefinitions ディレクトリには、一般的な Azure Sphere ボードと、それらが使用するチップに対してこのような定義が含まれています。このディレクトリは、 %ProgramFiles(x86)%\Microsoft Azure Sphere SDK\HardwareDefinitions Windows と /opt/azurespheresdk/HardwareDefinitions Linux 上にあります。

アプリケーション固有の 定義は、アプリケーションコードで参照されている周辺機器をボード固有の定義にマップします。アプリケーション固有の定義は、ボード固有の定義に基づいて構築され、任意のボード上の周辺機器を参照するために使用できる 1 つの識別子セットを定義します。したがって、複数のボードで実行されるアプリケーションは、ボードの種類ごとにアプリケーション固有の定義を持つ場合がありますが、アプリケーション自体で使用される周辺機器識別子のセットは 1 つだけです。コード自体は、異なるハードウェアで完全に変更されずに実行できます。開発者は、適切な定義を使用するために参照を変更するだけで済みます。たとえば、コーヒーメーカーのアプリケーションコードは、BrewingStatus インジケーター LED を参照します。コーヒーメーカーコントロールボードは、Contoso と Fabrikam の 2 つのサプライヤーによって供給されています。各ボードのアプリケーション固有の定義を使用することで、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>"}

[周辺機器] セクションの要素を次に示します。

名前 - アプリケーションコード内の周辺機器を参照するために使用される識別子。

Type - 周辺機器の種類 (Gpio、Uart、Adc など)。型情報を取得するには、「 Imports 」セクションに記載されているハードウェア定義ファイルを参照してください。

マッピング - [名前] フィールドの識別子を、インポートされたハードウェア定義ファイルの周辺機器に使用される識別子にマップします。

コメント - 生成されたヘッダーファイルに表示するのに役立つ情報を提供します。たとえば、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 ディレクトリで確認できます。

例: アプリケーション固有の定義

次の例は、架空のコーヒーメーカーアプライアンスのアプリケーション固有の定義を含むハードウェア定義ファイルの一部を示しています。

アプリケーションに含まれる周辺機器の中には、2 つのインジケーター 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]\(インポート\) セクションには、物理ボードまたはモジュールのハードウェア定義ファイルへのパスが含まれています。
```
"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などの周辺機器を含む新しいボード固有の定義が作成されます。これは、この新しいオレンジ色の LED にCOFFEEMAKER_STATUS_BREWINGマップする、コーヒーメーカーのアプリケーション固有の定義の新しい実装によってインポートされます。実際のコーヒーメーカーアプリケーションコードは変更されません。

同様に、 Azure Sphere サンプルアプリで使用される "sample_appliance.json" 定義の新しい実装により、これらのサンプルアプリを MyBoard で変更せずに実行できます。

ヘッダーファイル

ヘッダーファイルは、ハードウェア定義を含む JSON ファイルから生成されます。ボード固有の定義とアプリケーション固有の定義の両方に対してヘッダーファイルを作成する必要があります。

azsphere hardware-definition generate-header コマンドを使用して、ヘッダーファイルを生成します。

ヘッダーファイルを作成するには、Azure Sphere コマンドプロンプトで次の行を入力します。を JSON ファイルの名前に置き換えます <filename> 。

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 ファイルとそれに付随するヘッダーファイルを作成したので、アプリケーションで使用する手順については、「ターゲットハードウェアの依存関係を管理する」を参照してください。

次の方法で共有

ハードウェア定義

ハードウェア定義ファイル

ハードウェア定義ファイルの形式

例: ボード固有の定義

例: アプリケーション固有の定義

ヘッダーファイル

フィードバック

その他のリソース

次の方法で共有

ハードウェア定義

ハードウェア定義ファイル

ハードウェア定義ファイルの形式

例: ボード固有の定義

例: アプリケーション固有の定義

ヘッダー ファイル

フィードバック

その他のリソース

ヘッダーファイル