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

利用方法概要

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

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

事前準備

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

SIMとプロジェクトの登録

ご利用の流れ（SCO-LTEM1NUC） の2～4を参考に 利用予定のセキュアモバイルコネクトSIMをモノプラットフォームのプロジェクトへ紐付けを行ってください。

サービスアダプタの追加

クラウドアプリケーション側の動作確認用として ご利用の流れ（SCO-LTEM1NUC） の7-1を参考にwebsocketのサービスアダプタを追加してください。

PCの設定

ここではwindows PCを前提として説明しています。 同様の作業が可能なツールがあれば他のOSでも可能かと思われます。

本ドキュメントの手順は下記のターミナルを使用して確認しております。 一部手順が送受データの都合でターミナルソフトにより扱いが難しいためソフトを指定して説明を行っています。

HTerm

一部バイナリデータの送受を必要とするため、バイナリデータの見やすさ送りやすさからこちらのターミナルを使用します。
http://der-hammer.info/pages/terminal.html
バイナリデータとの同時表示の為、下記のスクリーンショットの設定での利用を推奨します。
(Input control panelのTypeとSend on enterは状況に合わせて切り替えて使用します。)
hterm_setting.png hterm_setting_option.png

nRF9160-DKの設定

Getting started with nRF9160 DK の、Minimum requirements、Updating the DK firmwareの項を参考に、 nRF9160-DK application and modem firmwareとnRF9160 SiP modem firmwareを整えてください。

また何か初期状態とは異なる状態になっている可能性がある場合にはファクトリーリセットを試してください。

AT%XFACTORYRESET=0

動作の確認はnRF9160-DKのUSB-UARTコンソールをターミナルから操作します。 ターミナルソフトでnRF9160-DKとシリアル通信できる状態としてください。

シリアルポート設定

  • 115200bps、 8bit、パリティ無し、ストップビット1bit
  • 使用される改行コード 受信/送信方向共に:CR+LF
  • ローカルエコー : ON

シリアルポートの確認

nRF9160-DKをPCに接続すると３つのシリアルポートが認識されますが、うち一つのみがATコマンド用のポートです。 本ドキュメントの作業ではATコマンド用のポートを使用しますので、このポートの番号を確認しておきます。 ターミナルでATと打った際にOKが返ってくるポートがATコマンド用のポートです。

HTermでのシリアル接続例

左上のconnectボタンで適切なシリアルポートに接続し、ATコマンドを送った例です。

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

モノプラットフォーム用のルート証明書はこちらからダウンロードできます。
SAKURAIoTRootCA.crt

nRF9160-DKのATコマンドポートに接続し任意のターミナルソフトから %CMNGコマンドを使用してnRF9160へ証明書を書き込みます
Credential storage management %CMNG

本ドキュメントでは証明書がtag 222番に書き込まれているとして説明します。

書き込み例

