API references

MediaTek Cloud Sandbox (MCS) provides a bunch of RESTful APIs by which you can build your IoT applications and services. For example, you can upload the data points generated by the devices to MCS and retrieve them back for analysis later on.

MCS also provide an easy-to-read charts and reports to visualize your data and devices in real time.

Request URL

The base URL of MCS services is

https://api.mediatek.com/mcs/v2/

You can access and operate a specific resource by specifying a resource ID in the request URL. Take the request below as an example, we can access data points under a specific device and channel by providing their ID in the request.

https://api.mediatek.com/mcs/v2/devices/{deviceID}/datachannels/{dataChannelID}/datapoints.csv

Example

Here is the complete HTTP request for retrieving data points (please replace {variable} to your real device data), we will go into details of each API in later section.

curl -X GET \
  https://api.mediatek.com/mcs/v2/devices/{deviceID}/datachannels/{dataChannelID}/datapoints.csv \
  -H 'devicekey: {deviceKey}' \

Request Method

The MCS RESTful APIs can be accessed with the following HTTP methods:

GET - To retrieve resources.

POST - To create resources.

PUT - To update resources.

DELETE - To delete resources.

Request Header

1. Access Token

The request attempt is allowed only after it successfully pass the authentication. Therefore, you have to add some special HTTP headers in the request for MCS services to deal with authentication.

There are 2 different types of authentication.

  • Service provider account:

    If you are going to develop your own application, including a mobile App or web application, you can apply for an appID and appSecret on Profile -> Service provider page and use this credential to access all MCS open APIs.

    Add appID and appSecret in the header for all your MCS API requests.

      appId: {your_appId}
      appSecret: {your_appSecret}
    
  • Device key:

    If you are developing device application and only need to use device-related APIs, such as uploading and retrieving data points, you can use device ID and key directly for authentication. You can find the device ID and key in the device details page, and then add deviceKey in the header for all your device-related API requests.

      deviceKey: {your_device_key}
    

    Since the device ID is already used in the request URL to specify the resource to be accessed, it is not necessary to add it into the header.

2. content-type

You must add content-type to the request header. This field allows the MCS service to know the format of request body and how to process the data subsequently.

  • content-type: application/json the body is in JSON format.
  • content-type: text/csv the body is in CSV format.

Request Body

MCS supports request content in either JSON or CSV format. The parameters required by each API is different. Therefore, the detailed request content will be described in the chapter of individual APIs.

Parameters

Here are some basic parameters using in MCS APIs.

  • Timestamp

    The timestamp is used to record the exact time when a resource was created or updated, such as the time when the data point was uploaded, the time the prototype was created, and so on.

    In the MCS system, timestamp is in Unix Epoch format and the time unit is milliseconds. If you want to convert the Unix Epoch to human readable time format, please refer to http://www.epochconverter.com/. For example:

    Timestamp in milliseconds: 1524720177000 is converted to Human time (GMT): Thursday, April 26, 2018 5:22:57 AM

  • Resource ID

    Each time a prototype, test device, data channel, or firmware file is created, a unique ID is assigned to the resource. This ID is not editable and then you can access the resource by specifying the ID.

    For example, to retrieve data from a specific data channel, you will need to know the ID of this data channel and test device. And then specify these 2 IDs in the request URL.

    Here are 3 major resource types in MCS:

    1. Data channel:Data channel is a logical placeholder in the cloud for data generated from a specific component of a physical device, or a command from the cloud to be pushed into a specific component of the connected physical device. In other words, data channel is designed for one-way or two-way communications between the cloud and the connected physical device.

      MCS provides RESTful APIs to easily retrieve data from the data channels and update the data channel.

    2. Device:There are two types of devices which you can create in MCS: test device and Beta device. The test device enables you to test the functionality of the prototype before it is Beta-released. The Beta device can be created after a prototype is Beta-released and it’s used by the end user.

    3. Prototype:A prototype is a service that’s delivered as a result. The MSC provides several APIs to make use of the prototype. The developer can add data channels in a prototype and test the prototype by creating a test device before releasing it.

Client Errors

MediaTek Cloud Sandbox (MCS) uses the standard HTTP status code to indicate if an API request is successful or failed. The HTTP status codes users may encounter are:

200 OK - The request is successful.

201 Created - The request has been fulfilled and a new resource is being created.

202 Accepted - The request has been accepted for processing, but the process has not been completed yet.

204 No Content - The server processed the request successfully, but isn’t returning any content. This is usually used as a response for a successful delete request.

400 Bad Request - The server cannot process the request due to an unexpected parameter received from the client.

401 Unauthorized - Authorization has failed or it hasn’t been provided. A header for Authorization is required.

403 Forbidden - The server is refusing to respond to a valid request.

404 Not Found - The requested resource could not be found.

405 Method Not Allowed - The request was made from a resource that used a method which is not supported.

500, 502 Server Error - MCS server has encountered an error.

Upload data points

Description

Use HTTPs POST to upload data points

Request

URL

  • Upload with CSV format
https://api.mediatek.com/mcs/v2/devices/{deviceId}/datapoints.csv
  • Upload with JSON format
https://api.mediatek.com/mcs/v2/devices/{deviceId}/datapoints

You can upload 5 data points in an upload request at most.

Method

POST

Header

1. Access token

  • Upload from device

      deviceKey: {your_device_key}
    
  • Upload from your own App (Service provider)

      appId: {your_appId}
      appSecret: {your_appSecret}
    

    You can get the appId and appSecret under the Service provider section in the Profile page.

