API 參考資料集

MediaTek Cloud Sandbox (MCS) 提供一系列的 RESTful API 讓您能夠便利的使用,例如上傳和讀取資料點,或是透過 TCP socket 對裝置下指令。MCS 亦能儲存照時間排序的資料數列,並以圖表化形式呈現給您。

Request URL

您可以透過以下網址來呼叫 MCS API:

https://api.mediatek.com/v2

參數

跟在連接點後的參數用來在 URL 路徑內,定義特定的資源:

https://api.mediatek.com/v2/devices/{deviceId}/retrieveDataPoints

在上方的範例中,您可以看到 deviceId 在 URL 中被定義了。在任何的 API 請求中,不是以 URL 形式傳送的參數,都必須定義以 JSON 或是 CSV 格式包裝。您必須定義一個content -Type header 為application/json 或是 text/csv

客戶端錯誤

Mediatek Cloud Sandbox (MCS) 使用標準 HTTP 狀態來表達 API 請求的成功或是錯誤。以下是您呼叫 MCS API 有可能遇到的 HTTP 狀態:

200 OK - 請求成功。

201 Created- 請求成功,並且新資源已建立。

202 Accepted - 請求成功,但尚未完成。

204 No Content -請求成功,但伺服器無回應任何內容。通常是刪除特定資源的請求回覆。

400 Bad Request - 伺服器無法處理請求,由於客戶端給的參數錯誤。

401 Unauthorized - 無提供授權或授權失敗。需要提供授權的 header。

403 Forbidden -伺服器拒絕對一個不合格的請求做回覆。

404 Not Found - 請求的資源不存在。

405 Method Not Allowed - 請求的方法不支援。

500, 502 Server Error - MCS伺服器錯誤。

HTTP 請求方式

The MediaTek Cloud Sandbox (MCS) 提供以下型式的 API 請求方式:

GET - 用來取得資源狀態。

POST - 用來建立資源。

PUT - 用來更新資源狀態。

DELETE - 用來刪除資源。

授權

所有的 API 請求皆須被授權。您必須有一個 header Authentication 為您的 Bearer token。如果未提供此授權碼,系統則會回覆您無授權訊息。

資源 ID

每次當一個產品原型,資料通道,或是測試裝置被建立後,都會有一個獨特的 ID 被指派給該資源。這個獨特的 ID 是不可編輯的,且您將再存取此資源時用到。您無法存取您無 ID 的資源。

舉例來說,如欲從 MCS 取得某一資料通道的資料,您必須擁有此資料通道以及所述測試裝置的資源 ID。

資源

以下是您使用 MCS 時,會時常使用到的詞彙:

資料通道

一個資料通道是一個能夠傳送從裝置回傳的資料至 MCS 平台,或是能夠將指令從 MCS 平台傳達至裝置的通道。簡單來說,資料通道是一個雲和裝置之間單方向或是雙方向的溝通管道。

MCS 提供了許多 API 讓使用者能夠快速的存取資料通道上得資料點。

裝置

在 MCS 平台上有兩種種類的裝置,其中第一種是測試裝置。測試裝置為在商品上市前,開發者可以用來測試開發結果的裝置。第二種裝置為商轉後大量給終端使用者實際使用的裝置。

MCS 提供了許多 API 讓開發者和其他使用者能夠快速的存取資料通道上的資料點,或是遠端控制裝置狀態。

產品原型

產品原型是您將來要交付的終端商品。MCS 提供了許多 API 讓使用者能夠使用。開發者能在產品原型頁面中開發產品,例如新增資料通道並建立測試裝置來測試確保之後商轉功能。

上傳資料點

描述

使用 HTTPs POST 來上傳資料點

請求 URL

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

API請求默認值為 JSON 格式,如欲使用 CSV 格式,請在 API 請求 URL 最後端加上.csv

請注意,MCS 限制單筆上傳資料量為一次不能上傳多於五筆資料點。

動作

