SIPF Object protocol コマンド構造¶

SIPF Object Protocolではデバイスとデバイスアダプタの間をコマンドと呼ばれる形式のバイナリデータを送受することで通信を成立させます。このコマンド形式は、マシン処理のしやすさや通信料を優先した、比較的低用量で低負荷なバイナリ形式として設計されています。

ユーザはデバイスからデバイスアダプタに対して何かしらの要求を行う際には、このコマンド形式のバイナリデータを生成し送出する必要があります。また、逆にデバイスアダプタからの応答もこのコマンド形式に基づいて送られてくるので、受け取ったバイナリデータをデバイス側でパースし、解釈する必要があります。

コマンド内で使用される多バイト長の数値はビッグエンディアンで表記されます。

コマンド内のフィールドは何段階かに階層化されており、一部のフィールドは他のフィールドの設定値により構造が変化します。

コマンドは下記のフィールドから構成されます。

SIPF Object Protocol Command¶
Length(byte)	フィールド名	概要
12	COMMAND_HEADER	コマンドの基本的な情報
Variable	COMMAND_PAYLOAD	コマンドの詳細な情報

COMMAND_HEADER ¶

COMMAND_HEADERは下記のフィールドから構成されます。

COMMAND_HEADER¶
Length(byte)	フィールド名	データ型	概要
1	COMMAND_TYPE	符号なし整数	コマンドの種別
8	COMMAND_SEND_TIMESTAMP_MS	符号なし整数	コマンド送信時時刻
1	COMMAND_FLAGS	符号なし整数	コマンドの特性フラグ
2	COMMAND_PAYLOAD_LENGTH	符号なし整数	COMMAND_PAYLOADの長さ

COMMAND_TYPE ¶

デバイスとデバイスアダプタの間でやり取りする指示の種別を表す数値です。

種別により使用可能な送信方向が異なり、その方向性を下記のように定義します。

UP_Stream : デバイスからデバイスアダプタ方向へ

DOWN_Stream : デバイスアダプタからデバイス方向へ

COMMAND_TYPEによりCOMMAND_PAYLOADの構成が変化します。こちらの詳細はCOMMAND_PAYLOADの項で解説します。

以下にコマンド種別一覧を示します。

COMMAND_TYPE List¶
値	種別名	使用方向	概要
0x00	OBJECTS_UP	UP_Stream	Objectをデバイスアダプターへ送信
0x01	RSVD	RSVD	RSVD
0x02	TRANSMISSION_ID	DOWN_Stream	OBJECTS_UPで送信されたオブジェクト群に対する「転送ID」を応答する
0x10	RSVD	RSVD	RSVD
0x11	OBJECTS_DOWN_REQUEST	UP_Stream	デバイス宛のObjectを送るようにデバイスアダプターへ要求
0x12	OBJECTS_DOWN	DOWN_Stream	OBJECTS_DOWN_REQUESTに応じてObjectをデバイスへ送信
0x20	RSVD	RSVD	RSVD
0x21	RSVD	RSVD	RSVD
0x22	RSVD	RSVD	RSVD
0xFF	ERROR	DOWN_Stream	デバイスから送信されたコマンドに何らかの異常がある

COMMAND_SEND_TIMESTAMP_MS ¶

デバイスまたはデバイスアダプタからコマンドを送出した時点の時刻のフィールドです。

8byteの符号なし整数で、UNIXエポックからの経過時間[ミリ秒]です。

デバイスアダプタからデバイス時 ¶

デバイスアダプタからデバイスに対して送信されるコマンドの際には常にこの時刻はセットされています。デバイス側は必要に応じてこの時刻情報を利用してください。

デバイスからデバイスアダプタ時 ¶

デバイスからデバイスアダプタに対して送信する際には、デバイス側の現在時刻を設定して送信することを想定しています。ここで設定された時刻は、サービスアダプタ側のjsonフォーマットのtimestamp_srcというフィールドに適用されます。

しかし、デバイス側ローカル時刻を持たない用途もあるため、必要としない場合はこの時刻フィールドを使用する必要はありません。使用しない場合は全ビット0を指定することを推奨します。このときサービスアダプタ側のjsonフォーマットでは、 UNIXエポック時刻(1970-01-01T00:00:00Z)が適用されます。

また、必ずしも現在時刻を設定する必要があるわけではなく、どのような時刻情報を設定するかはユーザのシステム設計にゆだねられています。デバイスの起動からのmsや、計測回数など、現在時刻と異なる情報で利用することも不可能ではありません。ただし、サービスアダプタ側のjsonフォーマットではRFC 3339形式での適用となるため適切な変換などをユーザ側で行う必要があります。しかし、通常の利用方法の範囲ではそのような情報は一つのオブジェクトとして送受されることを推奨します。

