ELmote® CLOUD

ELmote_CLOUD_horizontal

本ドキュメントは、IoT向けデータ基盤 ELmote® CLOUDに関するマニュアルである。




ELmote® CLOUDとは

ELmote® CLOUDは、IoTデバイスのデータを保存・検索するサービスである。基本サービスとして、

  • データ保存サービス: 特定のURLにHTTPリクエスト（POST）を発行することで、クラウドにデータを保存するサービス

  • データ検索サービス: クラウドに保存したデータについて、期間やタグで検索した結果を取得するサービス

を提供する。また、これらの上位機能として、ダッシュボードや警報のサービスを提供する。


準備

ELmote® CLOUDを利用するにあたり、

  • アカウントID
  • ユーザ名
  • 初期パスワード
  • 連絡先メールアドレス（パスワード変更時の通知先として利用）

が必要となる。アカウントID・ユーザ名は、サービス提供元から提供される。初期パスワードは、連絡先メールアドレス宛に以下のようなメールで通知される。

件名: 【重要】 ELmote® CLOUDからのお知らせ: パスワード初期化通知

 ELmote® CLOUDをご利用いただき、ありがとうございます。

このEメールはシステムから送信しています。
ELmote® CLOUDのパスワードを初期化しました。
新しいパスワードは以下です

xxxxxxxxxxxxxxxxx

ログイン後、パスワードを更新してください。

このEメールが間違って送信されたと思われる場合、サポートに連絡してください。

今後ともどうぞよろしくお願いいたします。


初回ログイン、パスワード変更

はじめに、パスワードを変更する。

login_0

サービス提供サイトのトップ画面で、アカウントID、ユーザ名、初期パスワードを入力する。

正しく入力できていれば、「Login」を押した後、パスワード変更画面に遷移する。

login_1

古いパスワード、新しいパスワードを入力し、「Change Password」を押下する。

パスワードは以下の条件を満たす必要がある。

  • 8文字以上32文字未満
  • 英数字
  • スペースを含んではいけない
  • 最低1文字以上の記号を含まなければいけない

「パスワード変更に成功しました。トップ画面から、再度ログインしてください。」というメッセージが表示されれば、パスワード変更に成功している。


パスワードが不明な場合

トップ画面から、パスワード変更画面に遷移する。

login_2

login_3

アカウント名、ユーザ名および連絡先メールアドレスを入力し、「Send Email」を押す。

入力が適切であれば、連絡先メールアドレスに仮パスワードが送信される。仮パスワードでログインすると、パスワード変更画面に遷移するので、新しいパスワードに変更する。


アカウント名、ユーザ名が不明な場合

サービス提供元（elmote-cloud[at]elspina.tech）に連絡いただきたい。




LoggerCore Service

LoggerCore Serviceは、IoTデータの保存・検索を提供する、 ELmote® CLOUDの基本サービスである。

APIKEY

APIKEYは、データ保存・検索する際に、リクエストヘッダに含める認証用キーである。初期状態では何も表示されていないが、画面内のリロードボタンをクリックするとキーを新たに発行する。

APIKEYは2つまで利用できる。注意として、APIKEYを更新すると、古いAPIKEYでの通信は利用できなくなるので、注意いただきたい。

loggercore_0




POST

データを保存する際はPOSTリクエストを発行する。サンプルは画面内に表示されている通りである。以下、画面内の説明と重複するが、サンプルと注意点を説明する。

loggercore_1


サンプル

$ curl -X POST \
    -H "authorization: < Your APIKEY >" \
    -H "data_identifier: < Your Data Identifier >" \
    -H "data_tag_1: < Your Data Tag >" \
    -d '{"key": "value"}' \
    https://api.elmotecloud.elspina.space/v1/api/lv3/core/endpoint
  • authorization (必須)　: APIKEYを指定する。1と2のどちらでもよい。
  • data_identifier (必須) : データ識別子（下記注意参照）を指定する。文字として、#（シャープ）と,（カンマ）は指定できない。
  • data_tag_1, data_tag_2, data_tag_3 (任意): データタグ（下記注意参照）を最大3つまで指定する。文字として、#（シャープ）と,（カンマ）は指定できない。