HTTPs POST

參數

Header

Token

若是裝置:

deviceKey: `device_key_here`

若是服務提供者:

appId: `appId_here`
appSecret: `appSecret_here`

您可以在個人檔案頁面中的服務提供者分頁,申請取得 appId 以及 appSecrete。

Content Type

JSON 格式:

Content-Type:`application/json`

Comma Separated Value (CSV) 格式:

Content-Type:`text/csv`

內容

CSV 格式:

語法:

:Data_Channel_Id_1, :Timestamp, :Value_1, :Value_2, :Value_3\n

:Data_Channel_Id_2, :Timestamp, :Value_1\n

如欲參考更多詳細的資料通道類型之格式,請參考資料通道格式,您可點擊右方快速聯結前往.

請注意:若您不需要上傳裝置的時間點,則您可保持 Timestamp 為空(但保留逗號),此時時間點則會由MCS所收到資料點的時間。

範例:

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

第一行:資料通道 ID 為 1,並且給予時間點,26 為上傳的值(此時的資料通道類型為整數)。

第二行:資料通道 ID 為 2,並且不給予時間點,26.34 為上傳的值(此時的資料通道類型為浮點數)。

JSON 格式

語法:

每個 JSON 格式的資料點,都包含下列三種型態的資料:

dataChnId, timestamp, values

Values 是資料點的值,大部分情況下代表一個值。但也有例外,例如 GPS 資料就會有三個值。

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

資料點1: 資料通道 ID 為 1,並且給予時間點,26 為上傳的值(此時的資料通道類型為整數)。

資料點2: 資料通道 ID 為 2,並且給予時間點,緯度 26.34,經度 12,高度 59,為上傳的值(此時的資料通道類型為 GPS )。

請注意,我們在此使用的 unix timestamp miniseconds 時間值,若須轉換成可讀格式,您可以使用以下連結: http://www.epochconverter.com/

回覆

回覆代碼

200

回覆 Header

Content-Type:application/json

回覆內容

範例:

請求 URL:

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

請求內容:

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

回覆內容:

{
    "results": "success"
}

錯誤回覆

當錯誤發生時,回覆代碼為非 200 之其他代碼。回覆內容為 JSON 格式並會包括以下資訊:

欄位名稱 格式 描述
code Integer 錯誤代碼
url String API 錯誤頁面 url
description String 錯誤描述

範例:

{
    "results": "None of the data points is valid.",
    "descriptions": [
        "The type of uploaded data point for data channel test01 is not matched to Switch"
    ]
}

讀取資料點

描述

使用 HTTPs GET 來取得裝置回傳的資料點

請求 URL

讀取特定資料通道中的資料點:

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

API 請求默認值為 JSON 格式,如欲使用 CSV 格式,請在 API 請求 URL 最後端加上.csv。 使用此 API,您可以選擇您要的資料範圍:

  • 只讀取最後一個資料點:
    https://api.mediatek.com/mcs/v2/devices/:deviceId/datachannels/:datachannelId/datapoints
    
  • 讀取一段時間範圍內的資料點:
    在請求url尾端加上`?start=:startTime&end=:endTime`
    

請注意,若您只使用開始時間和結束時間,系統只會回覆您此區間內的最後一筆資料。若您希望取得此區間內的更多資料點,您可以使用 limit 來定義您想取得此區間內的幾筆資料點。

  • 限制您要讀取的資料點數目 (舉例來說, 如果您輸入 limit=5, 則您會讀取前五筆資料點):
    在請求url尾端加上 `?limit=:limit`
    

您亦可以將以上四種方式混合使用。

查詢字串

下面幾種查詢方式亦可以使用

欄位名稱 格式 是否必填 描述
start_time Number Optional 查詢起始時間
end_time Number Optional 查詢中止時間
limit Number Optional 要回傳的資料點數目 ( 默認值 = 1 )
offset Number Optional 第幾筆開始的資料點

