FESTIVAL実験参加者のための対話的ユーザーガイド

このユーザーガイドはFESTIVAL実験ポータルを知ろうとする実験参加者のために作成されています。

ここからPDF版がダウンロードできます: Userguide (v1.3)(英語).


実験の流れ

もしまだFESTIVALプラットフォームのアカウントを作成していない場合、最初にアカウントを作成してください。作成したアカウントは実験ポータルへのアクセスに使用します。電子メールアドレスとパスワードはのちほどプラットフォームの利用認証のために使用されます。
アカウントを作成するとFESTIVALプラットフォームの機能への以下のようなアクセスが可能になります:

  • APIを直接使用してプログラムにより実験を実施する。
  • ポータルを使用してリソースを探索し実験を作成する。

実験ポータルはリソースの探索と実験の作成・管理のより簡易な手段を提供し、EaaS APIは高度な実験のためのより複雑な作業の実施を可能にします。たとえばEaaS API上に専用のアプリケーションを作成することも可能です。
このプラットフォームを利用した実験は以下のようにいくつかの段階で実行されます:

  • 最初の段階は実験の作成です。この段階ではユーザーは実験を作成し、その詳細を記述します。
  • 第2段階はリソースの探索です。ユーザーは見つけられる限りの適切なリソースを実験に追加できます。
  • リソースの選択が完了すると、実験が開始できます。リソース(例えばアクチュエーターやVM)を実験期間中確保しておくため、この第2段階は重要です。
  • 実験の実施中、実験参加者をサポートするためFESTIVALプラットフォームはいくつかのツールを提供します。一例として、実験結果の収集ツールがあり、実験参加者はOMLライブラリーを利用して有用なデータを収集することができます。
  • また、実験期間を含む実験の詳細を変更することも可能です。ただし、プラットフォームにアクセスする他の実験参加者の状況に依存します。
  • 最後に、実験は以下の2つの状況で終了となります:
    • 定められた実験期間が終了し延長しなかった場合。この場合、FESTIVALプラットフォームは最終日の少なくとも1週間前までに通知を行います。
    • 実験が完了しユーザーが終了を望む場合。この場合、ユーザーはポータルまたはEaaS APIを通じて実験を停止することが可能です。

実験ポータル

実験ポータルはFESTIVALプラットフォームのユーザーのためのwebアプリケーションで、プラットフォームの機能を提供します。FESTIVALプロジェクトが実験参加者に提供している多くのリソース(センサー、仮想マシン、オープンデータなど)は、実験ポータルから利用できます。
実験者の視点から見ると、ポータルは標準のWebブラウザで動作するwebアプリケーションです。レスポンシブデザインにより、例えばタブレットなどの他のデバイスから利用することもできます。
最初のステップとして、ポータルを使いたい実験参加者はアカウントを作成する必要があります。アカウントを作成し、ログインすると、実験参加者はリソースの閲覧、リソースの検索、実験の作成ができるようになります。実験を作成すると、実験期間中にリソースを割り当てられるようになります。また、実験を開始するとそれらを利用できるようになります。

実験ポータルの機能の詳細については、以下のセクションをクリックしてください。 [bg_faq_start]

セキュリティ: アカウントの作成とログイン

FESTIVALプラットフォームのアカウントは、実験ポータルで作成します。そのための特定のウェブページがあります。実験ポータルのメインページにアクセスすると、ログインページにリダイレクトされます。アカウントを持っていない場合はアカウントを作成します。アカウントを作成するには、実験参加者はフルネーム、電子メールアドレス(ログインしたりトークンを取得したりするために使用します)、パスワードを入力する必要があります。新しいアカウントが作成されると、実験ポータルは公開鍵、秘密鍵を表示します。秘密鍵はSSH接続で仮想マシンなど のITリソースにアクセスするときに必要になります。SSH接続の認証は公開鍵/秘密鍵方式で行います。プライバシーとセキュリティのため、プラットフォームは公開鍵のみを保持します。そのため、プラットフォームを利用するためには、これらの鍵をダウンロードする必要があります。実験参加者は、これらの鍵をローカルコンピュータに保存し、使用しているSSHクライアントで利用できるようにしておく必要があります。
登録が終了すると、ユーザーは登録に使用した資格情報を使用してポータルにログインし、リソースを検索したり実験を作成したりすることができるようになります。ただし、実験の作成には”expert”ロールが必要です。[bg_faq_end][bg_faq_start]

