概要


Gluinアプリ/Webページ(下記、アプリ)とは、Webアプリ用のWebインタフェースを利用して接続するアプリケーション、及びWebページを指します。XHR(XML Http Request)を用いた、RestfulなAPIを使用し、デバイスへアクセスすることができます。また、アクセスへは各アプリごとに払い出されたTokenを使用するため、Webページなどに埋め込むことも可能です。
またこれらの通信を簡単に行うために、gluinapp.jsをライブラリを提供しています。



アプリ/Webページの動作


■全体フロー

Gluinに接続したデバイスを利用するアプリは下記のフローで動作します。アプリはまずユーザID/パスワードを用いてGluinサーバにログインします。ログインするとそのユーザに紐づけ有られたデバイス一覧を取得することや、アプリを登録しデバイスへのアクセスTOKENを得ることができるようになります。また、この登録を行うと、Gluinサイト上の管理画面に表示され、Gluinサイト上でもアプリの削除やデバイスへのアクセス状態の管理ができるようになります。

登録した後は、それぞれのデバイスへの読み書きや、アプリへのコールバック処理ができるようになります。アプリの登録は、通信が切れたり、アプリを終了しても継続しています。最終的にアプリをアンインストールするなど今後アプリを使用しなくなる際には、Gluinサーバからアプリの登録を解除しておきます。


図:アプリの動作


それぞれの動作について下記で説明します。

■Gluinサーバへのログイン

下記はgluinapp.jsを用いた場合の接続例です。最初にgluinappオブジェクトを作成し、ユーザ名とパスワード、URLを設定し接続を行います。接続に成功すれは引き続き、デバイスの登録処理に移ります。
var myGluin = new GluinApp();    // gluinappオブジェクトの作成

myGluin.login( "GluinサーバのURL", 
    "ユーザ名", 
    "パスワード", 
    function() {
      console.log("ログイン成功");
        //	ここでログイン成功時の処理を行います。
    },
    function() {
      console.log("ログイン失敗");
        //	ここでログイン失敗時の処理を行います。
    }
);

				

接続に必要な情報は次の通りです。
ITEM DESCRIPTION
ユーザ名 ユーザごとにデバイス管理が独立しています。現在はGluinサイトのIDと共通です。
パスワード 現在はGluinサイトのパスワードと共通です。
GluinサーバのURL Restful(XHR)用のURLです。ハッカソン等のイベントでアカウントと同様にご連絡しております。デバイス接続用のURLとは異なりますでご注意ください。



■デバイス一覧の取得

Gluinサーバにログインすると、デバイスの一覧が取得できるようになります。なお取得できるデバイスは、ログインしたユーザに紐づけられたデバイスのみです。
myGluin.device_list("デバイスID",
    function(devices) {
        console.log(devices);
    	//	一覧が返って来たときの処理です
    },
    function() {
        console.log("device not found");
    	//	失敗、デバイスが見つからなかった場合の処理です
    }
);

一覧の取得時には、下記のパラメタを設定することができます。
ITEM DESCRIPTION
デバイスID nullを指定すると全デバイス情報を返します。二度目以降など事前に情報がほしいデバイスのIDが分かっている場合には、第一引数に指定することで特定のデバイス情報のみを問い合わせることができます


また、成功した場合には次のようなオブジェクト(JSON)が返ってきます。
{
    "type": "device-list-response",
    "status": "200 OK",
    "devices": {
        "デバイスID1": {
            "is_active": true,
            "name": "エナハースイッチ",
            "description": "電池不要のスイッチです。スイッチを押した力で発電し、オン/オフ信号を送ります",
            "icon": "iSwitch",
            "スイッチ": {
                "type": "boolean",
                "mode": "readonly",
                "direction": "uponly",
                "value": false
            }
        },
        "デバイスID2": {
            "is_active": true,
            "name": "Temperature Sensor",
            "description": "Temperature Sensor. Send Temperature when it changes",
            "icon": "iSensor",
            "humid": {
                "type": "float",
                "mode": "readeonly",
                "direction": "uponly",
                "value": 0
            },
            "temperature": {
                "type": "float",
                "mode": "readeonly",
                "direction": "uponly",
                "value": 0
            }
        },
        // 以下繰り返し
     }
}
各要素は次の通りです。
ITEM DESCRIPTION
デバイスID1,2,.. デバイスを一意に識別する識別子です。
is_active デバイスの状態です。Gluinサーバに接続中であれば true, 切断されてオフラインであればfalseになります。
name デバイスの名前です。Gluinサイト上でも変更できます。
description デバイスの説明です。
icon デバイスの表示用アイコンです。Gluinサイト上でデバイスを表示する際に利用されます
humid, temperature, ... デバイスが持つ属性値の名前です。値として属性値の値や型を取得することができます。詳細は、Gluinデバイスをご参照ください。