請注意:

1. 使用 limit 查詢最後 n (n=數目) 的資料點時,將不能指定 start_timeend_time時。

2. 當您指定 start_timeend_time 時,若還是有使用設定回傳資料點數目,此時,此回傳資料點數目的查詢將會被忽略。

每次請求最多只能讀取 1000 筆資料點

動作

HTTPs GET

參數

Header

Device Key

deviceKey: `device_key_here`

回覆格式

您能選擇回覆 JSON 或是 CSV 格式

JSON:

請求 url 結尾為 datapoints

CSV:

請求 url 結尾為 datapoints.csv

回覆

回覆代碼

200

回覆 Header

JSON 格式:

Content-Type:`application/json`

CSV 格式:

Content-Type: `text/csv`

回覆內容

資料格式: JSON

若使用 JSON 回覆格式,則會包含以下欄位:

欄位名稱 格式 描述
dataChannels Object Array 含有資料點的資料通道

資料詳情

資料通道

欄位名稱 格式 描述
dataChnId Number 資料通道 ID
isOverflow Bool 要求的資料點是否超過數目限制
dataPoints Object Array 資料點

資料點

欄位名稱 格式 描述
createdAt Number 以 Unix timestamp 格式紀錄的資料點建立時間
values Object 資料點的值

請注意,我們在此使用的 unix timestamp miniseconds 時間值,若須轉換成可讀格式,您可以使用以下連結: http://www.epochconverter.com/

範例:

請求 URL:

https://api.mediatek.com/mcs/v2/devices/a1234567890/datachannels/10001/datapoints?start=946684800&end=946784800

JSON 格式的回覆內容:

{
    "deviceId": "DXLQwmnN",
    "dataChannels": [
        {
            "dataChnId": "test01",
            "isOverflow": false,
            "dataPoints": [
                {
                    "recordedAt": 1432538716989,
                    "values": {
                        "value": "HI"
                    }
                }
            ]
        }
    ]
}

CSV 格式的回覆內容:

test_data_channel,1432538716989,100

錯誤回覆

當錯誤發生時,回覆代碼為非 200 之其他代碼。回覆內容為 JSON 格式並會包括以下資訊:

欄位名稱 格式 描述
code Integer 錯誤代碼
url String API 錯誤頁面 url
description String 錯誤描述

範例:

{
    "results": "you dont have permission!"
}

讀取裝置資訊

描述

使用 HTTPs GET 來讀取裝置資訊

請求 URL

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

動作

HTTPs GET

參數

Header

Authorization: Bearer '{token}'

Content-Type:application/json

回覆

回覆代碼

200

回覆 Header

Content-Type:application/json

回覆內容

回覆格式: JSON

JSON格式的回覆會包含以下幾個欄位:

欄位名稱 格式 描述
deviceId String Device ID
deviceKey String Device Key
name String 裝置名稱
description String 裝置描述
product Object 產品原型
dataChannels Object Array 資料通道
fw Object 韌體資訊
trustIpRange String Array 可連至 MCS 的信賴網域範圍
lastIp String 最後一次收到裝置資料點的網域位址
deviceImageURL String 裝置圖片 URL
isHeartbeating Bool 裝置是否在線
isVerified Bool 裝置是否已被驗證註冊
isActive Bool 裝置是否已註冊
isTest Bool 是否為測試裝置
activatedAt Number 裝置註冊時間
deactivatedAt Number 裝置註銷時間 (若裝置已註冊且未被註銷,則此值的默認值為 null)
tags Object Array 裝置標籤
privilege String 裝置使用者權限

資料詳情

產品原型

欄位名稱 格式 描述
prodId String 產品原型 ID
prodVersion String 產品原型版本
name String 產品原型名稱
description String 產品原型描述
displayConfigs Object Array 一個 JSON 格式的物件,定義資料通道將如何呈現
chip String 產品原型所使用的晶片類型

資料通道