2. Content Type

  • For Comma Separated Value (CSV) format:

      Content-Type: text/csv
    
  • For JSON format:

      Content-Type: application/json
    

Body

  • For CSV format:

    Syntax:

      {Data_Channel_Id_1},{Timestamp},{Value_1},{Value_2},{Value_3}\n*
    
      {Data_Channel_Id_2},{Timestamp},{Value_1}\n*
    

    Please refer to the data channel format section for more detailed information on the request and response format for each type of data channel.

    Note: :Timestamp field is optional. If there is no value provided in this field, MCS server will add the timestamp while receiving the data points.

    Example:

      1,1432538716989,26
      2,,26.34,12,59
    

    Line 1: "1" is the data channel ID, "1432538716989" is the timestamp generated by your device or application, "26" is the value of this data point.

    Line 2: "2" is the data channel ID. In this case, we leave the timestamp field empty, and then MCS server will append the current timestamp while it receives this data point. "26.34", "12" and "59" are the values of this data point. (This is a GPS data channel)

  • For JSON format:

    Syntax:

    Each JSON object represents of a data point which is composed of

    1. dataChnID
    2. timestamp
    3. values: This is the combination of data emitted by this channel. In Some cases, a data channel is represented by more than one data. For example, the values of GPS channel consists of latitude, longitude and altitude.

      {
      "datapoints":[
         {
            "dataChnId":"1",
            "timestamp":1432538716989,
            "values":{
               "value":"26"
            }
         },
               {
            "dataChnId":"2",
            "timestamp":1432538716989,
            "values":{
               "latitude":"26.34",
               "longitude":"12",
               "altitude":"59"
              }
         }
      ]
      }
      
      

      JSON object 1: "1" is the data channel ID, "1432538716989" is the timestamp generated by your device or application, "26" is the value of this data point.

      JSON object 2: "2" is the data channel ID. In this case, we leave the timestamp field empty, and then MCS server will append the current timestamp while it receives this data point. Because it is a GPS data channel, there are 3 values specified in the values object.

Response

Response Code

200

Header

  • For CSV format:

      content-type: text/html
    
  • For JSON format:

      content-type: application/json    
    

Body

  • For CSV format:

      Success.
    
  • For JSON format:

      {
              "results": "success"
      }
    

Error Response

If there is an error while processing the request, MCS server will respond a non-200 response code and construct the response body with the following fields:

Field Name Type Description
code Integer Error code
message String General error message
description String Detailed error description

Example:

  • For CSV format:

      400,None of data points uploaded success.
    
  • For JSON format:

      {
          "apiVersion": "2.18.3",
          "code": 400,
          "message": "None of data points uploaded success.",
          "errors": [
              {
                  "code": 400,
                  "message": "400 Bad Request"
              }
          ],
          "results": "",
          "descriptions": [
              "There is no such data channel displays_boolean for this device."
          ],
          "statusCode": 400,
          "options": {}
      }
    

Retrieve data points

Description

Use HTTPs GET to retrieve data point values of a device.

Request

URL

You can retrieve the data points by specifying the following parameters in the request URI and query string.

  • Resource path
Resource Name Type Required Description
device ID String Mandatory You need to specify the device ID for which you would like to get data in the request URL
data channel ID String Mandatory You need to specify the data channel ID for which you would like to get data in the request URL
  • Query string

    Following fields should be constructed and appended to the end of the URL:

Field Name Type Required Description
start Number Optional Start Timestamp of the query period
end Number Optional End Timestamp of the query period
limit Number Optional number of the data points to be returned ( Default = 1 )
offset Number Optional offset of the data points being retrieved
order String Optional The data is sorted in descending order of timestamp. You also can "asc" or "desc" to define the order by your own.

MCS service can return data points in either JSON or CSV format, you can specify the format in the resource name of the HTTP request.

The maximum number of returned data points for each data channel is 1000.

  • Retrieve data points in JSON format

      https://api.mediatek.com/mcs/v2/devices/{deviceId}/datachannels/{datachannelId}/datapoints?start={startTime}&end={endTime}&limit={limit}&offset={offset}
    
  • Retrieve data points in CSV format

    If you would like to retrieve the data points in CSV format, please add .csv in the resource name.

      https://api.mediatek.com/mcs/v2/devices/{deviceId}/datachannels/{datachannelId}/datapoints.csv?start={startTime}&end={endTime}&limit={limit}&offset={offset}
    

Examples

  • To get the latest data point in JSON format:

      https://api.mediatek.com/mcs/v2/devices/DL6sA7iSx/datachannels/my_data_channel/datapoints
    
  • To get the latest data point in CSV format:

      https://api.mediatek.com/mcs/v2/devices/DL6sA7iSx/datachannels/my_data_channel/datapoints.csv
    
  • To get the data points within a time frame:

      https://api.mediatek.com/mcs/v2/devices/DL6sA7iSx/datachannels/my_data_channel/datapoints?limit=1000&start=1524107855148&end=1524550447427
    

    You have to use start, end and also limit to identify how many data points within a specified time frame you would like to retrieve. If there is no limit parameter, MCS service only returns the latest data point of that period.

  • To limit the number of data points. MCS service only returns the latest N data points.

      https://api.mediatek.com/mcs/v2/devices/DL6sA7iSx/datachannels/my_data_channel/datapoints?limit=10    
    

