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)

コード	タイプ	説明
100	データ操作	デバイス側でデータを追加
101	データ操作	デバイス側でデータを更新
102	データ操作	デバイス側でデータを削除
103	データ照会	デバイス側でデータ一覧を照会
104	データ照会	デバイス側でデータ詳細を照会
105	ファイルアップロード	デバイス側でファイルをアップロード（通知）
106	ユーザー操作	ユーザー側で QR コードをスキャン
107	ユーザー操作	ユーザー側でデータを更新
108	ユーザー操作	ユーザー側でデータを削除
109	ユーザー操作	ユーザー側でデータを追加
500	エラー	デバイス側のリクエストエラー

3. HTTP インターフェース

3.1 デバイス登録

リクエストインターフェース：

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

リクエストパラメータ：

パラメータ	型	説明
deviceType	string	開発ボード定義内の `Product name` フィールドを参照
mac	string	デバイスの MAC アドレス。「:」なし、大小文字は区別しません

{
  "deviceType": "basic",
  "mac": "AABBCCDDEEFF"
} 

レスポンスパラメータ：

パラメータ	型	説明
code	int	ステータスコード（0 は成功）
data	string	返却される deviceToken
msg	string	レスポンスメッセージ

{
  "code": 0,
  "data": "4fbb52fb5b6243e083377f45d216820f",
  "msg": "success"
} 

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

リクエストインターフェース：

URL： https://ezdata2.m5stack.com/api/v2/device/uploadDeviceFile
メソッド： POST (multipart/form-data)
説明： HTTP 経由でファイルをアップロードします。アップロード成功後、サーバーは WebSocket/MQTT を通じて cmd: 105 のレスポンスメッセージを配信します。

リクエストパラメータ：

パラメータ	型	説明
deviceToken	string	デバイストークン
file	file	アップロードするファイル

レスポンスパラメータ：

パラメータ	型	説明
code	int	ステータスコード（200 は成功）

4. 接続プロトコル

4.1 WebSocket 接続

リクエストインターフェース：

URL： wss://ezdata2.m5stack.com/ws
メソッド： WebSocket

4.1.1 ログイン

リクエストインターフェース：

メッセージタイプ：ログインリクエスト
説明： deviceToken を使用して WebSocket サーバーに接続します。

リクエストパラメータ：

パラメータ	型	説明
deviceToken	string	デバイストークン

{
  "deviceToken": "4fbb52fb5b6243e083377f45d216820f"
}

レスポンスパラメータ：

パラメータ	型	説明
-	string	ログイン成功メッセージ

device Login successful

4.1.2 ハートビート (Heartbeat)

リクエストインターフェース：

メッセージタイプ：ハートビートリクエスト
説明： WebSocket 接続を維持します。

リクエストパラメータ：

パラメータ	型	説明
deviceToken	string	デバイストークン
body	string	ハートビート信号（固定値: "ping"）

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

レスポンスパラメータ：

パラメータ	型	説明
-	string	ハートビート応答

pong

4.2 MQTT 接続

リクエストインターフェース：

サーバーアドレス： uiflow2.m5stack.com
ポート： 1883
プロトコル： MQTT 3.1.1

接続パラメータ：

パラメータ	型	説明
名称	string	`ez{mac}ez`
ClientId	string	`ez{mac}ez`
ユーザー名	string	`{deviceToken}`（デバイストークン）
Password	string	パスワード不要

Topic：

トピック	方向	説明
`$ezdata/{deviceToken}/up`	Publish	上りデータ
`$ezdata/{deviceToken}/down`	Subscribe	下りデータ

説明：

mac: デバイスの MAC アドレス。「:」なし、大小文字は区別しません
deviceToken: 登録インターフェースで取得

5. ビジネスデータ通信 (Payload)

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

5.1 データ追加 (CMD: 100)

リクエストインターフェース：

コマンドコード： 100
タイプ：データ操作
説明：デバイス側でデータフィールドを追加

リクエストパラメータ：

パラメータ	型	説明
deviceToken	string	デバイストークン
body.name	string	データフィールド名
body.value	string	データフィールド値
body.requestType	int	リクエストタイプ（固定値: 100）

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

レスポンスパラメータ：

パラメータ	型	説明
cmd	int	コマンドコード（100）
code	int	ステータスコード（200 は成功）
body.deviceToken	string	デバイストークン
body.name	string	データフィールド名
body.value	string	データフィールド値

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

