OMA Lightweight M2M IoT Agent : ユーザ＆開発ガイド

目次

概要

Lightweight M2M IoT Agent は、OMA NGSI プロトコルのブリッジを FIWARE コンポーネント (OMA NGSI)用の内部プロトコルと組み合わせて実装する、標準の FIWARE IoT Agent です。この IoT Agent は、パブリックの Node.js IoT Agent Library に基づいています。ここで、IoT Agent とその API について詳細な情報を提供しています。

そして、このプロジェクトは、2つの API を持っています :

  • サウス・バウンド (LWM2M) : この情報は、OMA Lightweight M2M の公式ページに記載されています。すでにサポートされている Lightweight M2M のサブセットに関する情報は、使用している LWM2M Library for Node.js にあります。
  • North Bound Administration API : すべての IoT Agent は1つの管理 API を共有しており、Node.JS IoT Agent Library Documentation のドキュメントにあります。
  • Northbound NGSI API : ノース・バウンド NGSI マッピングに関する情報は、同じ Node.JS IOTA Libr ary documentation にあります。

例と詳細な情報は、"はじめに" をご覧ください。

はじめに

このドキュメントは、さまざまなタイプの構成でエージェントを使用する方法の簡単なステップ・バイ・ステップの例を示すための ハウツー のセットをリンクしています。これらの設定オプションは互いに排他的ではないことに注意することが重要です. IoT Agent は、いくつかのデバイスを事前にプロビジョニングし、いくつかの設定グループを定義し、いくつかのスタティックな設定をそれぞれ異なるタイプのデバイスに割り当てることができます。

ガイドの中には、以下の特徴を持つ Robot と呼ばれる偽のデバイスタイプの使用を共有するものもあります :

  • サービス Factory と サブサービス /robots の一部になります
  • LWM2M リソース ID /7392/0/1 にマップされた、number タイプの Battery というアクティブな属性を持っています
  • LWM2M リソース ID /7392/0/2 にマップされた、string タイプの Message と呼ばれるパッシブ属性があります
  • LWM2M リソース ID /7392/0/3 にマップされた、location タイプの Position というコマンド属性があります

いくつかのガイドでは、WeatherBaloon タイプの偽装されたデバイスを使用して、次の特性を持つ自動の OMA レジストリマッピングの使用を示します :

  • サービス Weather とサブサービス /baloons の一部になります
  • リソース ID /6/0/0 を持つパッシブ属性 (位置：経度)
  • リソース ID /6/0/1 を持つパッシブ属性 (位置：緯度)
  • リソース ID /3303/0/0 を持つパッシブ属性 (温度センサ)
  • リソース ID /3312/0/0 を持つアクティブな属性 (電源制御)

各ガイドには、その内容に関する簡単な説明が表示されます :

  • デバイス・プロビジョニング・ガイド : このガイドでは、IoT Agent の設定、起動、使用方法、測定値を送信する前の各デバイスをプロビジョニングについて示します
  • 設定プロビジョニング・ガイド : このガイドでは、エージェントに登録するときに自動プロビジョニングされるようにデバイスのグループを設定する方法を示します
  • スタティック構成ガイド : このガイドでは、着信デバイスをスタティックに構成された異なるタイプにマッピングするスタティック・ルートを設定する方法を示します

テスト

IoT Agent には、主な機能をチェックするためのテストスイートが付属しています。テストスイートを実行するには、Grunt クライアントをインストールしておく必要があります。次のコマンドを使用してインストールできます。root権限が必要です :

npm install -g grunt-cli
クライアントがインストールされ、依存関係がダウンロードされたら、以下を使用してテストを実行できます : 
grunt
これにより、機能テストと構文チェックも実行されます。

注意 : これはエンド・ツー・エンドのテストなので、コンポーネントの実際のインスタンスに対して実行されます。実際の Context Broker が config.js に設定されていることを確認してください。このテストでは、実行前と実行後にデータベースをクリーンアップするので、このテストをプロダクションのマシンで実行しないでください。

開発

プロジェクトビルド

プロジェクトは Grunt Task Runner を使用して管理されます。

使用可能なタスクのリストについては、次のように入力します : 

grunt --help

次のセクションでは、使用可能なオプションについて詳しく説明します。

コントリビューション・ガイドライン

概要

オープンソースプロジェクトのため、次の点を尊重するなら誰もが貢献できます :

  • コードを投稿する前に、著者はすべてのテストが確実に行われるようにする必要があります。下記のテストの起動方法を参照してください
  • 開発されたコードは、linters によって強制される構文ガイドラインに従わなければなりません
  • コードは、以下に定義する分岐モデルと変更ログのポリシーに従って開発する必要があります
  • 新しい機能が追加された場合は、既に作成されたサンプルの例に従って、ユニットテストを提供する必要があります

コントリビューションを開始するには :

1. リポジトリをフォークするには、ページの右上にある "Fork" ボタンをクリックします
2. フォークされたリポジトリをクローン :

git clone https://github.com/your-github-username/lightweightm2m-iotagent.git
3. lightweightm2m-iotagent のメインのリポジトリをリモートとしてリポジトリに追加すると、リモート・リポジトリの名前を使用できますが、lightweightm2m-iotagent である必要はありません。次の手順で使用します :
git remote add lightweightm2m-iotagent https://github.com/telefonicaid/lightweightm2m-iotagent.git

コントリビューションを開始する前に、フォークされたリポジトリ内の develop ブランチと、lightweightm2m-iotagent メインリポジトリ内の develop ブランチを、この手順に従って同期させてください。

1. 開発ブランチにいない場合に備えて、ローカルの develop ブランチに変更します : 

  git checkout develop
2. リモートの変更を取得します :
  git fetch lightweightm2m-iotagent