Method

GET

Header

Access token

  • Retrieved by device

      deviceKey: {your_device_key}
    
  • Retrieved by your own App (Service provider account)

      appId: {your_appId}
      appSecret: {your_appSecret}
    

    You can get the appId and appSecret under the Service provider section in the Profile page.

Response

Response Code

200

Header

  • For JSON format:

      content-type: text/html
    
  • For CSV format:

      content-type: application/json    
    

Body

  • For JSON format:

    The response body is constructed in JSON format and the data points are wrapped in the dataPoints array under dataChannels object.

dataChannels object

Field Name Type Description
dataChnId String Data Channel ID
isOverflow Bool Is the number of queried data points more than maximum number
data points Object Array All the data points that matches your query criteria

dataPoints Array

Field Name Type Description
recordedAt Number Unix timestamp of the data point
values Object The values of a data point

Example:

  • Response in JSON format

      {
          "apiVersion": "2.18.3",
          "code": 200,
          "message": "Request has succeeded",
          "deviceId": "DL6sA7iSx",
          "dataChannels": [
              {
                  "dataChnId": "my_data_channel",
                  "isOverflow": false,
                  "dataPoints": [
                      {
                          "recordedAt": 1524550447427,
                          "values": {
                              "value": 35
                          }
                      },
                      {
                          "recordedAt": 1524119075906,
                          "values": {
                              "value": 30
                          }
                      }
                  ]
              }
          ]
      }
    
  • Response in CSV format

      my_data_channel,1524119075906,35
      my_data_channel,1524550447427,30
    

Error Response

When error is incurred, the response code will be non-200 and the response body will construct in JSON format with the following fields:

Field Name Type Description
code Integer Error code
message String General error message

Example:

  • For CSV format:

      404,channel not found
    
  • For JSON format:

      {
          "apiVersion": "2.18.3",
          "code": 404,
          "message": "channel not found",
          "errors": [
              {
                  "code": 404,
                  "message": "404 Not Found"
              }
          ],
          "statusCode": 404,
          "options": {}
      }
    

Retrieve device information

Description

Use HTTPs GET to retrieve devices

Request URL

https://api.mediatek.com/mcs/v2/devices/:deviceId

Action

HTTPs GET

Parameters

Header

Authorization: Bearer '{token}'

Content-Type:application/json

Response

Response Code

200

Response Header

Content-Type:application/json

Response Body

Data Format: JSON

The response body will construct in JSON format with the following fields:

Field Name Type Description
deviceId String Device ID
deviceKey String Device Key
name String Device Name
description String Device Description
product Object Product Info
dataChannels Object Array Data Channels
fw Object Firmware Info
trustIpRange String Array Trusted IP range from where the device is allowed to conntect to MCS
lastIp String Last IP the device seen from
deviceImageURL String Device image URL
isHeartbeating Bool Is the device currently online
isVerified Bool Has the device registration been verified
isActive Bool Is the device active
isTest Bool Is the device a test device
activatedAt Number Timestamp of the device activation
deactivatedAt Number Timestamp of the device deactivation ( Default = null if the device is active and has not been deactivated )
tags Object Array Tags of the device
privilege String User's privilege on the device

Detailed Object Fields

product

Field Name Type Description
prodId String Product ID
prodVersion String Product Version
name String Product Name
description String Product Description
displayConfigs Object Array A JSON format object indicatig how each data channel will be displayed
chip String Product Chip

dataChannel

Field Name Type Description
dataChnId Number Data Channel ID
isAvailable Bool Is the device normal
name String Channel Name
channelType Object Data Channel Type
isHidden Bool Is the data channel hidden to end users?
isControllable Bool Is the data channel controllable by cloud commands
description String Data Channel Description
unitType Object Data Unit Type
format String data channel format

firmware

Field Name Type Description
fwId String Firmware ID
name String Frimware Name
description String Firmware Description
version Number Firmware Version

displayConfig

Field Name Type Description
displayType Number How to display
displayOrder Number The order of displaying the component
dataChnIds Number Array ID of data channel that is being configured to display on the console

tag

Field Name Type Description
tagId Number Tag ID
name String Tag Name

Example:

Request URL

https://api.mediatek.com/mcs/v2/devices/d1234567890

https://api.mediatek.com/mcs/v2/devices/d1234567890,d1234567891

Response Body

