このチュートリアルでは、FIWARE に接続する IoT デバイスでの MQTT プロトコルの使用を紹介します。以前のチュートリアルで作成した、UltraLight 2.0 IoT Agent は、Mosquitto message broker を介して MQTT を使用して一連のダミー IoT デバイスと通信するように再構成されます。

MQTT とは何ですか？¶

"With the technology at our disposal, the possibilities are unbounded. All we need to do is make sure we keep talking."

— Stephen Hawking

"MQTT は、IoT (Internet of Things) で使用される、パブリッシュ・サブスクライブ・ベースのメッセージング・プロトコルです。これは TCP/IP プロトコルの上で動作し、"小規模なコードのフットプリント"が必要な、またはネットワーク帯域幅が制限されている遠隔地との接続用に設計されています。目標は、帯域幅効率が良く、バッテリ電力をほとんど消費しないプロトコルを提供することです。"¹

以前のチュートリアルでは、デバイスとの IoT Agent 間の転送メカニズムとして HTTP を使用していました。HTTP は、各デバイスが IoT Agent に直接接続するリクエスト/レスポンスのパラダイムを使用します。MQTT は、パブリッシュ・サブスクライブがイベント駆動型であり、メッセージをクライアントにプッシュするという点で異なります。MQTT ブローカと呼ばれる、追加の中央通信ポイントが必要です。このポイントは、送信側と正当な受信側間のすべてのメッセージのディスパッチを担当します。ブローカにメッセージを発行する各クライアントには、メッセージへのトピックが含まれています。トピックはブローカのルーティング情報です。メッセージを受信する各クライアントは、特定のトピックにサブスクライブし、ブローカは、一致するトピックを含むすべてのメッセージをクライアントに配信します。したがって、クライアントはお互いに知り合う必要はなく、トピックにしか関係しません。このアーキテクチャは、データ・プロデューサとデータ・コンシューマとの間の依存性を伴わずに、スケーラビリティの高いソリューションを実現します。

2 つのトランスポート・プロトコルの違いの概要を以下に示します :

HTTP トランスポート	MQTT トランスポート

IoT Agent は IoT デバイスと直接通信します	IoT Agent は、MQTT Broker を介して間接的に IoT デバイスと通信します
Request-Response のパラダイム	Publish-Subscribe のパラダイム
IoT デバイスは、常に通信を受信する準備ができている必要があります	IoT デバイスは、いつ通信を受けるかを選択します
より高い消費電力要件	低消費電力要件

UltraLight 2.0 IoT Agent は、UltraLight 2.0 構文を使用してメッセージを送信または解釈するだけですが、複数の転送メカニズムを使用してメッセージを送受信するために使用できます。したがって、同じ FIWARE Generic Enabler を使用して、より幅広い範囲の IoT デバイスに接続することができます。

Mosquitto MQTT Broker¶

Mosquitto は、このチュートリアルで使用する、すぐに利用できるオープンソースの MQTT ブローカです。EPL/EDL の下でライセンスされています。詳細は、https://mosquitto.org/ をご覧ください。

デバイス・モニタ¶

このチュートリアルの目的のために、一連のダミー IoT デバイスが作成され、Context Broker に接続されます。使用されるアーキテクチャとプロトコルの詳細は、IoT Sensors のチュートリアルにあります。各デバイスの状態は、次の UltraLight デバイス・モニタの Web ページで確認できます : http://localhost:3000/device/monitor

FIWARE Monitor

アーキテクチャ¶

このアプリケーションは、以前のチュートリアルで作成したコンポーネントに基づいています。Orion Context Broker と IoT Agent for UltraLight 2.0 の 2 つの FIWARE コンポーネントを使用します。アプリケーションが “Powered by FIWARE” と認定されるには、Orion Context Broker を使用するだけで十分です。Orion Context Broker と IoT Agent はオープンソースの MongoDB 技術を利用して、保持している情報の永続性を保ちます。また、前回のチュートリアルで作成したダミー IoT デバイスも使用します。また、オープンソースで、EPL/EDL で入手できる Mosquitto ブローカのインスタンスを追加します。

したがって、全体的なアーキテクチャは次の要素で構成されます :