■Gluinサーバへのアプリ登録

Gluinサーバへログインしたのち、アプリ情報を登録します。Gluinサーバに事前に設定は必要なく、ここで登録された情報に基づいてGluinサイト上で表示されます。
var appid = "xxxxxxxxxxxxxxxx";	// アプリID
var myapp_name = "リモートスイッチアプリ";	//	アプリ名
var myapp_desc = "スイッチwebアプリケーションです。ON/OFFの信号を送受信できます";	//	アプリの説明
var myapp_icon = "iApp";	//	アイコン

myGluin.register( appid, myapp_name, myapp_desc, myapp_icon, 
    function() {
        console.log("APP REGISTER SUCCESS");
        //	アプリ登録が成功した場合の処理
    },
    function() {
        console.log("APP REGISTER FAILED");
        //	アプリ登録が失敗した場合の処理
	}
);
				

各要素は次の通りです。
ITEM DESCRIPTION
アプリID ユニークなIDです。UUIDなどで生成されることをお勧めします。なお、異なるIDで登録すると別アプリ扱いになります。基本的に同一端末上で起動する同一アプリは同じIDで登録するよう留意してください。同じアプリでも異なる端末で動作する場合は、異なるアプリIDを使用します。
アプリ名 人が見て分かるアプリ名です。ユニークである必要はありません。
アプリの説明 Gluinサイト上でアプリの詳細画面で見ることができます。どのような目的のアプリであるかなど、レシピで利用される方々に分かるように補足説明を書くことができます。
アイコン Gluinサイト上で表示されるアイコンです。下記の値を指定することができます 現在 "iApp" が使用できます。



■デバイスアクセス用のTOEKNを取得する

アプリを登録すると、デバイスへのアクセスTOEKNを得ることが可能になります。取得、設定できるTOKENの種類は次の通りです。

ITEM DESCRIPTION
GET TOKEN デバイスの値を取得することができるアクセストークンです。
SET TOKEN デバイスへの値を書き込むことができるトークンです。
callback URL トークンではありませんが、デバイスの値が変わった時に呼ばれるURLです。これを指定することで、GET TOKENでポーリングすることなく即座に値の変化を取得することができます。

トークンを取得するには次のaccess_requestを使用します。
        
var appid = "xxxxxxxxxxxxxxxx";	// アプリID
var deviceid = "デバイスID2";	// TOKENを取得するデバイスのID
var propname = "temperature"; //デバイスの属性値名
var callbackurl = "http://example.example/callbackpath?ID=abc";      
myGluin.access_request( appid, deviceid, propname, ["get","set", "callback"], 
    callbackurl, 
    function(get_token, set_token) {
      //	成功した場合の処理
        
        console.log(get_token);
        console.log(set_token);
        
    },
    function() {
      //	失敗した場合の処理
    });

				

各引数は次の通りです。
ITEM DESCRIPTION
アプリID ユニークなIDです。登録したアプリIDを指定します。
デバイスID TOKENを取得するデバイスのデバイスIDを指定します。
デバイスの属性値名 デバイスが持つどの属性値へのTOKENを取得するか指定します。
["set", "get", "callback"] 取得するトークンの種類を配列で指定します。必要なもののみを指定することができます。
callback URL 指定した属性値に変化があった場合に、通知されるURLです。HTTPでBODY部分はGET TOEKNと同様になります。取得するトークンでcallbackを指定したときには指定必須です。



■デバイスの属性値を取得する

取得したGET TOKENを使ってデバイスの値を取得することができます。なお、取得時の認証はTOKENのみで行われるため、ログインする必要はありません。一度TOKENを取得すると、後はTOKENのみでアクセスできるようになります。

