﻿======================================================================
              TomuCore User API 仕様 ver. 1.02
======================================================================


                                            2010-1-12b ver1.0
                                       宮寺, 大島, 岩井, 戸辺

                                                変更履歴
                                       2010-1-09//藤田チェック
                                       2010-1-12a ver1.01//戸辺修正
                                       2010-1-12b ver1.02//岩井修正
                                         Data->SensorDataにして構造化
                                         Valueの構造化
                                         ResQuery.SensorDataSet構造変更


0. メモ
  <Value> の中は、センサの種類別に、分かれます。詳しくは(4.3) の例をご確認ください。  実装を進める中で詳細を決め、この仕様をバージョンアップする。

1. はじめに
  本仕様は、雰囲気検索サーバや、アンビエントルートナビゲーションサーバ等
のサーバから TomuCore を呼び出すときに利用されるAPIである。
   TomuCore User API は、AXlib と呼ばれるライブラリで実現され、AXlibは、
XMPP通信ライブラリを呼び出す。
   サーバはJavaで実装されるものとする。

2. primitives
  次の4種類の非同期リクエストprimitiveを規定する。

  (1)getAllSensorProperties
     対象とするTomuCoreノードで管理する、すべてのセンサ属性を引き出す。
     ITScanにおいては、TomuCoreノードは、気象センサと立体差分カメラ※の
     センサ属性を管理する。
  (2)getSensorProperty
     特定のセンサに対するセンサ属性を引き出す。
  (3)getSensorDataSet
     領域で指定する範囲内にあり、TomuCoreで管理する、すべてのセンサデータ
     を引き出す。時間については問わない。TomuCoreで管理するすべての保存
    センサデータを引き出す。
  (4)getCurrentSensorData
     領域で指定する範囲内にあり、TomuCoreで管理され、現在のすべての
     センサデータを引き出す。
     現在のデータとは、最も現時刻に近い過去のデータを指す。
      [FFS: 厳密には、
      将来変更の可能性があるが、ver. 1.0 においては、このように定義
      しておく。]

   レスポンスは、メッセージリスナーで受け取る。


   ※ 人流センサ、立体カメラ、と呼ぶこともある。極力、立体差分カメラ
      と呼ぶこととするが、長いので、周知徹底されていない。


3. 共通データ規定

 (1)リクエスト時のシーケンス番号には、UNIX time を用いる。

 (2)センサの種類

    int type;
    0x01  : 気温
    0x02  : reserved
    0x04  : 立体差分カメラ (人流に関するデータ)
    0x08  : 立体差分カメラ(交差点) ※※
    0x10  : 携帯画像

    final static int TEMP = 0x01;
    final static int PEDESTRIAN = 0x04;
    final static int INTER_PEDESTRIAN = 0x08;
    final static int IMAGE = 0x10;

    と定義し、気温と立体差分カメラの両方のデータを必要と
    するときには、
      TEMP | PEDESTRIAN
    で指定できる。

   ※※ 2010年度のITScanにおいては、交差点データを使わない可能性が
      高い。変更があったときには、ver 1.1 以降で規定する。


 (3) 地理上範囲
    緯度、経度の区画で指定する。地図上の長方形の左上隅の点の
     緯度、経度、横方向経度の幅(°)、縦方向緯度の高さ(°)
    の4種類の値を指定する。

    double  lat,    // Rangeの緯度
    double  lon,    // Rangeの経度
    double  width,    // Rangeの幅
    double  height,    // Rangeの高さ

    たとえば、館林市周辺で500m は、経度差で、小数点第2位程度で指定
    できる。

 (4) 向き
    真北を基準に時計回りの角度0~359。 向きがない場合は-1。

 (5)センサID
    気象センサや立体差分カメラの場合には、
    String staticSensorID;
    として規定する。
    参考までに、ITScanにおいては、TomuCore 内部でセンサが登録される
    ときのUNIX time が用いられる。

    携帯画像の場合には、URI がセンサIDとして、用いられる。


  (6)レスポンスの中で、各センサの値は、 <Value> ～ </Value>
     の中に示される。

  (7)センサ属性は、次の <SensorProperty> ～ </SensorProperty> で
    規定される。
  <SensorProperty>
    <SensorID>センサID：UNIX time</SensorID>
    <SensorName>センサ名：ルールなし</SensorName>  ※※※
    <Location>
      <Lat>緯度</Lat>
      <Lon>経度</Lon>
    </Location>
    <Direction>方向：真北を基準に時計回りの角度0~359</Direction>
  </SensorProperty>

※※※  センサ名は、通常、指定がなくてもよい。ただし、携帯画像の
 場合には、必ず必要とする。



4. 詳細規定


(4.1) getAllSensorProperties
   リクエスト:
      getAllSensorPropertyies()
      引数なし。
   レスポンス: <SensorProperty>のリスト

   ※例は未記載  要修正

(4.2) getSensorProperty
   リクエスト:
      getSensorProperty(
        String sensorID   // 取得したい固定センサのID
      )
   レスポンス：<SensorProperty>

