P2P地震情報 - EPSP ColdFire Gateway プロトコル仕様

EPSP ColdFire Gateway（EPSP-CFG）プロトコル仕様

基本概要: 0. 注意事項・連絡先
 1. バージョン
 2. 要求事項
 3. 基本仕様
 4. Codeリスト
サーバとのシステム通信: 1. 接続 [必須]
2. 認証 [任意]
3. カスタマイズ [任意]
4. エコー [必須]
5. 切断 [任意]
サーバとのデータ通信: 1. 加速度センサ値，震度換算値 [任意]
2. 地震情報 [任意]
3. 津波予報 [任意]
4. 地震感知情報 [任意]
5. 緊急地震速報 [任意]

基本概要

　本プロトコルは，P2P地震情報が使用するEPSP(Earthquake Peer-to-peer Sharing Protocol)の実装が困難な組み込み機器，とくに加速度センサが実装されたColdFire基板を対象に策定したものです．

目次へ

0. 注意事項・連絡先

予告なく変更することがあります．

本プロトコル仕様書に関するご質問などは，たくや(takuya@p2pquake.net)までご連絡ください．

本仕様書では，各通信仕様を紺色の太枠(class=code)で，通信サンプルを黒色の細枠(class=sample)で示します．
各通信仕様

通信サンプル

目次へ

1. バージョン

Ver.0x01 = 1 (2008/09/15): 策定

目次へ

2. 要求事項

　本プロトコルでは，次のような機能が必要です．

TCP/IP (IPv4)
- 1 セッションが確立できること．
- 500 オクテット（バイト）のデータを含むパケットが受信できること，すなわちMSS=500 オクテット，MTU/MRU=552 オクテット以上に対応すること．
  - 各データは1 パケットに収まるよう配慮していますが，TCPではそれが1 パケットとして送受信される保証はありません．
- 送受信あわせて約1000 オクテット/秒のデータ通信が可能なこと．
- ネットワークバイトオーダ（ビッグエンディアン）
  - データについてもネットワークバイトオーダを適用します．ただし，将来的にリトルエンディアンの選択も対応予定です．
DNS（名前解決）

　次の機能への対応は任意です．

加速度センサのデータ送信

目次へ

3. 基本仕様

　本プロトコルでは，クライアント-サーバ間で1対1の通信のみを行います．データはすべて以下の構造で送受信します．

バイト	1	2	3	4	…	n-2	n-1	n
名称	Length		Code	Data			Terminal

Length - 2 オクテット

CodeからTerminalまでのオクテット数を示す．16 ビット符号なし整数型で，範囲は3(0x0003)～498(0x01F2)．

Code - 1 オクテット

何のデータかを示す．8 ビット符号なし整数型で，範囲は0(0x00)～127(0x7F)．

ビット	7	6	5	4	3	2	1	0
概要	通信相手	通信方向	エラー	データタイプ
値	0	0: サーバへ 1: クライアントへ	0: いいえ 1: はい	0～31

Data - 0～495 オクテット

データ．

Terminal - 2 オクテット

　データの終端を示す．0xFFFFを指定する．

　なお，Terminal以外で0xFFFFが出現してはならない．データの境界を知るために，Lengthを読み取るか，Terminalを検出するか，どちらを選んでもよい．

　また，Dataにおけるchar配列の表記はこうである．char[19]とあるとき，サイズは20 オクテットで，文字列の末端に0x00(Null)を含む．つまり，指定可能な文字列は19 オクテットである．

目次へ

4. Codeリスト

RCO	type		e	data code					16進	10進	方向	data array	comment
RCO	7	6	5	4	3	2	1	0	16進	10進	方向	data array	comment
サーバとのシステム通信 - 1. 接続, 2. 認証
R	0	0	0	0	0	0	0	1	01	1	↑	char version	バージョン通知
R	0	1	0	0	0	0	0	1	41	65	↓	char version	バージョン通知
R	0	1	1	0	0	0	0	1	61	97	↓	char type, char[39] errorstr	バージョン非互換エラー
R	0	0	1	0	0	0	0	1	21	33	↑	char type, char[39] errorstr	バージョン非互換エラー
O	0	0	0	0	0	0	1	0	02	2	↑	char auto, char[16] username, char[16] password	認証要求
O	0	1	0	0	0	0	1	0	42	66	↓	NONE	認証成功
O	0	1	1	0	0	0	1	0	62	98	↓	char type, char[39] errorstr	認証失敗エラー
サーバとのシステム通信 - 3. カスタマイズ
O	0	0	0	0	0	1	0	0	04	4	↑	stub	取得情報選択
O	0	1	0	0	0	1	0	0	44	68	↓	NONE	取得情報選択成功
O	0	1	1	0	0	1	0	0	64	100	↓	char type, char[39] errorstr	取得情報選択エラー
O	0	0	0	0	0	1	0	1	05	5	↑	char 3d, char bits, int gals, int sprate, char nt_scale	加速度センサ有効化
O	0	1	0	0	0	1	0	1	45	69	↓	NONE	加速度センサ有効化成功
O	0	1	1	0	0	1	0	1	65	101	↓	char type, char[39] errorstr	加速度センサ有効化エラー
サーバとのシステム通信 - 4. エコー
R	0	1	0	0	1	0	0	0	48	72	↓	NONE	エコーリクエスト
R	0	0	0	0	1	0	0	0	08	8	↑	NONE	エコーリプライ
R	0	0	0	0	1	0	0	1	09	9	↑	NONE	エコーリクエスト
R	0	1	0	0	1	0	0	1	49	73	↓	NONE	エコーリプライ
サーバとのデータ通信
O	0	1	0	1	0	0	0	1	51	81	↓	stub	地震情報
O	0	1	0	1	0	0	1	0	52	82	↓	stub	津波予報
O	0	1	0	1	0	0	1	1	53	83	↓	stub	地震感知情報
O	0	1	0	1	0	1	0	0	54	84	↓	stub	緊急地震速報発表情報
O	0	0	0	1	1	0	0	0	18	24	↑	int x1, y1, z1, x2, y2, z2…（3軸モード時）	加速度センサ
O	0	1	0	1	1	0	0	0	58	88	↓	char scale	震度換算値