実験の作成

実験の作成手順は簡単です。左側のメニューから”Experiment”ページに移動できます(このページには、HOMEページから移動することもできます)。このページから実験参加者は自分の実験にアクセスしたり、新しく実験を作成したりできます。
右側には、実験概況(number of running、created、stopped)の表があります。実験一覧には、各実験のタイトル、日付、ステータス、割り当てらえたリソースの数といった概要を示されます。また、”Detail”ボタン(詳細を編集します)、”Set as current”ボタン、”Delete”ボタンがあります。
“Set as current”ボタンをクリックすると、”Current experiment”ボタンがページの上部に現れ、実験にリソースを割り当てられるようになります。”Unset”ボタンをクリックすると、current experimentの指定を外すことができます。新たに実験を作成するには、”Create a new experiment”ボタンをクリックし、簡単なフォームに記入する必要があります。全項目(実験の名前、実験の説明、開始日、終了日)の入力が必須です。作成されると、実験一覧に追加され、リソースの割当が可能になります。
同時に4つまで実験を作成できます。[bg_faq_end][bg_faq_start]

リソースの閲覧

リソースの閲覧機能を使用して、実験参加者はFESTIVALリソースを検索できます。実験参加者は、まずFESTIVALプラットフォームのアグリゲータの一覧からアグリゲータを選択します。IoT、IT、リビングラボ、オープンデータという4つの異なるアグリゲータがあります。
次に、実験参加者はテストベットの一覧からテストベットを選択します。どのようなテストベットがあるかは、選択したアグリゲータによります。
最後に、実験参加者は選択したテストベットで利用可能なリソースにアクセスし、その詳細を閲覧できます。[bg_faq_end][bg_faq_start]

リソースの検索

リソースの検索機能を使用して、ユーザーはすべてのFESTIVALリソースの高度な検索ができます。Search resourcesページのナビゲーションでは、検索条件の入力用フォームは左側にあり、検索に使用できるすべての条件が表示されます。最初に、実験参加者はアグリゲータを指示し、検索を実行するテストベットを選択する必要があります。次に、地理的な位置と半径を指定できます。地理的な位置を指定すると、自動補完のしかけで指定位置と一致する場所を地図上に 示します。次のフィールドで、リソースのタイトル、説明、正規表現のキーワードを指定すると、より正確な結果を得られます。さらに、取得できた結果の並べ替えの順序を指定できます。
リソースを閲覧または検索した後、実験参加者は”Detail”ボタンをクリックして、リソースの詳細を参照できます。タイプ、テストベット、URL、地理的な位置、利用可能性、リソースに対して実行できるアクションなどです。[bg_faq_end][bg_faq_start]

リソースの割当

リソースを使うためには、実験参加者は、作成済みの実験にリソースの割当を行う必要があります。そのためには、まず実験を”current experiment”に設定します。そのためには、利用可能な実験リストの”set as current”ボタンをクリックします。ある実験が”current”に設定されると、オレンジ色のボタンがページ上部 に現れ、選択されている実験が表示されます。
これにより、リソースを閲覧したり検索したりするとき、実験参加者は現在の実験にリソースを割り当てられるようになります(また、割り当て済みリソースの削除もできるようになります)。いずれの場合も、現在の実験が更新され、それに応じて(割り当てられたリソースの新しい数を示すために)ページのヘッダー部分も更新されます。[bg_faq_end][bg_faq_start]

実験の開始

