デバイスからプラットフォームに情報を送信するために、IoT Agents を使用することができます。このコンポーネントは、デバイスからの サウスバウンド・プロトコル要求を、Context Broker への NGSIリクエストにマップし、デバイスデータを NGSI エンティティおよび属性にマッピングするのに役立ちます。

Device API を使用すると、次のことが可能になります :

• メッセージ・フットプリントを減らし、コマンドを使用するため、デバイスを登録
• デバイスから FIWARE IoT Stack にデータを送信
• アプリケーションからデバイスにコマンドを送信

次のドキュメントは、IoT プラットフォームの IoTAgent Manager を介してデバイス接続を管理する方法を示しています。これらの APIs は、IoTAgent Libraryで定義されている標準の IoTAgent Device Provisioning APIs といくつかの違いが ありますが、プラットフォームのユーザにとって透過的でなければなりません。

サウスバウンド・プロトコルを構成¶

サウスバンド・プロトコル (South Bound protocol)、つまり、物理的なデバイスをプラットフォームと通信するために使用されるプロトコルが、サービスのために機能するには、デバイスに関する情報をプロビジョニングするか、デバイス自体をプロビジョニングするか、サブサービスごとにコンフィグレーション・グループをプロビジョニングするか、またはその両方によりプロビジョニングする必要があります。コンフィグレーション・グループは、サウスバウンド・プロトコルのNGSIマッピングのいくつかのデフォルト値を定義します。この値は、グループに関連付けられているすべてのデバイスに適用されます。デバイスは、通信でデバイスから提供された API キーに基づいてグループに関連付けられます。

コンフィグレーション・グループは、API を使用してプロビジョニングできます。サブサービスの管理者でない場合は、API キーが与えられている可能性があります。その場合、South Boundプロトコルを再度設定する必要はありません。将来の対話のために提供されたデータを使用してください。

次の抜粋は、コンフィグレーション・グループを API に直接プロビジョニングする方法を示しています :

POST /iot/services?protocol=IoTA-UL
Content-Type: application/json
Fiware-service: OpenIoT
Fiware-servicepath: /

{
  "services": [
    {
      "apikey": "801230BJKL23Y9090DSFL123HJK09H324HV8732",
      "entity_type": "SensorMachine",
      "commands": [
        {
          "name": "wheel1",
          "type": "Wheel"
        }
      ],
      "lazy": [
        {
          "name": "luminescence",
          "type": "Lumens"
        }
      ],
      "attributes": [
        {
          "name": "status",
          "type": "Boolean"
        }
      ],
      "static_attributes": [
        {
          "name": "bootstrapServer",
          "type": "Address",
          "value": "127.0.0.1"
        }
      ]
    }
  ]
}

このリクエストは、API キーを示す、Ultralight 2.0 コンフィグレーション・グループのプロビジョニングです。グループ内のすべてのデバイスに関連する entity_typeと、グループ内のすべてのデバイスが共有する共通の属性は、NGSI エンティティへのマッピングに関する情報とともに共有されます。

現在、IoT プラットフォームは、各プロトコルのサブサービスごとの構成グループの存在のみを可能にします。

IoTデバイスを登録¶

このステップはオプションです。デバイスを操作するためにコマンドを使用する場合や、メッセージサイズを小さくするために観測値を送信するときに属性識別子を減らすマッピングを定義する場合にのみ必要です。ただし、デバイスがプロビジョニングされていない場合は、コンフィグレーション・グループを設定する必要があります。

単に観測結果を送信したい場合は、これをスキップして"観測結果を送信"セクションを参照ください。

UL2.0 への登録

このサンプルでは、UL2.0 プロトコルと PING コマンドを使用して温度の観測結果を送信するためのデバイスが登録されています :

POST /iot/devices?protocol=IoTA-UL
Content-Type: application/json
X-Auth-Token: [TOKEN]
Fiware-Service: OpenIoT
Fiware-ServicePath: /