欄位名稱 格式 描述
dataChnId Number 資料通道 ID
isAvailable Bool 資料是否可用
name String 資料通道名稱
channelType Object 資料通道類型
isHidden Bool 資料通道是否對使用者隱藏
isControllable Bool 此資料通道是否為控制類型
description String 資料通道描述
unitType Object 資料通道單位值
format String 資料通道格式

韌體

欄位名稱 格式 描述
fwId String 韌體 ID
name String 韌體名稱
description String 韌體描述
version Number 韌體版本

顯示設定

欄位名稱 格式 描述
displayType Number 如何顯示
displayOrder Number 不同元件的顯示順序
dataChnIds Number Array 被設定為顯示的資料通道ID

標籤

欄位名稱 格式 描述
tagId Number 標籤 ID
name String 標籤名稱

範例:

請求 URL

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

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

回覆內容

{
   "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"
      }
   ]
}

錯誤回覆

當錯誤發生時,回覆代碼為非 200 之其他代碼。回覆內容為 JSON 格式並會包括以下資訊:

欄位名稱 格式 描述
code Integer 錯誤代碼
url String API 錯誤頁面 url
description String 錯誤描述

範例

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

取得連結

描述

使用 HTTPs GET 來設置裝置和 MCS Command server 之間的連線

請求 URL

設置裝置和 MCS Command server 之間的連線:

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

設定裝置和 Command server 之間的 TCP 長連結,裝置首先需要呼叫 RESTful API Get connection 來取得一組 ip 位置以及連接阜來建立 TCP 長連結。MCS 將會回覆 ip 地址和連接阜資訊給裝置。

Command server 回覆格式:

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

當裝置收到覆 ip 地址和連接阜後,裝置會發出一個 heartbeat 給 command server 來驗證。裝置也會每 120 秒發送一次 heartbeat 給 command server 來確保連線。

Heartbeat 格式:

    deviceId,deviceKey,timestamp

此處使用 UNIX timestamp 時間格式。若您不希望在 heartbeat 中傳送實際的 timestamp,您可以直接在 timestamp 欄位輸入 0 為其值 ,系統將自動帶入系統時間。

當 TCP 長連結建立後,您將可以透過 MCS 平台對裝置下指令。

指令格式:

{
    deviceId,deviceKey,timestamp,dataChnId,commandValue
}

動作

HTTPs GET

參數

Header

Content-Type:application/json or text/csv

deviceKey: device_key_here

回覆格式

回覆格式可以有 JSON 或是 CSV 兩種

JSON:

請求 url 結尾為 connections

CSV:

請求 url 結尾為 connections.csv

回覆

回覆代碼

200

回覆 Header

JSON格式:

Content-Type:`application/json`

CSV格式:

Content-Type: `text/csv`

回覆內容

回覆格式: JSON

JSON 格式的回覆內容會包含以下幾個欄位:

欄位名稱 格式 描述
ip array command server ip 位置
port integer command server 提供給裝置連接的連接阜

範例:

請求 URL

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

請求內容

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

}

錯誤回覆

當錯誤發生時,回覆代碼為非 200 之其他代碼。回覆內容為 JSON 格式並會包括以下資訊:

欄位名稱 格式 描述
code Integer 錯誤代碼
url String API錯誤頁面url
description String 錯誤描述

範例:

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

資料通道格式

此章節將會說明所有資料通道的 API 格式,此格式為裝置和 command server 溝通的格式。

**此處使用 UNIX timestamp 時間格式,且非必要欄位。您可保持 Timestamp 為空,此時時間點則會由 MCS 所收到資料點的時間。

MCS 支持 JSON 以及 CSV 兩種格式的資料。

開關

JSON 格式:

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

CSV 格式:

dataChnId,timestamp,{0 or 1}

0 代表關,1 代表開。

範例:

switch01,, 1

代表將 switch01 資料通道的狀態改為開,並且由系統自動帶入時間。

分類

JSON 格式:

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