The Things Stackから、webhookでデータを送信する場合のイメージは以下である（Alert設定あり）。

ttn_webhook


注意点

データ識別子とデータタグ

データ識別子（data_identifier）は、データの一意的な識別子を想定する。データタグ（data_tag_1など）は、補足的な識別情報を想定する。これらは、データを検索する際の検索条件として利用する。

例えば、LoRaWANデバイスのデータを保存する場合、以下のような指定が考えられる。

  • data_identifier: device eui
  • data_tag_1, data_tag_2, data_tag_3: 設置場所、事業者、アプリケーション名など

データを保存する際、data_identifierが過去に保存した際のものと重複していても、特に問題にせずそのまま保存する。後述するデータ検索の際にdata_identifer指定で検索すると、期待しない挙動となる可能性があるので、data_identifierは一意的とすることを強く推奨する。

Note: 一度保存したデータは基本的に削除されないが、検索の際に時間指定することで、過去のデータを検索対象外とすることは可能である。




GET

データを検索する際はGETリクエストを発行する。データの検索は以下２ステップで実行する。

  1. データを検索するためのトークンを取得する
  2. 1で取得したトークンを使ってデータをダウンロードする

サンプルは画面内に表示されている通りである。以下、画面内の説明と重複するが、サンプルと注意点を説明する。


サンプル

loggercore_2

トークン取得

データ識別子指定の場合
$ curl -H "authorization: < Your APIKEY >" \
    -H "accountid: < Your Account ID >" \
    -H "username: < Your Username >" \
    https://api.elmotecloud.elspina.space/v1/api/lv3/core/endpoint/history/tokens?data_identifier=IDENTIFIER
  • authorization (必須) : APIKEYを指定する。1と2のどちらでもよい。
  • data_identifier(任意): データ識別子を指定する。
データタグ指定の場合
$ curl -H "authorization: < Your APIKEY >" \
    -H "accountid: < Your Account ID >" \
    -H "username: < Your Username >" \
    https://api.elmotecloud.elspina.space/v1/api/lv3/core/endpoint/history/tokens?data_tags=TAG1,TAG2
  • authorization (必須) : APIKEYを指定する。1と2のどちらでもよい。
  • data_tags(任意): データタグを指定する。複数指定する場合はカンマ区切りで与える。複数指定した場合、指定した全てのタグを含むデータを検索対象とするトークンを取得する。

なお、data_identifierとdata_tagsは、いずれか一方のみを指定しなければならない。

また、トークンには有効期限（1時間）が存在するので、必要に応じて適宜再ダウンロードすること。


データ取得

$ curl -H "authorization: < Your APIKEY >" \
    -H "accountid: < Your Account ID >" \
    -H "username: < Your Username >" \
    https://api.elmotecloud.elspina.space/v1/api/lv3/core/endpoint/history/data?token=TOKEN&include_from=0&include_to=100&exclude_from=10&exclude_to=90

  • token (必須) : APIからダウンロードしたトークン。

  • include_from(任意): データを検索する開始時刻(unixtime)。

  • include_to(任意): データを検索する終了時刻(unixtime)。

    include_fromのみを指定した場合、include_fromからinclude_from + 3600秒を検索対象とする。
    include_toのみを指定した場合、include_to - 3600秒からinclude_toまでを検索対象とする。
    include_fromとinclude_toを両方省略した場合、直近の1時間を検索対象とする。

  • exclude_from(任意): データ検索対象から除外する開始時刻(unixtime)。

  • exclude_to(任意): データ検索対象から除外する開始時刻(unixtime)。

    exclude_fromのみを指定した場合、exclude_from以降の時点全てが検索対象外となる。
    exclude_toのみを指定した場合、exclude_toまで時点全てが検索対象外となる。
    exclude_fromとexclude_toを両方指定した場合、exclude_fromとexclude_toに囲まれた時点が検索対象外となる。

また、以下の制約が存在する。

  • include_fromとinclude_toの両方指定した場合で、include_to - include_from > 14日(86400 * 14)の場合はエラーとなる。
  • include, excludeで絞り込んだ後で、検索するデータ点が112以上の場合はエラーとなる。この場合、適当に検索時間を絞ることで、データを検索できる可能性がある。