{
   "results":[
      {
         "deviceId":"d1234567890",
         "deviceKey":"1234567890d",
         "deviceName":"My 1st device",
         "deviceDescription":"Livingroom Smart Plug 1",
         "product":{
            "prodId":"a1234567890",
            "prodVersion":"1",
            "name":"MediaTek Smart Plug",
            "description":"Monitors Power Usag",
            "displayConfigs":[
               {
                  "displayType":2,
                  "displayOrder":1,
                  "dataChnIds":[
                     100004,
                     100006
                  ]
               },
               {
                  "displayType":1,
                  "displayOrder":2,
                  "dataChnIds":[
                     100009
                  ]
               }
            ],
            "chip":"MT7688"
         },
         "dataChannels":[
            {
               "dataChnId":10001,
               "isAvailable":true,
               "name":"My 1st Data Channel",
               "channelType":{
                  "dataChnTypeId":1,
                  "name":"float"
               },
               "isHidden":false,
               "isControllable":false,
               "description":"My first data channel on MCS 2.0",
               "unitType":{
                  "unitTypeId":2,
                  "name":"°C"
               },
               "format":{
                  "lowerbound":0.0,
                  "upperbound":100.0,
                  "interval":0.5,
                  "defaultValue":5.0
               },
               "comps":[
                  {
                     "compId":1,
                     "name":"MTK Camera"
                  },
                  {
                     "compId":2,
                     "name":"MTK Thermometer"
                  }
               ]
            },
            {
               "dataChnId":10002,
               "isAvailable":true,
               "name":"My 2nd Data Channel",
               "channelType":{
                  "dataChnTypeId":2,
                  "name":"swtich"
               },
               "isHidden":false,
               "isControllable":true,
               "description":"My second data channel on MCS 2.0",
               "format":{
                  "options":[
                     {
                        "name":"low",
                        "value":"1"
                     },
                     {
                        "name":"medium",
                        "value":"2"
                     },
                     {
                        "name":"high",
                        "value":"3"
                     }
                  ]
               }
            }
         ],
         "fw":{
            "fwId":"f1234567890",
            "name":"Appliance Firmware 2.0",
            "description":"",
            "version":0.5
         },
         "trustIpRange":[
            "*.*.*.*"
         ],
         "lastIp":"140.112.106.1",
         "deviceImageURL":"http://img.mediatek.com/img003.jpg",
         "isHeartbeating":true,
         "isVerified":true,
         "isActive":true,
         "isTest":false,
         "activatedAt":946684800,
         "deactivatedAt":0,
         "tags":[
            {
               "tagId":20,
               "name":"Smart Home"
            },
            {
               "tagId":59,
               "name":"Energy"
            }
         ],
         "deviceNtCritGrps":[
            {
               "ntfCritGrpId":1,
               "name":"Continuous Operating Time"
               "ntfMthTypeId":1,
               "ntfMthTypeName":"email"
            }
         ],
         "privilege":"Owner"
      },
      {
         "deviceId":"d1234567891",
         "deviceKey":"1987654321d",
         "name":"My 2nd device",
         "description":"Livningroom Smart Plug 2",
         "product":{
            "prodId":"a1234567890",
            "name":"MediaTek Smart Plug",
            "description":"Monitors Power Usage",
            "displayConfigs":[
               {
                  "displayType":2,
                  "displayOrder":1,
                  "dataChnIds":[
                     100004,
                     100006
                  ]
               },
               {
                  "displayType":1,
                  "displayOrder":2,
                  "dataChnIds":[
                     100009
                  ]
               }
            ],
            "chip":"MT7688"
         },
         "dataChannels":[
            {
               "dataChnId":10001,
               "isAvailable":true,
               "name":"My 1st Data Channel",
               "channelType":{
                  "dataChnTypeId":1,
                  "name":"float"
               },
               "isHidden":false,
               "isControllable":false,
               "description":"My first data channel on MCS 2.0",
               "unitType":{
                  "unitTypeId":2,
                  "name":"°C"
               },
               "format":{
                  "lowerbound":0.0,
                  "upperbound":100.0,
                  "interval":0.5,
                  "defaultValue":5.0
               },
               "comps":[
                  {
                     "compId":1,
                     "name":"MTK Camera"
                  },
                  {
                     "compId":2,
                     "name":"MTK Thermometer"
                  }
               ]
            },
            {
               "dataChnId":10002,
               "isAvailable":true,
               "name":"My 2nd Data Channel",
               "channelType":{
                  "dataChnTypeId":2,
                  "name":"swtich"
               },
               "isHidden":false,
               "isControllable":true,
               "description":"My second data channel on MCS 2.0",
               "format":{
                  "options":[
                     {
                        "name":"low",
                        "value":"1"
                     },
                     {
                        "name":"medium",
                        "value":"2"
                     },
                     {
                        "name":"high",
                        "value":"3"
                     }
                  ]
               }
            }
         ],
         "fw":{
            "fwId":"f1234567890",
            "name":"Appliance Firmware 2.0",
            "description":"",
            "version":0.3
         },
         "trustIpRange":[
            "*.*.*.*"
         ],
         "lastIp":"140.112.106.2",
         "deviceImageURL":"http://img.mediatek.com/img003.jpg",
         "isHeartbeating":false,
         "isVerified":true,
         "isActive":true,
         "isTest":false,
         "activatedAt":946684800,
         "deactivatedAt":0,
         "tags":[
            {
               "tagId":20,
               "name":"Smart Home"
            },
            {
               "tagId":59,
               "name":"Energy"
            }
         ],
         "privilege":"Viewer"
      }
   ]
}

Error Response

When error is incurred, the response code will be non-200 and the response body will construct in JSON format with the following fields:

Field Name Type Description
code Integer Error Code
url String url to API Error detail page
description String Error Description

Example:

{
  "results": {
    "code": 1002,
    "url": "http://mcs.mediatek.com/api_errorcode?code=1002",
    "description": "You do not have access right to this API"
  }
}

Get connection

Description

Use HTTPs GET to set up connections between device and command server.

Request URL

To set up connections between device and command server:

https://api.mediatek.com/mcs/v2/devices/:deviceId/connections

To set up TCP long connection between the device and the command server, the device will need to first send a REST API Get connection to request a set of ip and port to build a TCP connection. The MCS will respond with its IP address and a port to the device.

Command server respond format:

{
    "ip": "ServerIp",
    "port": "serverPort"
}