目次へ

サーバとのシステム通信

目次へ

1. 接続 [必須]

p2pquake.ddo.jp:6920（p2pquake.ddo.jpの6920ポート）へTCP接続を行います．
- p2pquake.ddo.jpはダイナミックDNSで運用していますので，DNSキャッシュはTTLの範囲内で行うようにしてください．
Code 0x01（バージョン通知）を送信します．
Code 0x01 - バージョン通知
Length: 0x04 （2+4オクテット）
Data: char version

version: 対応するプロトコルバージョン（本仕様書は0x01）を指定する．

RAW: ......
HEX: 00040101FFFF
DESC: version=0x01
Code 0x41（バージョン通知）を受信します．または，Code 0x61（バージョン非互換エラー）を受信します．
Code 0x41 - バージョン通知
Length: 0x04 （2+4オクテット）
Data: char version

version: 対応するプロトコルバージョンが指定されている．

RAW: ..A...
HEX: 00044101FFFF
DESC: version=0x01

Code 0x61 - バージョン非互換エラー
Length: 0x2C （2+44オクテット）
Data: char type, char[39] errorstr

type: エラー番号が指定されている．
errorstr: エラーメッセージがASCIIで記されている．

RAW: .,a.Protocol version incompatible.............
HEX: 002C610150726F746F636F6C2076657273696F6E20696E636F6D70617469626C652E00000000000000000000FFFF
DESC: type=0x01, errorstr="Protocol version incompatible."
互換性がない場合は，Code 0x21（バージョン非互換エラー）を送信します．
Code 0x21 - バージョン非互換エラー
Length: 0x2C （2+44オクテット）
Data: char type, char[39] errorstr

type: エラー番号が指定されている．
errorstr: エラーメッセージがASCIIで記されている．

RAW: .,!.Protocol version incompatible.............
HEX: 002C210150726F746F636F6C2076657273696F6E20696E636F6D70617469626C652E00000000000000000000FFFF
DESC: type=0x01, errorstr="Protocol version incompatible."

目次へ

2. 認証 [任意]

　この認証機能を使用することによって次の効果が得られます．

Web上でカスタマイズ設定を行っておき，設定を自動適用すること．
加速度センサのデータをサーバで記録し，Web上で参照すること．
- 認証しない場合，震度換算値の取得のみが可能です．

　認証機能を使用するには，次のいずれかの方法を取る必要があります．

予め，Web上でユーザ名とパスワードを登録しておく．
自動登録を要求する．
- 認証時に"auto"フラグを立てると，指定したユーザ名とパスワードで自動的に登録処理を行います．

　仕様は次の通りです．

Code 0x02（認証要求）を送信します．
Code 0x02 - 認証要求
Length: 0x26 （2+38オクテット）
Data: char auto, char[16] username, char[16] password

auto: 自動登録を要求するかどうか．0x00: しない，0x01: する
username: ユーザ名
password: パスワード

RAW: .&..example..........foo................
HEX: 002602016578616D706C6500000000000000000000666F6F0000000000000000000000000000FFFF
DESC: auto=0x01, username="example", password="foo"

※ユーザ名，パスワードは平文で送信することに注意してください．
Code 0x42（認証成功）を受信します．または，Code 0x62（認証失敗エラー）を受信します．
Code 0x42 - 認証成功
Length: 0x03 （2+3オクテット）
Data: ありません

RAW: ..B..
HEX: 000342FFFF

Code 0x62 - 認証失敗エラー
Length: 0x2C （2+44オクテット）
Data: char type, char[39] errorstr

type: エラー番号が指定されている．
errorstr: エラーメッセージがASCIIで記されている．

RAW: .,b.Invalid username or password..............
HEX: 002C6201496E76616C696420757365726E616D65206F7220706173776F72642E0000000000000000000000FFFF
DESC: type=0x01, errorstr="Invalid username or password."

目次へ

3. カスタマイズ [任意]

Code 0x04（取得情報選択）を送信します．
Code 0x04 - 取得情報選択
stub