全ての必要なリソースを選択した後、実験参加者は実験を開始できます。実験のDetailページには、実験ステータス(created)と関連付けられたリソースの一覧が表示されます。実験参加者がStartボタンをクリックすると、プラットフォームは、実験に関連付けられたリソースを使えるようにするために必要な全ての手続きを実行します。この手続きを「リソース予約」と呼びます。このプロセスが終了すると、実験実行中となり、緑色の通知ボックスに手続きが正常に終了したことが表示され、実験ステータスがcreatedからrunningに変わります。
オープンデータリソース、ITリソース、およびIoTリソースの予約は完全に自動的に行われますが、リビングラボリソースの予約については、実験参加者とリビングラボの管理担当者が直接交渉する必要があります。リビングラボの活動には人間が関わるので、実験におけるリビングラボのすべての活動を決めるために交渉が不可欠です。
補足となりますが、実験に関連付けられたITリソース(つまり仮想マシン)は、実験開始前はVMテンプレートです。実験を開始すると、VMテンプレートは対応するインスタンスで置き換えられます。実験ステータスが変化(createdからrunningに変化)すると共に、実験に関連付けられたITリソースがテンプレートでなくインスタンスに変化します。
実験を開始すると、実験参加者は様々な方法でリソースにアクセスできるようになります。

  • オープンデータリソースおよびIoTリソースは、リソースのDetailページに表示されている情報(つまり、Current data URL)を使ってデータを取得できます。
  • リビングラボリソースは、他リソースとは異なる性質(サービス、専門知識、方法論、ステークホルダー)を持ち、リソースへのアクセスが特定の状況に依存するため、一定の方法を提供できません。実験参加者はリビングラボに連絡する必要があります。
  • ITリソースは、VMインスタンスが生成されると、ITリソースのDetailページに、VMに割り当てられたIPアドレスが表示されます(Resource URL parameter)。実験参加者は、実験ポータルへの登録フェーズの終わりにダウンロードした秘密鍵を使用して、SSHでこのIPアドレスに接続できます。

実験を開始すると、実験参加者は様々な方法でリソースにアクセスできるようになります。
実験実行中は、実験に必要なソフトウェアやツールを動作させるためにVMを使用できます。また、実験データ(例えば、センサーデータやネットワークデータなど)を収集するためにも使用できます。[bg_faq_end][bg_faq_start]

割り当てられたITリソース(仮想マシン)へのアクセス

実行中の実験に関連しているVMのResource URLには、VMのパブリックIPアドレスが示されています。このパブリックIPアドレスを使用して、VMにアクセスできます。

VMにアクセスするには、SSHコンソールを開き、実験ポータルでアカウントを作成した際にダウンロードした秘密鍵を使って認証します。

例えば、LinuxベースのOSを使用している場合は、sshコマンドで接続できます。
[code lang=bash]ssh -i /path/my-key-pair.pem IP_ADDRESS[/code]

