MQTTのサンプル
Hello MQTT
このチュートリアルでは、Things CloudでMQTTを事前定義されたメッセージ(「静的テンプレート」と呼ばれます)を使って利用する方法を学びます。
前提条件
このチュートリアルを進めるために、以下の前提条件を確認してください。
Things Cloudへアクセスするための有効なテナント・ユーザー・パスワードを持っていること
MQTTBox または同様のMQTTツールをインストールしていること
備考
チュートリアルのスクリーンショットはMQTTBoxを使用しています。他のツールの場合、見た目が異なる場合があります。
トライアルテナントを利用している場合、デフォルトユーザーではこのチュートリアルは動作しません。追加のユーザーを作成してください。また、テナントIDやURLの情報もトライアルテナントとは異なります。
MQTT接続の設定
MQTT接続を設定するには、以下の接続パラメータを渡す必要があります(下記のスクリーンショット参照)。
MQTTクライアント名 – クライアントを識別するための名前を付けてください(例:Things Cloud MQTT)。
MQTTクライアントID – 「ランダムID生成」ボタン(ほとんどのツールで用意されています)を使うか、自分で指定してください。このIDはThings Cloud内のデバイスに紐づけられます。同じデバイスで再接続したい場合は同じIDを使ってください。
プロトコル – 使用するプロトコルを選択します(例:mqtt/tcp)。
ホスト – テナントドメインをURLとして指定します(例:mytenant.je1.thingscloud.ntt.com/mqtt )。
ユーザー名 – この場合、ユーザー名は <tenantID>/<service-user> 形式です。Things Cloudプラットフォームへログインする際と同じ認証情報を使えます(ユーザーエイリアスはサポートされていません)。下記例では、テナントID「t76543210」とサービスユーザー「manga」の場合、ユーザー名は「t76543210/manga」となります。
パスワード – サービスユーザーのパスワード
Things CloudはTCPとWebSocketsの両方でMQTTをサポートしています。URLにはテナントドメイン(例:mytenant.je1.thingscloud.ntt.com/mqtt )またはインスタンスのドメイン(mqtt.<instance_domain>形式、例:mqtt.je1.thingscloud.ntt.com )を利用できます。
「クリーンセッション」など他の設定は今回の例では重要ではありません。必要に応じて変更できます。Save をクリックすると、以下のような画面が表示されます。
上部バーに青いボタンでNot Connected と表示されている場合は、設定(特にユーザー名とパスワード)を確認してください。ボタンが緑色なら、Things CloudへのMQTT接続が正常に確立されています。
データ送信
このチュートリアルの全てのMQTTパブリッシュメッセージは s/us トピックに送信されます。これはThings Cloudが提供する静的テンプレート用のトピックです。
デバイスの作成
最初に送信するメッセージは、デバイスの作成です。静的テンプレートは自動デバイス作成もサポートしていますが、この例では手動で作成します。テンプレート100
で新しいデバイスを作成できます。2つのオプションパラメータ(deviceName, deviceType)が利用可能です。
100,My first MQTT device,c8y_MQTTdevice
この後、デバイス管理アプリケーションで新しいデバイスとして表示されます。デバイスの識別情報 タブに切り替えると、デバイスとMQTT ClientIdを紐付けるための識別情報が自動で作成されていることが分かります。
名前とタイプ以外に情報はありませんので、マスターデータを追加する必要があります。
1回のパブリッシュで、複数の静的テンプレートを改行区切り(1行に1テンプレート)で送信できます。この機能を利用して、ハードウェア情報と必要なインターバルを1回のメッセージで送信できます。
ハードウェア情報はテンプレート110
で設定できます。3つのパラメータ(serialNumber, model, revision)が利用可能です。静的テンプレートのオプションパラメータは、不要な場合空欄で構いません。ハードウェアについては全てオプションです。
必要なインターバルはテンプレート117
で分単位で指定します。
110,,MQTT test model,1.2.3
117,10
デバイス管理アプリケーションの情報 ページをリロードすると、追加した情報が反映されているのが確認できます。
メジャーメントの作成
デバイスにマスターデータが追加されたので、メジャーメント送信を開始できます。
静的テンプレートで直接作成できるメジャーメントはいくつかあります:
210: 信号強度メジャーメント
211: 温度メジャーメント
212: バッテリーメジャーメント
温度・バッテリーメジャーメントは値と時刻がパラメータです。信号強度には2つの値(RSSIとBER)を渡せます。
Things CloudのMQTT実装では、タイムスタンプの指定は常にオプションです。指定しない場合、サーバーが現在時刻でタイムスタンプを自動作成します。
この例でもこの機能を利用します。また、最後のパラメータを設定しない場合、残りのカンマも入力する必要はありません。
上記以外のメジャーメントはテンプレート200
でカスタム作成できます。パラメータは、メジャーメントフラグメント、シリーズ、値、単位、時刻です。
200,myCustomTemperatureMeasurement,fahrenheit,75.2,F
デバイス管理アプリケーションをリロードすると、メジャーメント タブで新たに追加した4つのグラフが表示されます。
アラームの作成
次に、このデバイスにアラームを作成します。4つのアラーム重大度ごとにテンプレートがあります:
301: CRITICAL
302: MAJOR
303: MINOR
304: WARNING
いずれもタイプ(必須)、テキスト、時刻(いずれもオプション)を指定できます。
301,gpio_critical,There is a GPIO alarm
304,simple_warning
デバイスのアラームリストにクリティカルアラームとワーニングアラームが1つずつ追加されているはずです。
ワーニングにはテキストを指定しなかったため、デフォルトのアラームテキストで作成されています。
次に、クリティカルアラームをクリアします。テンプレート306
を使用し、クリアしたいアラームのタイプを指定します。
クリティカルアラームはクリアされます。
MQTT実装ではアラームIDを個別に管理する必要はありません。Things Cloudが自動的に処理するため、デバイスとの通信が極めて簡単になります。
イベントの作成
次に、デバイスに位置イベントを作成します。必要ならLatLongのウェブサイト で都市の緯度・経度を調べてください。
テンプレート401
で位置イベントを作成できます。パラメータは緯度、経度、高度、精度、時刻ですが、今回は最初の2つだけを使います。
デバイス管理アプリケーションのイベントリストで1つのイベントが確認できますが、位置情報自体はまだ更新されていません。これはRESTでは別のリクエストになるためです。MQTTではテンプレート402
を使うことで、イベント作成と同時にデバイスの位置情報も更新できます。
これでデバイスの位置情報 タブとトラッキング タブの両方に、直近の位置イベントと同じ緯度・経度が表示されます。
データ受信
ここまではクライアントからサーバーへのデータ送信だけでした。ここからはサーバーからクライアントへのデータ送信を行います。
まず、該当トピックをサブスクライブする必要があります。今回は2つサブスクライブします:
s/ds : デバイス用の静的オペレーションテンプレート
s/e : デバッグ用途のエラートピック
Subscribe 欄に両方のトピックを入力し、Subscribe をクリックしてください。この例ではQoSの選択は重要ではありません。
MQTTBoxは次のようになります:
オペレーションを受信する
現時点では、UIにオペレーション用のタブは表示されません。デバイスがどのオペレーションをサポートするかはまだ未定なので、テンプレート114
でサポートするオペレーション一覧を追加します。
今回は構成とシェルを追加します。
114,c8y_Command,c8y_Configuration
UIをリロードすると、構成 とシェル の2つの新しいタブが表示されます。
UIからシェルコマンドを作成し、実行 をクリックできます。
MQTTBoxでs/ds サブスクリプションの新しいメッセージが受信されるはずです。
511
は受信したオペレーションの種類(この場合はc8y_Command
)を示します。続いてdeviceIdentifier が続き、階層構造で複数の子デバイスがある場合に、どの子へのオペレーションか特定するため必要となります。最後はオペレーション固有のパラメータ(c8y_Command
の場合はコマンドテキストのみ)です。
オペレーションを受信したら、クライアント側で処理を開始します。アラームのステータス変更と同様、テンプレートにオペレーションタイプを追加できます。
処理が完了したら、テンプレート503
でオペレーションを成功としてマークできます。
オペレーションタイプ以外にも、オペレーションの種類に応じて追加パラメータが指定できます。c8y_Command
の場合は結果を返すことができます。
503,c8y_Command,Everything went fine
エラーから学ぶ
s/e トピックは、何か問題が発生した場合のデバッグに役立ちます。
たとえば、以下を送信すると
テンプレート999
が不明なため、トピック上にメッセージが表示されます。
40,999,No static template for this message id
※以降の「Hello MQTT C」「Hello MQTT Java」「Hello MQTT Java with certificates」「Hello MQTT browser-based」「Hello MQTT Node.js」「Hello MQTT Python」についても同様に、
アプリ名やUIに現れる箇所(Device Management application 等)も「デバイス管理アプリケーション」など日本語訳にしてください。
用語集のルールを適用し、マークダウン記号やコードブロック、{{}}は変更しないでください。
コメントや空白行はそのまま保持してください。