{
    "devices": [{
        "device_id": "[DEV_ID]",
        "entity_name": "[ENTITY_ID]",
        "entity_type": "thing",
        "timezone": "Europe/Madrid",
        "endpoint": "http://[DEVICE_IP]:[PORT]",
        "attributes": [{
            "object_id": "t",
            "name": "temperature",
            "type": "int"
        }],
        "commands": [{
            "name": "ping",
            "type": "command",
            "value": "[Dev_ID]@ping|%s"
        }],
        "static_attributes": [{
            "name": "att_name",
            "type": "string",
            "value": "value"
        }]
    }]
}

パラメータの説明。必須パラメータは"(必須)"とマークされ、残りはオプションです :

• device_id : デバイス識別子(必須)
• entity_name : ContextBrokerで使用されるエンティティ ID
• entity_type : ContextBroker 内のデバイスを表すエンティティ型
• protocol : デバイスがプラットフォームと通信するために使用するサウスバウンド・プロトコル(必須)
• timezone : デバイスのタイムゾーン
• endpoint : HTTP コマンドを受け付けるデバイスの場合、コマンドが送信されるデバイスのアドレス
• attributes : UL2.0 属性をデバイスを表すエンティティのContextBroker属性にマップするために使用
• commands : デバイスがサポートするコマンドを示すために使用します。HTTP属性の場合、"endpoint" 属性が必要です
• static_attributes : この属性の内容は、エンティティの属性としてすべての観測で送信

MQTTへの登録

次の例は、HTTP ではなく MQTT デバイスの同様の登録を示しています :

POST /iot/devices?protocol=IoTA-UL
Content-Type: application/json
X-Auth-Token: [TOKEN]
Fiware-Service: OpenIoT
Fiware-ServicePath: /

{
    "devices": [{
        "device_id": "[DEV_ID]",
        "entity_name": "[ENTITY_ID]",
        "entity_type": "thing",
        "timezone": "Europe/Madrid",
        "attributes": [{
            "object_id": "t",
            "name": "temperature",
            "type": "int"
        }],
        "commands": [{
            "name": "ping",
            "type": "command",
            "value": "[Dev_ID]@ping|%s"
        }],
        "static_attributes": [{
            "name": "att_name",
            "type": "string",
            "value": "value"
        }]
    }]
}

この例では、両方のプロビジョニングの唯一の違いは"endpoint" 属性の有無です。コマンドを受信しないデバイスの場合、後のプロビジョニング要求は両方のトランスポートプロトコルに対して有効です。

観測結果を送信¶

現在、プラットフォームで利用可能な2つのIoT Agentsがあり、それぞれが異なるプロトコルでリクエストをリッスンします : Ultralight 2.0 と JSON。いずれの場合も、MQTT と HTTP という2つの異なるトランスポート・プロトコルを使用して、ペイロードをエージェントに送信できます。以下のセクションでは、4つの可能なアプローチのそれぞれの例をいくつか示します。

適切な IoTAgent を選択するには、IoTA-UL または IoTA-JSON のクエリパラメータで宣言されたプロトコルを変更します。

UL2.0 HTTP を使用して測定値を送信

Ultralight2.0 (UL2.0) はSensorML (SML) 規格の提案された簡素化であり、ContextBroker にデバイス測定値(観測結果)を送信するために使用されます。この例では、シンプルさのために Ultralight2.0 が選択されています。

IoT デバイスからの観測結果の送信は、次の HTTP POST 要求で容易にできます :

POST /iot/d?k=<apikey>&i=<device_ID>
Content-Type: text/plain

t|25

前の例は、IoT Agent によって自動的に ContextBroker の対応するエンティティに送信される Temperature 属性の更新を送信します。

パイプ|で値を分離して、単一の観測結果に対する複数の測定値を送ることができます :

POST /iot/d?k=<apikey>&i=<device_ID>
Content-Type: text/plain

t|25|h|42|l|1299

次のペイロードで複数の観測結果を同じメッセージで送信することもできます :

POST /iot/d?k=<apikey>&i=<device_ID>
Content-Type: text/plain

t|23#h|80#l|95#m|Quiet

