プラットフォームへのデバイス接続のクイックスタート (Ultralight 2.0)¶
概要¶
デバイスは、IoT Agent コンポーネントを介して、センサに関する情報を送信したり、情報やコマンドを受け取ったりするために、プラットフォームに接続することができます。デバイスを接続する具体的な方法は、デバイスの機能と利用可能なプロトコルによって異なります。
現在のバージョンのプラットフォームは、Ultralight 2.0とJSONという2つのプロトコルをサポートしています。このドキュメントでは、1つのデバイスをプラットフォームに接続してデータを送信し、プラットフォームからデータを受信する方法を示します。
デバイスをプラットフォームに接続すると、Context Broker で利用可能なデバイスに関するすべての情報を含む単一のコンテキスト・エンティティが作成されますｎ。デバイスとのインタラクションは、常にこのエンティティを介した操作を通じて送られます。
Device APIs の詳細については、Device API のセクション を参照してください。各特定のプロトコル仕様へのリンクやその他の使用情報は、デバイス・ゲートウェイのセクション で確認できます。
この例では、SmartCity アプリケーションを設計していると仮定します。SmartCity アプリケーションは、ガーデニング・サービスにいくつかの異なるデバイスを使用します。この範囲では、smarttown と呼ばれるサービスと、/gardens と呼ばれるサブサービスが作成されたと仮定します。プラットフォームへのすべての要求には、ここで説明するように、適切な Fiware-servicepath と Fiware-service とヘッダーが含まれます。
測定をプラットフォームに送信¶
APIKey とプロトコルの設定¶
デバイスがサブサービスの情報を送信するには、構成グループを作成する必要があります。この構成グループは、デバイスが使用するプロトコルと、デバイスがその特定のグループに属することを識別するために使用される APIKey を指定します。
次のリクエストにより、サブサービス用に必要なグループが作成されます :
POST /iot/services
Content-Type: application/json
Fiware-service: smartown
Fiware-servicepath: /gardens
{
"services": [
{
"protocol": [
"IoTA-UL"
],
"apikey": "801230BJKL23Y9090DSFL123HJK09H324HV8732",
"entity_type": "Device"
}
]
}この要求は、デバイスを表すコンテキスト・エンティティのデフォルト型が "Device" であり、デバイスに使用するプロトコルが Ultralight 2.0 であることを指定します。
デバイスのプロビジョニング¶
次のステップは、デバイスをプラットフォームにプロビジョニングすることです。この例では、2つのセンサ、湿度センサ、および温度計を備えた気象ステーションを1台提供します。また、このプロビジョニングを使用して、エンティティのために静的な情報を追加することもできます。この情報は、デバイス自体では報告する必要はありませんが、エンティティ自体に表示する必要があります。例として、気象ステーションのリファレンスとその位置を静的に規定します。
プラットフォームにデバイスをプロビジョニングするために、IoT Agentに対して次の要求を出します :
POST /iot/devices
Content-Type: application/json
Fiware-service: smartown
Fiware-servicepath: /gardens
{
"devices": [
{
"device_id": "ws1956672",
"protocol": "IoTA-UL",
"entity_name": "WeatherStation1",
"entity_type": "Device",
"attributes": [
{
"object_id": "t",
"name": "temperature",
"type": "degrees"
},
{
"object_id": "h",
"name": "humidity",
"type": "percentage"
}
],
"commands": [
{
"name": "configuration",
"type": "command"
}
],
"static_attributes": [
{
"name": "location",
"type": "geo:point",
"value": "40.392, -3.759"
},
{
"name": "reference",
"type": "string",
"value": "917834508965243"
}
]
}
]
}これは、ws1956672 ワークステーションをシステムにプロビジョニングし、測定を受信する準備をします。
測定を送信¶
プラットフォームに測定値を送信するには、デバイスが次の要件を満たしている必要があります :
- プラットフォームのサウスバウンドへの接続性。つまり、物理デバイスとプラットフォームとの通信に使用されるポート
- MQTT または HTTP クライアント。現在サポートされているトランスポート・プロトコルのようなもの
最も一般的な制約デバイスには、リクエストをプラットフォームに送信できる HTTP クライアントがあると想定します。このプラットフォームとのやりとりは、デバイスがサポートしているプログラミング言語で実装できます。現時点では、サウスバウンドのインタラクションには SDK は提供されていません。
この場合、気象ステーションからの典型的な測定値レポートは、次のようなリクエストで構成されます :
POST /iot/d?k=801230BJKL23Y9090DSFL123HJK09H324HV8732&i=ws1956672
Content-Type: text/plain
t|22|h|78このリクエストにはいくつか気がつくはずです :
-
まず、パスは '/iot/d'です。通知パスは、使用されるプロトコルによって異なります。このパスは、Ultralight 2.0 プロトコルに割り当てられているパスです
-
また、クエリパラメータは、最初のセクションで定義された API キーと、前のセクションで定義されたデバイス ID を示します
-
リクエストのペイロードには、バーで区切られた測定値が含まれています。測定値を報告するために使用される属性の名前は、デバイスプロビジョニングの
object_id属性で定義されたものです -
Content-Typeヘッダは必須で、値text/plainを有していなければならない
すべてが OK であれば、システムは 200 OK コードと空のレスポンスを返します。
この測定値は、Context Broker(NGSIv1)の次のような コンテキスト・エンティティ を生成します :
{
"type": "Device",
"isPattern": "false",
"id": "WeatherStation1",
"attributes": [
{
"name": "temperature",
"type": "degrees",
"value": "22"
},
{
"name": "humidity",
"type": "percentage",
"value": "78"
},
{
"name": "location",
"type": "geo:point",
"value": "40.392, -3.759"
},
{
"name": "reference",
"type": "string",
"value": "917834508965243"
}
]
}NGSIv2 形式の同じエンティティでは :
{
"type": "Device",
"id": "WeatherStation1",
"temperature": {
"type": "degrees",
"value": "22"
},
"humidity": {
"type": "percentage",
"value": "78"
},
"location": {
"type": "geo:point",
"value": "40.392, -3.759"
},
"reference": {
"type": "string",
"value": "917834508965243"
}
}コマンドの送信¶
プラットフォームはデバイスがプラットフォームからコマンドまたは情報を受信する機会も提供します。この点を説明するために、デバイスにポーリング・コマンドを使用してコンフィギュレーション情報を送信する方法を示します。つまり、デバイスをオンラインにする必要はありませんが、デバイスがプラットフォームに接続するときに取得されるコマンドです。
コマンドはデバイス・プロビジョニングでも定義されています。上記のプロビジョニングの commands セクションのプロビジョニング・ペイロードのセクションで確認できます。
コマンドを実行するための情報は、デバイスを表すコンテキスト・エンティティを直接更新するかのように、NGSI クエリを使用してContext Broker に送信されます。一例として、次のリクエストとともに openUmbrella: false 設定オーダーを送信します :
PUT /v2/entities
Content-Type: application/json
Fiware-service: smartown
Fiware-servicepath: /gardens
{
"id": "WeatherStation1",
"type": "Device",
"configuration": {
"type" : "command",
"value" : "openUmbrella: false"
}
}このリクエストは、デバイスがそれを検索するのを待つ値 openUmbrella:false と共にコマンド configuration を格納します。
デバイスは、次の例のように、クエリパラメータ getCmd=1 を使用して、新しい測定値を送信するたびにシステムから保留中のすべてのコマンドを取得できます :
POST /iot/d?k=801230BJKL23Y9090DSFL123HJK09H324HV8732&i=ws1956672&getCmd=1
Content-Type: text/plain
t|27|h|89これまでの測定レポートとは異なり、空のペイロードでは返されませんが、保留中のすべてのコマンドのリストが次のように表示されます :
200 OK
ws1956672@configuration|openUmbrella: falseここでは、最初に Context Broker に送信した設定値を見ることができます。ご覧のとおり、値には検証のために以前にプロビジョニングされたデバイスIDが含まれています。
このドキュメントに記載されているように、ポーリングコマンドには有効期限があることを考慮に入れると、デバイスが妥当な時間内に使用可能なコマンドを取得しなければ、それらは破棄されます。コマンドの有効期限はプラットフォーム全体で定義されています。現在は1日に設定されています。
デバイスに送信されるコマンドの状態を追跡するために、IoT Agents はデバイス・エンティティに一連の追加の属性を作成します。これにより、ユーザはコマンドの現在の状態を確認でき、存在する場合はコマンドの結果を確認できます。追加の属性を持つコンテキスト・エンティティは、次のようになります (NGSIv1) :
{
"type": "Device",
"isPattern": "false",
"id": "WeatherStation1",
"attributes": [
{
"name": "temperature",
"type": "degrees",
"value": "22"
},
{
"name": "humidity",
"type": "percentage",
"value": "78"
},
{
"name": "location",
"type": "geo:point",
"value": "40.392, -3.759"
},
{
"name": "reference",
"type": "string",
"value": "917834508965243"
},
{
"name": "configuration_status",
"type": "commandStatus",
"value": "PENDING"
},
{
"name": "configuration_info",
"type": "commandResult",
"value": " "
}
]
}NGSIv2 形式の同じエンティティでは :
{
"type": "Device",
"id": "WeatherStation1",
"temperature": {
"type": "degrees",
"value": "22"
},
"humidity": {
"type": "percentage",
"value": "78"
},
"location": {
"type": "geo:point",
"value": "40.392, -3.759"
},
"reference": {
"type": "string",
"value": "917834508965243"
},
"configuration_status": {
"type": "commandStatus",
"value": "PENDING"
},
"configuration_info": {
"type": "commandResult",
"value": " "
}
}追加の属性は、元のコマンドと同じ名前で、_status プレフィックス (stauts 属性の場合)と、_infoサフィック (結果の場合)を持ちます。コマンドの可能な状態値は、ERROR, EXPIRED, PENDING, OKです。