API 參考手冊

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

請求網址(Request URL)

MCS 提供的各個服務皆位於此網址(URL)之下。

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

您可透過在請求網址(URL)當中指定資源 ID 來使用該資源所提供的服務。以底下的請求為例,我們透過指定裝置與資料通道的 ID(deviceID 與 dataChannelID)來使用 datapoints 相關的服務。

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

範例

以下為獲取 datapoints 的完整請求(需將 {variable} 換成您的真實數據),在後續的章節中會有更詳細的描述。

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

請求方法(Request Method)

The MediaTek Cloud Sandbox (MCS) 提供以下幾種 API 請求方法:

  • GET - 用來取得資源狀態。

  • POST - 用來建立資源。

  • PUT - 用來更新資源狀態。

  • DELETE - 用來刪除資源。

請求表頭(Request Header)

###1. 存取授權憑證(Access Token)

所有的 API 請求皆須被授權,因此您必須在請求表頭當中帶入授權憑證,才有權限存取對應的資源,進行對應的操作。MCS 開放的授權憑證主要有兩種:

  • 服務提供者(service provider)帳號

    如果您是自行開發應用程式,包括手機 App 或網站應用,您可以在個人檔案頁面中的服務提供者分頁,申請取得 appId 以及 appSecret,使用此憑證存取 MCS 開放的所有 APIs。接著在所有 MCS 服務請求表頭(request header)中帶入 appIDappSecret 資訊。

      appId: {your_appId}
      appSecret: {your_appSecret}
    
  • 裝置金鑰(device key):

    如果您開發的是裝置端的應用,且只需要使用裝置相關的服務 APIs,例如上傳與獲取資料點等,則您可直接使用裝置 ID 與金鑰作為認證。您可以在裝置詳情頁面中找到裝置 ID 與金鑰,接著在所有 MCS 服務請求表頭(request header)中帶入 deviceKey 資訊。

      deviceKey: {your_device_key}
    

    由於裝置 ID 已用於請求網址(request URL)中,用以指定所要存取的資源,因此不需再帶入表頭中。

###2. 內文格式(content-type) 您必須在請求表頭中加上 content-type 這個欄位讓 MCS 服務知道請求的內文格式並進行後續的處理與運算。

  • content-type: application/json 表示內文為 JSON 格式。
  • content-type: text/csv 表示內文為 CSV 格式。

請求內文(Request Body)

MCS 所支援的請求內文為 JSONCSV 格式,不同的 APIs 服務所需要的參數皆不同,因此詳細的請求內容會在個別的 APIs 章節中介紹。

參數(Parameter)

以下介紹幾個在使用 MCS APIs 時會用到的參數、格式以及代表意義。

  • 時間戳(timestamp)

    時間戳是用來記錄一個資源被創建或更新的時間點,像是上傳資料點當時的時間、產品原型被建立的時間等等。在 MCS 系統中,時間是用 Unix Epoch 格式來表示,時間單位為毫秒(millisecond)。若您需要將 Unix Epoch 時間轉換成可讀性較高的常規表示法,可參考 http://www.epochconverter.com/,例如:

    Timestamp in milliseconds: 1524720177000 可轉換成 Human time (GMT): Thursday, April 26, 2018 5:22:57 AM

  • 資源 ID

    每次當一個產品原型、測試裝置、資料通道或是韌體檔案被建立後,都會有一個獨特的 ID 被指派給該資源。這個獨特的 ID 是不可編輯的,您可透過它存取該資源。

    舉例來說,如欲從 MCS 取得某一資料通道的上傳數據,您必須先知道此資料通道 ID 以及所屬的測試裝置 ID,並將其帶入 HTTP 請求中以指定所要存取的資源。以下為三個 MCS 主要的資源類型。

    1. 資料通道:一個資料通道是一個能夠傳送從裝置回傳的資料至 MCS 平台,或是能夠將指令從 MCS 平台傳達至裝置的通道。簡單來說,資料通道是一個雲和裝置之間單方向或是雙方向的溝通管道。MCS 提供了許多 APIs 讓使用者能夠快速的存取資料通道上的資料點。

    2. 裝置:在 MCS 平台上有兩種種類的裝置,其中第一種是測試裝置。測試裝置為在商品上市前,開發者可以用來測試開發結果的裝置。第二種裝置為商轉後大量給終端使用者實際使用的裝置。MCS 提供了許多 APIs 讓開發者和其他使用者能夠快速的存取資料通道上的資料點,或是遠端控制裝置狀態。

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

回覆代碼(Response Code)

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伺服器錯誤。

上傳資料點

描述

使用 HTTPs POST 來上傳資料點

HTTP 請求

URL

  • 使用 CSV 格式:

      https://api.mediatek.com/mcs/v2/devices/{deviceId}/datapoints.csv
    
  • 使用 JSON 格式:

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

