チュートリアル: Eclipse ThreadX を使用して MXCHIP AZ3166 DevKit を IoT Hub に接続する

[アーティクル]
04/16/2024

このチュートリアルでは、Eclipse ThreadX を使用して、MXCHIP AZ3166 IoT DevKit (これ以降、MXCHIP DevKit と呼びます) を Azure IoT に接続します。

次のタスクを実行します。

C で MXCHIP DevKit をプログラミングするための、一連の組み込み開発ツールをインストールする
イメージをビルドして MXCHIP DevKit にフラッシュする
Azure CLI を使って、MXCHIP DevKit が安全に接続できる Azure IoT ハブを作成し、管理する
Azure IoT エクスプローラーを使用して、IoT ハブへのデバイスの登録、デバイスのプロパティの表示、デバイステレメトリの表示、デバイスでのダイレクトコマンドの呼び出しを行う

前提条件

Windows 10 または Windows 11 を実行している PC
有効な Azure サブスクリプション Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。
リポジトリを複製するための Git
Azure CLI。このチュートリアルで Azure CLI コマンドを実行するには、次の 2 つのオプションがあります。
- ブラウザーで CLI コマンドを実行する対話型シェルである Azure Cloud Shell を使用します。何もインストールする必要がないため、このオプションをお勧めします。 Cloud Shell を初めて使用する場合は、Azure portal にサインインします。 Cloud Shell のクイックスタートの手順に従って、Cloud Shell を起動し、Bash 環境を選択します。
- 必要に応じて、お使いのローカルコンピューターで Azure CLI を実行します。 Azure CLI が既にインストールされている場合は、az upgrade を実行して、CLI と拡張機能を最新バージョンにアップグレードします。 Azure CLI のインストール方法については、「Azure CLI をインストールする」をご覧ください。
ハードウェア
- MXCHIP AZ3166 IoT DevKit (MXCHIP DevKit)
- Wi-Fi 2.4 GHz
- USB 2.0 A male to Micro USB male ケーブル

開発環境の準備

開発環境を設定するには、まず、チュートリアルで必要なすべての資産を含む GitHub リポジトリを複製します。次に、一連のプログラミングツールをインストールします。

リポジトリを複製する

次のリポジトリを複製して、すべてのサンプルデバイスコード、設定スクリプト、オフラインバージョンのドキュメントをダウンロードします。このリポジトリを別のチュートリアルで複製している場合は、もう一度実行する必要はありません。

リポジトリを複製するには、次のコマンドを実行します。

git clone --recursive https://github.com/eclipse-threadx/getting-started.git

ツールのインストール

複製されたリポジトリには、必要なツールをインストールして構成する設定スクリプトが含まれています。別の組み込みデバイスのチュートリアルでこれらのツールをインストールしてある場合は、もう一度インストールする必要はありません。

Note

設定スクリプトでは、次のツールがインストールされます。

CMake: ビルド
ARM GCC: コンパイル
Termite: 接続されたデバイスリソースのシリアルポートの出力を監視

ツールをインストールするには:

エクスプローラーで、リポジトリ内の次のパスに移動し、get-toolchain.bat という名前の設定スクリプトを実行します。

getting-started\tools\get-toolchain.bat
インストールが完了したら、新しいコンソールウィンドウを開き、設定スクリプトによって行われた構成の変更を確認します。このコンソールを使用して、チュートリアルの残りのプログラミングタスクを実行します。 Windows CMD、PowerShell、または Git Bash for Windows を使用できます。
次のコードを実行して、CMake バージョン3.14 以降がインストールされていることを確認します。
```
cmake --version
```

クラウドコンポーネントを作成する

IoT Hub の作成

Azure CLI を使用して、デバイスのイベントとメッセージングを処理する IoT ハブを作成できます。

IoT ハブを作成するには:

CLI アプリを起動します。このクイックスタートの以降の部分で CLI コマンドを実行するには、コマンド構文をコピーして CLI アプリに貼り付け、変数の値を編集して Enter キーを押します。
- Cloud Shell を使ってい場合は、こちらの Cloud Shell のリンクを右クリックし、新しいタブで開くオプションを選びます。
- Azure CLI をローカルで使用している場合は、CLI コンソールアプリを起動し、Azure CLI にサインインします。
az extension add を実行して、azure-iot 拡張機能をインストールするか、最新バージョンにアップグレードします。
```
az extension add --upgrade --name azure-iot
```
az group create コマンドを実行してリソースグループを作成します。次のコマンドでは、MyResourceGroup という名前のリソースグループが centralus リージョンに作成されます。

注意

必要に応じて、別の location を設定することもできます。利用可能な場所を確認するには、az account list-locations を実行します。
```
az group create --name MyResourceGroup --location centralus
```
az iot hub create コマンドを実行して、IoT ハブを作成します。 IoT ハブの作成には数分かかることがあります。

YourIotHubName: コード内のこのプレースホルダーは、IoT Hub の実際の名前に置き換えてください。 IoT ハブ名は Azure でグローバルに一意である必要があります。このプレースホルダーは、このクイックスタートの残りの部分で、一意の IoT ハブ名を表すために使用されます。

--sku F1 パラメーターにより、Free レベルの IoT ハブが作成されます。 Free レベルのハブは機能セットが限られており、概念実証アプリケーションに使用されます。 IoT Hub のレベル、機能、価格の詳細については、「Azure IoT Hub の価格」を参照してください。
```
az iot hub create --resource-group MyResourceGroup --name {YourIoTHubName} --sku F1 --partition-count 2
```
IoT ハブが作成されたら、コンソールに JSON 出力を表示し、後の手順で使用するために hostName 値をコピーします。 hostName 値は次の例のようになります。

{Your IoT hub name}.azure-devices.net

IoT エクスプローラーの構成

このクイックスタートの残りの部分では、IoT エクスプローラーを使用して、IoT ハブへのデバイスの登録、デバイスのプロパティとテレメトリの表示、デバイスへのコマンドの送信を行います。このセクションでは、作成した IoT ハブに接続して、パブリックモデルリポジトリからプラグアンドプレイモデルを読み取るように、IoT エクスプローラーを構成します。

IoT ハブへの接続を追加するには:

Azure IoT エクスプローラーをインストールします。このツールは、Azure IoT リソースを監視および管理するためのクロスプラットフォームユーティリティです。
CLI アプリで az iot hub connection-string show コマンドを実行して、IoT ハブの接続文字列を取得します。
```
az iot hub connection-string  show --hub-name {YourIoTHubName}
```
引用符で囲まずに接続文字列をコピーします。
Azure IoT エクスプローラーで、左側のメニューの [IoT Hub] を選びます。
[+ 接続の追加] を選択します。
接続文字列を [接続文字列] ボックスに貼り付けます。
[保存] を選択します。

接続が成功すると、IoT エクスプローラーが [デバイス] ビューに切り替わります。

パブリックモデルリポジトリを追加するには:

IoT エクスプローラーで、 [ホーム] を選択してホームビューに戻ります。
左側のメニューで、 [IoT プラグアンドプレイの設定] を選択し、 [+ 追加] を選択して、ドロップダウンメニューから [パブリックリポジトリ] を選択します。
https://devicemodels.azure.com に、パブリックモデルリポジトリのエントリが表示されます。
[保存] を選択します。

デバイスの登録

このセクションでは、新しいデバイスインスタンスを作成し、作成した IoT ハブに登録します。新しく登録したデバイスの接続情報を使用して、後のセクションで物理デバイスを安全に接続します。

デバイスを登録するには:

