EzData2 Device API Documentation

1. Overview

EzData2 currently provides two connection methods, MQTT and WebSocket, for device-side data interaction. Before device access, the hardware device MAC address must be used to call the registration API to obtain a Device Token. After registration is completed and the Device Token is successfully obtained, visit my.m5stack.com to log in to your personal account, click Add Group, and select the Token option. Copy and paste the Device Token to create the Group, completing the binding between the Device Token and the account. A single device’s Device Token corresponds to a data collection Group. Referring to the communication protocol below, after logging in and authenticating with the Device Token, the device can perform create, read, update, and delete operations on data fields.

2. Basic Definitions

2.1 Commands and Responses (CMD / RequestType)

3. HTTP APIs

3.1 Device Registration

API: https://ezdata2.m5stack.com/api/v2/device/registerMac Method: POST Description: Register a device via MAC address and generate a deviceToken.

Request Parameters:

• deviceType: Refer to the Product name field in Board Definitions.
• mac: Device MAC address, without ":" separators, case-insensitive.

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

Response Parameters:

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

3.2 Device File Upload

API: https://ezdata2.m5stack.com/api/v2/device/uploadDeviceFile Method: POST Description: Upload files via HTTP. After successful upload, the server will send a cmd: 105 response message via WebSocket/MQTT.

4. Connection Protocols

4.1 WebSocket Connection

WS Address: wss://ezdata2.m5stack.com/ws

4.1.1 Login

Request:

{
  "deviceToken": "4fbb52fb5b6243e083377f45d216820f"
}

Response:

device Login successful

4.1.2 Heartbeat

Request:

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

Response:

pong

4.2 MQTT Connection

Server Address: uiflow2.m5stack.com Port: 1883

Connection Information:

• Name: ez{mac}ez

• ClientId: ez{mac}ez

• Username: {deviceToken} (your device token)

• mac: Device MAC address, without ":" separators, case-insensitive.

Topics:

• Upstream (Publish): $ezdata/{deviceToken}/up
• Downstream (Subscribe): $ezdata/{deviceToken}/down

5. Business Data Interaction (Payload)

The following content represents the message body for WebSocket or MQTT.

5.1 Add Data (CMD: 100)

Request:

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

Response:

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

5.2 Update Data (CMD: 101)

Request:

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

Response:

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

5.3 Delete Data (CMD: 102)

Request:

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

Response:

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

5.4 Query Data List (CMD: 103)

Request:

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

Response:

{
  "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 Query Single Data Detail (CMD: 104)

Request:

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

Response:

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

5.6 Image Upload Result Notification (CMD: 105)

Description: This message is triggered by an HTTP upload. The device receives the response via a persistent connection.

Request: (Initiated via HTTP https://ezdata2.m5stack.com/api/v2/device/uploadDeviceFile)

WebSocket/MQTT Response:

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