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ぴったりまで使用できずに短くなる場合があることに注意してください。