IoT エクスプローラーのホームビューで、 [IoT Hub] を選択します。
前に追加した接続が表示されます。接続プロパティの下にある [View devices in this hub](このハブのデバイスを表示) を選択します。
[+ 新規] を選択し、デバイスのデバイス ID (例: mydevice) を入力します。他のプロパティはすべてそのままにしておきます。
[作成] を選択します。
コピーボタンを使って、[デバイス ID] と [主キー] フィールドをコピーしておきます。

次のセクションに進む前に、前の手順で取得した次の各値を安全な場所に保存します。次のセクションでは、これらの値を使ってデバイスを構成します。

hostName
deviceId
primaryKey

デバイスの準備

MXCHIP DevKit を Azure に接続するには、Wi-Fi と Azure IoT の設定の構成ファイルを変更し、イメージをリビルドして、イメージをデバイスにフラッシュします。

構成を追加する

テキストエディターで次のファイルを開きます。

getting-started\MXChip\AZ3166\app\azure_config.h
次に示すように、ファイルの先頭付近にある次の行をコメントアウトします。
```
// #define ENABLE_DPS
```
Wi-Fi 定数をローカル環境の次の値に設定します。

定数名値

WIFI_SSID {自分の Wi-Fi SSID}

WIFI_PASSWORD {自分の Wi-Fi パスワード}

WIFI_MODE {ファイル内の列挙された Wi-Fi モード値のいずれか}
Azure IoT デバイス情報の定数を、Azure リソースの作成後に保存した値に設定します。

定数名値

IOT_HUB_HOSTNAME {ホスト名の値}

IOT_HUB_DEVICE_ID {自分のデバイス ID 値}

IOT_DEVICE_SAS_KEY {自分のプライマリキー値}
ファイルを保存して閉じます。

定数名	値
`WIFI_SSID`	{自分の Wi-Fi SSID}
`WIFI_PASSWORD`	{自分の Wi-Fi パスワード}
`WIFI_MODE`	{ファイル内の列挙された Wi-Fi モード値のいずれか}

定数名	値
`IOT_HUB_HOSTNAME`	{ホスト名の値}
`IOT_HUB_DEVICE_ID`	{自分のデバイス ID 値}
`IOT_DEVICE_SAS_KEY`	{自分のプライマリキー値}

イメージをビルドする

コンソールまたはエクスプローラーで、次のパスのスクリプト rebuild.bat を実行してイメージをビルドします。

getting-started\MXChip\AZ3166\tools\rebuild.bat
ビルドが完了したら、次のパスにバイナリファイルが作成されたことを確認します。

getting-started\MXChip\AZ3166\build\app\mxchip_azure_iot.bin

イメージをフラッシュする

MXCHIP DevKit で、リセット ボタンとマイクロ USB ポートを見つけます。これらのコンポーネントは、次の手順で使用します。次の図で両方が強調表示されています。
マイクロ USB ケーブルを MXCHIP DevKit のマイクロ USB ポートに接続し、それをコンピューターに接続します。
エクスプローラーで、前のセクションで作成したバイナリファイルを見つけます。
バイナリファイル mxchip_azure_iot.bin をコピーします。
エクスプローラーで、コンピューターに接続されている MXCHIP DevKit デバイスを見つけます。このデバイスは、ドライブラベル AZ3166 でシステム上にドライブとして表示されます。
バイナリファイルを MXCHIP Devkit のルートフォルダーに貼り付けます。自動的に点滅が始まり、数秒後に完了します。

Note

点滅のプロセス中、MXCHIP DevKit の緑色の LED が切り替わります。

デバイス接続の詳細を確認する

Termite アプリを使用して、通信を監視し、デバイスが正しく設定されていることを確認できます。

Termite を開始します。

ヒント