ただ、適切な情報でこの時刻フィールドを利用すると、デバイスからの送信タイミングとユーザークラウドアプリケーション側の動作タイミング等の関係を把握することができ、設計意図とことなる挙動をした際などのデバッグに役立てる事がでる場合があります。

COMMAND_FLAGS ¶

送出されるコマンドの特性を表すフラグです。現時点ではRSVDの為、全ビット0を指定してください。

COMMAND_PAYLOAD_LENGTH ¶

COMMAND_PAYLOADのbyte数を符号なし整数で設定します。実際のCOMMAND_PAYLOADのbyte数と正確に一致していなければなりません。

COMMAND_PAYLOADは最大で1024byte以下である必要があります。

COMMAND_PAYLOAD ¶

PAYLOADの構造はHEADER内のCOMMAND_TYPEによって異なります。

ここでは、各COMMAND_TYPE毎に、コマンドの詳細動作とPAYLOADの構造を解説します。

OBJECTS_UP ¶

1つ以上のObjectをデバイスからデバイスアダプタに対して送信するときに使用します。

PAYLOADは、送信するObjectを OBJECTデータ型で表現したものを順番に並べたものとなります。

この時のOBJECTの並び順については管理保証外となっており、サービスアダプタ側でのjsonでの並び順との一致性などは保証されません。順序が重要になるような利用をされる場合はTAGを有効に利用して管理してください。

COMMAND_PAYLOAD構造(OBJECTS_UP)¶
Length(byte)	フィールド名	データ型	概要
Variable	OBJECT	OBJECT	送信するObject-1
Variable	OBJECT	OBJECT	送信するObject-2
Variable	OBJECT	OBJECT	送信するObject-3
・・・	・・・	・・・	・・・
Variable	OBJECT	OBJECT	送信するObject-n

下記の条件を満たす必要があります

全Objectの合計のLengthが1024byte以下である必要があります。
全Objectの合計のLengthと、COMMAND_PAYLOAD_LENGTHが一致している必要があります。
同時に送信可能な最大Object数は個々のObjectのLengthに依存し、全Objectの合計のLengthが1024byte以下になる個数にする必要があります。

TRANSMISSION_ID ¶

OBJECTS_UPコマンドが送信された時にデバイスアダプタからデバイスに対して送信されるコマンドで、 OBJECTS_UPコマンドの結果とOTIDをデバイスに対して通知します。

COMMAND_PAYLOAD構造(TRANSMISSION_ID)¶
Length(byte)	フィールド名	データ型	概要
1	OBJECTS_UP_RESULT	符号なし整数	結果のコード
16	OTID	符号なし整数	このObjectの転送に割り振られたユニークID

OBJECTS_UP_RESULT ¶

OBJECTS_UPコマンドの結果をコードで表したものが格納されます。なお、エラー時はデバイスアダプタ側で最初に検出された問題が応答されるため、該当のOBJECTS_UPコマンドに含まれる問題が応答されたコードだけとは限りません。

OBJECTS_UP_RESULT¶
コード値	意味
0x00	成功
0x01-FF	エラー(種別は現在RSVD)

OTID ¶

128bitの符号なし整数です。

Object転送単位(送信したObjectのセット)に対してユニークなIDが採番されそのIDをデバイスへ通知します。このIDはOTID(Object Transfer ID)と呼び、ユーザの用途の必要性に応じて送受信の管理に使用します。

デバイスからのObject送信時、このOTIDはサービスアダプタ側のjson上でも共通のものが通知され、デバイスとクラウドアプリケーションとでお互いに送信したObject転送単位を識別/把握する手段ことができます。

OBJECTS_DOWN_REQUEST ¶

デバイスがデバイスアダプタに対して、このデバイス宛のObjectがあったら送信するように要求するときに使用するコマンドです。

PYALOADの1byteは現在RSVDです。全bit0としてください。

COMMAND_PAYLOAD構造(OBJECTS_DOWN_REQUEST)¶
Length(byte)	フィールド名	データ型	概要
1	RSVD	RSVD	RSVD(All 0)

OBJECTS_DOWN ¶

OBJECTS_DOWN_REQUESTに対するデバイスアダプタの応答です。

PAYLOADは、Object転送単位にかかわる情報と、この転送単位に含まれるObjectを OBJECTデータ型で表現したものを順番に並べたものとなります。

サービスアダプタに対して異なるObject転送単位として送信されたObjectはモノプラットフォーム上に滞留したとしても統合されてまとめて届くようなことは無く、一度のOBJECTS_DOWN_REQUESTに対するOBJECTS_DOWNで一つのObject転送単位毎にデバイスに対して送られます。

