EzData2 Device インターフェースドキュメント

1. 概要

EzData2 は現在、MQTT と WebSocket の 2 種類の接続方式を提供しており、デバイス側でのデータ連携を実現できます。 デバイスを接続する前に、ハードウェアデバイスの MAC アドレスを使用して登録インターフェースを呼び出し、Device Token を取得する必要があります。登録が完了し、Device Token を正常に取得した後、my.m5stack.com にアクセスして個人アカウントにログインし、Add Group をクリックして Token オプションを選択します。 Device Token をコピーして貼り付けることで作成が完了し、Device Token とアカウントの紐付けが行われます。単一デバイスの Device Token は、1 つのデータセット Group に相当します。 デバイス側では、以下の通信プロトコルを参照し、Device Token によるログイン認証完了後、データフィールドの追加・削除・更新・取得（CRUD）操作を行うことができます。

2. 基本定義

2.1 コマンドとレスポンス（CMD / RequestType）

3. HTTP インターフェース

3.1 デバイス登録

エンドポイント： https://ezdata2.m5stack.com/api/v2/device/registerMac メソッド： POST 説明： MAC アドレスを使用してデバイスを登録し、deviceToken を生成します。

リクエストパラメータ：

• deviceType: 開発ボード定義 内の Product name フィールドを参照
• mac: デバイスの MAC アドレス（「:」区切りなし、大文字小文字は不問）

{ "deviceType": "", "mac": "" }

レスポンスパラメータ：

{ "code": 0, "data": "", "msg": "" }

3.2 デバイスファイルアップロード

エンドポイント： https://ezdata2.m5stack.com/api/v2/device/uploadDeviceFile メソッド： POST 説明： HTTP 経由でファイルをアップロードします。アップロードが成功すると、サーバーは WebSocket / MQTT を通じて cmd: 105 のレスポンスメッセージを送信します。

4. 接続プロトコル

4.1 WebSocket 接続

WS アドレス： wss://ezdata2.m5stack.com/ws

4.1.1 ログイン

リクエスト：

{ "deviceToken": "4fbb52fb5b6243e083377f45d216820f" }

レスポンス：

device Login successful

4.1.2 ハートビート（Heartbeat）

リクエスト：

{ "deviceToken": "4fbb52fb5b6243e083377f45d216820f", "body": "ping" }

レスポンス：

pong

4.2 MQTT 接続

サーバーアドレス： uiflow2.m5stack.com ポート： 1883

接続情報：

• 名称： ez{mac}ez

• ClientId： ez{mac}ez

• ユーザー名： {deviceToken}（デバイスの Token）

• mac: デバイスの MAC アドレス（「:」区切りなし、大文字小文字は不問）

Topic（トピック）：

• アップリンク（Publish）： $ezdata/{deviceToken}/up
• ダウンリンク（Subscribe）： $ezdata/{deviceToken}/down

5. 業務データ通信（Payload）

以下は WebSocket または MQTT のメッセージボディ内容です。

5.1 データ追加（CMD: 100）

リクエスト：

{ "deviceToken": "4fbb52fb5b6243e083377f45d216820f", "body": { "name": "adasd", "value": "ddsad", "requestType": 100 } }

レスポンス：

{ "body": { "deviceToken": "4fbb52fb5b6243e083377f45d216820f", "name": "adasd", "value": "ddsad" }, "cmd": 100, "code": 200 }

5.2 データ変更（CMD: 101）

リクエスト：

{ "deviceToken": "4fbb52fb5b6243e083377f45d216820f", "body": { "name": "adasd", "value": "ddsad", "requestType": 101 } }

レスポンス：

{ "body": { "deviceToken": "4fbb52fb5b6243e083377f45d216820f", "name": "adasd", "value": "ddsad" }, "cmd": 101, "code": 200 }

5.3 データ削除（CMD: 102）

リクエスト：

{ "deviceToken": "4fbb52fb5b6243e083377f45d216820f", "body": { "name": "adasd(3)", "value": "ddsad", "requestType": 102 } }

レスポンス：

{ "body": { "deviceToken": "4fbb52fb5b6243e083377f45d216820f", "name": "adasd(3)", "value": "ddsad" }, "cmd": 102, "code": 200 }

5.4 データ一覧取得（CMD: 103）

リクエスト：

{ "deviceToken": "4fbb52fb5b6243e083377f45d216820f", "body": { "requestType": 103 } }

レスポンス：

{ "body": [ { "createTime": 1751274100000, "dataToken": "6a330c4bf0924da3a2b11c833f9c2db1", "id": "6a330c4bf0924da3a2b11c833f9c2db1", "name": "adasd", "updateTime": 1751274100000, "value": "ddsad" }, { "createTime": 1751274119000, "dataToken": "60ea29ff4df446358b7bf2151939abb4", "id": "60ea29ff4df446358b7bf2151939abb4", "name": "adasd(1)", "updateTime": 1751274119000, "value": "ddsad" } ], "cmd": 103, "code": 200 }

5.5 単一データ詳細取得（CMD: 104）

リクエスト：

{ "deviceToken": "4fbb52fb5b6243e083377f45d216820f", "body": { "name": "adasd", "requestType": 104 } }

レスポンス：

{ "body": { "createTime": 1751274100000, "dataToken": "6a330c4bf0924da3a2b11c833f9c2db1", "id": "6a330c4bf0924da3a2b11c833f9c2db1", "name": "adasd", "updateTime": 1751274100000, "value": "ddsad" }, "cmd": 104, "code": 200 }

5.6 画像アップロード結果通知（CMD: 105）

説明：本メッセージは HTTP インターフェースによるアップロードによってトリガーされ、デバイス側は長時間接続を通じてレスポンスを受信します。

リクエスト： （HTTP https://ezdata2.m5stack.com/api/v2/device/uploadDeviceFile を通じて送信）

WebSocket / MQTT レスポンス：

{ "body": { "deviceToken": "4fbb52fb5b6243e083377f45d216820f", "name": "deviceFile", "value": "https://ezdata2-oss-dev.m5stack.com/37a6259cc0c1dae299a7866489dff0bd/deviceFile/deviceFile.jpg" }, "cmd": 105, "code": 200 }