1. MSM-PF端末との通信

本節ではMSM-PF端末との通信に関する仕様を説明します。

1.1. 接続構成

下図のようにMSM-PF端末とMSM-PFクラウドサービス間は、管理情報用とデータ交換用の2つの MQTTS接続を行います。また、ファイルダウンロード時にはHTTPSが使用されます。

1.2. 認証

MSM-PF端末には個体毎のIDとクライアント証明書が発行され、MSM-PF端末内に保持しています。MSM-PFクラウドサービスとの通信には MQTTSとHTTPSがありますが、どちらの場合にもクライアント証明書を使ったクライアント認証が行われます。

1.3. 端末管理情報

MSM-PFクラウドサービスは、センサー設定ファイルやファームウェアを MSM-PF端末へ配信します。これは、MSM-PF端末が以下のステップを実行することで実現されています。

• 端末管理情報を取得する

• 端末管理情報に含まれるセンサー設定ファイルやファームウェアの入手先URLから、ファイルをダウンロードする

端末管理情報はMSM-PF端末からMSM-PFクラウドサービスへ各種動作状態を通知することにも使用します。

端末管理情報は以下の構造の JSONです。

MSM-PFクラウドサービスからMSM-PF端末への通知

キー	型	説明
sensor_settings	オブジェクト	センサー設定ファイルの情報
sensor_settings.url	文字列	センサー設定ファイルをダウンロードするための URL
fw	オブジェクト	配信中のファームウェアの情報
fw.fpga	オブジェクト	FPGAコンフィグレーションデータ
fw.fpga.version	文字列	バージョン
fw.fpga.url	文字列	ファイル配布URL
fw.fpga.md5	文字列	ファイルのMD5ハッシュ値
fw.edge	オブジェクト	エッジ処理プログラム
fw.edge.version	文字列	バージョン
fw.edge.url	文字列	ファイル配布URL
fw.edge.md5	文字列	ファイルのMD5ハッシュ値

MSM-PF端末からMSM-PFクラウドサービスへの通知

キー	型	説明
current_fw	オブジェクト	MSM-PF端末の動作状態
current_fw.fpga	オブジェクト	FPGAコンフィグレーション
current_fw.fpga.version	文字列	動作中のバージョン
current_fw.edge	オブジェクト	エッジ処理プログラム
current_fw.edge.version	文字列	動作中のバージョン
current_fw.status	オブジェクト	動作状態
current_fw.status.status_code	文字列	動作状態コード
current_fw.status.description	文字列	動作状態の説明

端末管理情報の交換には、管理情報用のMQTTS接続で AWS IoT Coreのデバイスシャドウ機能を使用します。具体的には、デバイスシャドウのうちの名前なしデバイスシャドウのstate.reportedプロパティに端末管理情報を格納します。

デバイスシャドウの取得方法や更新方法は、AWS IoT Coreのドキュメントを参照してください。

1.4. ファイルダウンロード

端末管理情報で得られたセンサー設定ファイルやファームウェアファイルのURLに対し、MSM-PF端末はHTTPS GETを行って、ファイルを取得します。ステータスコード302により、他のURLへのリダイレクトが返される場合があります。

1.5. センサーデータのアップロード

MSM-PF端末が収集したセンサーデータは、タイムスタンプとセンサー毎の値が並ぶ表の形に表現できます。センサー毎にサンプリング間隔は異なる場合がありますので、表のセルすべてにセンサー値が入っているとは限らないことに注意が必要です。

この表の行は、あるタイムスタンプ時に取得したセンサー値の集まりです。以下の説明では、この表の行を「サンプル点」と呼びます。

収集したセンサーデータの例

タイムスタンプ	センサー1	センサー2	センサー3	センサー4
2022-09-14T02:31:01.123456Z	100	20	0	874
2022-09-14T02:31:01.623460Z	101	20		790
2022-09-14T02:31:02.123459Z	99		131	826
2022-09-14T02:31:02.623457Z	102			881
2022-09-14T02:31:02.623457Z	97	21	62	830

MSM-PF端末は、データ交換用の MQTTS接続を使用してセンサーデータをアップロードします。MQTTメッセージの最大サイズは 4MBです。

センサーデータには 2つの形式があり、形式により使用する MQTTトピックが異なります。MQTTトピック中の %cは MSM-PF端末のIDに置き換えてください。

センサーデータの形式と使用するMQTTトピック

センサーデータの形式	MQTTトピック	MQTT QoS
sensordata形式	things/%c/sensordata	0 または 1
sensorjson形式	things/%c/sensorjson	0 または 1

どちらのメッセージ形式の場合も、1つのメッセージの中に複数のサンプル点を含むことができます。メッセージ内のサンプル点は、タイムスタンプは昇順に並んでいなければならず、また同じタイムスタンプが複数回含まれていてはなりません。同様に送信されるメッセージの間でも、含まれるサンプル点のタイムスタンプは昇順に並んでいなければならず、また同じタイムスタンプが複数回含まれていてはなりません。

