MQTTクライアントの例

概要

このセクションでは、Hello MQTTにて、MQTTクロス・プラットフォーム・アプリケーションを使用し、Things Cloud MQTTプロトコルを簡単に紹介します。

すべての例は Githubリポジトリよりダウンロードできます。

Hello MQTT

このチュートリアルでは、事前定義されたメッセージ（静的テンプレート）を使用して、Things CloudでMQTTを使用する方法を学びます。

前提条件

このチュートリアルを実行するには、次の前提条件を確認してください。

Things Cloudにアクセスするための有効なテナントID、ユーザー名、およびパスワードが必要です。
MQTTBoxまたは類似のMQTTツールをインストールします。

備考

チュートリアルのスクリーンショットではMQTTBoxを使用しています。他のツールでは異なる場合があります。

MQTT通信

MQTT接続の設定

MQTT接続を設定するには、次の接続パラメータ（下のスクリーンショット参照）を渡す必要があります。

MQTT Client Name – クライアントを識別するための名前 (例:Things Cloud MQTT) をクライアントに付けます。
MQTT Client Id – 「ランダムIDを生成する」ボタン（ほとんどのツールは同じようなボタンを提供します）を使用するか、自分で用意します。このIDはThings Cloudのデバイスとリンクします。同じデバイスに再接続するには、同じIDを使用します。
Protocol – 使用するプロトコル (mqtt/tcpなど) を選択します。
Host – テナントドメイン (例: mytenant.je1.thingscloud.ntt.com) をURLに指定します。
Username – この場合、Usernameの形式は<tenantID>/<username>です。Things Cloudプラットフォームへのログインに使用するものと同じ認証情報を使用できます。次の例に示すように、テナントID「t76543210」とユーザー名「manga」のUsernameは「t76543210/manga」です。
Password - ユーザー名に対するパスワードです。
Append timestamp to MQTT client id? - チェックを「No」に設定します。「Yes」にした場合、MQTT Client Id にタイムスタンプが付加されデバイスのExternalIdとリンクできなくなります。

Things Cloudは、TCPとWebSocketの両方を介してMQTTをサポートします。URLとして、テナントドメイン
（例：mytenant.je1.thingscloud.ntt.com/mqtt）またはインスタンスのドメインを mqtt.<instance_domain>
（例：mqtt.je1.thingscloud.ntt.com）の形式で使用できます。

MQTTBox設定の例

備考

テナントIDとテナントドメインをよりよく理解するために、Things Cloud OpenAPI仕様の Tenants > テナントIDとテナントドメインをご覧ください。

この例では、「クリーンセッション」のような他の設定は重要ではありません。必要に応じて変更できます。Saveをクリックすると、次のスクリーンショットのような画面が表示されます。

MQTTBox確立済み接続

トップ・バーにNot Connectedというラベルの青いボタンがある場合は、接続の設定を確認します(特にUsernameとPassword)。ボタンが緑色の場合は、Things CloudへのMQTT接続が正常に確立されています。

データ送信

このチュートリアルのすべてのMQTTパブリッシュメッセージは、トピックs/usに送信されます。これはThings Cloudがあらかじめ用意している静的テンプレートのためのトピックです。

MQTTBoxパブリッシュメッセージ

デバイスの作成

最初に送信されたメッセージでデバイスが作成されます。静的テンプレートはデバイスの自動作成をサポートしていますが、この例ではデバイスを手動で作成します。テンプレート100は、新しいデバイスを作成します。これは、オプションのパラメータ(deviceName、deviceType)と一緒に使用できます。

100,My first MQTT device,c8y_MQTTdevice

その後、このデバイスは新しいデバイスとしてデバイス管理アプリケーションに表示されます。デバイスの識別子タブに切り替えると、デバイスをMQTT ClientIdにリンクするためのIDが自動的に作成されていることがわかります。

デバイスには名前とタイプ以外の情報はないので、マスターデータを追加する必要があります。

改行(1行に1つのテンプレート)で区切られた複数の静的テンプレートをパブリッシュごとに使用できます。この機能は、1つのパブリッシュメッセージにデバイスのハードウェアと可用性監視に必要な間隔を設定するために使用されます。

ハードウェアは、テンプレート110で設定することができます。3つのパラメータを指定できます（シリアル番号、モデル、リビジョン）。静的テンプレートのオプションパラメータは、設定しない場合は空のままにしておくことができます。ハードウェアでは、すべてのパラメータは任意です。

可用性監視に必要な間隔はテンプレート117で設定でき、単一のパラメータ（分単位の間隔）を取ります。

110,,MQTT test model,1.2.3
117,10

デバイス管理アプリケーションでデバイスの情報タブをリロードすると、追加した情報が表示されます。

メジャーメントの作成

これでデバイスにマスターデータが入り、メジャーメントの送信を開始できます。静的テンプレートを使用して直接作成できるメジャーメントがいくつかあります。

210: 信号強度メジャーメント
211: 温度メジャーメント
212: バッテリーメジャーメント

温度とバッテリーのメジャーメントは、値と時間をパラメータとして取るだけです。信号強度には、2つの値(RSSIおよびBER)を渡すことができます。