Once get the server ip and port to connect, the device need to send a heartbeat to the command server to be identified. The device also need to sent heartbeats to the server every 120 seconds to stay connected, or the server will disconnect the device.

Heartbeat format:

    deviceId,deviceKey,timestamp

The timestamp is in UNIX time format. If you do not want to send the timestamp, just put 0 in the timestamp field and the system will use the system time as the timestamp.

After the TCP long connecion is built, the user can give command to the device via the MSC platform.

The command Format:

{
    deviceId,deviceKey,timestamp,dataChnId,commandValue
}

Action

HTTPs GET

Parameters

Header

Content-Type:application/json or text/csv

deviceKey: device_key_here

Return format

The return format can be in either JSON or CSV format

JSON:

when the request for resource ends with connections

CSV:

when the reqeust for resouce ends with connections.csv

Response

Response Code

200

Response Header

For JSON response:

Content-Type:`application/json`

For CSV response:

Content-Type: `text/csv`

Response Body

Data Format: JSON

The response body will construct in JSON format with the following fields:

Field Name Type Description
ip array the command server ip
port Integer the command server port for the device to connect

Example:

Request URL

https://api.mediatek.com/mcs/v2/devices/a1234567890/connections

Response Body

{
   "ip": xxx.xxx.xxx.xxx,
   "port":443

}

Error Response

When error is incurred, the response code will be non-200 and the response body will construct in JSON format with the following fields:

Field Name Type Description
code Integer Error Code
description String Error Description

Example:

{
  "results": {
    "code": 1002,
    "description": "You dont have permission"
  }
}

Data channel format

The API format of each data type is defined here. It is the format that the device report data to the command server.

**The timestamp is using the UNIX timestamp format, and it is not a required field. You can leave it blank, and the system will give the timestamp automatically as the server recorded time.

MCS supports both json and csv formats.

Switch

For json:

{
 "datapoints":[
      {
         "dataChnId":"dataChnId",
         "values":{
            "value":"{0 or 1}"
         }
      }
   ]
}

For csv:

dataChnId,timestamp,{0 or 1}

0 stands for OFF, and 1 stands for ON.

For example:

switch01,, 1

To turn the switch01 to on state, and do not give the timestamp.

Category

For json:

{
 "datapoints":[
      {
         "dataChnId":"dataChnId",
         "values":{
            "value":"{Key value}"
         }
      }
   ]
}

For csv:

dataChnId,timestamp,{Key Value}

The Key value will correspond to the Key name that you’ve set.

Integer

For json:

{
 "datapoints":[
      {
         "dataChnId":"dataChnId",
         "values":{
            "value":"{Integer value}"
         }
      }
   ]
}

For csv:

dataChnId,timestamp,{Integer}

Float

For json:

{
 "datapoints":[
      {
         "dataChnId":"dataChnId",
         "values":{
            "value":"{Float value}"
         }
      }
   ]
}

For csv:

dataChnId,timestamp,{Float}

Hex

For json:

{
 "datapoints":[
      {
         "dataChnId":"dataChnId",
         "values":{
            "value":"{HEX value}"
         }
      }
   ]
}

For csv:

dataChnId,timestamp,{Hex value}

Hex is referred to hexadecimal value which only takes value from A-D and 0-9.

String

For json:

{
 "datapoints":[
      {
         "dataChnId":"dataChnId",
         "values":{
            "value":"{string value}"
         }
      }
   ]
}

For csv:

dataChnId,timestamp,{string}

GPS

For json:

{
 "datapoints":[
       {
         "dataChnId":"dataChnId",
         "values":{
            "latitude":"{latitude value}",
            "longitude":"{longitude value}",
            "altitude":"{altitude value}"
         }
      }
   ]
}

For csv:

dataChnId,timestamp,{latitude},{longitude},{altitude}

The range of latitude is from -90 to 90. 0 to 90 stands for North and 0 to -90 stands for South.

The range of longitude is from -180 to 180. 0 to 180 stands for East and 0 to -180 stands for West.

The range of altitude is from -20000 to 20000 in meter.

GPIO

For json:

{
 "datapoints":[
      {
         "dataChnId":"dataChnId",
         "values":{
            "value":"{0 or 1}"
         }
      }
   ]
}

For csv:

dataChnId,timestamp,{0 ot 1}

0 stands for Low, and 1 stands for High.

PWM

For json:

{
 "datapoints":[
      {
         "dataChnId":"dataChnId",
         "values":{
            "value":"{string value}",
            "period":"{period value}"
         }
      }
   ]
}

The range of Period and Value is from 0 to 1000.

For csv:

dataChnId,timestamp,{Value},{Period}

Analog

For json:

{
 "datapoints":[
      {
         "dataChnId":"dataChnId",
         "values":{
            "value":"{Integer value}"
         }
      }
   ]
}

For csv:

dataChnId,timestamp,{Integer value}

The range of Integer value is defined by users.

Gamepad

For json:

{
 "datapoints":[
      {
         "dataChnId":"dataChnId",
         "values":{
            "value":"{up/down/right/left/A/B value|press(1) or release(0)}"
         }
      }
   ]
}

For csv:

dataChnId,timestamp,{up/down/right/left/A/B value|press(1) or release(0)}

User can decide to only have the up/down/right/left value only or to have the A/B value together at the same time.

For example, if user set the up value to up when you created the data channel, then click up button, the value will be up|0. If user press up button, the value will be up|1.

You can use pre-defined hotkeys on keyboard to control this data channel:

