nRF9160 Serial LTE MODEM applicationを利用したデバイスアダプタの利用例¶

[更新: 2022年9月15日]

本ドキュメントでは、デバイスアダプタの利用方法をnRF9160 Serial LTE MODEM application(以降nRF9160 SLM)を用いて解説します。ドキュメント内では説明の為PC上のターミナルで動作を例示しますが、 nRF9160 SLMを用いて行っている送受をMCU等を用いてデバイスに実装することで、実際にデバイスアダプタをご利用いただけます。

本ドキュメントで説明している構成に限らず、同様の通信が可能なデバイスであれば、任意のデバイスを利用してモノプラットフォームを利用いただけます。

ただし、どのような機材でも確実に動作することを保証するものではなく、個別の各デバイス自体の対応可否、LTE接続方法、設定/操作方法などはお客様ご自身で対応いただく必要があります。

本ドキュメントの想定環境 ¶

モノプラットフォームに登録したセキュアモバイルコネクトSIM: 現在のモノプラットフォームでは、セキュアモバイルコネクトを利用したLTEでの接続のみサポートしています。
nRF9160-DK: NORDIC社のnRF9160の評価ボードです。

https://www.nordicsemi.com/Products/Development-hardware/nrf9160-dk
nRF9160 DK application and modem firmware: 2022-06-02_880c82db(このバージョンで動作を確認しています)

https://www.nordicsemi.com/Products/Development-hardware/nRF9160-DK/Download#infotabs

利用方法概要 ¶

大まかに下記の手順で利用が可能となります。各手順の詳細については後述します。

事前準備
- SIMとモノプラットフォームの設定
- デバイス側の設定とLTEの接続
デバイスアダプタとの通信
- セッションキーの入手
- オブジェクトの送受

デバイスアダプタへのアクセス ¶

セッションキーの入手 ¶

SIPF Auth Protocol を使用して、モノプラットフォームを利用するためのセッションキーを入手します。

このセッションキーはセキュアモバイルコネクト回線経由でのみリクエスト可能で、接続に使用しているセキュアモバイルコネクトSIMに紐づいて自動的に生成されます。 SIPF Auth Protocolを使用してリクエストするたびに新たなセッションキーが生成され、過去に生成されたセッションキーは無効となります。また状況により無効となっている場合がありますのでセッションキーの利用時に問題がある時には再度セッションキーの取得を行ってください。

この機能により、お客様は各デバイス個体に対して固有キーを持たせることなく同一のプログラムでモノプラットフォームに対して異なる個体からのアクセスであることを識別させることができます。

この生成したセッションキーが有効な間は、他の「モノプラットフォームに登録されたセキュアモバイルコネクトSIMの回線」からでもこのセッションキーを使用してモノプラットフォームにアクセスできます。この時モノプラットフォーム上では「セッションキーを生成したセキュアモバイルコネクトSIMのデバイス」からのアクセスとして扱われる為、お客様の設計意図に合わせてキーを適切に管理してください。

SIPF Auth Protocolでのアクセス方法 ¶

後述の認証エンドポイントへ HTTP(HTTPS) POSTリクエストを送ることでセッションキーを入手できます。クエリストリングやリクエストボディは不要で、デバイスはアクセス元のアドレスを元に判別されます。

リクエストに成功すると、レスポンスボディにセッションキーとしてIDとパスワードが改行文字（LF, 文字コード 0x0a ）で区切られて返ります。一行目がID、二行目がパスワードで、パスワードの後ろにも改行が入ります（ID, 改行, パスワード, 改行の順）。

このセッションキーはリクエストするたびに新しいキーが生成され、以前のキーは利用できなくなります。このセッションキーはメモリ等に保存し、後述のオブジェクト送受信、ファイル送受信で利用します。デバイスの再起動等でセッションキーを紛失した場合は、再び認証エンドポイントからセッションキーを入手してください。

SIPF Auth protocol 認証エンドポイント ¶

HTTPでのリクエスト方法 ¶

セッションキーのリクエスト

AT#XHTTPCCON=1,"auth.sipf.iot.sakura.ad.jp",80
AT#XHTTPCREQ="POST","/v0/session_key",""
AT#XHTTPCCON=0

実行ログ

AT#XHTTPCCON=1,"auth.sipf.iot.sakura.ad.jp",80

#XHTTPCCON: 1

OK
AT#XHTTPCREQ="POST","/v0/session_key",""

OK

#XHTTPCREQ: 0
HTTP/1.1 200 OK
Server: nginx
Date: Thu, 01 Sep 2022 23:32:37 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 32
Connection: keep-alive


#XHTTPCRSP:156,1
uz2e9PDk5fRX
edceg-DCGYbximz#ZM

#XHTTPCRSP:32,1
AT#XHTTPCCON=0

#XHTTPCCON: 0

OK

このログの内:

uz2e9PDk5fRX
edceg-DCGYbximz#ZM

の部分が認証情報となります。一行目がユーザID、二行目がパスワードとなっており、各機能のbasic認証で使用します。

HTTPSでのリクエスト方法 ¶

セッションキーのリクエスト