もしこのデバイス宛のObject転送単位が無かった場合には、Object転送単位にかかわる情報の領域のみでObjectの領域の無いものがデバイスに対し送信されます。先頭34byteだけのPAYLOADが送信された場合にはこのデバイス宛のObject転送単位が無かったとみなすことになります。

COMMAND_PAYLOAD構造(OBJECTS_DOWN)¶
Length(byte)	フィールド名	データ型	概要
16	OTID	符号なし整数	このObjectの転送に割り振られたユニークID
8	TIMESTAMP_SRC	符号なし整数	このObjectの転送に対してユーザーがサービスアダプタへ送信時に付与した時刻情報
8	TIMESTAMP_PLATFORM_FROM_SRC	符号なし整数	このObjectの転送指示をサービスアダプタ側で付与した時刻情報
1	REMAINS	Boolean	今回デバイスアダプタから送信されたObject転送単位以外に、このデバイス宛のObject転送単位が残っているかを表します
1	RSVD	RSVD	RSVD
Variable	OBJECT	OBJECT	受信したObject-1
Variable	OBJECT	OBJECT	受信したObject-2
Variable	OBJECT	OBJECT	受信したObject-3
・・・	・・・	・・・	・・・
Variable	OBJECT	OBJECT	受信したObject-n

OTID ¶

128bitの符号なし整数です。

クラウドアプリケーションからサービスアダプタへObject転送単位のjsonを送信時、ユニークなIDがOTIDとして採番されクラウドアプリケーション側へ通知されます。この時のOTIDが格納され通知されます。このIDはOTID(Object Transfer ID)と呼び、ユーザの用途の必要性に応じて送受信の管理に使用します。

このOTIDはサービスアダプタ側/デバイスアダプタ側のjson上でも共通のものが通知され、デバイスとクラウドアプリケーションとでお互いに送信したObject転送単位を識別/把握する手段ことができます。

例外的な動作として、デバイスアダプタから受け取れるObject転送単位が無かった時にはこのOTIDは全ビット0が設定されて届きます。

TIMESTAMP_SRC ¶

ユーザークラウドアプリケーションからサービスアダプタに対してObject転送単位を送信時に付与可能な timestamp_src というフィールドがあり、そこに設定された時刻情報がこのフィールドに展開されています。ユーザクラウドアプリケーションがサービスアダプタに対して送信する際には、ユーザのクラウトアプリケーション側の現在時刻を設定して送信することを想定しています。

8byteの符号なし整数で、UNIXエポックからの経過時間[ミリ秒]です。

しかし、ユーザシステム的に時刻を持たせる必要のない用途もあるため、必要としない場合はこのフィールドをjson上で省略が可能になっています。その場合、サービスアダプタ側でUNIXエポック時刻(1970-01-01T00:00:00Z)が指定されたものとみなされ、デバイスアダプタ側ではこのTIMESTAMP_SRCは全ビット0が設定されて届きます。

また、必ずしも現在時刻を設定する必要があるわけではなく、どのような時刻情報を設定するかはユーザのシステム設計にゆだねられています。デバイスの起動からのmsや、計測回数など、現在時刻と異なる情報で利用することも不可能ではありません。ただし、サービスアダプタ側のjsonフォーマットではRFC 3339形式での適用となるため適切な変換などをユーザ側で行う必要があります。しかし、通常の利用方法の範囲ではそのような情報は一つのオブジェクトとして送受されることを推奨します。

ただ、適切な情報でこの時刻フィールドを利用すると、デバイスからの送信タイミングとユーザークラウドアプリケーション側の動作タイミング等の関係を把握することができ、設計意図とことなる挙動をした際などのデバッグに役立てる事がでる場合があります。

例外的な動作として、デバイスアダプタから受け取れるObject転送単位が無かった時にはこのTIMESTAMP_SRCは全ビット0が設定されて届きます。

TIMESTAMP_PLATFORM_FROM_SRC ¶

ユーザークラウドアプリケーションからサービスアダプタに対してObject転送単位のjsonを送信したときに自動的にサービスアダプタで付与されるモノプラットフォーム側で受け取ったタイミングを示す時間情報です。

8byteの符号なし整数で、UNIXエポックからの経過時間[ミリ秒]です。

デバイス側は必要に応じてこの時刻情報を利用してください。

例外的な動作として、デバイスアダプタから受け取れるObject転送単位が無かった時にはこのTIMESTAMP_PLATFORM_FROM_SRCは全ビット0が設定されて届きます。

REMAINS ¶

今回デバイスアダプタから送信されたObject転送単位以外に、このデバイス宛のObject転送単位が残っているかを表します。

0bit目のboolean値で表されます。

1～7bit目についてはRSVDです。

REMAINS¶
値	意味
0b0	現在このデバイス宛のObject転送は残っていない
0b1	現在このデバイス宛のObject転送が残っている

OBJECT ¶