FIWARE Orion Context Broker は、NGSI-v2 を使用してリクエストを受信します
FIWARE IoT Agent for UltraLight 2.0 は以下を行います :
- NGSI-v2 を使用してサウス・バウンド・リクエストを受信し、MQTT Broker 用の UltraLight 2.0 のトピックに変換します
- 登録されたトピックについて MQTT Broker をリッスンし、測定値をノース・バウンドに送信します
Mosquitto MQTT Broker は、必要に応じて MQTT トピックを IoT Agent と IoT デバイスの間でやりとりする中央通信ポイントとして機能します
MongoDB データベース :
- Orion Context Broker が、データ・エンティティ、サブスクリプション、レジストレーションなどのコンテキスト・データ情報を保持するために使用します
- IoT Agent がデバイスの URLs や Keys などのデバイス情報を保持するために使用します
MQTT 上で動作する UltraLight 2.0 プロトコルを使用して、ダミー IoT デバイスのセットとして機能する Web サーバー
このチュートリアルでは、コンテキスト・プロバイダの NGSI proxy は使用しません。これは以下を行います :
- NGSI-v2 を使用してリクエストを受信します
- 独自の API を独自のフォーマットで使用して、公開されているデータ・ソースへのリクエストを行います
- NGSI-v2 形式でコンテキスト・データを Orion Context Broker に返します
在庫管理フロントエンドは、このチュートリアルで使用していません。これは以下を行います :
- 店舗情報を表示し、ユーザーがダミー IoT デバイスと対話できるようにします
- 各店舗で購入できる商品を表示します
- ユーザが製品を購入して在庫数を減らすことを許可します

要素間のすべての対話は TCP を介して HTTP または MQTT リクエストによって開始されるため、エンティティはコンテナ化され、公開されたポートから実行されます。

Mosquitto MQTT Broker, IoT デバイス, IoT Agent を接続するために必要な設定情報は、関連する docker-compose.yml ファイルの services セクションにあります :

Mosquitto の設定¶

mosquitto:
    image: eclipse-mosquitto
    hostname: mosquitto
    container_name: mosquitto
    networks:
        - default
    expose:
        - "1883"
        - "9001"
    ports:
        - "1883:1883"
        - "9001:9001"
    volumes:
        - ./mosquitto/mosquitto.conf:/mosquitto/config/mosquitto.conf

mosquitto コンテナは、2 つのポートでリッスンしています :

ポート 1883 は、MQTT のトピックをポストできるように公開されています
ポート 9001 は、HTTP/Websocket 通信の標準ポートです

volumes の設定は、MQTT message broker のデバッグ・レベルを上げるために使用される設定ファイルです。

ダミー IoT デバイスの設定¶

tutorial:
    image: fiware/tutorials.context-provider
    hostname: iot-sensors
    container_name: fiware-tutorial
    networks:
        - default
    expose:
        - "3000"
        - "3001"
    ports:
        - "3000:3000"
        - "3001:3001"
    environment:
        - "DEBUG=tutorial:*"
        - "WEB_APP_PORT=3000"
        - "DUMMY_DEVICES_PORT=3001"
        - "DUMMY_DEVICES_API_KEY=4jggokgpepnvsb2uv4s40d59ov"
        - "DUMMY_DEVICES_TRANSPORT=MQTT"

tutorial コンテナは、2 つのポートでリッスンしています :

ポート 3000 が公開されているので、ダミー IoT デバイスを表示する Web ページが表示されます
ポート 3001 はチュートリアルのアクセスのためだけに公開されているため、cUrl または Postman は同じネットワーク以外からも、UltraLight コマンドを作成できます

tutorial コンテナは、次のように環境変数によって設定値を指定できます :

キー	値	説明
DEBUG	`tutorial:*`	ロギングに使用するデバッグ・フラグ
WEB_APP_PORT	`3000`	ダミー・デバイスのデータを表示する web-app が使用するポート
DUMMY_DEVICES_PORT	`3001`	コマンドを受信するためにダミー IoT デバイスが使用するポート
DUMMY_DEVICES_API_KEY	`4jggokgpepnvsb2uv4s40d59ov`	UltraLight インタラクションに使用されるランダムなセキュリティキー - デバイスと IoT Agent 間のインタラクションの完全性を保証するために使用されます
DUMMY_DEVICES_TRANSPORT	`MQTT`	ダミー IoT デバイスによって使用されるトランスポート・プロトコル

このチュートリアルでは、YAML ファイルで記述されている他の tutorial コンテナの設定値は使用しません。

IoT Agent for UltraLight 2.0 の設定¶

IoT Agent for UltraLight 2.0 は、Docker コンテナ内でインスタンス化できます。公式の Docker イメージは、Docker Hub からタグ付けされた fiware/iotagent-ul です。必要な構成を以下に示します :

