Open Api

Variable Description

{ts}: timestamp (UNIX time/milliseconds)

{mk}: Model key (model unique identifier, given by the server)

{dk}: device key (device unique identifier, given by the server)

{un}: module location (0 is the primary module)

{dn}: Module S/N (the module is generally HMI, and its S/N is fixed in the hardware)

{mach_no}: Device number (also called machine number, unique code of the device, given by the device primary module settings. If not given, the same as {dn})

{iot_sts}: Network status (0=offline|1=online|2=fault)

{mach_sts}: Device status (0=idle|1=run|2=fault)

{errN}: fault bit (0=normal|1=fault)

{req}: MQTT message processing trigger

{rid}: MQTT command task ID

Open API

BASE_URL: {miot_url}/api/das?key={api_key}

⚠️Note:

api_key needs to be obtained in Model App/Application Integration. Operations using api key are all related to the corresponding model.

miot_url is different for public cloud version and private version.

Public cloud version (SASS): https://da-en.m-iot.net,

Private version (op): http://server address

error code:

OK: Success
NG_KEY: The app is not configured or the configured {api_key} is inconsistent with the one given in the request
NG_API: The following api parameter is invalid
NG_MACH_NO: The device name does not exist or is not under the model corresponding to the api key
NG_MACH_DATA: The configuration parameter data sent is illegal
NG_MACH_APP_DATA : The app data sent is illegal
NG_ERR: Server error

Get the device running status

POST {BASE_URL}&api=get_mach_state

Request:

{
  "mach_no": "{mach_no}", // Device number. If not given, the running status of all devices will be returned in pages
  "page_no": 0, // Only valid when the device number is not given, page number (starting from 0), default 0
  "page_size": 10 // Only valid when the device number is not given, number of data rows per page, default 10, maximum 50
}

response:

{
  "code": "OK", // Error code
  "data": [
      {
          "mach_no": "{mach_no}",
          "mk": "{mk}",
          "iot_sts": 0, // Possible values: 0(offline)/1(online)
          "mach_sts": 0, // Possible values: 0(stop)/1(running)/2(fault)
          "mach_err": {
              "err1": true,
              "err3": true,
              // ...
          },
          "err_def" : {
              "err1": "Pot bottom overtemperature",
              "err3": "Gear switch failure",
              // ...
          },
          "mach_ixs": [
              { "ix": "voltage", "iv": 2.1 },
              // ...
          ]
      },
      // ...
  ]
}

Get device history data

POST {BASE_URL}&api=get_mach_data

Request:

{
  "mach_no": "{mach_no}", // Device number, required
  "mach_ixs": ["voltage", "current", ...], // Device parameter list, optional
  "data_start": 1676359431233, // Timestamp, greater than 0 means only return data greater than or equal to `data_start`
  "data_end": 1676359455175, // Timestamp, greater than 0 means only return data less than or equal to `data_end`
  "page_no": 0, // Page number (starting from 0), default 0
  "page_size": 10 // Number of data rows per page, default 10, maximum 50
}

response:

{
  "code": "OK", // error code
  "data": [
      {
          "ts": 1676359455175, // timestamp
          "mach_no": "{mach_no}",
          "mk": "{mk}",
          "mach_ixs": [
              { "ix": "voltage", "iv": 2.1 },
              // ...
          ]
      },
      // ...
]

}

### Get device fault data

- `POST {BASE_URL}&api=get_mach_errs`
- Request:

``` json
{
  "mach_no": "{mach_no}", // Device number. If not given, all device operating statuses will be returned in pages
  "data_start": 1676359431233, // Timestamp. If it is greater than 0, only data greater than or equal to `data_start` will be returned
  "data_end": 1676359455175, // Timestamp. If it is greater than 0, only data less than `data_end` will be returned
  "page_no": 0, // Page number (starting at 0), default is 0
  "page_size": 10 // The number of rows per page, the default is 10, the maximum is 50
}

response:

{
    "code": "OK", // error code
    "data": [
        {
            "ts": 1676359455175, // timestamp
            "mach_no": "{mach_no}",
            "mk": "{mk}",
            "mach_err": {
                "err1": true,
                "err2": false,
                "err3": true,
                // ...
            },
            "err_def": {
                "err1": "Pot bottom overtemperature",
                "err2": "Pot pressure too high",
                "err3": "Gear switch failure",
                // ...
            },
        },
        // ...
    ]
}

Get device meter read data

POST {BASE_URL}&api=get_mach_copies

Request:

{
    "day": "{yyyy-MM-dd}" // Meter reading date, accurate to the day (default is the current day)
}

response:

{
    "code": "OK", // Error code
    "data": [
        [
          {
              "rid" : "{rid}",
              "mach_no" : "{mach_no}",
              "node_name" : "{node_name}",
              "sts" : "{sts}", // Possible values: Task dispatched (1)/Task failed (2)/End notification (3)/End failed (4)/Task completed (5)
              "ts" : 1676359455175, // Timestamp
              "mach_ixs" : {
                  "power": 2,
                  "err1": 2,
                  //...
              }
          }
          //...same batch
        ]
        // ...
    ]
}

Get device fault data

POST {BASE_URL}&api=get_mach_errs

Request:

{
    "mach_no": "{mach_no}", // Device number. If not given, the running status of all devices will be returned in pages
    "data_start": 1676359431233, // Timestamp. If it is greater than 0, only data greater than or equal to `data_start` will be returned
    "data_end": 1676359455175, // Timestamp. If it is greater than 0, only data less than `data_end` will be returned
    "page_no": 0, // Page number (starting from 0), default 0
    "page_size": 10 // Number of data rows per page, default 10, maximum 50
}

response:

{
    "code": "OK", // error code
    "data": [
        {
            "ts": 1676359455175, // timestamp
            "mach_no": "{mach_no}",
            "mk": "{mk}",
            "mach_err": {
                "err1": true,
                "err2": false,
                "err3": true,
                // ...
            },
            "err_def": {
                "err1": "Pot bottom overtemperature",
                "err2": "Pot pressure too high",
                "err3": "Gear switch failure",
                // ...
            },
        },
        // ...
    ]
}

Get the send task (including status)

POST {BASE_URL}&api=get_mach_task
Request:

{
    "rid":{rid}
}

response:

{
  "code": "OK",
  "data": {
    "rid": {rid},
    "mk": "{mk}",
    "cmd": "conf", //conf: configuration parameter delivery pack: application data delivery
    "sts": 5, //1: request delivery 2: request failure (device-side task execution failed, or no response message was received within the given time) 5: task completed
    "kvs": {
      "set_RH": 34
    },
    "req_at": "2024-01-24T16:46:15.933571+08:00"
  }
}

Get the model

POST {BASE_URL}&api=get_mach_dtm
response:

{
  "code": "OK",
  "data": {
    "mk": "{mk}",
    "name": "{name}",
    "dtus": 1,
    "mach": "{mach}",
    "remarks": "",
    "ixs": [
      {
        "ix": "set_RH",
        "un": 0,
        "name": "Humidity setting",
        "unit": "%",
        "ix_kind": "env",
        "rw_mode": "rw",
        "type": "number",
        "remarks": ""
      },
      ...
    ]
  }
}

Send device configuration parameters (asynchronous)

Case: Remote lock/unlock

POST {BASE_URL}&api=set_mach_ixs
Request:

{
    "mach_no": "{mach_no}", // Device number, required
    "mach_ixs": { "locked": 1 } // Parameter key-value pair
}

response:

{
    "code": "OK" // Error code
}

Send device application data packets (asynchronous)

The content of the device application data packet does not belong to the object model. Its content is negotiated and determined by the third-party application and the DTU application, and the platform is not aware of it.

POST {BASE_URL}&api=set_mach_app
Request:

{
    "mach_no": "{mach_no}", // Device number, required
    "mach_app": {
        // Any content, required
    }
}

response:

{
    "code": "OK" // Error code
}

Web Hook

Web Hook registration configuration is completed in Model App/Application Integration
Third-party applications hook_api receives data and responds uniformly

{
    "code": "OK" // Error code
}

Device Events

Push data

{
    "ts":"{ts}",
    "mach_no": "{mach_no}",
    "mach_evt": "new" // Possible values: new device (new)/online (on)/offline (off)/running (work)/idle (idle)
}

Device model data

Push data

{
    "ts":"{ts}",
    "mach_no": "{mach_no}",
    "mach_ixs": {
        "active": 1, // Activated (1)/Deactivated (0)
        "locked": 1, // Locked (1)/Unlocked (0)
        // ...
    }
}

Device Answer

After the device is configured and sent through the open API (configuration parameters, app data), the device responds (whether it is successful).When the task execution fails on the device side, or no response message is received within a given time, it is considered failed.

Push data

{
    "ts":"{ts}",
    "mach_no": "{mach_no}",
    "mach_ack": {
        "rid":{rid},
        "ok":true // Successful or not
    }
}

Device fault data

Push data

{
    "ts":"{ts}",
    "mach_no": "{mach_no}",
    "mach_err": {
        "err1": true,
        "err3": true,
        // ...
    },
}

App Data

The device app data content does not belong to the data model. Its content is negotiated and determined by the third-party app and the DTU app, and the platform is not aware of it.

Push data

{
    "ts":"{ts}",
    "mach_no": "{mach_no}",
    "mach_app": {
        // Arbitrary content, determined by negotiation between the device-side application and the third-party application
    }
}

Open Api

Open API​

Get the device running status​

Get device history data​

Get device meter read data​

Get device fault data​

Get the send task (including status)​

Get the model​

Send device configuration parameters (asynchronous)​

Send device application data packets (asynchronous)​

Web Hook​

Device Events​

Device model data​

Device Answer​

Device fault data​

App Data​

Open API

Get the device running status

Get device history data

Get device meter read data

Get device fault data

Get the send task (including status)

Get the model

Send device configuration parameters (asynchronous)

Send device application data packets (asynchronous)

Web Hook

Device Events

Device model data

Device Answer

Device fault data

App Data