AT%CMNG=0,222,0,"
-----BEGIN CERTIFICATE-----
MIIDvDCCAqSgAwIBAgIBATANBgkqhkiG9w0BAQsFADBuMQswCQYDVQQGEwJKUDEO
MAwGA1UECAwFT3Nha2ExEzARBgNVBAcMCk9zYWthLUNpdHkxHTAbBgNVBAoMFFNB
S1VSQSBpbnRlcm5ldCBJbmMuMRswGQYDVQQDDBJTQUtVUkEgSW9UIFJvb3QgQ0Ew
IBcNMjEwNzA1MDAyMjU4WhgPMzAyMDExMDUwMDIyNThaMG4xCzAJBgNVBAYTAkpQ
MQ4wDAYDVQQIDAVPc2FrYTETMBEGA1UEBwwKT3Nha2EtQ2l0eTEdMBsGA1UECgwU
U0FLVVJBIGludGVybmV0IEluYy4xGzAZBgNVBAMMElNBS1VSQSBJb1QgUm9vdCBD
QTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAL0zQFgyYX796DUPRGkK
gYl8tZAtxmyviS+qiZtHA0IbojbI6Du9Bql69FU9CovFpGDRRLpgdqAVAyBIQUFl
496FIBzYWymA5Owu0NWwXK0xpd6hgNuudCd8x74rp9tipR+wI6+VWhW6hMClMiBH
bxs7AkMnTE4e68oWZ/dIxsMmcD0uanpBvSKXW2RHK4jPp9dcMVeCcnPoEP3fE6Up
eb5iyszb1spT81Idbvqj7K1hQZ7MLhc1CKgtqmgt4czUqlqn5Qx5rXLhGNZIlAmz
k3jJwJ4nzK2zQMf4N5MGa48MW3tAHDpJW8cvXBVUdPBUjDQbtyZfvAbxSIzHuM+b
TQMCAwEAAaNjMGEwHQYDVR0OBBYEFO+mxxbwfw+PcRHppDm8qDvu1vj5MB8GA1Ud
IwQYMBaAFO+mxxbwfw+PcRHppDm8qDvu1vj5MA8GA1UdEwEB/wQFMAMBAf8wDgYD
VR0PAQH/BAQDAgGGMA0GCSqGSIb3DQEBCwUAA4IBAQCXANbPp0ExgAOH8YBVmOwt
VrGoFeq/I3Ox6e9ySZso8nTJVyVKaLBPKfwbSYIfAVTRS2Nvz/OnOyC2Yhu9gIgL
6MNrEqgMP6cSHKdMKUcUeJiGIJm8ZzXGKZ92WuVhdNvQZGqAsJjQcJgCyFgA80Ca
wFYPwveiYzuvAGuTUk0B7ZD3t9/rIlb1d+VSpLjsSp8RC40n18rEjMUMpvBV1y1a
cYCdGB99WD9W7iRZOpH9l9mEbiwRTCbuTvGwbrT3BvhA9869sW0CcvPKW49D7Z3z
Eo+4monPLeooX+knx96eIj6pJ/kFnn70oaPFXCjmaLjTisk5IXAh3zX4gP37a6DE
-----END CERTIFICATE-----"

OK
AT%CMNG=1

%CMNG: 0,6,"0606060606060606060606060606060606060606060606060606060606060606"
%CMNG: 42,0,"59AD0FE6DE08C5294E6E5B6A4A6C6180D4DD6E3A27FDA2454282D6A716C8FD60"
%CMNG: 222,0,"B945534633B951AFF9FEA8FCE8AC31C8B6DF4A6B68007E1883A5E51467BB7100"
%CMNG: 4242424,0,"D1C290EA1E4544DEC1934931FBFA1FB2060EB3A0F2239BA191F444ECBCE35CBB"
%CMNG: 16842753,0,"2C43952EE9E000FF2ACC4E2ED0897C0A72AD5FA72C3D934E81741CBD54F05BD1"
%CMNG: 16842753,1,"DF352B346E2AD8F678701433D700A9D55C5BD56BDD51E79B2EE407B77CECC491"
%CMNG: 16842753,2,"777EBDC497532CD4C9B71785BD6BD5A70A039A34C06124ADC8664D53CBD040B6"
%CMNG: 4294967293,10,"2C43952EE9E000FF2ACC4E2ED0897C0A72AD5FA72C3D934E81741CBD54F05BD1"
%CMNG: 4294967294,6,"CD17107A52DE05A929D8C4A8892768A8E5520B3A7AD92D88AE31114EBAEAF098"
%CMNG: 4294967292,11,"B2C46C2AE7C81943A8BD6DD4ED2A50B659A225A098A177BACB575459CD57CAEF"

OK

証明書リストで出てくる書き込んだもの以外の証明書の種類や数は今までの使用状況により異なります。 書き込んだ222番が正しく書き込まれていれば問題ありません。

HTermでの書き込み、

および確認の様子です。

nRF9160-DKのLTE接続

nRF9160-DKをLTE網に接続します。

こちらの情報を参考に接続を行います。 接続後、作成したモノプラットフォームのプロジェクトに登録されているSIMの情報ページでセッションがCreateになり、PC側でSIMの情報ページに記載されているIPアドレスが取得できていれば接続できています。

接続コマンド例

AT+CGDCONT=1,"IP","sakura"
AT+CEREG=5
AT+CPSMS=0
AT%XSYSTEMMODE=1,0,0,0
AT+COPS=1,2,"44020"
AT+CFUN=1
AT+COPS?
AT+CGATT?
AT%XCBAND
AT+CESQ
AT%NBRGRSRP
AT+CGDCONT?