iot-agent:
    image: fiware/iotagent-ul:latest
    hostname: iot-agent
    container_name: fiware-iot-agent
    depends_on:
        - mongo-db
    networks:
        - default
    expose:
        - "4041"
    ports:
        - "4041:4041"
    environment:
        - IOTA_CB_HOST=orion
        - IOTA_CB_PORT=1026
        - IOTA_NORTH_PORT=4041
        - IOTA_REGISTRY_TYPE=mongodb
        - IOTA_LOG_LEVEL=DEBUG
        - IOTA_TIMESTAMP=true
        - IOTA_CB_NGSI_VERSION=v2
        - IOTA_AUTOCAST=true
        - IOTA_MONGO_HOST=mongo-db
        - IOTA_MONGO_PORT=27017
        - IOTA_MONGO_DB=iotagentul
        - IOTA_PROVIDER_URL=http://iot-agent:4041
        - IOTA_MQTT_HOST=mosquitto
        - IOTA_MQTT_PORT=1883

iot-agent コンテナは、Orion Context Broker の存在に依存し、そのようなデバイスの URLs 及び Keys としてデバイス情報を保持するために MongoDB データベースを使用します。コンテナは 1 つのポートで待機しています :

ポート 4041 は、チュートリアルのアクセスのためだけに公開されているため、cUrl または Postman は同じネットワーク以外からも、プロビジョニング・コマンドを作成できます

iot-agent コンテナは、次のように環境変数によって設定値を指定できます :

キー	値	説明
IOTA_CB_HOST	`orion`	コンテキストを更新する Context Broker のホスト名
IOTA_CB_PORT	`1026`	Context Broker がコンテキストを更新するためにリッスンするポート
IOTA_NORTH_PORT	`4041`	IoT Agent の設定および Context Broker からのコンテキスト更新の受信に使用されるポート
IOTA_REGISTRY_TYPE	`mongodb`	メモリまたはデータベースに IoT デバイス情報を保持するかどうかを指定
IOTA_LOG_LEVEL	`DEBUG`	IoT Agent のログ・レベル
IOTA_TIMESTAMP	`true`	接続されたデバイスから受信した各測定値にタイムスタンプ情報を提供するかどうかを指定
IOTA_CB_NGSI_VERSION	`v2`	アクティブな属性の更新を送信するときにNGSI v2 を使用するように指定するかどうか
IOTA_AUTOCAST	`true`	Ultralight の数値が文字列ではなく数値として読み取られるようにする
IOTA_MONGO_HOST	`context-db`	mongoDB のホスト名 - デバイス情報を保持するために使用
IOTA_MONGO_PORT	`27017`	mongoDB はリッスンしているポート
IOTA_MONGO_DB	`iotagentul`	mongoDB で使用されるデータベースの名前
IOTA_PROVIDER_URL	`http://iot-agent:4041`	コマンドが登録されたときに Context Broker に渡された URL。Context Broker がデバイスにコマンドを発行したときに転送 URL の場所として使用
IOTA_MQTT_HOST	`mosquitto`	MQTT Broker のホスト名
IOTA_MQTT_PORT	`1883`	MQTT Broker がトピックを受信するためにリッスンしているポート

ご覧のように、MQTT トランスポートの使用は、2 つの環境変数 IOTA_MQTT_HOST と IOTA_MQTT_PORT によってのみ制御されます。

前提条件¶

Docker と Docker Compose¶

物事を単純にするために、両方のコンポーネントが Docker を使用して実行されます。Docker は、さまざまコンポーネントをそれぞれの環境に分離することを可能にするコンテナ・テクノロジです。

Docker Windows にインストールするには、こちらの手順に従ってください
Docker Mac にインストールするには、こちらの手順に従ってください
Docker Linux にインストールするには、こちらの手順に従ってください

Docker Compose は、マルチコンテナ Docker アプリケーションを定義して実行するためのツールです。YAML file ファイルは、アプリケーションのために必要なサービスを構成するために使用します。つまり、すべてのコンテナ・サービスは 1 つのコマンドで呼び出すことができます。Docker Compose は、デフォルトで Docker for Windows と Docker for Mac の一部としてインストールされますが、Linux ユーザはここに記載されている手順に従う必要があります。

次のコマンドを使用して、現在の Docker バージョンと Docker Compose バージョンを確認できます :

docker-compose -v
docker version

Docker バージョン 20.10 以降と Docker Compose 1.29 以上を使用していることを確認し、必要に応じてアップグレードしてください。

Cygwin for Windows¶

シンプルな bash スクリプトを使用してサービスを開始します。Windows ユーザは cygwin をダウンロードして、Windows 上の Linux ディストリビューションと同様のコマンドライン機能を提供する必要があります。