Dashboard

Dashboardは、 ELmote® CLOUDが保存するデータをグラフなどで可視化するサービスである。

dashboard_3


表示するコンテンツを追加する

コンテンツを追加する場合、画面右上部の「Locked」と表示されているアイコンをクリックしてから、左上の点線で囲まれたボタンをクリックする。

dashboard_0

dashboard_1

追加できるコンテンツは、

  • Latest Value Monitor: あるデータについて、最新の値を表示する
  • History Value Monitor: あるデータについて、時系列の値をグラフで表示する
  • Parser: Latest Value MonitorおよびHistory Value Monitorで、データに対し適用するParser

の3種類である。


Latest Value Monitor

Latest Value Monitorでは、

  • Name: 表示名
  • Identifier: データ保存時に指定した、data_identifier
  • Tag1, Tag2, Tag3 : データ保存時に指定した、data_tag（指定しなくても、data_identifierで検索するので、動作上は問題ない）
  • Parser

を指定する。


History Value Monitor

History Value Monitorでは、

  • Name: 表示名
  • Identifier: データ保存時に指定した、data_identifier
  • Tag1, Tag2, Tag3 : データ保存時に指定した、data_tag（指定しなくても、data_identifierで検索するので、動作上は問題ない）
  • Parser
  • Timerange: グラフで表示する時間の幅

を指定する。


Parser Editor

Parser Editorでは、

  • Name: 表示名

を指定する。また、データに対するParserを定義する。

【重要】　Parserは、以下の制約を満たす必要がある。

  • Parserの入力となるデータ構造（event）は、保存したデータそのものをオブジェクトとして想定する。例えば、The Things Stackから送信したデータに対するParserの例は以下である。
function(event) {
    //
    // write your parser ...
    //

    const device_id = event.end_device_ids.device_id;
    const decoded_payload = event.uplink_message.decoded_payload;
    const latitude = decoded_payload.latitude;

    //
    // Parser must return key-value object.
    //
    const ret = {'latitude': latitude};
    return ret;

}

Note: Latest Value MonitorやHistory Value Monitorが期待したように表示されない場合、Parserの定義が適切でない可能性がある。Parserは上述の制約があるので、ELmote® CLOUDに保存したデータ構造を確認し、適宜修正いただきたい。


コンテンツを編集する

一度保存したコンテンツの設定は、後から編集することができる。また、表示位置の変更、背景色の変更が可能である。これらは、Lockを解除した状態であれば、各コンテンツの右上に表示されるアイコンから設定できる。

dashboard_2




Alert

Alertは、設定した条件に併せて外部サービスに警報を出すサービスである。


考え方

alert_0


  • まず、webインタフェースで警報の条件、発報先を設定する。設定後にIDが払い出されるので、これを記録する。

  • 外部からデータを送信する際、ヘッダーに「alert_setting」という項目を追加し、値にIDを入れる。例えばThe Things Stackなら以下のようになる。

    alert_3


  • 届いたデータが、警報条件（JavaScript）を満たすかどうかをチェックする。この時、

    • オブジェクトをreturnした場合、警報条件を満たしたと判断し、発報先にオブジェクトをJSON文字列として送信する。

    • falseをreturnした場合、警報条件を満たさなかったと判断する。

    例えば、以下は単に受け取ったデータを警報として発報する例である（Slack）。

    alert_2


    以下はデータの一部で条件付けする例である。

    alert_4


  • 発報先は、webインタフェースの「URL」で指定する。

  • 発報の際に、追加で必要なheaderが存在する場合は、webインタフェースの「header」に指定する。

以上の仕組みにより、次の制約が発生する:

  • 発報の条件は、 ELmote® CLOUDに届いた1件のデータに対してのみが条件付け可能である。例えば、1時間の間に届いたすべてのデータに対する何らかの条件付け（合計が閾値以下である、など）といった発報条件は、サポートされていない。

  • 発報のタイミングは、ELmote® CLOUDに届いた時点である。例えば、3時間データが届いていないことに対する条件付けといった発報条件は、サポートされていない。