※現在のVersionでは、自動的にGET TOKENとデバイスを紐づけるレシピの自動生成は行われません。Gluinサイト上で、GET TOKENに対して、デバイスの属性値を紐づける必要があります。レシピ例はこちらをご参照ください。下記はサイト上でレシピを作成した後に実行可能になります。
var get_toekn = "yyyyyyyyyyyyyyyyyyyyyyyy"; // GET TOKENです。access_requestで取得する必要があります。
myGluin.get_value( "GluinサーバのURL", get_toekn, 
  function(v) {
  	//	値が正しく取得できた時の処理です
    console.log("value: " + v );
  }, 
  function(e) {
  	//	エラー時の処理です。
    console.log("Error: " + e );
  }
);
        

各引数は次の通りです。
ITEM DESCRIPTION
GET TOKEN access_requestで取得したGET TOKENです。
GluinサーバのURL Restful(XHR)用のURLです。ハッカソン等のイベントでアカウントと同様にご連絡しております。デバイス接続用のURLとは異なりますでご注意ください。



■デバイスの属性値を設定する

取得したSET TOKENを使ってデバイスの値を取得することができます。なお、設定時の認証はTOKENのみで行われるため、ログインする必要はありません。一度TOKENを取得すると、後はTOKENのみでアクセスできるようになります。

※現在のVersionでは、自動的にSET TOKENとデバイスを紐づけるレシピの自動生成は行われません。Gluinサイト上で、SET TOKENに対して、デバイスの属性値を紐づける必要があります。下記はサイト上でレシピを作成した後に実行可能になります。レシピ例はこちらをご参照ください。有効に動作しているレシピがない場合、Gluinサーバは要求に対してエラーを返します。


var set_toekn = "zzzzzzzzzzzzzzzzzzzzzzz"; // SET TOKENです。access_requestで取得する必要があります。
var value = true;	//	設定する属性値です
myGluin.set_value( "GluinサーバのURL", set_toekn, value,
  function(v) {
  	//	値が正しく設定できた時の処理です
    console.log("value: " + v );
  }, 
  function(e) {
  	//	エラー時の処理です。
    console.log("Error: " + e );
  }
);

        

各引数は次の通りです。 なお、成功、失敗のCallback関数については、値のSETはGluinサーバに値が正しく送信されたことに対する成功、失敗の判定になります。Gluinサーバからさらにデバイスへ値を設定しようとした際に、エラーが起きた場合は反映されません。そのため正しくデバイスの属性値が変更されたかを確認するにはget_valueにより値を取得して確認する必要があります。有効に動作しているレシピがない場合、Gluinサーバは要求に対してエラーを返します。
ITEM DESCRIPTION
SET TOKEN access_requestで取得したSET TOKENです。
設定する属性値 指定したデバイスの属性値に設定する値です。
GluinサーバのURL Restful(XHR)用のURLです。ハッカソン等のイベントでアカウントと同様にご連絡しております。デバイス接続用のURLとは異なりますでご注意ください。



■Callbackを受ける

デバイスの属性値が変化した際、登録したCallback URLに情報を受けることができます。

※現在のVersionでは、自動的にCallback URLとデバイスを紐づけるレシピの自動生成は行われません。Gluinサイト上で、Callback URLの入力に対して、デバイスの属性値の出力を紐づける必要があります。レシピ例はこちらをご参照ください。下記はサイト上でレシピを作成した後に実行可能になります。


ITEM DESCRIPTION
Method POST
HTTPヘッダ Content-Type: application/json; charset=utf-8
Content-length: 可変
Host: callback_urlのホスト
BODY {"value": 紐づけたデバイスの属性値 }



■アプリ登録解除

Gluinサーバからアプリ情報を削除することができます。ただし、これを行うとレシピなどからも削除されてしまうので、以後も使用するようであれば登録解除を行わないでください。アプリをアンインストールするときなどに使用します。
var appid = "xxxxxxxxxxxxxxxx";	// アプリID
myGluin.deregister( appid,
  function() {
    //	登録解除が成功した場合の処理です
    console.log("APP DEREGISTER SUCCESS");
  },
  function() {
    //	登録解除が失敗した場合の処理です
    console.log("APP DEREGISTER FAILED");
  }
);
        

各引数は次の通りです。
ITEM DESCRIPTION
アプリID ユニークなIDです。登録したアプリIDを指定します。



サンプルプログラム


gluin用のWebアプリのサンプルです。ダウンロードページからご利用ください。

■SwitchControlApp

ON/OFFを送信するWebアプリです。Gluinデバイスと異なり、TOKENを取得し、都度Restful APIにて情報取得、設定を行います。