起動¶

開始する前に、必要な Docker イメージをローカルで取得または構築しておく必要があります。リポジトリを複製し、以下のコマンドを実行して必要なイメージを作成してください :

git clone https://github.com/FIWARE/tutorials.IoT-over-MQTT.git
cd tutorials.IoT-over-MQTT
git checkout NGSI-v2

./services create

その後、リポジトリ内で提供される services Bash スクリプトを実行することによって、コマンドラインからすべてのサービスを初期化することができます :

./services start

注: クリーンアップをやり直したい場合は、次のコマンドを使用して再起動することができます :
./services stop

IoT Agent のプロビジョニング (Ultra Light over MQTT)¶

チュートリアルを正しく実行するには、ブラウザのデバイス・モニタページが表示されていることを確認し、ページをクリックして cUrl コマンドを入力する前にオーディオを有効にしてください。デバイス・モニタには、Ultralight 2.0 構文を使用して、ダミー IoT デバイスのアレイの現在の状態が表示されます。

デバイス・モニタ¶

デバイス・モニタは次の場所にあります : http://localhost:3000/device/monitor

Mosquitto Health の確認¶

まず、IoT Agent とダミー IoT デバイスの役割を模倣し、MQTT を使用していくつかのメッセージを送受信します。このチュートリアルのこのセクションでは、いくつかのオープン・ターミナルが必要です。

MQTT サブスクライバを開始 (1st ターミナル)¶

最終的にシステムによって正しく接続されると、IoT Agent は関連するすべてのイベントにサブスクライブし、センサの測定値の形式でノース・バウンドのトラフィックを待ち受けます。したがって、すべてのトピックを対象にサブスクリプションを作成する必要があります。同様に、アキュエーターは、コマンドがサウス・バウンドで送信されたときにそれ自体に影響を及ぼすイベントを受け取るために、単一のトピックにサブスクライブする必要があります。コミュニケーションのラインが開いていることを確認するには、特定のトピックをサブスクライブして、メッセージが公開されたときに何かを受け取れるかどうかを確認します。

新しいターミナルを開き、次のように新しい mqtt-subscriber の Docker コンテナを作成します :

docker run -it --rm --name mqtt-subscriber \
  --network fiware_default efrecon/mqtt-client sub -h mosquitto -t "/#"

ターミナルはイベントを受信する準備ができます。

MQTT パブリッシャを開始 (2nd ターミナル)¶

ノース・バウンドの測定値を送信するセンサは、MQTT Broker へ測定値を公開して、サブスクライバに送信することができます。センサはサブスクライバに直接接続する必要はありません。

新しいターミナルを開き、次のように mqtt-publisher の Docker コンテナを実行してメッセージを送信します :

docker run -it --rm --name mqtt-publisher \
  --network fiware_default efrecon/mqtt-client pub -h mosquitto -m "HELLO WORLD" -t "/test"

1st ターミナル - 結果 :¶

MQTT Broker が正常に機能している場合は、メッセージを別のターミナルで受信する必要があります :

HELLO WORLD

MQTT サブスクライバを停止 (2nd ターミナル)¶

MQTT サブスクライバを終了するには、次の Docker コマンドを実行します :

docker stop mqtt-subscriber

Mosquitto ログを表示¶

通信が MQTT Broker を介して行われたことを示すために、次のように mosquitto の Docker コンテナのログを検査することができます :

docker logs --tail 10 mosquitto

結果 :¶

1529661883: New client connected from 172.18.0.5 as mqttjs_8761e518 (c1, k0).
1529662472: New connection from 172.18.0.7 on port 1883.
1529662472: New client connected from 172.18.0.7 as mosqpub|1-5637527c63c1 (c1, k60).
1529662472: Client mosqpub|1-5637527c63c1 disconnected.
1529662614: New connection from 172.18.0.7 on port 1883.
1529662614: New client connected from 172.18.0.7 as mosqsub|1-64b27d675f58 (c1, k60).
1529662623: New connection from 172.18.0.8 on port 1883.
1529662623: New client connected from 172.18.0.8 as mosqpub|1-ef03e74b0270 (c1, k60).
1529662623: Client mosqpub|1-ef03e74b0270 disconnected.
1529667841: Socket error on client mosqsub|1-64b27d675f58, disconnecting.

IoT Agent Service Health の確認¶

IoT Agent が動作しているかどうかは、公開されているポートに対して HTTP リクエストを行うことで確認できます :

1 リクエスト :¶

curl -X GET \
  'http://localhost:4041/iot/about'

レスポンスは次のようになります :