(4.3) getSensorDataSet
    リクエスト:
    getSensorDataSet(
      long  seq,    // クエリのシーケンス番号を指定する(UNIX time)
      double  lat,    // Rangeの緯度
      double  lon,    // Rangeの経度
      double  width,    // Rangeの幅
      double  height,    // Rangeの高さ
      int    theta1,    // データの向き開始角. 向きがない場合は-1
      int    theta2,    // データの向き終了角. 向きがない場合は-1
      int    type,    // データの種類
    )
    レスポンスは大まかに以下の構造になります。
 <ResQuery>	
  <SensorDataSet>
   <StaticSensorData>	or <MonbileSensorData> *n個
     <Value>..各タイプごとのデータ構造:XXValue型</Value>
   </StaticSensorData>	or </MonbileSensorData> 
  </SensorDataSet>
 </ResQuery>

 詳細
    <Seq>クエリのシーケンス番号</Seq>
    <NumberOfSensorData>データの個数</NumberOfSensorData>
    .....
    <StaticSensorData>
      <Type>データの種類</Type>
      <SensedTime>データの取得時刻</SensedTime>
        ...  データの種類により、異なる。詳細は下記。
      <Value>データの内容</Value>
    </StaticSensorData>

    **** Data部の記法
    //  温度の場合
    <StaticSensorData>
    <Type>TEMP</Type>
    <StaticSensorID>センサID</StaticSensorID>
     <Value>
        <CelsiusTempValue>温度の値</CelsiusTempValue>
     </Value>
    </StaticSensorData>

    //  写真の場合
    <MobileSensorData>
    <Type>IMAGE</Type>
    <SensorName>センサ名</SensorName>
    <Location>位置</Location>
    <Direction>方向</Direction>
    <Value>
      <URLValue>URL</URLValue>
    </Value>
    </MobileSensorData>

    //  人流の場合
    <StaticSensorData>
    <Type>PEDESTRIAN</Type>
    <StaticSensorID>センサID</StaticSensorID>
      <Value>
        <StreetPedestrianFlowValue>
        //軸タイプ(道に対してどちらに歩いているか:
        //axis+ or axis- or stay), 人数, 単位時間(1min等)
        <MeasurementTimeSec>60</MeasurementTimeSec>
        <ChiefAxis><Plus>1</Plus><Minus>10</Minus></ChiefAxis>
        <Residence>6</Residence>
        </StreetPedestrianFlowValue>
      </Value>
    </StaticSensorData>

    //  交差点の人流の場合
    <StaticSensorData>
    <Type>INTER_PEDESTRIAN</Type>
    <StaticSensorID>センサID</StaticSensorID>
        //軸タイプ(axisM+ or axisM- or axisS+ or axisS- or stay),
       //人数, 単位時間(1min等)</Value>
        // ※2010年度のITScanにおいては、交差点データを使わない可能性が
       //高い。変更があったときには、ver 1.1 以降で規定する。
      <Value>
        <InterPedestrianFlowValue>
        //軸タイプ(道に対してどちらに歩いているか:
        //axis+ or axis- or stay), 人数, 単位時間(1min等)
        <MeasurementTimeSec>60</MeasurementTimeSec>
        <ChiefAxis><Plus>1</Plus><Minus>10</Minus></ChiefAxis>
        <SubAxis><Plus>5</Plus><Minus>2</Minus></SubAxis>
        <Residence>6</Residence>
        </InterPedestrianFlowValue>
      </Value>
    </StaticSensorData>




// 以下，例
<ResQuery>
<SensorDataSet>
  <Seq>201004011200000</Seq>
  <NumberOfSensorData>PEDESTRIAN</NumberOfSensorData>
  <StaticSensorData>
    <Type>TEMP</Type>
    <SensedTime>201003310123456</SensedTime>
    <StaticSensorID>201003251424053</StaticSensorID>
    <Value>6.3</Value>
  </StaticSensorData>
  <StaticSensorData>
    <Type>IMAGE</Type>
    <SensedTime>201003310154321</SensedTime>
    <SensorName>dendai camera</SensorName>
    <Location>
      <Lat>38.53</Lat>
      <Lon>141.02</Lon>
    </Location>
    <Direction>283</Direction>
    <Value>http://www.hogehoge.jp/picture/201003310154321.jpg</Value>
  </StaticSensorData>
  <StaticSensorData>
    <Type>PEDESTRIAN</Type>
    <SensedTime>201003310130000</SensedTime>
    <StaticSensorID>201003221542235</StaticSensorID>
    <Value>
    <StreetPedestrianFlowValue>
        <MeasurementTimeSec>60</MeasurementTimeSec>
        <ChiefAxis><Plus>1</Plus><Minus>10</Minus></ChiefAxis>
        <Residence>6</Residence>
    </StreetPedestrianFlowValue>
    </Value>
  </StaticSensorData>
  <StaticSensorData>
    <Type>INTER_PEDESTRIAN</Type>
    <SensedTime>201003310120000</SensedTime>
    <StaticSensorID>201003202002539</StaticSensorID>
    <Value>
    <StreetPedestrianFlowValue>
        <MeasurementTimeSec>60</MeasurementTimeSec>
        <ChiefAxis><Plus>1</Plus><Minus>10</Minus></ChiefAxis>
        <SubAxis><Plus>5</Plus><Minus>2</Minus></SubAxis>
        <Residence>6</Residence>
    </StreetPedestrianFlowValue>
    </Value>
  </StaticSensorData>
</SensorDataSet>
</ResQuery>
5. FFS
// 過去データを区別する(仮:対案歓迎)
getCurrentSensorDataSet()
// 自分で作るライブラリ"AXLib"の中で呼び出される
// アプリケーション側からは呼び出されない

// 識別メッセージコードを入れる
requestType    1
過去      undefined

                                                                  以上