接続ログ

Ready
AT+CGDCONT=1,"IP","sakura"

OK
AT+CEREG=5

OK
AT+CPSMS=0

OK
AT%XSYSTEMMODE=1,0,0,0

OK
AT+COPS=1,2,"44020"

OK
AT+CFUN=1

OK

+CEREG: 0

+CEREG: 2,"1810","01835B02",7

+CEREG: 5,"1810","01835B02",7,0,18,"11100000","11100000"
AT+COPS?

+COPS: 1,2,"44020",7

OK
AT+CGATT?

+CGATT: 1

OK
AT%XCBAND

%XCBAND: 1

OK
AT+CESQ

+CESQ: 99,99,255,255,11,38

OK
AT%NBRGRSRP

%NBRGRSRP: 174,475,46,325,475,42,186,475,35

OK
AT+CGDCONT?

+CGDCONT: 0,"IP","sakura","10.64.173.162",0,0
+CGDCONT: 1,"IP","sakura","",0,0

OK

以降の説明はLTE接続状態が維持されている前提となります。

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

セッションキーの入手

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

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

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

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

SIPF Auth Protocolでのアクセス方法

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

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

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

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 を参照してください。

オブジェクト送信例

以下の各例では、リクエストボディーに 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キーを押します。

hterm_obj_http_connect_cmd.png


hterm_obj_http_connected.png

  • 送信要求。

    デバイスアダプタに対してオブジェクトプロトコルのデータ本体を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上ではこのような状態になります。

hterm_obj_http_post_req.png



この状態になったらオブジェクトプロトコルの送信バイナリを送出します。
Sample Binary for OBJECT_UP のバイナリの末尾にbodyの終端を#XHTTPCREQコマンドに伝える +++ を付加して送信します。


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

00000000000000000000002c00010101030202ffff090308400921fb54442d1810040300112220050f303132616263414243e6bca2e5ad972b2b2b

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

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

hterm_obj_http_post_body.png



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

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

AT#XHTTPCCON=0

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

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

hterm_obj_http_disconnect.png



  • コマンドの結果と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キーを押します。

hterm_obj_https_connect_cmd.png


hterm_obj_https_connected.png

  • 送信要求。

    デバイスアダプタに対してオブジェクトプロトコルのデータ本体を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上ではこのような状態になります。

hterm_obj_https_post_req.png



この状態になったらオブジェクトプロトコルの送信バイナリを送出します。
Sample Binary for OBJECT_UP のバイナリの末尾にbodyの終端を#XHTTPCREQコマンドに伝える +++ を付加して送信します。


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

00000000000000000000002c00010101030202ffff090308400921fb54442d1810040300112220050f303132616263414243e6bca2e5ad972b2b2b

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

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

hterm_obj_https_post_body.png



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

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

AT#XHTTPCCON=0

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

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

hterm_obj_https_disconnect.png



  • コマンドの結果と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 を参照してください。

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

オブジェクト送信と同様にセッションキーを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キーを押します。

hterm_obj_http_connect_cmd.png


hterm_obj_http_connected.png

  • 受信要求。

    デバイスアダプタに対してオブジェクトプロトコルのデータ本体を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上ではこのような状態になります。

hterm_objdown_http_post_req.png



この状態になったらオブジェクトプロトコルの受信要求のバイナリを送出します。
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上ではこのような状態になります。

hterm_objdown_http_post_body.png



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

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

AT#XHTTPCCON=0

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

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

hterm_objdown_http_disconnect.png



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

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

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

応答データ

12 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 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
44 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キーを押します。

hterm_obj_https_connect_cmd.png


hterm_obj_https_connected.png

  • 受信要求。

    デバイスアダプタに対してオブジェクトプロトコルのデータ本体を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上ではこのような状態になります。

hterm_objdown_https_post_req.png



この状態になったらオブジェクトプロトコルの受信要求のバイナリを送出します。
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上ではこのような状態になります。

hterm_objdown_https_post_body.png



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

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

AT#XHTTPCCON=0

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

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

hterm_objdown_https_disconnect.png



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

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

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

応答データ

12 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 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
44 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