ハードウェアの定義

[アーティクル]
09/27/2024

重要

これは Azure Sphere (レガシ) のドキュメントです。 Azure Sphere (レガシ) は 2027 年 9 月 27 日に再提供されておりユーザーは現時点で Azure Sphere (統合) に移行する必要があります。 TOC の上にある Version セレクターを使用して、Azure Sphere (統合) のドキュメントを表示します。

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

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

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

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

アプリケーション固有 定義は、アプリケーションコードで参照される周辺機器をボード固有の定義にマップします。アプリケーション固有の定義は、ボード固有の定義に基づいて構築され、任意のボード上の周辺機器を参照するために使用できる 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": " "},
   ]
}

Metadata セクションには、ファイル (ファイルの種類、バージョンなど) に関する情報が含まれています。

Description セクションには、ボードまたはモジュールに関する情報が含まれています。 "MainCoreHeaderFileTopContent" フィールドには、生成されるヘッダーファイルの先頭に配置される情報が含まれています。

Imports セクションでは、基になるハードウェアプラットフォーム (ボードまたはモジュール) のハードウェア定義ファイルのパス名を指定します。

Peripherals セクションには、このボードがアプリケーションで使用するために公開する周辺機器がリストされます。周辺機器の説明の形式は次のとおりです。

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

Peripherals セクションの要素を次に示します。

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

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

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

Comments - 生成されるヘッダーファイルに表示される有用な情報を指定します。たとえば、ISU* 周辺機器のピン割り当てや、オンボード LED と基になる MCU またはモジュールの GPIO ピンのマッピングなどです。

例: ボード固有の定義

次の例は、MyBoard という架空の MT3620 開発ボードのボード固有の定義を含むハードウェア定義ファイルの一部を示しています。 MyBoard の周辺ピン配置定義を指定します。 MT3620 MCU のチップ固有のハードウェア定義ファイル (mt3620.json) からリソース定義をインポートします。 Peripherals セクションの情報により、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"} ],
```
Peripherals セクションでは、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 ファイルの名前に置き換えます。

Azure Sphere CLI
Azure Sphere クラシック CLI

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

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

Note

Azure Sphere クラシック CLI は廃止されます。 Azure Sphere (Integrated) を使用することをお勧めします。

ヘッダーファイル filename.h が作成され、inc/hw フォルダーに配置されます。

たとえば、次の行を入力して、JSON ファイルからヘッダーファイルを生成します。

Azure Sphere CLI
Azure Sphere クラシック CLI

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

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

Note

Azure Sphere クラシック CLI は廃止されます。 Azure Sphere (Integrated) を使用することをお勧めします。

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

次の方法で共有

ハードウェアの定義

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

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

例: ボード固有の定義

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

ヘッダーファイル

フィードバック

その他のリソース

次の方法で共有

ハードウェアの定義

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

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

例: ボード固有の定義

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

ヘッダー ファイル

フィードバック

その他のリソース

ヘッダーファイル