最後に、IoT デバイスをこの方法で接続した後で、ユーザまたは適切なアクセス権を持つ他の開発者が Data API を使用してデバイスに割り当てられた NGSIエンティティを読み取るか、管理ポータルでデータを参照できます。

UL2.0 MQTT を使用して測定値を送信

サービスの下で一度プロビジョニングされたデバイスは、MQTT メッセージを IoTAgent にパブリッシュできます。これらのメッセージにはそれぞれ1つの情報が含まれています。つまり、1つのメッセージが ContexBroker ドメインの1つの単一のエンティティに変換されます。情報は、典型的にはセンサの測定値とすることができます。

これは、デバイスによって使用されるトピック階層です :

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

ここで:

• "api-key" : サービスごとに固有値です。プロビジョニング API によって提供されます
• "device-id" : 通常、センサidです。 "api-key"ごとにユニークでなければなりません
• "attrName" : 測定される大きさの名前です(name of the magnitude being measured)。たとえば、温度、圧力など。これはContextBrokerに公開されている属性の名前です

例 :

$ mosquitto_pub -h $HOST_IOTAGENT_MQTT -u theUser -P thePassword -t /<api_key>/mydevicemqtt/t -m 44.4

この例で気づくように、MQTTブローカは一連の資格情報を使用してユーザを認証します。あなたの資格情報がわからない場合は、サポートチームに新しいセットを提供するよう依頼してください。

別のシナリオは、デバイスがペイロード内に複数の現象を送信する場合に発生する可能性があります。すなわち、1つのMQTTメッセージがすべての測定値を運びます。ContextBrokerの場合、デバイスごとに1つのエンティティ・パブリケーションが存在しますが、mqttメッセージに含まれる測定値ごとに異なる属性をすべて含みます。各現象または測定値は別の属性になります。IoT Agent の情報を解析できるようにするには、デバイスは HTTP の場合と同じ Ultralight 2.0 形式に従う必要があります。

トピック:

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

例:

$ mosquitto_pub -h $HOST_IOTAGENT_MQTT -u theUser -P thePassword -t /<api_key>/mydevicemqtt/attrs -m "t|5.4#o|4.3#n|3.2#c|2.1"

JSON HTTPを使用して測定を送信

JSON IoT Agent で使用される単純な JSONプロトコル は、各測定値を JSON オブジェクトの属性にマップします。次の例は、3つの異なる量の測定値を送信する方法を示しています :

POST  /iot/json?k=<apikey>&i=<device_ID>
Content-type: application/json

{
    "t": 5.4,
    "o": 4.3,
    "n": 3.2,
    "c": 2.1
}

JSON プロトコルの HTTP 転送では、単一の測定値構文は使用できません。

JSON MQTT を使用して測定を送信

IoT Agent の MQTT トランスポートで使用するペイロードは、HTTP バージョンで使用されているペイロードとまったく同じです。両方のアプローチの主な違いは、測定値を送信しているデバイスの DeviceID と、そのデバイスに関連付けられているサービスの APIKey を指定する方法です。MQTT トランスポートの場合、両方の情報が MQTT トピックで指定されます。例で説明します。

MQTT トランスポートには、単一の測定レポートと複数の測定レポートの2種類の測定レポートがあります。例は、mosquitto_pub 文として示されています。

単一の測定の場合、測定の値はメッセージ・ペイロードとして送信されます。これは、次の例に示すように、MQTT トピックに限定された更新に必要な残りの情報です :

$ mosquitto_pub -h $HOST_IOTAGENT_MQTT -u theUser -P thePassword -t /<myapikey>/<mydevicemqtt>/attrs/<measurename> -m '5.4'

$ mosquitto_pub -h $HOST_IOTAGENT_MQTT -u theUser -P thePassword -t /<myapikey>/<mydevicemqtt>/attrs -m '{ "t": 5.4, "o": 4.3, "n": 3.2, "c": 2.1 }'

<apiKey>/<deviceId>/cmd

<apiKey>/<deviceId>/cmdexe

<device name>@<command name>|<command value>

Robot1@turn|left

weatherStation167@ping|param1:1|param2:2

<device name>@<command name>|result

weatherStation167@ping|Ping ok