{
    "libVersion": "2.6.0-next",
    "port": "4041",
    "baseRoot": "/",
    "version": "1.6.0-next"
}

Failed to connect to localhost port 4041: Connection refused のレスポンスを受け取ったらどうしますか？

Connection refused レスポンスを受け取った場合、IoT Agent がこのチュートリアルで期待される場所には見つかりません。各 cUrl コマンドの URL とポートを正しい IP アドレスで置き換える必要があります。すべての cUrl コマンドのチュートリアルでは、localhost:4041 で IoT Agent が使用可能であると想定しています。

以下の対策を試してください :

Docker コンテナが動作していることを確認するには、次のようにしてください :
docker ps
実行中の 4 つのコンテナが表示されます。IoT Agent が実行されていない場合は、必要に応じてコンテナを再起動できます。このコマンドは、開いているポート情報も表示します

docker-machine と Virtual Box をインストールしている場合は、Context Broker, IoT Agent およびダミー IoT デバイスの Docker コンテナが別の IP アドレスで実行されている可能性があります。次に示すように仮想ホスト IP を取得する必要があります :
curl -X GET \
'http://$(docker-machine ip default):4041/version'
または、コンテナ・ネットワーク内からすべての curl コマンドを実行します :
docker run --network fiware_default --rm appropriate/curl -s \
 -X GET 'http://iot-agent:4041/iot/about'

IoT デバイスの接続¶

IoT Agent は、IoT デバイスと Context Broker との間のミドルウェアとして機能します。したがって、ユニークな ID を持つコンテキスト・データのエンティティを作成できる必要があります。サービスがプロビジョニングされ、未知のデバイスが測定を行うと、デバイスが認識され、既知の ID にマッピングされない限り、IoT Agent は、提供された <device-id> を使用してこれをコンテキストに追加します。

すべての IoT デバイス <device-id> が常に一意であるという保証はないため、IoT Agent へのすべてのプロビジョニングのリクエストには、2 つの必須ヘッダーが必要です :

fiware-service ヘッダは、特定のサービスのエンティティを別の mongoDB データベースに保持できるように定義されています
fiware-servicepath は、デバイスのアレイを区別するために使用できます

たとえば、スマート・シティのアプリケーションでは、さまざまな部門 (公演、交通機関、ごみ収集など) ごとに異なる fiware-service ヘッダが必要であり、それぞれ fiware-servicepath が特定の公園などを参照します。これは、各サービスのデータとデバイスが必要に応じて識別され、分離されることを意味しますが、データはサイロ化されません。たとえば公園内のスマート・ビンのデータは、ゴミ箱の GPS ユニットと組み合わせて、効率的な方法でトラックのルートを変更することができます。

スマート・ビンと GPS ユニットは、さまざまなメーカから来る可能性が高く、使用される <device-id>s に重複がないことは保証できません。fiware-service ヘッダと fiware-servicepath ヘッダの使用は、これが常に当てはまることを保証し、Context Broker がコンテキスト・データの元のソースを識別することを可能にします。

MQTT のサービス・グループのプロビジョニング¶

グループのプロビジョンを呼び出すことは、常にデバイスを接続する最初のステップです。MQTT 通信では、プロビジョニングによって認証キーが提供されるため、IoT Agent はサブスクライブするトピックを認識します。

すべてのデバイスにデフォルトのコマンドと属性を設定することもできますが、このチュートリアルでは各デバイスを個別にプロビジョニングするため、これは行われません。

この例では、匿名のデバイス・グループをプロビジョニングします。IoT Agent に、一連のデバイスが /ul/4jggokgpepnvsb2uv4s40d59ov トピックにメッセージを送信して通信することを通知します。

注測定値とコマンドは、さまざまな MQTT トピックを介して送信されます:

Measures は /<protocol>/<api-key>/<device-id>/attrs トピックで送信されます

Commands は /<api-key>/<device-id>/cmd トピックで送信されます

この背後にある理由は、デバイスから IoT Agent にノースバウンドで測定値を送信する場合、データを解析するために必要な IoT Agent を明示的に識別する必要があるためです。これは、関連する MQTT トピックの前にプロトコルを付けることによって行われます。そうでない場合、どのエージェントが測定値を処理しているかを定義する方法がありません。このメカニズムにより、スマート・システムは必要に応じてさまざまなデバイスをさまざまな IoT Agent に接続できます。

サウスバウンド・コマンドの場合、デバイスのプロビジョニング手順中に正しい IoT Agent がコマンドに登録されており、デバイスは常に適切な形式でコマンドを受信するため、この区別は不要です。