up = W

down = S

left = A

right = D

Key A = ,

Key B = .

Image

For json:

{
 "datapoints":[
      {
         "dataChnId":"dataChnId",
         "values":{
            "value":"{image file base64 encoding string value}"
         }
      }
   ]
}

For csv:

dataChnId,timestamp,{image file base64 encoding string value}

To upload an image to the image display data channel, you have to convert the image file to base64 encoding. Upload the base 64 encoding string to the data channel, then the image will saved and shown.

Please be noted that the image data channel supports uploading files in JPG, JPEG, and PNG formats. However, after uploaded to MCS, all types of files will be saved in .PNG format.

Video Stream

Unlike the other data channels of which the data points can be uploaded in either JSON or CSV format, video stream data channel needs a video converter instlled on the device before you can start streaming on MCS.

Here are the video specifications that MCS currently supports:

  • Video format: MPEG1
  • Maximum resolution supported: 320x240
  • Maximum fps supported: 30
  • URL of MCS video relay server:
http://stream-mcs.mediatek.com/:deviceId/:deviceKey/:dataChnId/:width/:height

Please replace the deviceId, deviceKey, dataChnID, width and height with the real values. The width and height represent the display resolution of your video.

  • Recommended video converter on LinkIt Smart 7688: FFmpeg
ffmpeg -s 176x144 -f video4linux2 -r 30 -i /dev/video0 -f mpeg1video -r 30 -b 800k http://stream-mcs.mediatek.com/:deviceId/:deviceKey/:dataChnId/176/144

Command server format

The command server format of each data type is defined here. It is the format that the command server sent to the device to process.

**The timestamp is using the UNIX timestamp format.

The device will get the data as the following format from the command server, and the user can write a parser in the device to parse the data needed.

Prerequsite

Before the device can get the command from command server, you need to first connect the device to MCS.

Call the RESTful API: GET https://api.mediatek.com/mcs/v2/devices/{deviceId}/connections to obtain the response value for Socket Server IP and Port. Command server respond format:

{
    "ip": "ServerIp",
    "port": "serverPort"
}

Open a tcp connection to the given ip and port and send a heartbeat message.

Heartbeat format:

    deviceId,deviceKey,timestamp

The timestamp is optional, if you do not want to send the timestamp, just put 0 in the timestamp field.

After the TCP long connecion is built, the user can give command to the device via the MCS platform.

The command Format:

    deviceId,deviceKey,timestamp,dataChnId,commandValue

Command formats for each data channel type

Switch

deviceId,deviceKey,timestamp,dataChnId,{0 or 1}

0 stands for OFF, and 1 stands for ON.

For example:

switch01,, 1

To turn the switch01 to on state, and do not give the timestamp.

Category

deviceId,deviceKey,timestamp,dataChnId,{Key Value}

The Key value will correspond to the Key name that you’ve set.

Integer

deviceId,deviceKey,timestamp,dataChnId,{Integer}

Float

deviceId,deviceKey,timestamp,dataChnId,{Float}

Hex

deviceId,deviceKey,timestamp,dataChnId,{Hex value}

Hex is referred to hexadecimal value which only takes value from A-D and 0-9.

String

deviceId,deviceKey,timestamp,dataChnId,{string}

GPS

deviceId,deviceKey,timestamp,dataChnId,{latitude},{longitude},{altitude}

The range of latitude is from -90 to 90. 0 to 90 stands for North and 0 to -90 stands for South.

The range of longitude is from -180 to 180. 0 to 180 stands for East and 0 to -180 stands for West.

The range of altitude is from 0 to 20000 in meter.

GPIO

deviceId,deviceKey,timestamp,dataChnId,{0 ot 1}

0 stands for Low, and 1 stands for High.

PWM

deviceId,deviceKey,timestamp,dataChnId,{value},{period}

Analog

deviceId,deviceKey,timestamp,dataChnId,{value}

Gamepad

deviceId,deviceKey,timestamp,dataChnId,{up/down/right/left/A/B value| press(1) or release(0)}

Image

deviceId,deviceKey,timestamp,dataChnId,{image file base64 encoding string value}

Report Device Firmware Version

Description

Use HTTPs PUT to report the current firmware version of the device to MCS.

Request URL

https://api.mediatek.com/mcs/v2/devices/:deviceId/firmwares

The device is able to report its current firmware version to MCS platform by using this API. Please note: The reported version must be one of the uploaded firmwares on MCS platform.

This API could be used by device to report its initial firmware version when it boots up for the first time and then keep this firmware information updated when the firmware upgrade is done. This could be a useful information for device management.

Action

HTTPs PUT

Parameters

Header

deviceKey: device_key_here

Content-Type:application/json

Body

For JSON format

{
    "version": "fw_version"
}

Return format

The return format is in json format

Response

Response Code

200

Response Header

For JSON response:

Content-Type:`application/json`

Response Body

Data Format: JSON

The response body will construct in JSON format with the following fields:

Field Name Type Description
fwId string the firmware ID of this reported version
code string http status code
message string system log message

Example:

Request URL

https://api.mediatek.com//mcs/v2/devices/DAWfOAsi/firmwares

Request Header

deviceKey: g06jBWOtB0kqHk2B

Content-Type:application/json

Request Body

{
    "version": "v1"
}

Response Body

{
    "apiVersion": "2.8.0",
    "code": 200,
    "message": "Request has succeeded",
    "fwId": "FAa6B540CMmJ"
}