3. それらをマージします :
  git rebase lightweightm2m-iotagent/develop

このガイドラインに従ったコントリビューションは develop ブランチに追加され、次のバージョンでリリースされます。リリース・プロセスについては、下記のリリースのセクションで説明しています。

ブランチ・モデル

リポジトリには2つの特別なブランチがあります :

  • master : プロジェクトの最後の安定版のコードを保持します。新しいバージョンがリリースされたときにのみ更新され、常に develop の最新の状態で更新されます
  • develop : 最後の安定した開発コードが含まれています。新機能とバグ修正は常に develop にマージされます

新しい機能やリファクタリングの開発を開始するには、task/<taskName> の名前を持つ新しいブランチを作成する必要があります。このブランチは、develop ブランチの現在のバージョンから作成する必要があります。新しい機能が完了すると、develop に機能分岐からプルリクエストが作成されます。プルリクエストを作成する前に、linters とテストの両方をチェックすることを忘れないでください。

バグ修正は、bug/<bugName> と呼ばれるブランチ名を除いて、他のタスクと同じように機能します。

リポジトリに貢献するためには、これらの同じスキームを分岐したリポジトリに複製する必要があります。そのため、新しい機能や修正は、すべて develop の最新のバージョンから取得して、develop に再度マージする必要があります。

すべての task/* と bug/* ブランチは一時的なものなので、マージされたら削除する必要があります。

release/<versionNumber> という別の一連のブランチがあり、製品の各バージョンごとに1つあります。この分岐は、プロジェクトのリリースされた各バージョンを指し、永続的でリリースごとに作成されます。

チェンジ・ログ

プロジェクトには、プロジェクトのルートにある CHANGES_NEXT_RELEASE というバージョンの変更履歴が含まれています。新しい機能やバグフィックスが develop にマージされるたびに、この変更ログに新しいエントリを追加する必要があります。新しいエントリには、解決している問題のリファレンス番号(存在する場合)が含まれているはずです。

新しいバージョンがリリースされると、変更履歴がクリアされ、そのバージョンの最後のコミット時に修正されたままになります。変更履歴の内容は、Github release のリリースの説明にも移動されます。

リリース

リリースを行うプロセスは、次の手順で構成されます :

1. 新しいタスクブランチを作成して、sufix-next を持つ、package.json内の開発バージョン番号を、sufix なしの新しいターゲットバージョンに変更し、PRを develop に変更します
2. バージョン番号で指定された develop の最終バージョンからタグを作成し、それをリポジトリにプッシュします
3.作成したタグから Github でリリースを作成します。 この説明では、変更履歴の内容を追加します
4. バージョン番号で指定された develop の最終バージョンからリリース・ブランチを作成します
5. develop を master にPR
6. 次のリリースを準備するための新しいタスクを作成し、現在のバージョン番号にサフィックス -next を追加して、これを開発バージョンとして通知します

テスト

前提条件

このコンポーネントテストは、いくつかのソフトウェア要件が実行される エンド・ツー・エンドのテストであることに注意することが重要です。この要件は次のとおりです :

  • localhost で実行している MongoDB インスタンス
  • testConfig.js で構成された場所で実行されている Orion Context Broker のインスタンスです。デフォルトは別名 oriondb です
  • このインスタンスは、Grunt テスターからの接続に対して 1026 と 27017 のポートをオープンしている必要があります

ライブラリ

Mocha Test Runner + Chai Assertion Library + Sinon Spies, stubs.

テスト環境は、テストの実行中にグローバルに使用できる chai.expect と `chai.should()' を使用して、BDD のテスト・スタイルを実行するように事前設定されています。また、Sinon-Chai プラグインも使用できます。

proxyquire でテスト中のモジュールのモックを行うことができます

実行

テストを実行するには、次のように入力します : 

grunt test

テストレポートは、Jenkins と一緒に使用して、TAP または XUnit プラグインを使用してプロジェクト品質メトリックを監視することができます。report/test/unit_tests.tap に TAP レポートを生成するには、次のように入力します : 

grunt test-report

コーディング・ガイドライン

提供された .jshintrc と .gjslintrc フラグファイルを使用します。後者は Python を必要とし、grunt-init を使用してプロジェクト・スケルトンを作成する際に、その使用を無効にすることができます。ソースコードのスタイルを確認するには : 

grunt lint

Checkstyle レポートは Jenkins と一緒に使用して、Checkstyle プラグインと Violations プラグインを使用してプロジェクトの品質メトリックを監視することができます。report/lint/ で Checkstyle と JSLint のレポートを生成するには、次のように入力します : 

grunt lint-report

継続的なテスト

src ファイルまたはテストを変更して、継続的なテストをサポートします。連続テストの場合は : 

grunt watch

ソースコードのドキュメント

HTML ドキュメントを site/doc/ 下に生成します。DocLinks プラグインを使用して、jenkins と一緒に使用できます。ソースコードのドキュメントをコンパイルするには、以下を入力します : 

grunt doc

コード・カバレッジ

テストのコード・カバレッジを分析します。

HTML カバレッジレポートをsite/coverage/ 下に生成し、サマリを出力するには、次のように入力します : 

# Use git-bash on Windows
grunt coverage

Cobertura プラグインを使用して Jenkins と一緒にプロジェクトの品質メトリクスを監視するために使用できる Cobertura レポートを report/coverage/cobertura-coverage.xml に生成するには、次のように入力します : 

# Use git-bash on Windows
grunt coverage-report

コードの複雑さ

Plato を使用してコードの複雑さを分析し、そのレポートを site/report/ 下に保存します。DocLinks プラグインを使用して jenkins と一緒に使用できます。複雑さのレポートには、次のように入力します : 

grunt complexity