AT#XHTTPCCON=1,"auth.sipf.iot.sakura.ad.jp",443,11
AT#XHTTPCREQ="POST","/v0/session_key",""
AT#XHTTPCCON=0

実行ログ

AT#XHTTPCCON=1,"auth.sipf.iot.sakura.ad.jp",443,11

#XHTTPCCON: 1

OK
AT#XHTTPCREQ="POST","/v0/session_key",""

OK

#XHTTPCREQ: 0
HTTP/1.1 200 OK
Server: nginx
Date: Thu, 01 Sep 2022 08:03:33 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 32
Connection: keep-alive


#XHTTPCRSP:156,1
uz2e9PDk5fRX
edceg-DCGYbximz#ZM

#XHTTPCRSP:32,1
AT#XHTTPCCON=0

#XHTTPCCON: 0

OK

このログの内:

uz2e9PDk5fRX
edceg-DCGYbximz#ZM

の部分が認証情報となります。一行目がユーザID、二行目がパスワードとなっており、各機能のbasic認証で使用します。

入手した認証キーの整形 ¶

nRF9160 SLMのATコマンドでBASIC認証を利用する時、IDとパスワードを : で連結したものをbase64エンコードしてオプションで渡す必要があります。
取得した認証キーが下記のような場合

uz2e9PDk5fRX
edceg-DCGYbximz#ZM

まず、IDとパスワードを : で連結し、下記のようにします。

uz2e9PDk5fRX:edceg-DCGYbximz#ZM

次にこの文字列をbase64エンコードし、下記のような文字列にします。

dXoyZTlQRGs1ZlJYOmVkY2VnLURDR1lieGlteiNaTQ==

以降の機能の利用時にこのbase64エンコードされた文字列を使用するので控えておく必要があります。

オブジェクト送受信機能の利用 ¶

SIPF Object Protocol を使用して、クラウドアプリケーションに対して温度や時間などの構造化された オブジェクト をバイナリデータでモノプラットフォームを介して送受できます。

オブジェクト、オブジェクト転送単位とは ¶

モノプラットフォームでは、「データ型」「タグ」「値」の組を オブジェクト と呼びます。このオブジェクトを送受することで、ただの数値や文字列の羅列の送受ではなく、温度や時間等の意味のある情報としてやり取りを行えます。

データ型: 値のデータ形式を表します。 32bit整数や文字列等、値のバイナリ表現をどう解釈するべきかの定義です。
タグ: 値が表しているものの定義です。お客様側で任意に定義可能で、値の意味するものをデバイスとクラウドアプリケーション間で共有できます。例えば、 1 は温度、 2 は時間など、あらかじめお客様側で取り決めておくことで、届いた情報を適切に処理できます。
値: 送信する値のバイナリ表現です。バイトオーダーは ビッグエンディアン で指定してください。

送受は、 オブジェクト転送単位 と呼ばれる1つ以上のオブジェクトのセットを単位として行います。オブジェクト転送単位でまとめられたオブジェクトは、デバイスアダプタサイドでもサービスアダプタサイドでも常に一塊で扱われ、オブジェクト同士が関連のある情報として扱かうことができ、管理することができます。 (例：時刻/温度/湿度/計測場所、4つのオブジェクトを転送単位にまとめることで、ある時間のある場所の温湿度の情報、として表現できます。)

デバイスアダプタに送信したバイナリデータはモノプラットフォーム内でJSON形式に変換され、サービスアダプタ・クラウドアプリケーション間ではJSON形式でやりとりされます。形式の詳細はデータフォーマットを参照ください。

デバイスアダプタ側での形式については SIPF Object Protocolで送受されるデータ形式についてで述べます。

SIPF Object Protocolで送受されるデータ形式について ¶

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

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

コマンド構造 ¶

コマンドのバイナリ構造の詳細は下記に記載してあります。
SIPF Object protocol コマンド構造

SIPF Object Protocolでのアクセス手段 ¶

SIPF Object Protocol コマンド形式のバイナリデータをデバイスアダプタとデバイスの間で送受する必要がありますが、 SIPF Object Protocolではその送受の下回りのプロトコルとしていくつかの手段を提供しています。その中から使用するデバイスが持つ機能等に応じてお客様側で選択いただけます。また今後の拡張として、より最適化されたプロトコルや、他の一般的なプロトコルの追加も検討しています。

現在はHTTPとHTTPSに対応しており、SIPF Object Protocolのバイナリデータをリクエスト/レスポンスボディとして送受できます。

デバイスからデバイスアダプタ方向へのオブジェクト送信方法 ¶

SIPF Auth Protocolで取得したセッションキーをBasic認証のユーザー名/パスワードに指定し、オブジェクトプロトコル用のエンドポイントに対して OBJECTS_UP コマンドをPOSTしてください。

コマンド自体についての詳細は COMMAND_TYPE_OBJECTS_UP を参照してください。

オブジェクトプロトコル用エンドポイント ¶

http://da.sipf.iot.sakura.ad.jp/v0

https://da.sipf.iot.sakura.ad.jp/v0

オブジェクト送信例 ¶

以下の各例では、リクエストボディーに Sample Binary for OBJECT_UP のバイナリ列を使用しています。