stub
Code 0x44（取得情報選択成功）を受信します．または，Code 0x64（取得情報選択エラー）を受信します．
Code 0x44 - 取得情報選択成功
Length: 0x03 （2+3オクテット）
Data: ありません

RAW: ..D..
HEX: 000344FFFF

Code 0x64 - 取得情報選択エラー
Length: 0x2C （2+44オクテット）
Data: char type, char[39] errorstr

type: エラー番号が指定されている．
errorstr: エラーメッセージがASCIIで記されている．

RAW: .,d.Invalid parameter........................
HEX: 002C6401496E76616C696420706172616D657465722E00000000000000000000000000000000000000000000FFFF
DESC: type=0x01, errorstr="Invalid parameter."
Code 0x05（加速度センサ有効化）を送信します．
Code 0x05 - 加速度センサ有効化
Length: 0x0A （2+10オクテット）
Data: char 3d, char bits, int gals, int sprate, char nt_scale

3d: 3軸センサかどうか．0x00: いいえ（2軸），0x01: はい（3軸）
bits: センサ（A/Dコンバータ）のビット数．
gals: 0～2^[bits]の範囲をガル換算値するといくらか．
sprate: サンプリングレート（Hz単位）．
nt_scale: Code 0x58（震度換算値）を送信するしきい値（震度換算値）の10倍．

※nt_scaleを1以上にすると，震度換算値の10倍がそれを上回った場合にのみ，サーバがCode 0x58を送信します．

RAW: ......ﾍ.d#..
HEX: 000A05010C0FCD006423FFFF
DESC: 3d=0x01, bits=0x0C=12, gals=0x0FCD=4045, sprate=0x0064=100, nt_scale=0x23=35→震度3.5相当

※ColdFire基板かつ±1.5 gモードの場合，bits及びgals指定は上記のようにします．
Code 0x45（加速度センサ有効化成功）を受信します．または，Code 0x65（加速度センサ有効化エラー）を受信します．
Code 0x45 - 加速度センサ有効化成功
Length: 0x03 （2+3オクテット）
Data: ありません

RAW: ..E..
HEX: 000345FFFF

Code 0x65 - 加速度センサ有効化エラー
Length: 0x2C （2+44オクテット）
Data: char type, char[39] errorstr

type: エラー番号が指定されている．
errorstr: エラーメッセージがASCIIで記されている．

RAW: .,e.Invalid parameter........................
HEX: 002C6501496E76616C696420706172616D657465722E00000000000000000000000000000000000000000000FFFF
DESC: type=0x01, errorstr="Invalid parameter."

目次へ

4. エコー [必須]

　セッションが正常に確立されているかどうかを調べます．

1～5 分おきにサーバから発信されます．
クライアントから発信することも可能ですが，推奨はしません．

　サーバからのエコーリクエストに関する仕様は次の通り．

Code 0x48（エコーリクエスト）を受信します．
Code 0x48 - エコーリクエスト
Length: 0x03 （2+3オクテット）
Data: ありません

RAW: ..H..
HEX: 000348FFFF
Code 0x08（エコーリプライ）を送信します．
Code 0x08 - エコーリプライ
Length: 0x03 （2+3オクテット）
Data: ありません

RAW: .....
HEX: 000308FFFF

目次へ

5. 切断 [任意]

任意のタイミングでセッションを切断できます．
- システムの終了時はもちろん，エコーリクエストが10分以上来ない場合，無通信状態が10分以上続く場合，セッション状態が異常となった場合など，状況に応じて切断できます．
エコーリプライがない場合，無通信状態が続く場合，セッション状態が異常となった場合などには，サーバから切断されることがあります．

目次へ

サーバとのデータ通信

目次へ

1. 加速度センサ値，震度換算値 [任意]

Code 0x18（加速度センサ）を送信します．
Code 0x18 - 加速度センサ
Length: 可変（最大498オクテット）
Data（2軸モード時）: int x1, y1, x2, y2…
Data（3軸モード時）: int x1, y1, z1, x2, y2, z2…

x1, y1, z1…: 加速度センサの値を指定する．先頭が古いサンプル，末尾が新しいサンプル．

※最低1サンプルから，2軸モード時は247サンプル，3軸モード時は165サンプルまでまとめて送信可能です．1サンプル毎の送信はオーバーヘッドが大きいため推奨しません．

RAW: ....ﾖ.)...ﾑ.B....
HEX: 000F1807D608290B0007D108420B02FFFF
DESC: x1=0x07D6=2006, y1=0x0829=2089, z1=0x0B00=2816, x2=0x07D1=2001, y2=0x0842=2114, z2=0x0B02=2818（3軸モード時）
Code 0x58（震度換算値）を受信します．
Code 0x58 - バージョン通知
Length: 0x04 （2+4オクテット）
Data: char scale

scale: 震度換算値の10倍が記されている．

※1回のCode 0x18に対し，1回のCode 0x58が返るとは限りません．サーバ側が送信間隔を適宜制限することがあります．

RAW: ..X#..
HEX: 00045823FFFF
DESC: scale=0x23=35→震度3.5相当