SIPF Object protocol コマンド構造

[更新: 2022年9月15日]

SIPF Object Protocol は、デバイスとデバイスアダプタ間で オブジェクト （タグ・データ型・値の組）の送受信に使われるプロトコルです。

デバイスとデバイスアダプタの間で特定の形式のデータを送り合うことでオブジェクトの送受信を行います。本ドキュメントではこのデータのことを コマンド と呼びます。

コマンドは、デバイス側での処理のしやすさやコンパクトさを重視した、比較的軽量・低負荷なバイナリ形式として設計されています。

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

注釈

本ドキュメントでは、特に断りのない限り 1byte=1octet(8bit) とします。
コマンド内のバイトオーダーは ビッグエンディアン を使用しています。
コマンド内のフィールドは数段階に階層化されており、一部のフィールドは他のフィールドの値により構造が変化します。

コマンドは下記のフィールド、 ヘッダ と ペイロード から構成されます。

コマンド
長さ[byte]	フィールド名	概要
12	COMMAND_HEADER	コマンドのヘッダ（基本的な情報）
可変	COMMAND_PAYLOAD	コマンドのペイロード（詳細な情報） ※ `COMMAND_HEADER` の値によって変わります

COMMAND_HEADER 

コマンドの基本的な情報です。全てのコマンドで共通で、以下のフィールドから構成されます。

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

COMMAND_TYPE 

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

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

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

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

COMMAND_TYPE の値によって COMMAND_PAYLOAD の構成が変化します。詳細は COMMAND_PAYLOAD の項で解説します。

以下にコマンド種別一覧を示します。一覧にない値は将来のための予約値で、現時点では使われていません。

COMMAND_TYPE List
値	種別名	使用方向	概要
0x00	COMMAND_TYPE_OBJECTS_UP	uplink	1つ以上のオブジェクト（オブジェクト群）をデバイスアダプタへ送信
0x02	COMMAND_TYPE_TRANSMISSION_ID	downlink	`COMMAND_TYPE_OBJECTS_UP` で送信されたオブジェクト群に対する「転送ID」を応答する（ `COMMAND_TYPE_OBJECTS_UP` に対するデバイスアダプタからの応答）
0x11	COMMAND_TYPE_OBJECTS_DOWN_REQUEST	uplink	クラウドアプリケーションからデバイス宛に送信されたオブジェクト群を送るようにデバイスアダプタへ要求
0x12	COMMAND_TYPE_OBJECTS_DOWN	downlink	オブジェクト群を応答（ `COMMAND_TYPE_OBJECTS_DOWN_REQUEST` に対するデバイスアダプタからの応答）
0xFF	COMMAND_TYPE_ERROR	downlink	デバイスから送信されたコマンドに何らかの問題がある

COMMAND_SEND_TIMESTAMP_MS 

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

8byteの符号なし整数で、UNIXエポック（ 1970-01-01T00:00:00.000Z ）からの経過時間[ミリ秒]です。

デバイスからデバイスアダプタへの送信時 

デバイスからデバイスアダプタに対して送信する際には、デバイス側の現在時刻を設定して送信することを想定しています。ここで設定された時刻は、サービスアダプタを通してクラウドアプリケーションに渡されるJSONデータの timestamp_src フィールドに、RFC3339形式に変換されて適用されます。

この値はモノプラットフォーム内部では使われません。そのため、クラウドアプリケーション側で必要としない場合は必ずしも正確な値を指定する必要はありません。例えば全ビット0を指定すると、クラウドアプリケーションにはUNIXエポックが渡されます。

この時刻フィールドを指定すると、デバイスからの送信タイミングとクラウドアプリケーション側の動作タイミング等の関係を把握でき、デバッグに役立つ場合があります。

デバイスアダプタからデバイスへの送信時 

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

COMMAND_FLAGS 

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

COMMAND_PAYLOAD_LENGTH 

COMMAND_PAYLOAD の長さ（バイト数）を符号なし整数で設定します。実際の COMMAND_PAYLOAD の長さと正確に一致していなければなりません。

この値は1024byte以下でなければいけません 。

COMMAND_PAYLOAD 

ペイロードの構造は、ヘッダ内の COMMAND_TYPE によって異なります。また、 ペイロードの長さは1024byte以下でなければいけません 。

COMMAND_TYPEごとのペイロード構造 

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

COMMAND_TYPE_OBJECTS_UP 

デバイスからデバイスアダプタに対して送ります（uplink）。

オブジェクト群を送信する時に使うコマンドです。

ペイロードは、送信するオブジェクトをバイナリ形式で必要なだけ並べたものです。

ここで指定したオブジェクト群は、そのままの並び順でサービスアダプタからクラウドアプリケーションに渡されます。