HTTP 通信が使用されていないため、resource 属性は空白のままになります。cbroker の URL の場所はオプションの属性です。IoT Agent が提供されていない場合、 IoT Agent は設定ファイルで定義されているデフォルトの context broker URL を使用しますが、完全性のためにここに追加されています。

2 リクエスト :¶

curl -iX POST \
  'http://localhost:4041/iot/services' \
  -H 'Content-Type: application/json' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /' \
  -d '{
 "services": [
   {
     "apikey":      "4jggokgpepnvsb2uv4s40d59ov",
     "cbroker":     "http://orion:1026",
     "entity_type": "Thing",
     "resource":    ""
   }
 ]
}'

センサのプロビジョニング¶

エンティティを作成するときは、NGSI-LD 仕様に従って URN を使用するのが一般的な良い方法です。さらに、データ属性を定義するときに意味のある名前を理解する方が簡単です。これらのマッピングは、デバイスを個別にプロビジョニングすることによって定義できます。

3 つのタイプの測定属性をプロビジョニングできます :

attributes は、デバイスからのアクティブな読み取りです
lazy 属性はリクエストに応じて送信されます。IoT Agent は測定結果を返すようにデバイスに通知します
static_attributes は、Context Broker に渡されるデバイスに関する静的なデータ(リレーションシップなど)を示す名前です

注 : 個別 id が必要でないか、または集約されたデータが十分である場合は、attributes は個別にではなくプロビジョニング・サービス内で定義できます。

3 リクエスト :¶

curl -iX POST \
  'http://localhost:4041/iot/devices' \
  -H 'Content-Type: application/json' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /' \
  -d '{
 "devices": [
   {
     "device_id":   "motion001",
     "entity_name": "urn:ngsi-ld:Motion:001",
     "entity_type": "Motion",
     "protocol":    "PDI-IoTA-UltraLight",
     "transport":   "MQTT",
     "timezone":    "Europe/Berlin",
     "attributes": [
       { "object_id": "c", "name": "count", "type": "Integer" }
     ],
     "static_attributes": [
       { "name":"refStore", "type": "Relationship", "value": "urn:ngsi-ld:Store:001"}
     ]
   }
 ]
}
'

リクエストでは、デバイス motion001 を URN urn:ngsi-ld:Motion:001 に関連付け、コンテキスト属性 ccount (これは Integer と定義されています) を持つデバイス読み込み c をマッピングします。refStore は static_attribute として定義され、デバイスを Store urn:ngsi-ld:Store:001 内に配置します。

リクエストのボディに transport=MQTT 属性を追加するだけで、IoT Agent に測定を受け取るために、/<api-key>/<device-id> トピックに登録する必要があることを通知するのに十分です。

次のトピックに MQTT メッセージをポストすることで、モーション・センサ のデバイス motion001 からのダミー IoT デバイスの測定値をシミュレートできます。

4 MQTT リクエスト :¶

docker run -it --rm --name mqtt-publisher --network \
  fiware_default efrecon/mqtt-client pub -h mosquitto -m "c|1" \
  -t "/ul/4jggokgpepnvsb2uv4s40d59ov/motion001/attrs"

-mパラメータの値によってメッセージが定義されます。これは Ultra Light の構文です
-t パラメータの値によってトピックが定義されます

トピックは、次の形式でなければなりません :

/<protocol>/<api-key>/<device-id>/attrs

注以前のチュートリアルで、モーション・センサと IoT Agent との間の HTTP 接続性をテストするとき、同様のダミー HTTP リクエストが送られて、count 値が更新されました。今回は、IoT Agent が MQTT トピックをリッスンするように構成されており、MQTT トピックにダミー・メッセージをポストする必要があります。

MQTT トランスポート・プロトコルを使用する場合、IoT Agent は MQTT トピックをサブスクライブし、デバイス・モニタは各トピックに送信されたすべての MQTT メッセージを表示するように構成されます。効果的に Mosquitto が送受信するリスト・メッセージを表示します。

MQTT を介して接続された IoT Agent を使用して、サービス・グループはエージェントがサブスクライブしているトピックを定義しています。api-key がトピックのルートと一致するので、モーション・センサからの MQTT メッセージは、以前にサブスクライブした IoT Agent に渡されます。

特にデバイス (motion001) をプロビジョニングしたので、IoT Agent は、Orion Context Broker でリクエストを発行する前に属性をマップできます。

Context Broker からエンティティ・データを取得することで、測定値が記録されたこと確認できます。fiware-service ヘッダと fiware-service-path ヘッダを追加することを忘れないでください。