FESTIVALプラットフォームが提供する秘密鍵はpem形式です。SSHコンソール用のプログラムがこの形式をサポートしていない場合、適切な形式に変換する必要があります。例えば、Putty (http://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html)は、ppk形式を使います。PuttyGenツールを使えば、pem形式のファイルをppk形式に変換できます。

鍵ファイルをppk形式に変換すると、PuttyのパラメータにVMのパブリックIPアドレス と秘密鍵設定できるようになります。

SSHコンソールが開いたら、ログインするためにVMのデフォルトユーザのユーザー名を入力します。これは実験者のユーザー名ではありません。通常、ユーザー名はVMにインストールされているOSによって異なります(例えば、Ubuntuベースのマシンの場合、ユーザー名はubuntuです)。


[bg_faq_end][bg_faq_start]

実験結果の収集

実験実行中は、ITアグリゲータが提供するテストベットのVMインスタンスから実験データの収集ができます。FESTIVALプラットフォームはVMインスタンスからアクセスできるOMLサーバーを提供しています。
正しく実験データを収集して実験に関連付けるには、OMLクライアントを適切に設定する必要があります。
公式に利用できるOMLクライアントとしては、OML4Py、OML4R、OML4J、OML4JS、OML4Nodeなどがあります。

さらに、ITアグリゲータのテストベットでは、NodeJS用のOML4NodeをベースにしたOMLクライアントのサンプルスクリプトを持つVMテンプレート(例 OMLCollectorVM – m1.small – Template(KHN))が提供されています。サンプルスクリプトには、OMLサーバーに接続したり、データを収集したりする方法についての説明があります。

特にスクリプトは、スクリプトを実行するための設定を行うセクションとデータを取得するリソースを設定するセクションから構成されています。

スクリプトは時間ベースのジョブスケジューラを使用しているので、最初のセクションではジョブスケジューラの設定ができます。

[code]// Change this parameter to schedule the job. (E.g. the value “* /30 * * * *” will run the job every 30 minutes).
var cronTime = “* * * * * *”;[/code]

2番目のセクションでは、データを取得するリソースの設定ができます。

[code]var resources = [

{resourceName:”HyogoTemp”, resourceUrl:”https://api.festival-project.eu/festival/eaas/experimentation/aggregators/IOT-0/testbeds/jose/resources/hyogo001_temperature-info-valueasfloat/current_data”},
{resourceName:”KyotoTemp”, resourceUrl:”https://api.festival-project.eu/festival/eaas/experimentation/aggregators/IOT-0/testbeds/jose/resources/kyoto001_temperature-info-valueasfloat/current_data”},
{resourceName:”HyogoHumidity”, resourceUrl:”https://api.festival-project.eu/festival/eaas/experimentation/aggregators/IOT-0/testbeds/jose/resources/hyogo001_humidity-info-valueasfloat/current_data”},
{resourceName:”KyotoHumidity”, resourceUrl:”https://api.festival-project.eu/festival/eaas/experimentation/aggregators/IOT-0/testbeds/jose/resources/kyoto001_humidity-info-valueasfloat/current_data”}

];[/code]

resources 配列の各要素は2つのフィールドから構成されています。

  • resourceName: スクリプト内でリソースを識別するために使用します(指定する名前は一意でなければなりません)。
  • resourceUrl: 特定のリソースの最新のデータを取得するためのURLです。resourceUrlには、リソースの現在のデータを取得するためのEaaS APIを指定します。そのため、認証が必要です。各リソースのURLは、実験ポータルのリソースの詳細ページの”Current data URL”フィールドに表示されます。

3番目のセクションでは、認証に使用するパラメータを設定できます。

[code]var userName = ‘john.doe@company.com’; // Your user name on Festival

var userPass = ‘john’; // Your user password on Festival[/code]

4番目のセクションでは、OMLサーバーに接続するためのパラメータの設定とデータを集めるための測定のスキーマの設定ができます。

[code]// OML Configuration

//omlAppName is the title of your measurement NOTE: blank spaces,upper case letter (A-Z)  and special chars (except “_”) are not allowed due to PostgreSQL restrictions

//Please see at https://www.postgresql.org/docs/9.3/static/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS

omlAppName = ‘data_collection’;
omlDomain = ‘experiment ID’;   // Your experiment ID; blank space are not allowed
omlHost = ‘festival.ckp.jp’; // Do not change it
omlPort = 1234; // Do not change it
omlCollect = ‘tcp:festival.ckp.jp:1234’; // Do not change it
omlMeasurementTitle = ‘hyogo_kyoto_temp_humidity’;
omlMeasurementSchema = [[‘hyogo_temp’, oml.T.double], [‘kyoto_temp’, oml.T.double], [‘hyogo_humidity’, oml.T.double], [‘kyoto_humidity’, oml.T.double]];[/code]

OMLの設定パラメータ:

  • omlAppName: 測定のタイトルを指定します。
  • omlDomain: experiment IDを指定します。
  • omlHost: OMLサーバーのホスト名を指定します。
  • omlPort: OMLサーバーのTCPポートを指定します。
  • omlCollect: OMLサーバーの完全なURLを指定します。
  • omlMeasurementTitle: OMLによって生成され、保存されるDBのテーブルのタイトルを指定します。
  • omlMeaturementSchema: 生成されるテーブルのスキーマを指定します。

omlHost、omlPort、およびomlCollectは変更しないでください。変更すると、測定値を収集できないようになります。

上記の設定項目は、別言語のOMLクライアントを使う場合も適切な設定のために考慮しなければならない項目です。各OMLクライアントは、収集したデータを保存するためのデータ収集スキーマを定義する独自のAPIを提供します。

スクリプトの5番目のセクションは、リソースからデータを集めOMLサーバーに測定値を保存するコードがあります。

[code]// ### HERE YOU CAN GET SENSOR DATA ###

var cronJob = cron.job(cronTime, function(){
var myResults = getResourceData();
var hyogoTemp = -1;
var kyotoTemp = -1
var hyogoHumidity = -1
var kyotoHumidity = -1
var hyogoTempData = getResource(myResults, “HyogoTemp”);
var kyotoTempData = getResource(myResults, “KyotoTemp”);
var hyogoHumidityData = getResource(myResults, “HyogoHumidity”);
var kyotoHumidityData = getResource(myResults, “KyotoHumidity”);
hyogoTemp = hyogoTempData.data.dataValue;
kyotoTemp = kyotoTempData.data.dataValue;
hyogoHumidity = hyogoHumidityData.data.dataValue;
kyotoHumidity = kyotoHumidityData.data.dataValue;

// Write data on OML

oml.init({appName: omlAppName,domain: omlDomain , host: omlHost, port: omlPort, collect: omlCollect});
var mp = oml.mp(omlMeasurementTitle, omlMeasurementSchema);
mp(hyogoTemp, kyotoTemp, hyogoHumidity, kyotoHumidity);

});[/code]

getResourceData関数は内部的に以下のメソッドを呼び出します。

  • getSecurityToken: userNameとuserPassを使用してトークンを取得します。
  • getData(token): resources配列に指定された全部のcurrenctDataを取得するためにEaaS APIリクエストを発行します。

測定値ごとにgetResource関数を呼び出して、収集したデータを一時変数(HyogoTemp、KyotoTempなど)に保存します。

最後に、Oml.init(…) を呼び出してOMLサーバーへ接続し、Oml.mp(…) により測定ポイントを生成し、OMLサーバーにデータを保存します。

OMLサーバーに集められた実験データは、実験ポータルの実験のDashboardで利用できます。[bg_faq_end][bg_faq_start]

実験結果の可視化

実験の実行中に集められたデータは、実験ポータルで表示できます。experiment detailページで、Dashboardボタンをクリックすると、MyExperiment-Dashboardセクション にアクセスできます。
このセクションには、実験に割り当てられたVMの一つで実行されたOMLクライアントから得られたすべての実験データが表示されます。実験参加者は各データを可視化できます。

  • 収集されたデータの型を示すschema
  • データの推移を表す折れ線グラフとデータの表

測定値を可視化するには、まず、見たいデータ範囲(期間)を指定し、Get Dataボタンをクリックします。
Measurementsパネルの右側にschemaパネルがあり、収集されたデータの名前とタイプが表示されます。グラフの下には収集された全データの表があります。実験参加者は、グラフのデータの一部をハイライトしたり、特定の値を示したりできます。
実験参加者は表示したい値を選択することにより、グラフの表示を変更できます。3つのデータのうち2つを選択し、Redrawボタンをクリックします。
[bg_faq_end][bg_faq_start]

実験の終了

以下2つの条件のうちのいずれかで、実験が終了します。

  • 実験者参加者が、ポータルのExperimentページでStopボタンをクリックしたとき。
  • 実験の作成時に設定した期限が切れ、破棄されたとき。

どちらの場合も、stopコマンドが実行され、プラットフォームは実験に割り当てられていたリソースを開放します。このプロセスが終了すると、実験が停止し、緑色の通知ボックス に手続きが正常に終了したことが表示されます。
ただし、リビングラボリソースの解放については、リソース予約手続きと同じく、他のリソースとは異なっています。そのリソースの解放は、自動的には行われず、実験参加者とリビングラボ管理担当者の合意が必要なためです。ITリソースについては、解放によってVMが削除されます。実験リソースの一覧からVMインスタンスが削除され、VMテンプレートが再び関連付けられます。
[bg_faq_end][bg_faq_start]

API の使用とトークンの取得

以下に示すように、FESTIVAL Experimentationポータルは、RESTful APIを提供しています。このAPIは実験でも使用可能です。ポータルが提供するすべての機能は、EaaS APIから利用できます。

EaaS APIは、以下のリンクから利用できます。すべてのメソッドがswaggerで提供されています:

http://tools.festival-project.eu/swagger-ui/#/default

APIに使用されるすべてのメソッドは、有効なトークンをヘッダーに設定する必要があります。以下の2つの方法のいずれかで、トークンを取得できます:

  • ポータルにログインし、一番上にあるtokenボタンをクリックします。その様子を次の図に示します。

  • セキュリティRest APIを使用してトークンを取得します。

長期にわたる実験の場合、こちらの方法をお薦めします。上記リンクには、以下のようにcurlコマンドを使用する方法が示されています。

[code]curl -X POST https://api.festival-project.eu/festival/eaas/security/token -H ‘content-type: application/json’ -d ‘{“email”:”test@test.com”,”password”: “************”}'[/code][bg_faq_end]

詳しくは、FESTIVAL成果報告書の D2.5 Integrated Reusable components for EaaS を参照してください。