Error Response

When error is incurred, the response code will be non-200 and the response body will construct in JSON format with the following fields:

Field Name Type Description
code Integer Error Code
message String Error Description

Example:

{
    "apiVersion": "2.8.0",
    "code": 404,
    "message": "404 Not Found",
    "errors": [
        {
            "code": 404,
            "message": "404 Not Found"
        }
    ],
    "statusCode": 404,
    "options": {}
}

Retrieve Device Available Firmware

Description

Use HTTPs GET to retrieve the available firmwares for this device from MCS.

Request URL

https://api.mediatek.com/mcs/v2/devices/:deviceId/firmwares/available

To retrieve the available firmwares for this device.

If this device has reported its firmware version to MCS platform, this API provides a list of firmwares which are compatible with the current version. If the device hasn't reported any firmware yet, then, only the firmwares without any compatibility limitation are listed.

Query string

Following fields could be constructed and appended to the end of the URL:

Field Name Type Required Description
url string boolean An optional parameter. Append url=true to get the download URL in the response.

Action

HTTPs GET

Parameters

Header

deviceKey: device_key_here

Content-Type:application/json

Return format

The return format is in JSON format

Response

Response Code

200

Response Header

For JSON response:

Content-Type:`application/json`

Response Body

Data Format: JSON

The response body will construct in JSON format with the following fields:

Field Name Type Description
results array the available firmware list for the device, and it includes
1. fwid: The firmware ID
2. name
3. description
4. version
5. URL: The firmware download URL (If there is a query string, url=true, in the request)
code string http status code
message string system log message

Example:

Request URL

https://api.mediatek.com//mcs/v2/devices/DAWfOAsi/firmwares/available

Request Header

deviceKey: g06jBWOtB0kqHk2B

Content-Type:application/json

Response Body

{
    "apiVersion": "2.8.0",
    "code": 200,
    "message": "Request has succeeded",
    "results": [
        {
            "fwid": "FAdJBknrDsOM",
            "name": "hello firmware",
            "description": null,
            "version": "1"
        },
        {
            "fwid": "Fwnx3ZBxOLCK",
            "name": "firmware_2",
            "description": null,
            "version": "2"
        }
    ]
}

Error Response

When error is incurred, the response code will be non-200 and the response body will construct in JSON format with the following fields:

Field Name Type Description
code Integer Error Code
message String Error Description

Example:

{
    "apiVersion": "2.8.0",
    "code": 401,
    "message": "401 Unauthorized",
    "errors": [
        {
            "code": 401,
            "message": "401 Unauthorized"
        }
    ],
    "results": "you dont have permission!",
    "statusCode": 401,
    "options": {}
}

Retrieve Compatible Firmware by Version

Description

Use HTTPs GET to retrieve the compatible firmwares for a specified firmware version.

Request URL

https://api.mediatek.com/mcs/v2/devices/:deviceId/firmwares/available/:versionId

This API provides a flexibility to query the compatible firmwares for a specified firmware version.

Query string

Following fields could be constructed and appended to the end of the URL:

Field Name Type Required Description
url string boolean append url=true to get the download URL in the response.

Action

HTTPs GET

Parameters

Header

deviceKey: device_key_here

Content-Type:application/json

Return format

The return format is in json format

Response

Response Code

200

Response Header

For JSON response:

Content-Type:`application/json`

Response Body

Data Format: JSON

The response body will construct in JSON format with the following fields:

Field Name Type Description
results array the compatible firmwares list for the specified firmware version, please refer to /firmware/available API
code string http status code
message string system log message

Example:

Request URL

https://api.mediatek.com//mcs/v2/devices/DAWfOAsi/firmwares/available/1

Request Header

deviceKey: g06jBWOtB0kqHk2B

Content-Type:application/json

Response Body

{
    "apiVersion": "2.8.0",
    "code": 200,
    "message": "Request has succeeded",
    "results": [
        {
            "fwid": "FAdJBknrDsOM",
            "name": "hello firmware",
            "description": null,
            "version": "2"
        },
        {
            "fwid": "Fwnx3ZBxOLCK",
            "name": "firmware_2",
            "description": null,
            "version": "3"
        }
    ]
}

Error Response

When error is incurred, the response code will be non-200 and the response body will construct in JSON format with the following fields:

Field Name Type Description
code Integer Error Code
message String Error Description

Example:

{
    "apiVersion": "2.8.0",
    "code": 401,
    "message": "401 Unauthorized",
    "errors": [
        {
            "code": 401,
            "message": "401 Unauthorized"
        }
    ],
    "results": "you dont have permission!",
    "statusCode": 401,
    "options": {}
}

Retrieve Firmware URL

Description

Use HTTPs GET to retrieve the download URL of specified firmware.

Request URL

https://api.mediatek.com/mcs/v2/devices/:deviceId/firmwares/:fwId/url

To retrieve the download URL of specified firmware. You can use /firmwares/available API to get a list of compatible firmwares for your device and then specify the firmware ID in this API to get the download URL.

Action

HTTPs GET

Parameters

Header

deviceKey: device_key_here

Content-Type:application/json

Return format

The return format is in json format

Response

Response Code

200

Response Header

For JSON response:

Content-Type:`application/json`

Response Body

Data Format: JSON

The response body will construct in JSON format with the following fields:

Field Name Type Description
url array the firmware download URL
code string http status code
message string system log message

Example:

Request URL