Termite を Devkit に接続できない場合は、ST-LINK ドライバーをインストールして、もう一度やり直してください。追加の手順については、トラブルシューティングに関する記事を参照してください。
[設定] を選択します。
[Serial port settings](シリアルポートの設定) ダイアログで、次の設定を確認し、必要に応じて更新します。
- Baud rate(ボーレート) : 115,200
- Port(ポート) : MXCHIP DevKit が接続されているポート。ドロップダウンに複数のポートオプションがある場合は、使用する適切なポートを見つけることができます。 Windows のデバイスマネージャーを開き、 [ポート] を表示して、使用するポートを特定します。
[OK] を選択します。
デバイス上のリセット ボタンを押します。このボタンは、デバイス上にラベルが付いていて、マイクロ USB コネクタの近くにあります。

Termite アプリで、次のチェックポイント値を確認して、デバイスが初期化され、Azure IoT に接続されていることを確認します。

 Starting Azure thread


 Initializing WiFi
     MAC address: ******************
 SUCCESS: WiFi initialized

 Connecting WiFi
     Connecting to SSID 'iot'
     Attempt 1...
 SUCCESS: WiFi connected

 Initializing DHCP
     IP address: 192.168.0.49
     Mask: 255.255.255.0
     Gateway: 192.168.0.1
 SUCCESS: DHCP initialized

 Initializing DNS client
     DNS address: 192.168.0.1
 SUCCESS: DNS client initialized

 Initializing SNTP time sync
     SNTP server 0.pool.ntp.org
     SNTP time update: Jan 4, 2023 22:57:32.658 UTC
 SUCCESS: SNTP initialized

 Initializing Azure IoT Hub client
     Hub hostname: ***.azure-devices.net
     Device id: mydevice
     Model id: dtmi:eclipsethreadx:devkit:gsgmxchip;2
 SUCCESS: Connected to IoT Hub

 Receive properties: {"desired":{"$version":1},"reported":{"deviceInformation":{"__t":"c","manufacturer":"MXCHIP","model":"AZ3166","swVersion":"1.0.0","osName":"Eclipse ThreadX","processorArchitecture":"Arm Cortex M4","processorManufacturer":"STMicroelectronics","totalStorage":1024,"totalMemory":128},"ledState":false,"telemetryInterval":{"ac":200,"av":1,"value":10},"$version":4}}
 Sending property: $iothub/twin/PATCH/properties/reported/?$rid=3{"deviceInformation":{"__t":"c","manufacturer":"MXCHIP","model":"AZ3166","swVersion":"1.0.0","osName":"Eclipse ThreadX","processorArchitecture":"Arm Cortex M4","processorManufacturer":"STMicroelectronics","totalStorage":1024,"totalMemory":128}}
 Sending property: $iothub/twin/PATCH/properties/reported/?$rid=5{"ledState":false}
 Sending property: $iothub/twin/PATCH/properties/reported/?$rid=7{"telemetryInterval":{"ac":200,"av":1,"value":10}}

 Starting Main loop
 Telemetry message sent: {"humidity":31.01,"temperature":25.62,"pressure":927.3}.
 Telemetry message sent: {"magnetometerX":177,"magnetometerY":-36,"magnetometerZ":-346.5}.
 Telemetry message sent: {"accelerometerX":-22.5,"accelerometerY":0.54,"accelerometerZ":1049.01}.
 Telemetry message sent: {"gyroscopeX":0,"gyroscopeY":0,"gyroscopeZ":0}.

Termite は、次の手順でデバイスの出力を監視するために開いたままにしておきます。

デバイスのプロパティを表示する

Azure IoT エクスプローラーを使用して、デバイスのプロパティを表示および管理できます。このセクションとそれ以降のセクションでは、IoT Explorer に表示されるプラグアンドプレイ機能を使用して、MXCHIP DevKit を管理および操作します。これらの機能は、パブリックモデルリポジトリで MXCHIP DevKit 用に公開されているデバイスモデルに依存します。このチュートリアルの前の方で、このリポジトリでデバイスモデルを検索するように IoT エクスプローラーを構成しました。 IoT エクスプローラーのデバイスペインの左側のメニューからアクションを選択することで、プラグアンドプレイを使用せずに多くのアクションを実行できます。ただし、プラグアンドプレイを使用すると、エクスペリエンスが強化されることが多々あります。 IoT エクスプローラーでは、プラグアンドプレイデバイスで指定されたデバイスモデルを読み取り、そのデバイスに固有の情報を提示できます。