MCS 單筆上傳一次最多五筆資料點。

方法(Method)

POST

表頭(Header)

1. 存取憑證(Access token)

  • 透過裝置上傳

      deviceKey: {your_device_key}
    
  • 透過您自行開發的應用程式(服務提供者帳號)

      appId: {your_appId}
      appSecret: {your_appSecret}
    

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

2. Content Type

  • 使用 CSV 格式:

      Content-Type: text/csv
    
  • 使用 JSON 格式:

      Content-Type: application/json
    

內文(Body)

  • 使用 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“;”1432538716989“ 為上傳數據時,裝置或您的應用程式產生的時間戳(timestamp);”26“ 為上傳的值。
    第二行:資料通道 ID 為 ”2“;時間戳(timestamp)的欄位為空,由 MCS 服務器自動補上;”26.34“、”12“ 與 ”59“為上傳的數據(此時的資料通道類型為 GPS)。

  • 使用 JSON 格式:

    語法:

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

    1. dataChnId
    2. timestamp
    3. 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“;”1432538716989“ 為上傳數據時,裝置或您的應用程式產生的時間戳(timestamp);”26“ 為上傳的值。

      資料點2: 資料通道 ID 為 ”2“;時間戳(timestamp)的欄位為空,由 MCS 服務器自動補上;”26.34“、”12“ 與 ”59“為上傳的數據(此時的資料通道類型為 GPS)。

HTTP 回覆

回覆代碼

200

表頭(Header)

  • 使用 CSV 格式:

      content-type: text/html
    
  • 使用 JSON 格式:

      Content-Type: application/json
    

內文(Body)

  • 使用 CSV 格式:

      Success.
    
  • 使用 JSON 格式:

      {
          "results": "success"
      }
    

錯誤回覆

當錯誤發生時,MCS 服務器會回應非 200 的錯誤代碼。回覆內容包括以下資訊:

欄位名稱 格式 描述
code Integer 錯誤代碼
message String 錯誤原因
description String 詳細的錯誤描述

範例:

  • 使用 CSV 格式:

      400,None of data points uploaded success.
    
  • 使用 JSON 格式:

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

讀取資料點

描述

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

HTTP 請求

URL

您可以透過指定 URL 中資源路徑與查詢參數來讀取特定資料通道中的資料點。

  • 資源路徑
資源名稱 型別 是否必填 描述
裝置 ID 字串 必填 您需在 URL 中指定你所要獲取資料的裝置 ID
資料通道 ID 字串 必填 您需在 URL 中指定你所要獲取資料的資料通道 ID
  • 查詢參數
參數名稱 型別 是否必填 描述
start 數字 選填 查詢起始時間
end 數字 選填 查詢中止時間
limit 整數 選填 要回傳的資料點數目 ( 默認值 = 1 )
offset 整數 選填 第幾筆開始的資料點
order 字串 選填 資料預設是按照時間戳,由新到舊回傳,您也可透過指定 "asc" 或 "desc" 改變順序

MCS 可將您請求的數據回傳成 JSON 或是 CSV 格式,您可藉由 HTTP 請求中的資源名稱來指定回傳的格式。

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

  • 獲取 JSON 格式的數據

      https://api.mediatek.com/mcs/v2/devices/{deviceId}/datachannels/{datachannelId}/datapoints?start={startTime}&end={endTime}&limit={limit}&offset={offset}
    
  • 獲取 CSV 格式的數據

    若您希望數據以 CSV 的格式回傳,請在資源名稱的最後加上 .csv,變成 datapoints.csv

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

範例

  • 讀取最新一個資料點並以 JSON 格式回傳:

      https://api.mediatek.com/mcs/v2/devices/DL6sA7iSx/datachannels/my_data_channel/datapoints
    
  • 讀取最新一個資料點並以 CSV 格式回傳:

      https://api.mediatek.com/mcs/v2/devices/DL6sA7iSx/datachannels/my_data_channel/datapoints.csv
    
  • 讀取一段時間範圍內的資料點:

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

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

  • 限制您要讀取的資料點數目,MCS 只會回傳最新的 N 筆資料:

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

方法(Method)

GET

表頭(Header)

存取憑證

  • 透過裝置讀取數據

      deviceKey: {your_device_key}
    
  • 透過您自行開發的應用(服務提供者帳號)

      appId: {your_appId}
      appSecret: {your_appSecret}
    

回覆

回覆代碼

200

表頭(Header)

  • JSON 格式:

      content-type: text/html
    
  • CSV 格式:

      content-type: application/json    
    

內文(Body)

  • JSON 格式:

    回應的內文為 JSON 的格式,請求的數據位於 dataChannels 物件下的 dataPoints 陣列中。