CSV 格式:

dataChnId,timestamp,{Key Value}

Key value 的值將會對應至您所設定的 Key name。

整數

JSON 格式:

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

CSV 格式:

dataChnId,timestamp,{Integer}

浮點數

JSON 格式:

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

CSV 格式:

dataChnId,timestamp,{Float}

十六進位數

JSON 格式:

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

CSV 格式:

dataChnId,timestamp,{Hex value}

十六進位數的值為 A-F 以及 0-9。

字串

JSON 格式:

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

CSV 格式:

dataChnId,timestamp,{string}

GPS

JSON 格式:

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

CSV 格式:

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

緯度範圍從 -90 至 90。 0 至 90 代表北緯,0 至 -90 代表南緯。

經度範圍從 -180 至 180。 0 至 180 代表東經,0 至 -180 代表西經。

高度範圍從 -20000 至 20000 公尺。

GPIO

JSON 格式:

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

CSV 格式:

dataChnId,timestamp,{0 ot 1}

0 代表低,1 代表高。

PWM

JSON 格式:

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

PWM的值和期間只能為 0 至 1000 之間。

CSV 格式:

dataChnId,timestamp,{Value},{Period}

類比

JSON 格式:

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

CSV 格式:

dataChnId,timestamp,{Integer value}

整數的範圍需由使用者自行定義

遊戲控制器

JSON 格式:

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

CSV 格式:

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

使用者可以決定是否同時給上下左右的值和 AB 鍵的值。

舉例來說,若使用在建立遊戲控制器資料通道時,將上的值設為 up,當使用者點上時,對應的值為 up|0。若長按 up,對應的值則為 up|1

您可以使用預設的鍵盤熱鍵如下:

上 = W

下 = S

左 = A

右 = D

鍵 A = ,

鍵 B = .

圖片

JSON 格式:

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

CSV 格式:

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

在上傳圖片檔案至 MCS 之前,您必須先將圖片檔案轉為 base64 編碼的字串。上傳此字串至圖片資料通道後,此圖片將會被儲存與顯示。

請注意,目前圖片資料通道支援 JPG、JPEG、和 PNG三種圖片檔案格式。一旦上傳至 MCS 後,則都會被儲存為 PNG 檔案格式。

影像串流

有別於其他資料通道,可以透過上傳 CSV 或是 JSON 格式的資料更新資料點,您在使用影像串流前必須先在設備上安裝視頻轉換器套件。

以下是目前 MCS 所支援的影像串流規格

  • 影像格式:MPEG1
  • 最大解析度:320x240
  • 最大畫面更新率:30 fps
  • MCS 影像串流服務器:
http://stream-mcs.mediatek.com/:deviceId/:deviceKey/:dataChnId/:width/:height

請將其中的 deviceId, deviceKey, dataChnId, width 和 height 更換成您設備上實際的數據。其中 width 與 height 是上傳影像串流時所設定的解析度大小。

  • 在 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 格式

此章節將會說明所有 command server 的格式,此格式為 command server 發送指令置裝置的格式。

**此處使用 UNIX timestamp 時間格式。

裝置會從 command server 接收到以下格式的指令,並且使用者可以自行寫一段解析程式來處理收到的指令。

事前準備

在裝置能接收 MCS 指令前,裝置須先和 MCS 平台做相連。

呼叫 RESTful API: GET https://api.mediatek.com/mcs/v2/devices/{deviceId}/connections to 來取得一組 ip 位置以及連接阜來建立連結。

Command server 回覆格式:

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

來打開任意一個 tcp connection,並且傳送一個 heartbeat 訊息。

Heartbeat 格式:

    deviceId,deviceKey,timestamp

若您不希望在 heartbeat 中傳送實際的 timestamp,您可以直接在 timestamp 欄位輸入 0 為其值。

當 TCP 長連結建立後,您將可以開始使用 MCS 平台來對您的裝置下指令。