このObject転送単位に含まれるObjectを OBJECTデータ型で表現したものです。複数個含まれる場合は順番に並びます。

この時のOBJECTの並び順については管理保証外となっており、サービスアダプタ側でのjsonでの並び順との一致性などは保証されません。順序が重要になるような利用をされる場合はTAGを有効に利用して管理してください。

デバイスアダプタから受け取れるObject転送単位が無かった時には、このTIMESTAMP_PLATFORM_FROM_SRCは全ビット0が設定されて届きます。

ERROR ¶

デバイスから発行される各種コマンドに対して、デバイスアダプタ側でコマンドとして解釈ができなかった時に応答されます。

コマンドとして解釈できるもののPAYLOAD等に不備がある場合は、基本的に各コマンドに対応する応答内のResultで通知され、このERRORでの応答はありません。

COMMAND_PAYLOAD構造(ERROR)¶
Length(byte)	フィールド名	データ型	概要
1	ERROR_CODE	符号なし整数	エラーコード

ERROR_CODE¶
値	意味
0x01	定義されていないCOMMAND_TYPEが使用された
0x02	コマンド全体の長さが、COMMAND_HEADERとして必要最低限の長さ(12byte)に満たない
0x03	COMMAND_PAYLOADの長さが、コマンドで必要とされる長さと一致しない

共通事項 ¶

OBJECTデータ型 ¶

個々のObjectは下記のように構成されます。

COMMAND_HEADER¶
Length(byte)	フィールド名	データ型	概要
1	OBJECT_TYPE	符号なし整数	Objectの値の型種別を表します
1	OBJECT_TAG	符号なし整数	Objectの値につけるTAGを表します
1	OBJECT_VALUE_LENGTH	符号なし整数	OBJECT_VALUEの長さ
Variable	OBJECT_VALUE	OBJECT_TYPEに依存	Objectの値

OBJECT_TYPE ¶

1byteの符号なし整数で表され、このObjectのOBJECT_VALUEがどのような形式の値なのかをIDで表現します。 32bit整数や、文字列等、VALUEのバイナリをどう解釈するべきかの定義になります。

対応する形式は、各種OBJECT_TYPE を参照してください。

OBJECT_TAG ¶

1byteの符号なし整数で表され、オブジェクト内のVALUEが何を表しているかをデバイスとクラウドアプリケーション間で共有する為の情報とすることができます。例えば、TAG=1は温度、TAG=2は時間、TAG=3はON、などあらかじめユーザ側で取り決めておくことで、送受する情報を適切に処理可能となります。

OBJECT_VALUE_LENGTH ¶

1byteの符号なし整数で表され、 OBJECT_VALUEの長さを表します。 OBJECT_TYPEによって既定の長さのものと可変長のものとがあります。

TYPE毎のLENGTHは、各種OBJECT_TYPE を参照してください。

可変長のものは最大255byte以下にする必要があります。

OBJECT_TYPEによる規定長や、可変長VALUEの実際の長さを正確に適用する必要があります。不正確なLENGTHを設定してしまうと化けたデータやエラーになることがあります。

各種OBJECT_TYPE ¶

OBJECT_TYPE一覧¶
TYPE_ID	名称	VALUEのLength(Byte)	バイナリの格納形式
0x00	uint8	1	8bit符号なし整数
0x01	int8	1	8bit符号つき整数
0x02	uint16	2	16bit符号なし整数
0x03	int16	2	16bit符号つき整数
0x04	uint32	4	32bit符号なし整数
0x05	int32	4	32bit符号つき整数
0x06	uint64	8	64bit符号なし整数
0x07	int64	8	64bit符号つき整数
0x08	float32	4	32ビット浮動小数点数（IEEE754 単精度）
0x09	float64	8	64ビット浮動小数点数（IEEE754 倍精度）
0x0A～0x0F	RSVD	RSVD	RSVD
0x10	binary	Variable	可変長byte列 ※
0x11～0x1F	RSVD	RSVD	RSVD
0x20	string_utf8	Variable	可変長utf8文字列 ※
0x21～0xFF	RSVD	RSVD	RSVD

可変長byte列 ¶

任意長のバイナリ列を、 1byte目からbyte単位に順に並べたものになります。 word単位でのエンディアン処理などは行いません。

最大byte数は255byteまでとなります。

可変長utf8文字列 ¶

任意長のutf8エンコードされた文字列のバイナリ列を、 byte列として1byte目からbyte単位に順に並べたものになります。

LENGTHが文字数ではなくバイナリ列のbyte数であることに注意してください。

最大文字数での定義は無く、代わりにutf8エンコードされた文字列のバイナリ列のサイズが最大255byte以下であることが要求されます。使用する各文字のbyte数によって255byteぴったりまで使用できずに短くなる場合があることに注意してください。