5 リクエスト :¶

curl -X GET \
  'http://localhost:1026/v2/entities/urn:ngsi-ld:Motion:001?type=Motion' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /'

レスポンス :¶

{
    "id": "urn:ngsi-ld:Motion:001",
    "type": "Motion",
    "TimeInstant": {
        "type": "ISO8601",
        "value": "2018-05-25T10:51:32.00Z",
        "metadata": {}
    },
    "count": {
        "type": "Integer",
        "value": "1",
        "metadata": {
            "TimeInstant": {
                "type": "ISO8601",
                "value": "2018-05-25T10:51:32.646Z"
            }
        }
    }
}

レスポンスは、id=motion001 のモーション・センサのデバイスが IoT Agent によって正常に識別され、エンティティ id=urn:ngsi-ld:Motion:001 にマッピングされていることを示します。この新しいエンティティは、コンテキスト・データ内で作成されました。ダミー IoT デバイスの測定リクエストからの c 属性は、コンテキスト内のより意味のある count 属性にマップされています。お気づきのように、TimeInstant 属性がエンティティと属性のメタデータの両方に追加されました。これはエンティティと属性が最後に更新された時刻を表し、IOTA_TIMESTAMP 環境変数が IoT Agent の起動時に設定されます。

アクチュエータのプロビジョニング¶

アクチュエータのプロビジョニングは、センサのプロビジョニングと同様です。transport=MQTT 属性は、使用される通信プロトコルを定義します。MQTT 通信の場合、endpoint は、デバイスがコマンドをリッスンしている HTTP url がないため、属性は不要です。コマンドのアレイは、/<api-key>/<device-id>/cmd トピックに送信されるメッセージに直接マップされます。commands アレイには、呼び出すことができる各コマンドのリストが含まれています。

以下の例では、deviceId = bell001 のベルがプロビジョニングされています。

6 リクエスト :¶

curl -iX POST \
  'http://localhost:4041/iot/devices' \
  -H 'Content-Type: application/json' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /' \
  -d '{
  "devices": [
    {
      "device_id": "bell001",
      "entity_name": "urn:ngsi-ld:Bell:001",
      "entity_type": "Bell",
      "protocol": "PDI-IoTA-UltraLight",
      "transport": "MQTT",
      "commands": [
        { "name": "ring", "type": "command" }
       ],
       "static_attributes": [
         {"name":"refStore", "type": "Relationship","value": "urn:ngsi-ld:Store:001"}
      ]
    }
  ]
}
'

Context Broker を接続する前に、/v2/op/update エンドポイントを使用して、IoT Agent のノース・ポートに直接 REST リクエストを行うことで、IoT Agent からデバイスにコマンドを送信できることをテストできます。Context Broker に接続すると、最終的に Context Broker によって呼び出されるのは、このエンドポイントです。設定をテストするには、次のようにコマンドを直接実行します :

7 リクエスト :¶

curl -iX POST \
  http://localhost:4041/v2/op/update \
  -H 'Content-Type: application/json' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /' \
  -d '{
    "actionType": "update",
    "entities": [
        {
            "type": "Bell",
            "id": "urn:ngsi-ld:Bell:001",
            "ring" : {
                "type": "command",
                "value": ""
            }
        }
    ]
}'

デバイス・モニタのページを表示している場合は、ベル変更の状態も表示できます。

ベルを鳴らすコマンドの結果は、Orion Context Broker 内のエンティティにクエリすることによって読み取ることができます。

8 リクエスト :¶

curl -X GET \
  'http://localhost:1026/v2/entities/urn:ngsi-ld:Bell:001?type=Bell&options=keyValues' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /'

レスポンス :¶

{
    "id": "urn:ngsi-ld:Bell:001",
    "type": "Bell",
    "TimeInstant": "2018-05-25T20:06:28.00Z",
    "refStore": "urn:ngsi-ld:Store:001",
    "ring_info": " ring OK",
    "ring_status": "OK",
    "ring": ""
}

TimeInstant は、エンティティに関連付けられたコマンドが呼び出された時刻を最後に表示します。リング・コマンドの結果を ring_info 属性の値で見ることができます。

スマート・ドアのプロビジョニング¶

コマンドと測定の両方を提供するデバイスをプロビジョニングするだけでは、リクエストのボディに attributes 属性と command 属性の両方を含む HTTP POST リクエストを作成するだけです。再度、transport=MQTT 属性は、使用される通信プロトコルを定義します。デバイスがコマンドをリッスンする HTTP url がないため、endpoint 属性は必要ありません。

9 リクエスト :¶

