概要


Gluinデバイスとは、デバイス用のWebインタフェースを利用して接続するデバイス、およびWebアプリケーションを指します。WebSocketを用いてGluinサーバに接続し、常にコネクションを維持しておくことで、リアルタイムの通信を実現しています。
またこれらの通信を簡単に行うために、gluin.js他をライブラリを提供しています。



デバイスの動作


■全体フロー

Gluinに接続するデバイスは、下記のフローで動作します。まずGluinサーバへ、WebSocketを使用して接続します。その後、初めて接続する際にはデバイスの情報を登録します。この登録時にデバイスが持つ属性値などがサーバに登録されます。登録後は、Gluinサーバへ情報を上げたり(Gluinサーバにとってはデバイスからの出力)、Gluinサーバから指示を受ける(Gluinサーバにとってはデバイスへの入力)を繰り返します。その後、デバイスがオフラインになる場合は、Websocketのコネクションを切断します。また、デバイスの登録を削除することもできますが、その場合そのデバイスを使用しているレシピからもデバイスが消えてしまいますので、今後もデバイスを使用するのであれば、登録解除は行わず、Websocketのコネクションだけ切断します。



図:デバイスの動き


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

■Gluinサーバへの接続

下記はgluin.jsを用いた場合の接続例です。最初にgluinのオブジェクトを作成し、ユーザ名とパスワード、URLを設定し接続を行います。接続に成功すれは引き続き、デバイスの登録処理に移ります。
var myGluin = new DMS();    // gluinオブジェクトの作成
myGluin.set_user( ‘ユーザ名’, ‘パスワード’ ); // ユーザIDとパスワードの設定
myGluin.set_server( ‘ws://xxx.yyy.com:8080/dx’ ); // URLの設定

myGluin.connect(     //  接続
  function() {
     console.log(‘connect成功’);      //接続成功時の処理
     // ここでデバイス登録処理
  },
  function() { 
    console.log(‘connect失敗’);        // 接続失敗時の処理
  }
);

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



■Gluinサーバへの登録

Gluinサーバへ接続すると、デバイスの情報を登録します。Gluinサーバに事前に設定は必要なく、ここで登録された情報に基づいてGluinサイト上で表示されます。

var mydevice_id = "device-12:22:33:44"; // デバイスIDです。var mydevice_name = "仮想ライト";    // デバイスの名前です。
var mydevice_desc = "Web App上の仮想ライトです"; //デバイスの説明です。
var mydevice_icon = "iLight"; // Gluinサイト上のアイコンです
var mydevice_props = {  //登録するデバイスの属性値です。
      "電源": {   //  属性値名です
        "value": false,     // 初期値です
        "type": "boolean",   //  値の型です
        "mode": "readwrite", // デバイスから値を読みだすか、書き込むかを指定します
        "direction": "updown"    //  値はGluinサーバに上げられるか、読み込みリクエストを受けるかを指定します。
      },
      "色": { 
        "value": “#FF4433”, 
        "type": "string", 
        "mode": "readwrite", 
        "direction": "updown"
      }
    };

myGluin.dx_device_register_request(mydevice_id , mydevice_props, mydevice_name, mydevice_desc, mydevice_icon ’, 
    console.log(‘Register成功’), 
    console.log(‘Register失敗’));


登録時には下記の情報が必要です。
ITEM DESCRIPTION
デバイスID ユニークなIDです。UUIDなどで生成されることをお勧めします。なお、異なるIDで登録すると別デバイス扱いになりますので、基本的に同じデバイスは同じIDで登録するよう留意してください。
デバイス名 人が見て分かるデバイス名です。ユニークである必要はありません。また、Gluinサイト上で変更することができますので、デフォルトの名前を付けておきます。オプションです。
デバイスの説明 Gluinサイト上でデバイスの詳細画面で見ることができます。入出力値やデバイスの特性など、レシピで利用される方々に分かるように補足説明を書くことができます。オプションです。
デバイスのアイコン Gluinサイト上で表示されるアイコンです。下記の値を指定することができます 現在、iSensor, iSwitch, iLight, iMonitor, iMic, iSpeakerが使用可能です。
属性値 デバイスが持つ属性値です。まず名前を指定します。この名前はデバイス内でユニークである必要があります。またその属性を次のように指定します。
  • value:初期値
  • type:属性値のタイプです。boolean, integer, float, stringが指定できます。
  • mode:デバイスから値を読みだすか、書き込むかを指定します。readonly, writeonly, readwriteが指定できます。
  • direction: // 値はGluinサーバに上げられるか、読み込みリクエストを受けるか、動作するリクエストの向きを指定します。今はupdownのみの動作です。



■Gluinサーバへの情報アップロード

登録後は、属性値に関する情報をgluinサーバに上げることができます。登録時と違い、変化のある内容だけをアップロードすることができます。例えば、属性値が二つあっても一つだけを次のようにして送ることが可能です。
myGluin.dx_device_update_request( mydevice_id, 
  { 
    "電源": {
        "value": true
    }
  }, console.log(‘Update 成功’), console.log(‘Update 失敗’));

■Gluinサーバからの指示

Gluinサーバからデバイスに指示(リクエスト)が送信される場合があります。この指示には、最新情報の取得、及びデバイスの属性値の書き換え(たとえばON/OFFの変更)があります。
※現在は最新情報取得リクエストをGluinサーバから投げることはありませんので、属性値の書き換えだけになります。

これを処理するために、指示を受けた時にコールバックされるハンドラを登録しておきます。ハンドラの中では、デバイスIDを確認し、属性値を取り出します。どの属性値が支持されたかはオブジェクトを列挙するのが安全ですが、自身の属性値が分かっている場合には直接名前から取得することができます。

値を取得したのち、もしデバイスに反映させた場合には、gluinサーバへの情報を上げる動作と同じように、値が変わった旨をgluinサーバに通知します。これを行わないとgluinサーバでは指示した値に変わったのか、そうでないかが分からないため、通知することを推奨します。

//myGluin.on_device_get_message = get_request_handler; // 取得要求のハンドラ
myGluin.on_device_set_message = set_request_handler;  // 値設定要求のハンドラ

//function get_request_handler( devid, props_obj )
//{
//  // props_objの中に値を入れて、returnで返す
//}

function set_request_handler( devid, props_obj )
{
  if (devid == mydevice_id) {   //デバイスIDの比較。同じコネクションで複数のデバイスを扱うことができるので確認が必要です。
    var prop = props_obj["電源"];   //  指示された属性値を取出し。
    if (prop) {
      var val = prop["value"]; //  指示された値の取出し
      //処理する。もし、値を書き換えたら、updateでそれをサーバに通知。
      myGluin.dx_device_update_request( mydevice_id, { 
          "電源": {
              "value":val
          }
      }, null, null );
    }
  }
}

■デバイス登録解除

Gluinサーバからデバイス情報を削除することができます。ただし、これを行うとレシピなどからも削除されてしまうので、以後も使用するようであれば登録解除を行わないでください。ほかの人に渡すなどを行う際に使用します。
myGluin.dx_device_deregister_request( mydevice_id, 
    function() {
      //  成功時の処理。サーバから切断する
      myGluin.disconnect();
    },
    function() {
      //  失敗時の処理。サーバから切断する
      myGluin.disconnect();
    } );




サンプルプログラム


Webアプリで疑似的にgluinデバイスを作るサンプルアプリです。ダウンロードページからご利用ください。

■VirtualSwitch

スイッチを模擬したWebアプリです。Gluinに接続し、Boolean値のON/OFFを送ることができます。Firefoxブラウザまたは、Firefox OS 1.4(実機、及びシミュレータ)で動作いたします。

■VirtualSwitch_hyb

スイッチを模擬したWebアプリです。スイッチのON/OFFをGluinサーバに上げることは、上記と同じですが、GluinサーバからもON/OFFをコントローすることができるようになっています。Gluinサイト上でスイッチを切り替えるとWebアプリ内のスイッチがON/OFFされるのが確認できます。

■VirtualLight

色調制御ができるライトを模擬したWebアプリです。電源という属性値でというON/OFFが制御できるほか、色に"#RRGGBB"の文字列を送ると、その色に明りを変えることができます。なお、電源OFFの状態では真っ黒表示です。