IoT エクスプローラーでデバイスの IoT プラグアンドプレイコンポーネントにアクセスするには:

IoT エクスプローラーのホームビューで [IoT Hub] を選択し、 [View devices in this hub](このハブのデバイスを表示) を選択します。
デバイスを選択します。
[IoT プラグアンドプレイコンポーネント] を選択します。
[既定のコンポーネント] を選択します。 IoT エクスプローラーに、デバイスに実装されている IoT プラグアンドプレイコンポーネントが表示されます。

[インターフェイス] タブで、デバイスモデルの [説明] の JSON コンテンツを確認します。 JSON には、デバイスモデルの各 IoT プラグアンドプレイコンポーネントの構成の詳細が含まれています。

IoT エクスプローラーの各タブは、デバイスモデルの IoT プラグアンドプレイコンポーネントの 1 つに対応しています。

タブ	Type	名前	説明
Interface	インターフェイス	`MXCHIP Getting Started Guide`	MXCHIP DevKit のモデル例
プロパティ (読み取り専用)	プロパティ	`ledState`	LED の現在の状態
プロパティ (書き込み可能)	プロパティ	`telemetryInterval`	デバイスがテレメトリを送信する間隔
コマンド	コマンド	`setLedState`	LED のオン/オフを切り替えます

Azure IoT エクスプローラーを使用してデバイスのプロパティを表示するには:

[プロパティ (書き込み可能)] タブを選択します。テレメトリが送信される間隔が表示されます。
telemetryInterval を 5 に変更し、 [Update desired value](必要な値の更新) を選択します。これにより、デバイスでは、この間隔を使用してテレメトリが送信されるようになります。
IoT エクスプローラーは通知で応答します。 Termite で更新を監視することもできます。
テレメトリの間隔を 10 に戻します。

Azure CLI を使用してデバイスのプロパティを表示するには:

az iot hub device-twin show コマンドを実行します。

az iot hub device-twin show --device-id mydevice --hub-name {YourIoTHubName}

コンソール出力でデバイスのプロパティを調べます。

利用統計情報データを表示する

Azure IoT エクスプローラーを使用すると、デバイスからクラウドへのテレメトリのフローを表示できます。必要に応じて、Azure CLI を使用して同じタスクを実行することもできます。

Azure IoT エクスプローラーでテレメトリを表示するには:

IoT エクスプローラーで、デバイスの [IoT プラグアンドプレイコンポーネント] (既定のコンポーネント) ペインから、 [テレメトリ] タブを選択します。 [Use built-in event hub](組み込みのイベントハブを使用する) が [はい] に設定されていることを確認します。
[スタート] を選択します。
デバイスからクラウドにメッセージが送信されるときのテレメトリを表示します。

Note

Termite アプリを使用して、デバイスからテレメトリを監視することもできます。
[Show modeled events](モデル化されたイベントを表示する) チェックボックスをオンにして、デバイスモデルで指定されたデータ形式でイベントを表示します。
[停止] を選択して、イベントの受信を終了します。

Azure CLI を使用してデバイステレメトリを表示するには:

az iot hub monitor-events コマンドを実行します。 Azure IoT で以前に作成した、デバイスと IoT ハブの名前を使用します。
```
 az iot hub monitor-events --device-id mydevice --hub-name {YourIoTHubName}
```

コンソールに JSON 出力を表示します。

 {
     "event": {
         "origin": "mydevice",
         "module": "",
         "interface": "dtmi:eclipsethreadx:devkit:gsgmxchip;1",
         "component": "",
         "payload": "{\"humidity\":41.21,\"temperature\":31.37,\"pressure\":1005.18}"
     }
 }

