EzData2 Device Interface Documentation

1. Overview

EzData2 currently provides two connection methods: MQTT and WebSocket, which can be used by devices to implement data interaction. Before device access, the hardware device MAC address must be used to call the registration interface to obtain a Device Token. After completing registration and successfully obtaining the Device Token, 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 it, completing the binding between the Device Token and the account. The Device Token of a single device is equivalent to one dataset Group. The device side can refer to the communication protocol below; after logging in and verification based on the Device Token, it can perform create, read, update, and delete operations on data fields.

2. Basic Definitions

2.1 Commands and Responses (CMD / RequestType)

3. HTTP Interfaces

3.1 Device Registration

Request Interface:

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

Request Parameters:

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

Response Parameters:

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

3.2 Device File Upload

Request Interface:

• URL: https://ezdata2.m5stack.com/api/v2/device/uploadDeviceFile
• Method: POST (multipart/form-data)
• Description: Upload a file via HTTP. After a successful upload, the server will send a response message with cmd: 105 via WebSocket/MQTT.

Request Parameters:

Response Parameters:

4. Connection Protocols

4.1 WebSocket Connection

Request Interface:

• URL: wss://ezdata2.m5stack.com/ws
• Method: WebSocket

4.1.1 Login

Request Interface:

• Message Type: Login request
• Description: Connect to the WebSocket server using the deviceToken

Request Parameters:

{
  "deviceToken": "4fbb52fb5b6243e083377f45d216820f"
}

Response Parameters:

device Login successful

4.1.2 Heartbeat

Request Interface:

• Message Type: Heartbeat request
• Description: Keep the WebSocket connection alive

Request Parameters:

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

Response Parameters:

pong

4.2 MQTT Connection

Request Interface:

• Server Address: uiflow2.m5stack.com
• Port: 1883
• Protocol: MQTT 3.1.1

Connection Parameters:

Topics:

5. Business Data Interaction (Payload)

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

5.1 Add Data (CMD: 100)

Request Interface:

• Command Code: 100
• Type: Data Operation
• Description: Device adds a data field

Request Parameters:

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

Response Parameters:

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

5.2 Modify Data (CMD: 101)

Request Interface:

• Command Code: 101
• Type: Data Operation
• Description: Device modifies a data field

Request Parameters:

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

Response Parameters:

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

5.3 Delete Data (CMD: 102)

Request Interface:

• Command Code: 102
• Type: Data Operation
• Description: Device deletes a data field

Request Parameters:

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

Response Parameters:

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

5.4 Query Data List (CMD: 103)

Request Interface:

• Command Code: 103
• Type: Data Query
• Description: Device queries the data list

Request Parameters:

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

Response Parameters:

{
  "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 Details (CMD: 104)

Request Interface:

• Command Code: 104
• Type: Data Query
• Description: Device queries details of a single data item

Request Parameters:

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

Response Parameters:

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

5.6 File Upload Result Notification (CMD: 105)

Description:

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

Request Interface:

• Trigger Source: HTTP https://ezdata2.m5stack.com/api/v2/device/uploadDeviceFile
• Command Code: 105
• Type: File Upload
• Description: The server returns the file upload result via WebSocket/MQTT

Response Parameters (WebSocket/MQTT):

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