dataChannels 物件

欄位名稱 格式 描述
dataChnId 字串 資料通道 ID
isOverflow 布林 要求的資料點是否超過數目限制
dataPoints JSON 物件陣列 資料點

dataPoints 陣列

欄位名稱 格式 描述
createdAt 數字 以 Unix timestamp 格式紀錄的資料點建立時間
values JSON 物件 資料點的值

範例:

  • 以 JSON 格式回傳

      {
          "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
                          }
                      }
                  ]
              }
          ]
      }
    
  • 以 CSV 格式回傳

      my_data_channel,1524119075906,35
      my_data_channel,1524550447427,30
    

錯誤回覆

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

欄位名稱 格式 描述
code 整數 錯誤代碼
message 字串 錯誤描述

範例:

  • 以 CSV 格式回傳

      404,channel not found
    
  • 以 JSON 格式回傳

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

讀取裝置資訊

描述

使用 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

裝置可使用此 API 向 MCS 平台回報當前正在使用的韌體版本。請注意,回報的版本號碼,必須是先前已經上傳至 MCS 平台的韌體之一。

首次啟用裝置時,可透過呼叫此 API 來回報裝置韌體資訊,以方便後續裝置版本的管理。此外,當裝置完成韌體更新時,亦可用來更新 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

取得裝置所有可使用的韌體列表。

若您已將裝置的韌體版本回報至 MCS 平台,您可以使用此 API 獲取相容的韌體資訊,包含韌體的下載網址。若您未曾回報裝置的韌體版本,其回傳的韌體資訊為無版本相容性限制的所有韌體資訊。

查詢參數

可將下列參數帶入請求 URL

Field Name Type Required Description
url 字串 布林值 非必要的参数。加上 url=true 後,伺服器將會回傳各韌體的下載網址

動作

HTTPs GET

參數

Header

deviceKey: device_key_here

Content-Type:application/json

回覆格式

回覆格式為 JSON

Response

回覆代碼

200

回覆 Header

JSON 格式:

Content-Type:`application/json`

回覆內容

JSON 格式

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

欄位名稱 格式 描述
results array 該裝置所有可使用的韌體列表,其中包含以下資訊
1. fwid: 韌體 ID
2. name
3. description
4. version
5. URL: 韌體的下載網址 (需在請求中加入 url=true 的查詢參數)
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

此 API 在版本相容性的查詢上提供了更彈性的作法,可直接查詢與指定版本相容的韌體列表。

查詢參數

可將下列參數帶入請求 URL

Field Name Type Required Description
url 字串 布林值 非必要的参数。加上 url=true 後,伺服器將會回傳各韌體的下載網址

動作

HTTPs GET

參數

Header

deviceKey: device_key_here

Content-Type:application/json

回覆格式

回覆格式為 JSON

回覆

回覆代碼

200

回覆 Header

JSON 格式

Content-Type:`application/json`

回覆內容

JSON 格式:

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

欄位名稱 格式 描述
results array 所有與特定版本相容的韌體列表,可參考 /firmware/available API
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": {}
}

取得韌體下載網址

Description

使用 HTTPs GET 來取得指定韌體的下載網址。

請求 URL

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

透過指定韌體 ID 來取得此韌體的下載網址。您可先呼叫 /firmwares/available API 獲取與此裝置相容的所有韌體,再使用此 API 來取得單一韌體的下載點。

動作

HTTPs GET

參數

Header

deviceKey: device_key_here

Content-Type:application/json

回覆格式

回覆格式為 JSON

回覆

回覆代碼

200

回覆 Header

JSON 格式

Content-Type:`application/json`

回覆內容

JSON 格式

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

欄位名稱 格式 描述
url array 韌體下載網址
code string http 狀態代碼
message string 系統訊息

範例:

請求 URL

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

請求 Header

deviceKey: g06jBWOtB0kqHk2B

Content-Type:application/json

回覆內容

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

錯誤回覆

當錯誤發生時,回覆代碼為非 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 來啟用裝置

請求 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

或是要發佈裝置下一個或多個資料通道:

mcs/:deviceId/:deviceKey

MQTT 訂閱和發佈資料格式

一般發佈資料的格式為:

timestamp,dataChnId,value

其中timestamp使用UNIX時間戳格式 如果省略如下所示的時間戳值,則MCS將在收到時自動為該數據點建立時間戳。

,dataChnId,value

當針對特定的dataChnId發佈資料

mcs/:deviceId/:deviceKey/:dataChnId

您也可以省略dataChnId

,,value

當使用發佈裝置下一個或多個資料通道的格式時,您不可以省略dataChnId,但同時您可以在一次的發佈裡發佈多個資料點:

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

以下是針對不同資料通道型態的範例:

開關

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}