https://api.mediatek.com/mcs/v2/devices/DAWfOAsi/firmwares/FAdJBknrDsOm/url

Please be noted, you can get the firmware id by calling the retrieve device available firmware API.

Request Header

deviceKey: g06jBWOtB0kqHk2B

Content-Type:application/json

Response Body

{
    "apiVersion": "2.8.0",
    "code": 200,
    "message": "Request has succeeded",
    "url": "https://s3-ap-southeast-1.amazonaws.com/mtk.linkit/firmwares/PvFn1zENgBei/firmware1.bin"
}

Error Response

When error is incurred, the response code will be non-200 and the response body will construct in JSON format with the following fields:

Field Name Type Description
code Integer Error Code
message String Error Description

Example:

{
    "apiVersion": "2.8.0",
    "code": 404,
    "message": "404 Not Found",
    "errors": [
        {
            "code": 404,
            "message": "404 Not Found"
        }
    ],
    "statusCode": 404,
    "options": {}
}

Device activation

Description

Use HTTPs GET to activate the device.

Request URL

https://api.mediatek.com/mcs/v2/devices/activate/:activationCode

To activate the device.

Action

HTTPs GET

Parameters

Header

Content-Type:application/json

Return format

The return format is in json format

Response

Response Code

200

Response Header

For JSON response:

Content-Type:`application/json`

Response Body

Data Format: JSON

The response body will construct in JSON format with the following fields:

Field Name Type Description
code String http status code
deviceKey String The deviceKey
deviceId String The deviceId
chipname String The device name
message String System log message

Example:

Request URL

https://api.mediatek.com/mcs/v2/devices/activate/edb4b2eil152

Request Header

Content-Type:application/json

Response Body

{
    "apiVersion": "2.10.1",
    "code": 200,
    "message": "Request has succeeded",
    "deviceId": "JU5z4yVF",
    "deviceKey": "yQGymH0IRWFSVC37",
    "chipName": "Device for IoT prototype"
}

Error Response

When error is incurred, the response code will be non-200 and the response body will construct in JSON format with the following fields:

Field Name Type Description
code Integer Error Code
message String Error Description

Example:

{
    "apiVersion": "2.10.1",
    "code": 400,
    "message": "Wrong activate Code.",
    "errors": [
        {
            "code": 400,
            "message": "400 Bad Request"
        }
    ],
    "statusCode": 400,
    "options": {}
}

MQTT communication format

The MQTT communication format of each data type is defined here. This format is for both subscribe or publish.

The client device will get the data as the following format from the MQTT broker, and the user can write a parser in the device to parse the data needed. When publising, use the same format to publish the data back to the MCS MQTT broker.

Prerequsite

Before the client device can receive or send the message to MQTT broker, the client device need to connect to the MCS MQTT broker and subscribe or publish to a topic.

Set Up Connection

MQTT Broker Host: mqtt.mcs.mediatek.com

Port: 1883(un-encrypted) or 8883(encrypted)

Please note, MCS is using server site signed mechanism while using the encypted port.

Subscribe & Publish

After you've connected to the MCS MQTT broker, you can subscribe to specific device or data channel; you can also publish to specific data channel.

For subscription, the topic is defined in the following format:

mcs/:deviceId/:deviceKey/:dataChnId

Or to subscribe all data channels in a device:

mcs/:deviceId/:deviceKey/+

For publish, the topic is defined in the following format:

mcs/:deviceId/:deviceKey/:dataChnId

Or to publish any data channel(s) in a device:

mcs/:deviceId/:deviceKey

MQTT subscription and publish formats

The general format of the payload is:

timestamp,dataChnId,value

where timestamp is using UNIX timestamp format if you omit the timestamp value shown as below, then MCS will auto-create the timestamp for this datapoint when received.

,dataChnId,value

When publish under a specific dataChnId

mcs/:deviceId/:deviceKey/:dataChnId

you may also omit the dataChnId as well

,,value

When publish under a device (without specify data channel), you cannot omit dataChnId. You can upload several values in one publish:

timestamp,dataChnId1,value1
timestamp,dataChnId2,value2
.
.
.

Below are examples for different Data Channel types:

Switch

timestamp,dataChnId,{0 or 1}

0 stands for OFF, and 1 stands for ON.

For example:

, switch01, 1

To turn the switch01 to on state, and do not give the timestamp.

Category

timestamp,dataChnId,{Key Value}

The Key value will correspond to the Key name that you’ve set.

Integer

timestamp,dataChnId,{Integer}

Float

timestamp,dataChnId,{Float}

Hex

timestamp,dataChnId,{Hex value}

Hex is referred to hexadecimal value which only takes value from A-D and 0-9.

String

timestamp,dataChnId,{string}

GPS

timestamp,dataChnId,{latitude},{longitude},{altitude}

The range of latitude is from -90 to 90. 0 to 90 stands for North and 0 to -90 stands for South.

The range of longitude is from -180 to 180. 0 to 180 stands for East and 0 to -180 stands for West.

The range of altitude is from 0 to 20000 in meter.

GPIO

timestamp,dataChnId,{0 ot 1}

0 stands for Low, and 1 stands for High.

PWM

timestamp,dataChnId,{value},{period}

Analog

timestamp,dataChnId,{value}

Gamepad

timestamp,dataChnId,{up/down/right/left/A/B value| press(1) or release(0)}

Image

timestamp,dataChnId,{image file base64 encoding string value}