Ctrl + C キーを押して監視を終了します。

デバイス上のダイレクトメソッドを呼び出す

Azure IoT エクスプローラーを使用して、デバイスに実装したダイレクトメソッドを呼び出すこともできます。ダイレクトメソッドには名前があり、必要に応じて、JSON ペイロード、構成可能な接続、メソッドのタイムアウトを設定できます。このセクションでは、LED のオン/オフを切り替えるメソッドを呼び出します。必要に応じて、Azure CLI を使用して同じタスクを実行することもできます。

Azure IoT エクスプローラーでメソッドを呼び出すには:

IoT エクスプローラーで、デバイスの [IoT プラグアンドプレイコンポーネント] (既定のコンポーネント) ペインから [コマンド] タブを選択します。
setLedState コマンドで、 [state] を [true] に設定します。
[コマンドの送信] を選択します。 IoT エクスプローラーに通知が表示され、デバイスの黄色のユーザー LED ライトがオンになります。
[state] を [false] に設定し、[コマンドの送信] を選択します。黄色のユーザー LED がオフになります。
必要に応じて、Termite で出力を表示してメソッドの状態を監視することもできます。

Azure CLI を使用してメソッドを呼び出すには:

az iot hub invoke-device-method コマンドを実行し、メソッド名とペイロードを指定します。このメソッドでは、method-payload を true に設定すると LED がオンになり、false に設定するとオフになります。
```
az iot hub invoke-device-method --device-id mydevice --method-name setLedState --method-payload true --hub-name {YourIoTHubName}
```
CLI コンソールに、デバイスでのメソッド呼び出しの状態が表示されます。204 は成功を示しています。
```
{
  "payload": {},
  "status": 200
}
```
デバイスを調べて LED の状態を確認します。

Termite ターミナルを表示して、出力メッセージを確認します。

 Receive direct method: setLedState
     Payload: true
 LED is turned ON
 Device twin property sent: {"ledState":true}

トラブルシューティングとデバッグ

デバイスコードのビルド、デバイスのフラッシュ、または接続で問題が発生した場合は、トラブルシューティングに関する記事を参照してください。

アプリケーションのデバッグについては、「Visual Studio Code を使用したデバッグ」を参照してください。

リソースをクリーンアップする

このクイックスタートで作成した Azure リソースが不要になった場合は、Azure CLI を使用して、リソースグループとそのすべてのリソースを削除できます。

重要

リソースグループを削除すると、元に戻すことができません。リソースグループとそこに含まれるすべてのリソースは完全に削除されます。間違ったリソースグループやリソースをうっかり削除しないようにしてください。

名前でリソースグループを削除するには、以下の手順を実行します。

az group delete コマンドを実行します。このコマンドにより、作成したリソースグループ、IoT Hub、デバイスの登録が削除されます。
```
az group delete --name MyResourceGroup
```
az group list コマンドを実行して、リソースグループが削除されていることを確認します。
```
az group list
```

次のステップ

このチュートリアルでは、Eclipse ThreadX サンプルコードを含むカスタムイメージをビルドし、そのイメージを MXCHIP DevKit デバイスにフラッシュしました。また、Azure CLI または IoT エクスプローラーを使用して、Azure リソースを作成し、MXCHIP DevKit を安全に Azure に接続して、テレメトリの表示とメッセージの送信を行いました。

次の手順として、次の記事を読んで、埋め込み開発オプションの詳細を確認してください。

C SDK と Embedded C SDK を使用した埋め込みデバイスの接続の詳細

Eclipse ThreadX は、通信をセキュリティで保護し、基になる MCU/MPU ハードウェア保護メカニズムを使用してコードとデータの分離を作成するためのコンポーネントを OEM に提供します。ただし、各 OEM は最終的に、そのデバイスが進化するセキュリティ要件を確実に満たすようにする役目を負っています。