HTTP ¶

nRF9160 SLMのHTTPのATコマンドを用いてオブジェクトを送信します。
HTTP client AT commands

エンドポイントへの接続

まずデバイスアダプタのHTTPサーバーへ接続します。デバイスアダプタのhost名は da.sipf.iot.sakura.ad.jp になります。
```
AT#XHTTPCCON=1,"da.sipf.iot.sakura.ad.jp",80
```

デバイスアダプタへのhttp接続が成功すると次の応答が返ります。
#XHTTPCCON: 1

OK
HTermのInput control panelで、TypeにASCを選択、Send on enterにCR-LFをして、テキストボックスに上記ATコマンドを記入しEnterキーを押します。

送信要求。

デバイスアダプタに対してオブジェクトプロトコルのデータ本体をhttpのbodyとしてPOSTします。

HTTP method、パス、httpヘッダ(含むBASIC認証情報)、body type、body lengthを指定します。

BASIC認証情報は入手した認証キーの整形で生成した文字列を指定します。

body legthはオブジェクトプロトコルのデータ本体のbyte数を指定します。(#XHTTPCREQコマンドのbody終端に使用される +++ はこのlengthには含めません)

Sample Binary for OBJECT_UP では56になります。

AT#XHTTPCREQ="POST","/v0","Authorization:Basic dXoyZTlQRGs1ZlJYOmVkY2VnLURDR1lieGlteiNaTQ==\r\n","application/octet-stream",56
nRF9160 SLMに対してここまで送信すると下記の応答状態で待機になります。
OK

#XHTTPCREQ: 1
HTerm上ではこのような状態になります。

この状態になったらオブジェクトプロトコルの送信バイナリを送出します。

Sample Binary for OBJECT_UP のバイナリの末尾にbodyの終端を#XHTTPCREQコマンドに伝える +++ を付加して送信します。

送信バイナリ+ +++ のHEX表記例

00000000000000000000002c00010101030202ffff090308400921fb54442d1810040300112220050f303132616263414243e6bca2e5ad972b2b2b

HTermのInput control panelで、TypeにHEXを選択、Send on enterにNoneをして、テキストボックスに送信バイナリのHEX文字列と、と終端文字列の+++のASCIIコードをHEXで記入しEnterキーを押します。

HTerm上ではこのような状態になります。

エンドポイントからの切断

bodyの送信が終了したらデバイスアダプタのHTTPサーバから切断します。
AT#XHTTPCCON=0

HTermのInput control panelで、TypeにASCを選択、Send on enterにCR-LF選択をして、テキストボックスに切断のATコマンドを記入しEnterキーを押します。

HTerm上ではこのような状態になります。

コマンドの結果とOTIDの確認

先の#XHTTPCREQコマンドのレスポンス中に、オブジェクト送信のコマンドに対する応答も含まれています。下記の赤枠部がそのデータになります。(末尾のCF-LFはデータには含みません)

このデータにオブジェクト送信コマンドの結果と、成功していた場合はこの転送に割り当てられるID(OTID)が応答されます。このIDはサービスアダプタ経由でユーザサーバにも届けられ、必要に応じてユーザ側で到達の確認などに利用できます。

応答データ

02 00 00 01 83 16 FC 2C 93 00 00 12 00 00 83 96 81 9C 70 0A 4C 5D 9D DF FA CC 4D A5 63 2E

各フィールド概要

Field			Value	概要
COMMAND_HEADER	COMMAND_TYPE		02	COMMAND_TYPE_OBJECTS_UP
	COMMAND_SEND_TIMESTAMP_MS		00 00 01 83 16 FC 2C 93	送出時刻
	COMMAND_FLAGS		00	0(RSVD)
	COMMAND_PAYLOAD_LENGTH		00 12	18byte
COMMAND_PAYLOAD	COMMAND_TYPE_TRANSMISSION_ID	OBJECT_UP_RESULT	00	成功
		RESERVED	00	RSVD
		OTID	83 96 81 9C 70 0A 4C 5D 9D DF FA CC 4D A5 63 2E	OTID 0x8396819C700A4C5D9DDFFACC4DA5632E

オブジェクトを送信できていることの確認

デバイスから送信されたオブジェクトは 2. 送信データの確認から確認するのが一番容易です。 websocketのweb UIを表示した状態でオブジェクトを送信すると届いているのを確認できます。

サービスアダプタからクラウドアプリケーションに送信されるJSON例

{
  "id": "b68539df-b32b-4ef9-8d27-4da373e2c225",
  "device_id": "9819",
  "timestamp_src": "1970-01-01T00:00:00.000Z",
  "timestamp_platform_from_src": "2022-03-30T09:58:01.594Z",
  "timestamp_platform_to_dst": "2022-03-30T09:58:01.622Z",
  "type": "object",
  "payload": [
    {
      "type": "uint8",
      "tag": "01",
      "value": 1
    },
    {
      "type": "int16",
      "tag": "02",
      "value": -1
    },
    {
      "type": "float64",
      "tag": "03",
      "value": 3.141592653589793
    },
    {
      "type": "binary",
      "tag": "04",
      "value": "ABEi"
    },
    {
      "type": "string.utf8",
      "tag": "05",
      "value": "012abcABC漢字"
    }
  ]
}

HTTPS ¶

nRF9160 SLMのHTTPのATコマンドを用いてオブジェクトを送信します。
HTTP client AT commands

HTTPSにおけるコマンド送信方法は、ポートの違いとルート証明書の指定が必要なこと以外は基本的にHTTPと同じです。

エンドポイントへの接続

まずデバイスアダプタのHTTPサーバーへ接続します。デバイスアダプタのhost名は da.sipf.iot.sakura.ad.jp になります。また、証明書の書き込みで指定した証明書のtagを指定します。
```
AT#XHTTPCCON=1,"da.sipf.iot.sakura.ad.jp",443,222
```

デバイスアダプタへのhttp接続が成功すると次の応答が返ります。
#XHTTPCCON: 1

OK
HTermのInput control panelで、TypeにASCを選択、Send on enterにCR-LFをして、テキストボックスに上記ATコマンドを記入しEnterキーを押します。

送信要求。

デバイスアダプタに対してオブジェクトプロトコルのデータ本体をhttpのbodyとしてPOSTします。

HTTP method、パス、httpヘッダ(含むBASIC認証情報)、body type、body lengthを指定します。

BASIC認証情報は入手した認証キーの整形で生成した文字列を指定します。

body legthはオブジェクトプロトコルのデータ本体のbyte数を指定します。(#XHTTPCREQコマンドのbody終端に使用される +++ はこのlengthには含めません)

Sample Binary for OBJECT_UP では56になります。

AT#XHTTPCREQ="POST","/v0","Authorization:Basic dXoyZTlQRGs1ZlJYOmVkY2VnLURDR1lieGlteiNaTQ==\r\n","application/octet-stream",56
nRF9160 SLMに対してここまで送信すると下記の応答状態で待機になります。
OK

#XHTTPCREQ: 1
HTerm上ではこのような状態になります。

この状態になったらオブジェクトプロトコルの送信バイナリを送出します。

Sample Binary for OBJECT_UP のバイナリの末尾にbodyの終端を#XHTTPCREQコマンドに伝える +++ を付加して送信します。

送信バイナリ+ +++ のHEX表記例

00000000000000000000002c00010101030202ffff090308400921fb54442d1810040300112220050f303132616263414243e6bca2e5ad972b2b2b

HTermのInput control panelで、TypeにHEXを選択、Send on enterにNoneをして、テキストボックスに送信バイナリのHEX文字列と、と終端文字列の+++のASCIIコードをHEXで記入しEnterキーを押します。

HTerm上ではこのような状態になります。

エンドポイントからの切断

bodyの送信が終了したらデバイスアダプタのHTTPサーバから切断します。
AT#XHTTPCCON=0

HTermのInput control panelで、TypeにASCを選択、Send on enterにCR-LF選択をして、テキストボックスに切断のATコマンドを記入しEnterキーを押します。

HTerm上ではこのような状態になります。

コマンドの結果とOTIDの確認

先の#XHTTPCREQコマンドのレスポンス中に、オブジェクト送信のコマンドに対する応答も含まれています。下記の赤枠部がそのデータになります。(末尾のCF-LFはデータには含みません)

このデータにオブジェクト送信コマンドの結果と、成功していた場合はこの転送に割り当てられるID(OTID)が応答されます。このIDはサービスアダプタ経由でユーザサーバにも届けられ、必要に応じてユーザ側で到達の確認などに利用できます。

応答データ

02 00 00 01 83 2F 48 AE DB 00 00 12 00 00 C6 00 12 ED CE F8 45 36 A7 BE A8 11 97 F8 51 2A


02
00 00 01 83 2F 48 AE DB
00
00 12
00
00
C6 00 12 ED CE F8 45 36
A7 BE A8 11 97 F8 51 2A

各フィールド概要

Field			Value	概要
COMMAND_HEADER	COMMAND_TYPE		02	COMMAND_TYPE_OBJECTS_UP
	COMMAND_SEND_TIMESTAMP_MS		00 00 01 83 2F 48 AE DB	送出時刻
	COMMAND_FLAGS		00	0(RSVD)
	COMMAND_PAYLOAD_LENGTH		00 12	18byte
COMMAND_PAYLOAD	COMMAND_TYPE_TRANSMISSION_ID	OBJECT_UP_RESULT	00	成功
		RESERVED	01	RSVD
		OTID	C6 00 12 ED CE F8 45 36 A7 BE A8 11 97 F8 51 2A	OTID 0xC60012EDCEF84536A7BEA81197F8512A

オブジェクトを送信できていることの確認

デバイスから送信されたオブジェクトは 2. 送信データの確認から確認するのが一番容易です。 websocketのweb UIを表示した状態でオブジェクトを送信すると届いているのを確認できます。

サービスアダプタからクラウドアプリケーションに送信されるJSON例

{
  "id": "b68539df-b32b-4ef9-8d27-4da373e2c225",
  "device_id": "9819",
  "timestamp_src": "1970-01-01T00:00:00.000Z",
  "timestamp_platform_from_src": "2022-03-30T09:58:01.594Z",
  "timestamp_platform_to_dst": "2022-03-30T09:58:01.622Z",
  "type": "object",
  "payload": [
    {
      "type": "uint8",
      "tag": "01",
      "value": 1
    },
    {
      "type": "int16",
      "tag": "02",
      "value": -1
    },
    {
      "type": "float64",
      "tag": "03",
      "value": 3.141592653589793
    },
    {
      "type": "binary",
      "tag": "04",
      "value": "ABEi"
    },
    {
      "type": "string.utf8",
      "tag": "05",
      "value": "012abcABC漢字"
    }
  ]
}

デバイスアダプタからデバイス方向へのオブジェクト受信方法 ¶

SIPF Auth Protocolで取得したセッションキーをBasic認証のユーザー名/パスワードに指定し、オブジェクトプロトコル用のエンドポイントに対して OBJECTS_DOWN_REQUEST コマンドをPOSTしてください。

デバイスアダプタからは OBJECTS_DOWN コマンドが返ります。デバイスアダプタに対して受信すべきオブジェクトが到着していると、このコマンドには、クラウドアプリケーションから送られたオブジェクトがSIPF Object Protocolのバイナリ形式に変換されて格納されています。

詳細は COMMAND_TYPE_OBJECTS_DOWN_REQUEST 、 COMMAND_TYPE_OBJECTS_DOWN を参照してください。

オブジェクトプロトコル用エンドポイント ¶

http://da.sipf.iot.sakura.ad.jp/v0

https://da.sipf.iot.sakura.ad.jp/v0

オブジェクト送信と同様にセッションキーをBasic認証に指定して、 OBJECTS_DOWN_REQUEST コマンドをPOSTしてください。

オブジェクト受信例 ¶

クラウドアプリケーションからサービスアダプタに向けて、以下のようなJSONでオブジェクトを送信した場合の例で説明します。サービスアダプタへのオブジェクトへの送信方法は任意のクラウドアプリケーションから可能ですが、簡易的に行う方法としては WebSocket簡易UI を用意しています。

device_id の値は適宜利用されるデバイスに割り当てられているIDへの変更が必要です。コントロールパネルの、モノプラットフォーム-プロジェクトのデバイスタブでIDは確認できます。

{
  "device_id": "9426",
  "type": "object",
  "payload": [
    {
      "type": "uint8",
      "tag": "01",
      "value": 1
    },
    {
      "type": "int16",
      "tag": "02",
      "value": -1
    },
    {
      "type": "float64",
      "tag": "03",
      "value": 3.141592653589793
    },
    {
      "type": "binary",
      "tag": "04",
      "value": "ABEi"
    },
    {
      "type": "string.utf8",
      "tag": "05",
      "value": "012abcABC漢字"
    }
  ]
}

サービスアダプタからクラウドアプリケーションへは以下のようなJSONが応答されます。 (説明用データ取得の順序の都合上一部OTIDや時刻が異なります。適宜読み替えて対応をお願いします。)

{
  "device_id": "9426",
  "type": "notify",
  "id": "c012ecc7-147b-41ce-9d71-932b9a745bc2",
  "timestamp": "2022-09-13T01:38:32.562Z"
}

また以下の各例では、リクエストボディーに Sample Binary for OBJECT_DOWN_REQUEST を使用しています。

HTTP ¶

nRF9160 SLMのHTTPのATコマンドを用いてオブジェクトの受信要求を送信します。
HTTP client AT commands

エンドポイントへの接続

まずデバイスアダプタのHTTPサーバーへ接続します。デバイスアダプタのhost名は da.sipf.iot.sakura.ad.jp になります。
```
AT#XHTTPCCON=1,"da.sipf.iot.sakura.ad.jp",80
```

デバイスアダプタへのhttp接続が成功すると次の応答が返ります。
#XHTTPCCON: 1

OK
HTermのInput control panelで、TypeにASCを選択、Send on enterにCR-LFをして、テキストボックスに上記ATコマンドを記入しEnterキーを押します。

受信要求。

デバイスアダプタに対してオブジェクトプロトコルのデータ本体をhttpのbodyとしてPOSTします。

HTTP method、パス、httpヘッダ(含むBASIC認証情報)、body type、body lengthを指定します。

BASIC認証情報は入手した認証キーの整形で生成した文字列を指定します。

body legthはオブジェクトプロトコルのデータ本体のbyte数を指定します。(#XHTTPCREQコマンドのbody終端に使用される +++ はこのlengthには含めません)

Sample Binary for OBJECT_DOWN_REQUEST では13になります。

AT#XHTTPCREQ="POST","/v0","Authorization:Basic dXoyZTlQRGs1ZlJYOmVkY2VnLURDR1lieGlteiNaTQ==\r\n","application/octet-stream",13
nRF9160 SLMに対してここまで送信すると下記の応答状態で待機になります。
OK

#XHTTPCREQ: 1
HTerm上ではこのような状態になります。

この状態になったらオブジェクトプロトコルの受信要求のバイナリを送出します。

Sample Binary for OBJECT_DOWN_REQUEST のバイナリの末尾にbodyの終端を#XHTTPCREQコマンドに伝える +++ を付加して送信します。

受信要求バイナリ+ +++ のHEX表記例
110000000000000000000001002b2b2b

HTermのInput control panelで、TypeにHEXを選択、Send on enterにNoneをして、テキストボックスに受信要求バイナリのHEX文字列と、終端文字列の+++のASCIIコードをHEXで記入しEnterキーを押します。

HTerm上ではこのような状態になります。

エンドポイントからの切断

bodyの送信が終了したらデバイスアダプタのHTTPサーバから切断します。
AT#XHTTPCCON=0

HTermのInput control panelで、TypeにASCを選択、Send on enterにCR-LF選択をして、テキストボックスに切断のATコマンドを記入しEnterキーを押します。

HTerm上ではこのような状態になります。

コマンドの結果と受信オブジェクトの確認

先の#XHTTPCREQコマンドのレスポンス中に、オブジェクト受信要求のコマンドに対する応答も含まれています。下記の赤枠部がそのデータになります。(末尾のCF-LFはデータには含みません)

このデータにオブジェクト受信要求コマンドの結果と、成功していた場合は受信したオブジェクトとそのオブジェクトの転送に割り当てられるID(OTID)が応答されます。このIDはサービスアダプタ経由でクラウドアプリケーションに応答したOTIDと同じものであり、必要に応じてユーザ側で到達の確認などに利用できます。

応答データ

00 00 01 83 34 81 F3  2E 00 00 4F 00 C0 12 EC  C7 14 7B 41 CE 9D 71 93  2B 9A 74 5B C2 00 00 00
00 00 00 00 00 00 01  83 34 7F 77 F1 00 00 00  01 01 01 03 02 02 FF FF  09 03 08 40 09 21 FB 54
2D 18 10 04 03 00 11  22 20 05 0F 30 31 32 61  62 63 41 42 43 E6 BC A2  E5 AD 97

各フィールド概要

Field			Value	概要
COMMAND_HEADER	COMMAND_TYPE		12	COMMAND_TYPE_OBJECTS_DOWN
	COMMAND_SEND_TIMESTAMP_MS		00 00 01 83 34 81 F3 2E	デバイスアダプタ送出時刻
	COMMAND_FLAGS		00	0(RSVD)
	COMMAND_PAYLOAD_LENGTH		00 4F	79byte
COMMAND_PAYLOAD	OBJECT_DOWN_RESULT		00	成功
	OTID		C0 12 EC C7 14 7B 41 CE 9D 71 93 2B 9A 74 5B C2	OTID 0xC012ECC7147B41CE9D71932B9A745BC2
	TIMESTAMP_SRC		00 00 00 00 00 00 00 00	クラウドアプリケーション送出時刻(未使用)
	TIMESTAMP_PLATFORM_FROM_SRC		00 00 01 83 34 7F 77 F1	サービスアダプタ到着時刻
	REMAINS		00	残り未受信オブジェクト無し
	RSVD		00	RSVD
	OBJECT1	OBJECT_TYPE	00	uint8
		OBJECT_TAG	01	TAG 1
		OBJECT_VALUE_LENGTH	01	1byte
		OBJECT_VALUE	01	1
	OBJECT2	OBJECT_TYPE	03	int16
		OBJECT_TAG	02	TAG 2
		OBJECT_VALUE_LENGTH	02	2byte
		OBJECT_VALUE	FF FF	-1
	OBJECT3	OBJECT_TYPE	09	float64
		OBJECT_TAG	03	TAG 3
		OBJECT_VALUE_LENGTH	08	8byte
		OBJECT_VALUE	40 09 21 fb 54 44 2d 18	3.141592653589793
	OBJECT4	OBJECT_TYPE	10	Binary
		OBJECT_TAG	04	TAG 3
		OBJECT_VALUE_LENGTH	03	8byte
		OBJECT_VALUE	00 11 22	0x001122
	OBJECT5	OBJECT_TYPE	20	UTF-8
		OBJECT_TAG	05	TAG 3
		OBJECT_VALUE_LENGTH	0f	8byte
		OBJECT_VALUE	30 31 32 61 62 63 41 42 43 e6 bc a2 e5 ad 97	"012abcABC漢字"

HTTPS ¶

nRF9160 SLMのHTTPのATコマンドを用いてオブジェクトの受信要求を送信します。
HTTP client AT commands

エンドポイントへの接続

まずデバイスアダプタのHTTPサーバーへ接続します。デバイスアダプタのhost名は da.sipf.iot.sakura.ad.jp になります。
```
AT#XHTTPCCON=1,"da.sipf.iot.sakura.ad.jp",443,222
```

デバイスアダプタへのhttp接続が成功すると次の応答が返ります。
#XHTTPCCON: 1

OK
HTermのInput control panelで、TypeにASCを選択、Send on enterにCR-LFをして、テキストボックスに上記ATコマンドを記入しEnterキーを押します。

受信要求。

デバイスアダプタに対してオブジェクトプロトコルのデータ本体をhttpのbodyとしてPOSTします。

HTTP method、パス、httpヘッダ(含むBASIC認証情報)、body type、body lengthを指定します。

BASIC認証情報は入手した認証キーの整形で生成した文字列を指定します。

body legthはオブジェクトプロトコルのデータ本体のbyte数を指定します。(#XHTTPCREQコマンドのbody終端に使用される +++ はこのlengthには含めません)

Sample Binary for OBJECT_DOWN_REQUEST では13になります。

AT#XHTTPCREQ="POST","/v0","Authorization:Basic dXoyZTlQRGs1ZlJYOmVkY2VnLURDR1lieGlteiNaTQ==\r\n","application/octet-stream",13
nRF9160 SLMに対してここまで送信すると下記の応答状態で待機になります。
OK

#XHTTPCREQ: 1
HTerm上ではこのような状態になります。

この状態になったらオブジェクトプロトコルの受信要求のバイナリを送出します。

Sample Binary for OBJECT_DOWN_REQUEST のバイナリの末尾にbodyの終端を#XHTTPCREQコマンドに伝える +++ を付加して送信します。

受信要求バイナリ+ +++ のHEX表記例
110000000000000000000001002b2b2b

HTermのInput control panelで、TypeにHEXを選択、Send on enterにNoneをして、テキストボックスに受信要求バイナリのHEX文字列と、終端文字列の+++のASCIIコードをHEXで記入しEnterキーを押します。

HTerm上ではこのような状態になります。

エンドポイントからの切断

bodyの送信が終了したらデバイスアダプタのHTTPサーバから切断します。
AT#XHTTPCCON=0

HTermのInput control panelで、TypeにASCを選択、Send on enterにCR-LF選択をして、テキストボックスに切断のATコマンドを記入しEnterキーを押します。

HTerm上ではこのような状態になります。

コマンドの結果と受信オブジェクトの確認

先の#XHTTPCREQコマンドのレスポンス中に、オブジェクト受信要求のコマンドに対する応答も含まれています。下記の赤枠部がそのデータになります。(末尾のCF-LFはデータには含みません)

このデータにオブジェクト受信要求コマンドの結果と、成功していた場合は受信したオブジェクトとそのオブジェクトの転送に割り当てられるID(OTID)が応答されます。このIDはサービスアダプタ経由でクラウドアプリケーションに応答したOTIDと同じものであり、必要に応じてユーザ側で到達の確認などに利用できます。

応答データ

00 00 01 83 35 CD 6B  6D 00 00 4F 00 5E A4 AA  99 24 58 4B 81 90 57 64  40 86 8A 28 4D 00 00 00
00 00 00 00 00 00 01  83 35 C5 25 E1 00 00 00  01 01 01 03 02 02 FF FF  09 03 08 40 09 21 FB 54
2D 18 10 04 03 00 11  22 20 05 0F 30 31 32 61  62 63 41 42 43 E6 BC A2  E5 AD 97

各フィールド概要

Field			Value	概要
COMMAND_HEADER	COMMAND_TYPE		12	COMMAND_TYPE_OBJECTS_DOWN
	COMMAND_SEND_TIMESTAMP_MS		00 00 01 83 35 CD 6B 6D	デバイスアダプタ送出時刻
	COMMAND_FLAGS		00	0(RSVD)
	COMMAND_PAYLOAD_LENGTH		00 4F	79byte
COMMAND_PAYLOAD	OBJECT_DOWN_RESULT		00	成功
	OTID		5E A4 AA 99 24 58 4B 81 90 57 64 40 86 8A 28 4D	OTID 0xC012ECC7147B41CE9D71932B9A745BC2
	TIMESTAMP_SRC		00 00 00 00 00 00 00 00	クラウドアプリケーション送出時刻(未使用)
	TIMESTAMP_PLATFORM_FROM_SRC		00 00 01 83 35 C5 25 E1	サービスアダプタ到着時刻
	REMAINS		00	残り未受信オブジェクト無し
	RSVD		00	RSVD
	OBJECT1	OBJECT_TYPE	00	uint8
		OBJECT_TAG	01	TAG 1
		OBJECT_VALUE_LENGTH	01	1byte
		OBJECT_VALUE	01	1
	OBJECT2	OBJECT_TYPE	03	int16
		OBJECT_TAG	02	TAG 2
		OBJECT_VALUE_LENGTH	02	2byte
		OBJECT_VALUE	FF FF	-1
	OBJECT3	OBJECT_TYPE	09	float64
		OBJECT_TAG	03	TAG 3
		OBJECT_VALUE_LENGTH	08	8byte
		OBJECT_VALUE	40 09 21 fb 54 44 2d 18	3.141592653589793
	OBJECT4	OBJECT_TYPE	10	Binary
		OBJECT_TAG	04	TAG 3
		OBJECT_VALUE_LENGTH	03	8byte
		OBJECT_VALUE	00 11 22	0x001122
	OBJECT5	OBJECT_TYPE	20	UTF-8
		OBJECT_TAG	05	TAG 3
		OBJECT_VALUE_LENGTH	0f	8byte
		OBJECT_VALUE	30 31 32 61 62 63 41 42 43 e6 bc a2 e5 ad 97	"012abcABC漢字"

サンプルバイナリデータ ¶

Sample Binary for OBJECT_UP ¶

OBJECTS_UP.bin

このバイナリに含まれるオブジェクト

TAG=1 : uint8=1
TAG=2 : int16=-1
TAG=3 : float64=3.141592653589793
TAG=4 : bin=0x001122
TAG=5 : string_utf8="012abcABC漢字"

バイナリダンプ

00000000  00 00 00 00 00 00 00 00  00 00 00 2c 00 01 01 01  |...........,....|
00000010  03 02 02 ff ff 09 03 08  40 09 21 fb 54 44 2d 18  |........@.!.TD-.|
00000020  10 04 03 00 11 22 20 05  0f 30 31 32 61 62 63 41  |....." ..012abcA|
00000030  42 43 e6 bc a2 e5 ad 97                           |BC......|
00000038

各フィールド概要

Field			Value	概要
COMMAND_HEADER	COMMAND_TYPE		00	COMMAND_TYPE_OBJECTS_UP
	COMMAND_SEND_TIMESTAMP_MS		00 00 00 00 00 00 00 00	送出時刻(未使用)
	COMMAND_FLAGS		00	0(RSVD)
	COMMAND_PAYLOAD_LENGTH		00 2c	44byte
COMMAND_PAYLOAD	OBJECT1	OBJECT_TYPE	00	uint8
		OBJECT_TAG	01	TAG 1
		OBJECT_VALUE_LENGTH	01	1byte
		OBJECT_VALUE	01	1
	OBJECT2	OBJECT_TYPE	03	int16
		OBJECT_TAG	02	TAG 2
		OBJECT_VALUE_LENGTH	02	2byte
		OBJECT_VALUE	FF FF	-1
	OBJECT3	OBJECT_TYPE	09	float64
		OBJECT_TAG	03	TAG 3
		OBJECT_VALUE_LENGTH	08	8byte
		OBJECT_VALUE	40 09 21 fb 54 44 2d 18	3.141592653589793
	OBJECT4	OBJECT_TYPE	10	Binary
		OBJECT_TAG	04	TAG 3
		OBJECT_VALUE_LENGTH	03	8byte
		OBJECT_VALUE	00 11 22	0x001122
	OBJECT5	OBJECT_TYPE	20	UTF-8
		OBJECT_TAG	05	TAG 3
		OBJECT_VALUE_LENGTH	0f	8byte
		OBJECT_VALUE	30 31 32 61 62 63 41 42 43 e6 bc a2 e5 ad 97	"012abcABC漢字"

Sample Binary for OBJECT_DOWN_REQUEST ¶

OBJECTS_DOWN_REQUEST.bin

バイナリダンプ

00000000  11 00 00 00 00 00 00 00  00 00 00 01 00           |.............|
0000000d

各フィールド概要

Field		Value	概要
COMMAND_HEADER	COMMAND_TYPE	11	COMMAND_TYPE_OBJECTS_DOWN_REQUEST
	COMMAND_SEND_TIMESTAMP_MS	00 00 00 00 00 00 00 00	送出時刻(未使用)
	COMMAND_FLAGS	00	0(RSVD)
	COMMAND_PAYLOAD_LENGTH	00 01	1byte
COMMAND_PAYLOAD	RSVD	00	uint8

nRF9160 Serial LTE MODEM applicationを利用したデバイスアダプタの利用例¶

本ドキュメントの想定環境 ¶

利用方法概要 ¶

事前準備 ¶

SIMとモノプラットフォームの設定 ¶

SIMとプロジェクトの登録 ¶

サービスアダプタの追加 ¶

PCの設定 ¶

HTerm ¶

nRF9160-DKの設定 ¶

シリアルポート設定 ¶

シリアルポートの確認 ¶

HTermでのシリアル接続例 ¶

ルート証明書の入手とnRF9160への書き込み ¶

nRF9160-DKのLTE接続 ¶

デバイスアダプタへのアクセス ¶

セッションキーの入手 ¶

SIPF Auth Protocolでのアクセス方法 ¶

SIPF Auth protocol 認証エンドポイント ¶

HTTPでのリクエスト方法 ¶

HTTPSでのリクエスト方法 ¶

入手した認証キーの整形 ¶

オブジェクト送受信機能の利用 ¶

オブジェクト、オブジェクト転送単位とは ¶

SIPF Object Protocolで送受されるデータ形式について ¶

コマンド構造 ¶

SIPF Object Protocolでのアクセス手段 ¶

デバイスからデバイスアダプタ方向へのオブジェクト送信方法 ¶

オブジェクトプロトコル用エンドポイント ¶

オブジェクト送信例 ¶

HTTP ¶

HTTPS ¶

デバイスアダプタからデバイス方向へのオブジェクト受信方法 ¶

オブジェクトプロトコル用エンドポイント ¶

オブジェクト受信例 ¶

HTTP ¶

HTTPS ¶

サンプルバイナリデータ ¶

Sample Binary for OBJECT_UP ¶

Sample Binary for OBJECT_DOWN_REQUEST ¶