COMMAND_PAYLOAD構造(COMMAND_TYPE_OBJECTS_UP)
長さ[byte]	フィールド名	データ型	概要
可変	OBJECT	オブジェクト	送信するオブジェクト1
可変	OBJECT	オブジェクト	送信するオブジェクト2
・・・	・・・	・・・	・・・

COMMAND_TYPE_TRANSMISSION_ID 

デバイスアダプタからデバイスに対して送られます（downlink）。

デバイスが送信した COMMAND_TYPE_OBJECTS_UP コマンドに対するデバイスアダプタからの返答コマンドです。 COMMAND_TYPE_OBJECTS_UP コマンドの結果と OTID （後述）をデバイスに対して通知します。

COMMAND_PAYLOAD構造(COMMAND_TYPE_TRANSMISSION_ID)
長さ[byte]	フィールド名	データ型	概要
1	OBJECTS_UP_RESULT	符号なし整数	結果コード
1	RESERVED	符号なし整数	将来のために予約されています。
16	OTID	符号なし整数	このオブジェクト群に割り振られたユニークID `OBJECTS_UP_RESULT` の値が `0x00` のときのみ意味のある値が入っていますそれ以外では意味を持たないので無視してください

COMMAND_TYPE_OBJECTS_DOWN_REQUEST 

デバイスからデバイスアダプタに対して送ります（uplink）。

自デバイス宛のオブジェクト群があったら送信するように要求するときに使用するコマンドです。

COMMAND_PAYLOAD構造(COMMAND_TYPE_OBJECTS_DOWN_REQUEST)
長さ[byte]	フィールド名	データ型	概要
1	RESERVED	符号なし整数	将来のために予約されています。

COMMAND_TYPE_OBJECTS_DOWN 

デバイスアダプタからデバイスに対して送られます（downlink）。

COMMAND_TYPE_OBJECTS_DOWN_REQUEST に対するデバイスアダプタの応答です。プラットフォームに滞留している、デバイス宛に送られたオブジェクト群が返されます。

クラウドアプリケーションからサービスアダプタに対して複数回オブジェクト群を送信した場合でも、プラットフォーム内でオブジェクト群が統合されることはありません。

プラットフォームに滞留しているオブジェクト群がない場合、オブジェクト群が空のペイロードが返されます。つまり、ペイロードの長さが35byteの場合はプラットフォームに滞留しているオブジェクト群がないとみなせます。

COMMAND_PAYLOAD構造(COMMAND_TYPE_OBJECTS_DOWN)
長さ[byte]	フィールド名	データ型	概要
1	OBJECTS_DOWN_REQUEST_RESULT	符号なし整数	`COMMAND_TYPE_OBJECTS_DOWN_REQUEST` に対する結果コード
16	OTID	符号なし整数	このオブジェクト群の転送に割り振られたユニークID
8	TIMESTAMP_SRC	符号なし整数	このオブジェクト群をクラウドアプリケーションがサービスアダプタへ送信したときの時刻
8	TIMESTAMP_PLATFORM_FROM_SRC	符号なし整数	このオブジェクト群をサービスアダプタがクラウドアプリケーションから受信した時の時刻
1	REMAINS	符号なし整数	まだプラットフォームに残っているオブジェクト群があるか
1	RESERVED	符号なし整数	将来のために予約されています。
可変	OBJECT	オブジェクト	受信したオブジェクト1
可変	OBJECT	オブジェクト	受信したオブジェクト2
・・・	・・・	・・・	・・・

COMMAND_TYPE_ERROR 

デバイスアダプタからデバイスに対して送られます（downlink）。

デバイスから発行される各種コマンドに対して、 COMMAND_HEADER に不備や不整合がある場合に応答されます。

COMMAND_PAYLOAD 側に不備や不整合がある場合は本応答ではなく、各コマンドに対応する応答内の結果コード（ OBJECTS_UP_RESULT 等）で通知されます。

COMMAND_PAYLOAD構造(COMMAND_TYPE_ERROR)
長さ[byte]	フィールド名	データ型	概要
1	ERROR_CODE	符号なし整数	エラーコード

各フィールドの説明 

ここでは、ペイロード内の各フィールドについて説明します。

OBJECTS_UP_RESULT 

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

以下に値一覧を示します。一覧にない値は将来のための予約値で、現時点では使われていません。