5.2 データ更新 (CMD: 101)

リクエストインターフェース：

コマンドコード： 101
タイプ：データ操作
説明：デバイス側でデータフィールドを更新

リクエストパラメータ：

パラメータ	型	説明
deviceToken	string	デバイストークン
body.name	string	データフィールド名
body.value	string	データフィールド値
body.requestType	int	リクエストタイプ（固定値: 101）

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

レスポンスパラメータ：

パラメータ	型	説明
cmd	int	コマンドコード（101）
code	int	ステータスコード（200 は成功）
body.deviceToken	string	デバイストークン
body.name	string	データフィールド名
body.value	string	データフィールド値

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

5.3 データ削除 (CMD: 102)

リクエストインターフェース：

コマンドコード： 102
タイプ：データ操作
説明：デバイス側でデータフィールドを削除

リクエストパラメータ：

パラメータ	型	説明
deviceToken	string	デバイストークン
body.name	string	データフィールド名
body.value	string	データフィールド値
body.requestType	int	リクエストタイプ（固定値: 102）

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

レスポンスパラメータ：

パラメータ	型	説明
cmd	int	コマンドコード（102）
code	int	ステータスコード（200 は成功）
body.deviceToken	string	デバイストークン
body.name	string	データフィールド名
body.value	string	データフィールド値

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

5.4 データ一覧照会 (CMD: 103)

リクエストインターフェース：

コマンドコード： 103
タイプ：データ照会
説明：デバイス側でデータ一覧を照会

リクエストパラメータ：

パラメータ	型	説明
deviceToken	string	デバイストークン
body.requestType	int	リクエストタイプ（固定値: 103）

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

レスポンスパラメータ：

パラメータ	型	説明
cmd	int	コマンドコード（103）
code	int	ステータスコード（200 は成功）
body [].id	string	データ ID
body [].dataToken	string	データトークン
body [].name	string	データフィールド名
body [].value	string	データフィールド値
body [].createTime	long	作成時間（ミリ秒タイムスタンプ）
body [].updateTime	long	更新時間（ミリ秒タイムスタンプ）

{
  "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)

リクエストインターフェース：

コマンドコード： 104
タイプ：データ照会
説明：デバイス側で単一データの詳細を照会

リクエストパラメータ：

パラメータ	型	説明
deviceToken	string	デバイストークン
body.name	string	データフィールド名
body.requestType	int	リクエストタイプ（固定値: 104）

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

レスポンスパラメータ：

パラメータ	型	説明
cmd	int	コマンドコード（104）
code	int	ステータスコード（200 は成功）
body.id	string	データ ID
body.dataToken	string	データトークン
body.name	string	データフィールド名
body.value	string	データフィールド値
body.createTime	long	作成時間（ミリ秒タイムスタンプ）
body.updateTime	long	更新時間（ミリ秒タイムスタンプ）

{
  "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
コマンドコード： 105
タイプ：ファイルアップロード
説明：サーバーが WebSocket/MQTT を通じてファイルアップロード結果を返却

レスポンスパラメータ（WebSocket/MQTT）：

パラメータ	型	説明
cmd	int	コマンドコード（105）
code	int	ステータスコード（200 は成功）
body.deviceToken	string	デバイストークン
body.name	string	ファイルフィールド名
body.value	string	ファイル URL

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

Next Overview

Linux PC

CM4Stack

CoreMP135

AI アクセラレーターカード

LLM-8850 カード

クイックスタート

ビジョンモデル

大規模言語モデル

マルチモーダルモデル

音声モデル

生成モデル

アプリケーション一覧

高度な使用方法

LLM

リアルタイム音声アシスタント

OpenAI ボイスアシスタント

XiaoZhi ボイスアシスタント

XiaoLing ボイスアシスタント

AtomS3R-M12 Volcengine Kit

オフライン音声認識

Unit ASR

Module ASR

Industrial Control

StamPLC

IoT Measuring Instruments

Air Quality

PowerHub

Module13.2 PPS

VAMeter

T-Lite

入力デバイス

Ezdata

Ethernet Camera

PoECAM

Wi-Fi Camera

TimerCAM

Unit CamS3/-5MP

AI Camera

UnitV2

M5StickV/UnitV

LoRa & LoRaWAN

TTN (The Things Network)

Meshtastic

Motor Control

Unit Roller485/CAN

Develop Tools