Things Cloud MQTT実装でタイムスタンプを渡すことは、常にオプションです。これらを渡さない場合、サーバーは自動的に現在のサーバー時刻のタイムスタンプを作成します。

この例では、この機能を使用します。また、最後のパラメータを設定しない場合は、残りのカンマを入力する必要はありません。

210,-87
211,24
212,95

上記のメジャーメントの他に、テンプレート200を使用して、よりカスタムなメジャーメントを作成することもできます。パラメータとして、メジャーメントフラグメント、シリーズ、値、単位、時間を取ります。

200,myCustomTemperatureMeasurement,fahrenheit,75.2,F

デバイス管理アプリケーションをリロードすると、デバイスの計測値タブに、新しく追加されたメジャーメントを示す4つのグラフが表示されます。

アラームの作成

次に、このデバイスのアラームをいくつか作成します。次の4つのアラーム重大度のアラームを作成するテンプレートがあります。

301: クリティカル
302: メジャー
303: マイナー
304: 警告

それぞれ、タイプ(必須)、テキスト、時刻(両方ともオプション)を示します。

301,gpio_critical,There is a GPIO alarm
304,simple_warning

デバイスのアラームリストには、1つのクリティカルアラームと1つの警告アラームが含まれます。

警告アラームのテキストは設定していないので、デフォルトのアラームテキストで作成されます。

ここで、クリティカルアラームを再度クリアします。これを達成するために、クリアされるべきアラームのタイプを参照するテンプレート306を使用します。

306,gpio_critical

クリティカルアラームは後でクリアする必要があります。

MQTT実装では、アラームIDを処理する必要がないことに注意してください。Things Cloudがこの部分を引き継ぎ、デバイス間の通信を可能な限り容易にします。

イベントの作成

次に、デバイスの位置イベントをいくつか作成します。必要に応じて、LatLongのWebサイトを使用して都市の緯度と経度を取得できます。

テンプレート401を使用すると、位置イベントを作成し、緯度、経度、高度、精度、および時間をパラメーターとして取りますが、ここでは最初の2つのみを使用します。

401,51.227741,6.773456

デバイス管理アプリケーションでは、イベントリストにイベントが1つ表示されますが、位置は更新されていません。RESTではこれらは異なるリクエストであるためです。テンプレート401の代わりに、MQTTでテンプレート402を使用することができます。これは401とまったく同じように動作しますが、デバイス自体の位置も更新します。

402,51.227741,6.773456

これで、デバイスの位置タブと追跡タブの両方が表示され、位置タブには最後の位置イベントと同じ緯度と経度が表示されます。

受信データ

これまでは、クライアントからサーバーにデータを送信するためにMQTTだけを使用してきました。次に、サーバーからクライアントにデータを送信します。

これを実現するには、最初に責任のあるトピックをサブスクライブする必要があります。2つのサブスクリプションを行います。

s/ds : デバイスの静的オペレーションテンプレートのサブスクライブ
s/e : デバッグに使用できるエラートピックのサブスクライブ

Subscribeフィールドに両方のトピックを続けて入力し、Subscribeをクリックします。この例では、QoSの選択は重要ではありません。

その後、MQTTBoxは次のようになります。

MQTTBoxサブスクライブされたトピック

オペレーションの受信

現在の状態では、UIにオペレーション用のタブは表示されません。この時点まで、デバイスが正確に何をサポートしているかは不明でしたが、サポートされているオペレーションのリストはテンプレート114で変更することができます。サポートされているオペレーションのリストをここに追加できます。

デバイスの構成とシェルのサポートを追加します。

114,c8y_Command,c8y_Configuration

UIをリロードすると、新しいタブ（構成および シェル）が表示されます。

UIからシェルコマンドを作成し、実行をクリックします。

MQTTBoxに、s/dsサブスクリプション用の新しいメッセージが表示されます。

MQTTBoxオペレーション受信

511は受け取ったオペレーションの種類(この場合はc8y_Command)を示しています。この後にdeviceIdentifierが続き、専用のオペレーションを行うデバイスを特定します。これは、複数の子デバイスを持つ階層がある場合に必要です。そのような場合は、どの子デバイスにオペレーションが行われたかを知る必要があります。最後に、オペレーション固有のパラメータがあります。c8y_Commandの場合は、コマンドテキストのみです。

オペレーションを受信したら、そのオペレーションの実行を開始して、クライアントによるオペレーションの処理を開始できます。アラームのステータスを変更するのと同様に、オペレーションの種類をテンプレートに追加できます。

501,c8y_Command

処理が終了したら、テンプレート503でオペレーションを成功に設定できます。

このオペレーションには、オペレーションタイプの他に、オペレーションの種類に基づいて追加のパラメータを指定することもできます。c8y_Commandの結果を返すことができます。

503,c8y_Command,Everything went fine

エラーから学ぶ

トピックs/eは、問題が発生した場合のデバッグに役立ちます。例えば、下記を送信しようとすると、

999,I made this up

テンプレート999が不明であるため、このトピックに関するメッセージが表示されます。

40,999,No static template for this message id