curl -iX POST \
  'http://localhost:4041/iot/devices' \
  -H 'Content-Type: application/json' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /' \
  -d '{
  "devices": [
    {
      "device_id": "door001",
      "entity_name": "urn:ngsi-ld:Door:001",
      "entity_type": "Door",
      "protocol": "PDI-IoTA-UltraLight",
      "transport": "MQTT",
      "commands": [
        {"name": "unlock","type": "command"},
        {"name": "open","type": "command"},
        {"name": "close","type": "command"},
        {"name": "lock","type": "command"}
       ],
       "attributes": [
        {"object_id": "s", "name": "state", "type":"Text"}
       ],
       "static_attributes": [
         {"name":"refStore", "type": "Relationship","value": "urn:ngsi-ld:Store:001"}
       ]
    }
  ]
}
'

スマート・ランプのプロビジョニング¶

同様に、2 つのコマンド (on および off) と 2 つの属性を持つスマート・ランプは、次のようにプロビジョニングできます :

10 リクエスト :¶

curl -iX POST \
  'http://localhost:4041/iot/devices' \
  -H 'Content-Type: application/json' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /' \
  -d '{
  "devices": [
    {
      "device_id": "lamp001",
      "entity_name": "urn:ngsi-ld:Lamp:001",
      "entity_type": "Lamp",
      "protocol": "PDI-IoTA-UltraLight",
      "transport": "MQTT",
      "commands": [
        {"name": "on","type": "command"},
        {"name": "off","type": "command"}
       ],
       "attributes": [
        {"object_id": "s", "name": "state", "type":"Text"},
        {"object_id": "l", "name": "luminosity", "type":"Integer"}
       ],
       "static_attributes": [
         {"name":"refStore", "type": "Relationship","value": "urn:ngsi-ld:Store:001"}
      ]
    }
  ]
}
'

プロビジョニングされたデバイスの完全なリストは、/iot/devices エンドポイントに GET リクエストを行うことで取得できます。

11 リクエスト :¶

curl -X GET \
  'http://localhost:4041/iot/devices' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /'

Context Broker コマンドの有効化¶

IoT Agent を IoT デバイスに接続すると、Orion Context Broker にコマンドが利用可能になったことが通知されました。つまり、IoT Agent は、コマンド属性のコンテキスト・プロバイダとして自身を登録しました。

コマンドが登録されると、以前のチュートリアルで実行したように、IoT デバイスに直接 UltraLight 2.0 リクエストを送信するのではなく、ベルを鳴らし、スマート・ドアを開閉し、スマート・ランプをオン/オフに切り替えることができます。

IoT Agent のノース・ポートのすべての通信は、標準の NGSI 構文を使用します。IoT デバイスと Iot Agent 間で使用されるトランスポート・プロトコルは、この通信レイヤとは無関係です。効果的に、IoT Agent は、任意のデバイスを作動させるための既知のエンドポイントの単純化されたファサード・パターンを提供しています。

したがって、コマンドの登録と呼び出しをするこのセクションでは、以前のチュートリアルのインストラクションと重複しています

ベルを鳴らす¶

ring コマンドを呼び出すには、コンテキスト内で ring 属性を更新する必要があります。

12 リクエスト :¶

curl -iX PATCH \
  'http://localhost:1026/v2/entities/urn:ngsi-ld:Bell:001/attrs' \
  -H 'Content-Type: application/json' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /' \
  -d '{
  "ring": {
      "type" : "command",
      "value" : ""
  }
}'

デバイス・モニタのページを表示している場合は、ベル変更の状態も表示できます。

スマート・ドアを開く¶

open コマンドを呼び出すには、コンテキスト内で open 属性を更新する必要があります。

13 リクエスト :¶

curl -iX PATCH \
  'http://localhost:1026/v2/entities/urn:ngsi-ld:Door:001/attrs' \
  -H 'Content-Type: application/json' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /' \
  -d '{
  "open": {
      "type" : "command",
      "value" : ""
  }
}'

スマート・ランプの電源をオン¶

スマート・ランプをオンにするには、on 属性をコンテキストで更新する必要があります。

14 リクエスト :¶

curl -iX PATCH \
  'http://localhost:1026/v2/entities/urn:ngsi-ld:Lamp:001/attrs' \
  -H 'Content-Type: application/json' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /' \
  -d '{
  "on": {
      "type" : "command",
      "value" : ""
  }
}'

License¶

脚注¶

Wikipedia: MQTT - サービス間のすべてのメッセージのディスパッチを担当する MQTT ブローカーと呼ばれる中央通信ポイント