OBJECTS_UP_RESULT
コード値	意味
0x00	成功 OTIDには後述のユニークなIDが入ります
0x01	ペイロードの長さがオブジェクトとして必要な長さ（3byte）に満たない ※オブジェクトは、型（ OBJECT_TYPE ）・タグ（ OBJECT_TAG ）・長さ（ OBJECT_VALUE_LENGTH ）にそれぞれ1byteずつ要するため、最低3byte必要です。
0x02	型（ OBJECT_TYPE ）が定義域外
0x04	値の長さ（ OBJECT_VALUE_LENGTH ）が定義域外 ※0または221以上
0x05	値の長さ（ OBJECT_VALUE_LENGTH ）が、ペイロードの残りの長さを超えている ※例えば `COMMAND_PAYLOAD_LENGTH=6`, `OBJECT_VALUE_LENGTH=4` の場合に本エラーが発生します ※ `OBJECT_TYPE`, `OBJECT_TAG`, `OBJECT_VALUE_LENGTH` に各1byte、 `OBJECT_VALUE` に4byteでペイロードの長さは計7byte必要なため
0x06	値の長さ（ OBJECT_VALUE_LENGTH ）が、 OBJECT_TYPE で要求される長さと一致しない ※例えば `OBJECT_TYPE=0x00` （uint8）にもかかわらず `OBJECT_VALUE_LENGTH=2` の場合に本エラーが発生します
0x07	JSONで表現できない値（浮動小数点数のNaNやInfinity等）が渡された
0xFF	内部エラーデバイスアダプタ内部でエラーが発生した場合にこのエラーが返ります。しばらく時間を置いて再度試してください。

ERROR_CODE 

COMMAND_TYPE_ERROR コマンドのエラーコードです。

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

RESERVED 

将来のために予約されている値です。現時点では意味を持ちません。

アップリンク時にこの値を指定する必要がある場合は全ビット0を指定してください。また、ダウンリンク時にこのフィールドが含まれる場合は読み飛ばしてください。

OBJECTS_DOWN_REQUEST_RESULT 

1byteの符号なし整数です。

COMMAND_TYPE_OBJECTS_DOWN_REQUEST コマンドの結果コードです。

COMMAND_TYPE_OBJECTS_DOWN_REQUEST_RESULT
値	意味
0x00	コマンドを正常に処理した
0xff	内部エラー（データを正常に取得できなかった場合や、クラウドアプリケーションから送信されたデータのサイズが大きすぎる場合など）

OTID 

16byteの符号なし整数です。

転送されたオブジェクト群に対して付与されたユニークなIDです。このIDは OTID(Object Transfer ID) と呼びます。

デバイスからクラウドアプリケーション、または逆方向のいずれに対しても、オブジェクト群の送信時にはOTIDがデバイス・クラウドアプリケーションの両方に通知されます。これを利用して、デバイスとクラウドアプリケーションとでお互いに送信したオブジェクト群を識別・把握できます。

TIMESTAMP_SRC 

8byteの符号なし整数です。

クラウドアプリケーションからサービスアダプタに対してオブジェクト群を送信した際の timestamp_src フィールドの時刻です。 UNIXエポックからの経過秒数[ミリ秒]に変換した値が入ります。

なお、JSON上で timestamp_src フィールドは省略可能です。省略された場合は TIMESTAMP_SRC には全ビット0が入ります。

また、プラットフォームに滞留しているオブジェクト群がない場合にも TIMESTAMP_SRC には全ビット0が入ります。

TIMESTAMP_PLATFORM_FROM_SRC 

8byteの符号なし整数です。

クラウドアプリケーションからサービスアダプタに対してオブジェクト群を送信した際、 プラットフォーム側に届いた時点の時刻 です。 UNIXエポックからの経過秒数[ミリ秒]に変換した値が入ります。

なお、プラットフォームに滞留しているオブジェクト群がない場合には TIMESTAMP_PLATFORM_FROM_SRC には全ビット0が入ります。

REMAINS 

1byteの符号なし整数です。

今回デバイスアダプタから送信されたオブジェクト群の他に、まだプラットフォームに残っているオブジェクト群があるかどうかを示します。

まだ残っていれば1、もう残っていなければ0が入ります。

OBJECT 

送受信する値に、データ型およびタグ情報を付加してバイナリ形式で表したものです。

OBJECT
長さ[byte]	フィールド名	データ型	概要
1	OBJECT_TYPE	符号なし整数	OBJECT_VALUEの型種別
1	OBJECT_TAG	符号なし整数	OBJECT_VALUEにつけるタグ情報
1	OBJECT_VALUE_LENGTH	符号なし整数	OBJECT_VALUEの長さ
可変長	OBJECT_VALUE	OBJECT_TYPE に依存	オブジェクトの値

OBJECT_TYPE 

1byteの符号なし整数です。

OBJECT_VALUE の型種別、つまり OBJECT_VALUE のバイナリ列をどのように解釈すべきかを示します。

以下に型種別一覧を示します。一覧にない値は将来のための予約値で、現時点では使われていません。表内の「名称」は、データフォーマットの type と一致します。

OBJECT_TYPE一覧
`OBJECT_TYPE` の値	名称	`OBJECT_VALUE` の長さ[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 倍精度）
0x10	`binary`	可変	可変長バイト列 ※
0x20	`string.utf8`	可変	可変長UTF-8文字列 ※