指令的形式如下:

    deviceId,deviceKey,timestamp,dataChnId,commandValue

各種資料通道的 command 格式

開關

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

0 代表關,1 代表開。

範例:

switch01,, 1

代表將 switch01 資料通道的狀態改為開,並且由系統自動帶入時間。

分類

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

Key value 的值將會對應至您所設定的 Key name。

整數

deviceId,deviceKey,timestamp,dataChnId,{Integer}

浮點數

deviceId,deviceKey,timestamp,dataChnId,{Float}

十六進位數

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

十六進位數的值為 A-F 以及 0-9。

字串

deviceId,deviceKey,timestamp,dataChnId,{string}

GPS

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

緯度範圍從 -90 至 90。 0 至 90 代表北緯,0 至 -90 代表南緯。

經度範圍從 -180 至 180。 0 至 180 代表東經,0 至 -180 代表西經。

高度範圍從 0 至 20000 公尺。

GPIO

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

0 代表低,1 代表高。

PWM

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

類比

deviceId,deviceKey,timestamp,dataChnId,{value}

遊戲控制器

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

圖片

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

回報裝置韌體

描述

使用 HTTPs PUT 來向 MCS 平台回報裝置使用之韌體。

請求 URL

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

向 MCS 平台回報裝置正在使用的韌體。請注意,您必須將此功能自行編碼於您的裝置中,方可使用。

動作

HTTPs PUT

參數

Header

deviceKey: device_key_here

Content-Type:application/json

內容

####JSON 格式

{
    "version": "fw_version"
}

回覆格式

回覆格式為 JSON

回覆

回覆代碼

200

回覆 Header

JSON 格式:

Content-Type:`application/json`

回覆內容

JSON 格式

JSON 格式的回覆內容會包含以下幾個欄位:

欄位名稱 格式 描述
fwId string 裝置所回報的韌體 ID
code string http 狀態代碼
message string 系統訊息

範例:

請求 URL

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

請求 Header

deviceKey: g06jBWOtB0kqHk2B

Content-Type:application/json

請求內容

{
    "version": "v1"
}

回覆內容

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

錯誤回覆

當錯誤發生時,回覆代碼為非 200 之其他代碼。回覆內容為 JSON 格式並會包括以下資訊:

欄位名稱 格式 描述
code Integer 錯誤代碼
message String 錯誤描述

範例:

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

取得裝置所有韌體資訊

描述

使用 HTTPs GET 來從 MCS 平台取得該裝置所有韌體資訊清單。

請求 URL

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

取得裝置所有韌體資訊清單。

動作

HTTPs GET

參數

Header

deviceKey: device_key_here

Content-Type:application/json

回覆格式

回覆格式為 JSON

Response

回覆代碼

200

回覆 Header

JSON 格式:

Content-Type:`application/json`

回覆內容

JSON 格式

JSON 格式的回覆內容會包含以下幾個欄位:

欄位名稱 格式 描述
results array 所有該裝置的韌體清單資訊
code string http 狀態代碼
message string 系統訊息

範例:

請求 URL

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

請求 Header

deviceKey: g06jBWOtB0kqHk2B

Content-Type:application/json

回覆內容

{
    "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"
        }
    ]
}

錯誤回覆

當錯誤發生時,回覆代碼為非 200 之其他代碼。回覆內容為 JSON 格式並會包括以下資訊:

欄位名稱 格式 描述
code Integer 錯誤代碼
message String 錯誤描述

範例:

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

取得裝置可相容之韌體資訊

描述

使用 HTTPs GET 來從 MCS 取得裝置特定韌體可相容之韌體資訊。

請求 URL

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

取得裝置特定韌體可相容之韌體資訊。

動作

HTTPs GET

參數

Header

deviceKey: device_key_here

Content-Type:application/json

回覆格式

回覆格式為 JSON

回覆

回覆代碼

200

回覆 Header

JSON 格式

Content-Type:`application/json`