1.5.1. sensordata形式

タイムスタンプは UTCの1970年1月1日0時0分0秒からの経過時間で表現します。粒度はマイクロ秒で、経過時間を秒単位で表したときの整数部分と、1秒に満たない部分をマイクロ秒単位の整数とした、2つの数値の組み合わせで表現します。

1つのサンプル点は以下の形式で表現します。

1つのサンプル点のデータ構造

キー	型	説明
timestamp sec	文字列	タイムスタンプの秒部分を文字列にしたもの
timestamp usec	文字列	タイムスタンプのマイクロ秒部分を文字列にしたもの
sensor values	文字列	サンプル点内のセンサー値をカンマでつないだ文字列

MSM-PFクラウドへ送信するメッセージは、以下の表の sensordata形式のJSONとします。

sensordata形式

キー	型	説明
terminalId	文字列	MSM-PF端末のID
dateset number	文字列	dataset配列の要素数を文字列にしたもの
dataset	配列	各サンプル点のオブジェクトの配列

以下にsensordata形式のメッセージ例を記載します。インデントや改行を含んでいますが、これは説明を見やすくするためのものであり、送信メッセージには不要です。

{
  "terminalId": "MSMPF-33",
  "dataset number": "2",
  "dataset": [
    {
      "timestamp sec": "1663150180",
      "timestamp usec": "358",
      "sensor values": "1,0,12,,,,,,,,,,,40030,309,21"
    }, {
      "timestamp sec": "1663150180",
      "timestamp usec": "100359",
      "sensor values": "20,1,,,,3,4,,,,,,,40030,,19"
    }
  ]
}

1.5.2. sensorjson形式

sensorjson形式は、sensordata形式ではできない柔軟な構成を表現することができます。

sensordata形式はカラムとセンサーの対応付けを固定できることが前提となります。例えば複数の MSM-PF端末やセンサーデバイスを集約するゲートウェイを使う構成では、集約対象のMSM-PF端末やセンサーデバイスの追加や削除が発生します。この場合、カラムとセンサーの対応付けが変化するため、sensordata形式では表現できません。sensorjson形式ではセンサーデータ内にセンサー名等の情報を含めることができますので、センサーの追加や削除にも柔軟に対応することができます。

sensorjson形式で、1つのサンプル点を表現する構造例を以下に示します。

_timestampは UTCの1970年1月1日0時0分0秒からの経過時間(ミリ秒単位)で、少数部を使ってマイクロ秒の粒度を表現します。

1つのサンプル点のデータ構造

キー	型	説明
device	文字列	センサーデバイスの名称
id	文字列	センサーデバイスのID
sensor	文字列	センサーデバイス中のセンサー名
timestamp	数値	センサーデバイスが起動してからの経過時間(ミリ秒)
_timestamp	数値	タイムスタンプ
(センサーに依存したキー)	任意	センサー値、ラベル、単位等

sensorjson形式は、サンプル点のオブジェクトを1つ以上並べた配列のJSONです。

以下にsensorjson形式のメッセージ例を記載します。インデントや改行を含んでいますが、これは説明を見やすくするためのものであり、送信メッセージには不要です。

[
  {
    "device": "preMSM",
    "id": "2D7E",
    "sensor": "BME680",
    "timestamp": 5636.84,
    "_timestamp": 1663150180636.84,
    "temp": {
      "val": 31.13
    },
    "humid": {
      "val": 63.44
    },
    "press": {
      "val": 1017.54
    },
    "gas": {
      "val": 123.98
    }
  },
  {
    "device": "preMSM",
    "id": "2D7E",
    "sensor": "MCP4725",
    "timestamp": 5849.84,
    "_timestamp": 1663150180849.84,
    "DAC0": {
      "val": 1.65
    }
  }
]

1.6. 制御メッセージ通信

制御メッセージ通信には、センサーデータのアップロードに使うデータ交換用MQTTS接続を共用します。上り制御メッセージと下り制御メッセージには、以下のMQTTトピックを使用します。MQTTトピック中の%cはMSM-PF端末のIDに置き換えてください。

制御メッセージ通信に使用するMQTTトピック

制御メッセージの方向	MQTTトピック	MQTT QoS
上り制御メッセージ	things/%c/ctl-upstream	0
下り制御メッセージ	things/%c/ctl-downstream	0

制御メッセージはJSONのオブジェクトです。必須プロパティはtimestampで、UTCの1970年1月1日0時0分0秒からの経過時間(ミリ秒単位の数値)を送信側が設定します。

timestamp以外のプロパティは規定されていません。制御メッセージの内容、それによる挙動は、MSM-PF端末上のアプリケーションとダッシュボードの間で決定します。