回覆內容

JSON 格式:

JSON 格式的回覆內容會包含以下幾個欄位:

欄位名稱 格式 描述
results array 所有該裝置可相容的韌體清單資訊
code string http 狀態代碼
message string 系統訊息

範例:

請求 URL

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

請求 Header

deviceKey: g06jBWOtB0kqHk2B

Content-Type:application/json

回覆內容

{
    "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"
        }
    ]
}

錯誤回覆

當錯誤發生時,回覆代碼為非 200 之其他代碼。回覆內容為 JSON 格式並會包括以下資訊:

欄位名稱 格式 描述
code Integer 錯誤代碼
message String 錯誤描述

範例:

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

啟用裝置

描述

使用 HTTPs GET 來啟用裝置

請求 URL

使用以下 API 來啟用您的裝置

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

動作

HTTPs GET

參數

Header

Content-Type:application/json

回覆格式

回覆格式是 JSON 格式

回覆

回覆代碼

200

回覆 Header

JSON 格式:

Content-Type:`application/json`

回覆內容

回覆格式: JSON

JSON格式的回覆內容會包含以下幾個欄位

欄位名稱 資料型態 描述
code String http 狀態碼
deviceKey String The device key
deviceId String The device ID
chipname String 設備名稱
message String 系統日誌

範例:

請求 URL

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

請求 Header

Content-Type:application/json

回覆內容

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

錯誤回覆

當有錯誤發生時,回傳非 200 之其他回覆代碼。回覆內容為 JSON 格式並包含以下資訊:

欄位名稱 資料型態 描述
code Integer 錯誤代碼
message String 錯誤說明

範例:

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

MQTT 溝通格式

此章節將會說明所有 MQTT 溝通格式,此格式為當裝置有訂閱主題,或是欲傳送資訊至 MQTT Broker 時,所會接收或是發送的格式。

事前準備

終端裝置必須先連結至 MCS MQTT Broker 並且訂閱或是發佈至一個主題,之後才可和 MCS 做訊息交換。

設定連線

MQTT 伺服器: mqtt.mcs.mediatek.com

連接阜: 1883(未加密) 或 8883(加密)

請注意, 當您使用加密阜時,MCS 使用伺服器端加密方式。

訂閱 & 發佈

當您連結上 MCS MQTT 伺服器後,您可以訂閱整個裝置或是個別資料通道的訊息;或是發佈訊息至特定資料通道。

當要訂閱特定資料通道時,訂閱主題的格式如下:

mcs/:deviceId/:deviceKey/:dataChnId

或是可訂閱特定裝置下全部資料通道:

mcs/:deviceId/:deviceKey/+

當要發佈時, 發佈主題的格式如下:

mcs/:deviceId/:deviceKey/:dataChnId

MQTT 訂閱和發佈資料格式

**此處使用 UNIX timestamp 時間格式。

開關

timestamp,dataChnId,{0 or 1}

0 代表關,1 代表開。

範例:

,switch01, 1

代表將 switch01 資料通道的狀態改為開,並且由系統自動帶入時間。

分類

timestamp,dataChnId,{Key Value}

Key value 的值將會對應至您所設定的 Key name。

整數

timestamp,dataChnId,{Integer}

浮點數

timestamp,dataChnId,{Float}

十六進位數

timestamp,dataChnId,{Hex value}

十六進位數的值為 A-F 以及 0-9。

字串

timestamp,dataChnId,{string}

GPS

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

緯度範圍從 -90 至 90。 0 至 90 代表北緯,0 至 -90 代表南緯。

經度範圍從 -180 至 180。 0 至 180 代表東經,0 至 -180 代表西經。

高度範圍從 0 至 20000 公尺。

GPIO

timestamp,dataChnId,{0 ot 1}

0 代表低,1 代表高。

PWM

timestamp,dataChnId,{value},{period}

類比

timestamp,dataChnId,{value}

遊戲控制器

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

圖片

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