Skip to content

Commit

Permalink
modify the firmware api related documents. (#101)
Browse files Browse the repository at this point in the history
  • Loading branch information
@dariachen
dariachen authored Dec 14, 2017
1 parent 9ee13a9 commit 18641ed
Show file tree
Hide file tree
Showing 17 changed files with 234 additions and 186 deletions.
2 changes: 1 addition & 1 deletion content/en/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,9 +36,9 @@
* [Report Device Firmware](api_references/report_device_firmware.md)
* [Retrieve Device Available Firmware](api_references/retrieve_device_available_firmware.md)
* [Retrieve Device Firmware by version](api_references/retrieve_device_firmware_by_version.md)
* [Retrieve Firmware URL](api_references/retrieve_firmware_url.md)
* [Device activation](api_references/device_activation.md)
* [MQTT communication format](api_references/mqtt_communication_format.md)
* [Retrieve Firmware URL](api_references/retrieve_firmware_url.md)
* [Mobile application](mobile_application/README.md)
* [Mobile application--cn](mobile_application--cn/README.md)
* [7681 Firmware Update](7681_firmware_update/README.md)
Expand Down
10 changes: 6 additions & 4 deletions content/en/api_references/report_device_firmware.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Report Device Firmware
# Report Device Firmware Version

## Description

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


## Request URL
Expand All @@ -11,7 +11,9 @@ Use **HTTPs PUT** to report the firmware of the device to MCS.
https://api.mediatek.com/mcs/v2/devices/:deviceId/firmwares
```
To report the current firmware the device is using to the MCS. Please note that for MCS to get the firmware, you have to implement this API in your device to report the device firmware.
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
Expand Down Expand Up @@ -57,7 +59,7 @@ The response body will construct in JSON format with the following fields:

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

Expand Down
21 changes: 16 additions & 5 deletions content/en/api_references/retrieve_device_available_firmware.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

## Description

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


## Request URL
Expand All @@ -12,7 +12,19 @@ Use **HTTPs GET** to retrieve the available firmware for the device from MCS.
https://api.mediatek.com/mcs/v2/devices/:deviceId/firmwares/available
```
To retrieve the available firmware for this device.
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
Expand All @@ -21,14 +33,13 @@ HTTPs GET
## Parameters
### Header


deviceKey: `device_key_here`

Content-Type:`application/json`


### Return format
The return format is in json format
The return format is in JSON format

## Response

Expand All @@ -49,7 +60,7 @@ 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 |
| results | array | the available firmware list for the device, and it includes <br> 1. fwid: The firmware ID <br> 2. name <br> 3. description <br> 4. version <br> 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|

Expand Down
16 changes: 12 additions & 4 deletions content/en/api_references/retrieve_device_firmware_by_version.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Retrieve Device Firmware by version
# Retrieve Compatible Firmware by Version

## Description

Use **HTTPs GET** to retrieve the compatible firmware for specific firmware for the device from MCS.
Use **HTTPs GET** to retrieve the compatible firmwares for a specified firmware version.


## Request URL
Expand All @@ -11,7 +11,15 @@ Use **HTTPs GET** to retrieve the compatible firmware for specific firmware for
https://api.mediatek.com/mcs/v2/devices/:deviceId/firmwares/available/:versionId
```
To retrieve the compatible firmwares for specific firmware for this device.
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
Expand Down Expand Up @@ -48,7 +56,7 @@ The response body will construct in JSON format with the following fields:

| Field Name | Type | Description|
| --- | --- | --- | --- |
| results | array | the compatible firmwares for specific firmware for this device |
| 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|

Expand Down
10 changes: 5 additions & 5 deletions content/en/api_references/retrieve_firmware_url.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,16 @@

## Description

Use **HTTPs GET** to retrieve the firmware download url that the device want to download.

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 firmware url this device wants to download.
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
Expand Down Expand Up @@ -48,7 +48,7 @@ The response body will construct in JSON format with the following fields:

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

Expand All @@ -57,7 +57,7 @@ The response body will construct in JSON format with the following fields:

Request URL
```
https://api.mediatek.com//mcs/v2/devices/DAWfOAsi/firmwares/FAdJBknrDsOm/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.
Expand Down
2 changes: 1 addition & 1 deletion content/en/tutorial.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ <h5 class="componentCard__detail--tutorialTitle" >
</li>
<li>
<a href="tutorial/managing_firmware" >
Managing firmware
Firmware management
</a>
</li>
<li>
Expand Down
91 changes: 46 additions & 45 deletions content/en/tutorial/managing_firmware.md
View file
Original file line number Diff line number Diff line change
@@ -1,86 +1,87 @@
# Managing Firmware
# Firmware Management

MediaTek Clous Sandbox(MCS) enables you to manage the device firmware and supports Firmware Over-The-Air (FOTA) for upgrade.
MediaTek Cloud Sandbox(MCS) enables you to manage the device firmware and supports Firmware Over-The-Air (FOTA) for upgrade.

MCS provides firmware repository services for prototypes and their test devices. The services provide basic firmware upload and download with version control, a web management console for firmware management as well as APIs that enable test devices to retrieve compatible firmware from MCS.
MCS provides firmware repository services for the prototypes and test devices. This service provides basic firmware upload and download with version control, a web console for firmware management as well as APIs that enable test devices to retrieve compatible firmware from MCS.

MCS does not handle the device firmware upgrade operation, you need to code the device or call the firmware APIs available from your development board's SDK.
MCS won't handle the complete device firmware upgrade process on your device, the developers have to implement this and leverage the firmware related library in your development board's SDK.

## Uploading Firmware to the Prototype
## Upload a Firmware to MCS
You can manage the firmwares for your prototype on **Prototype Details -> Firmware** page.

To use the Firmware service, go to the **Firmware** tab in the **Prototype detail** page.

Click **Add firmware** to upload a new firmware,
To upload your first firmware, you just need to click **Add firmware** link, fill up the name and version of this firmware, select the firmware file and click **Upload**.

![](../images/Firmware/img_firmware_01.png)

Enter the Firmware name and version, select a firmware file and click **Upload**.

Next, select a firmware that's compatible with the firmware you've just uploaded.

![](../images/Firmware/img_firmware_02.png)
In the next step, you could configure the compatibility of this firmware. **All firmware** is selected by default, or you could also select **Limited firmware** and opt in the individual firmwares which are compatible with this version.

Choose the prerequisite firmware that's compatible with the firmware you've uploaded.
Only the devices which are using the compatible firmwares are allowed to fetch this firmware information and be upgraded to this version.

The default option is **All firmware** or you can specify your own selection by clicking on the limited firmware. Only the firmware listed in the prerequisite can be upgraded using the firmware you've uploaded.
Now, you can either click **Done** to finish the firmware upload process or click **Next** to push the firmware to selected devices.
![](../images/Firmware/img_firmware_02.png)

If you don't want to proceed to push the firmware to the test device, you can stop by clicking **Done**. Otherwise, click **Next** to push the firmware to the device.

After selecting the devices you'd like to upgrade, click **Push**.
![](../images/Firmware/img_firmware_03.png)

After selecting the devices you'd like to upgrade, click **Push**. You can also do this by clicking on the first icon next to the firmware.

You can also trigger this by clicking on the push icon in the firmware list.
![](../images/Firmware/img_firmware_04.png)

## Upgrading Firmware for Devices
## Upgrade a Firmware to Device

You can also upgrade the firmware from the **Device detail** page. In the Device detail page, click on the **firmware** tab, and you will see the current firmware used and the available firmware that the device can use for upgrade.
After the firmware is uploaded to MCS platform, you could **push** it to the connected devices on MCS web console or use **MCS APIs** to fetch the information of compatible firmwares.

Please note that the **Push** button will only be available when the device is connected. You can see the connection status of the device from the light signal in front of the device name. If the light is green, the device is connected; and if the light is grey, the device is offline.
The **push firmware** function is available on both **Prototype -> Firmware** or **Device details -> Firmware** page.

Please note that the **Push** button is only available when the device is connected to MCS platform. The icon in front of the device name indicates the device connection status. The green light means the device is connected; and it turns to grey color if the device is offline.

![](../images/Firmware/img_firmware_05.png)

Click **Push** button next to the firmware you want to use for device upgrade. After the upgrade process finishes, you will see a success message as shown below.

![](../images/Firmware/img_firmware_06.png)

Please note, in the MCS platform, firmware upgrade information is sent to a device, however the firmware upgrade process is not handled. Please create code for your device in order to receive the information and perform firmware download and upgrade.

The MCS command server will pass the code information to the device in the following format after clicking **Push**:

**deviceId,deviceKey,timestamp,FOTA,version,MD5,URL**
Please note: MCS could only **push** the firmware information down to the selected device, but it will not handle the complete firmware upgrade process on the device side. You have to implement your own program to download the firmware binary and upgrade the firmware accordingly.

* deviceId: the deviceId of the device
* deviceKey: the deviceKey of the device
* timestamp: the timestamp when the firmware is pushed
* FOTA: a string
* version: the version of the firmware being passed
* MD5: the MD5 of the firmware being passed
* URL: the download URL of the firmware being passed
After you click **push** button, MCS will send out the firmware information selected devices. Here are the supported protocol and format.

Or if you are using the MQTT to connect the device, the MCS MQTT Broker will pass the code information to the device in the following format after clicking **Push**:
1. TCP connection: **deviceId,deviceKey,timestamp,FOTA,version,MD5,URL**, for example

**timestamp,FOTA,version,MD5,URL**
```
Dbxxxx9k,TPJVxxxxxxxxBxBv,1513132150790,FOTA,2.0,null,https://cdn.mediatek.com/firmwares/P9MxxxxxxbTK/6a94dxxxxxxxxxxxxxxxxxxxx61f5df/a.bin
```

* deviceId: the device ID of the device
* deviceKey: the device key of the device
* timestamp: the timestamp when this firmware is pushed
* FOTA: a fixed string which stands for "Firmware Over-The-Air"
* version: the version of this firmware
* MD5: the MD5 hash of this firmware
* URL: the download URL of this firmware

* timestamp: the timestamp when the firmware is pushed
* FOTA: a string
* version: the version of the firmware being passed
* MD5: the MD5 of the firmware being passed
* URL: the download URL of the firmware being passed
2. MQTT connection: **timestamp,FOTA,version,MD5,URL**, for example

Also, for devices based on LinkIt Connect 7681, the firmware upgrade process is handled by MCS, and you do not need to do any additional coding. However, you need to set a unique firmware version due to device limitation related to LinkIt Connect 7681, which is that it can only upgrade to a firmware with higher version.
```
1513133357160,FOTA,2.0,null,https://cdn.mediatek.com/firmwares/P9MxxxxxxbTK/6a94dxxxxxxxxxxxxxxxxxxxx61f5df/a.bin
```

## Calling APIs to Report and Download Firmware from MCS
* timestamp: the timestamp when this firmware
* FOTA: a fixed string which stands for "Firmware Over-The-Air"
* version: the version of this firmware
* MD5: the MD5 hash of this firmware
* URL: the download URL of this firmware

MCS provides various firmware APIs to report current firmware version of the device, to retrieve all available firmware for device, as well as to get the firmware information you would like to use for upgrade. However, to use the APIs, you need to code them into your device.

For a device to report its firmware version to the MCS platform, please use the **Report device firmware** API [here](https://mcs.mediatek.com/resources/latest/api_references/) and code it into the device. Once the device reports its firmware version to MCS, the information will be shown in the device firmware tab.
Also, for devices based on LinkIt Connect 7681, the firmware upgrade process is handled by MCS, and you do not need to do any additional coding. However, you need to set a unique firmware version due to device limitation related to LinkIt Connect 7681, which is that it can only upgrade to a firmware with higher version.

If you don't want to do the firmware upgrade through the MCS platform, you can use the **Retrieve device available firmware** API [here](https://mcs.mediatek.com/resources/latest/api_references/) to get all the available firmware for the device.
## MCS APIs

After you've retrieved the available firmware list and you've decided on the firmware version for upgrade, use the **Retrieve firmware URL** API [here](https://mcs.mediatek.com/resources/latest/api_references/) to get the download location of the firmware.
MCS provides the following APIs for firmware management and development.

1. [Report firmware version of a device](http://mcs.mediatek.com/resources/latest/api_references/#report-device-firmware): This API allows device to report its current firmware version back to MCS platform. Only the version number which has been uploaded onto MCS platform can be reported.

2. [Retrieve the compatible firmwares](http://mcs.mediatek.com/resources/latest/api_references/#report-device-firmware): After the 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 its firmware yet, then, only the firmwares without any compatibility limitation are listed.



Expand Down
10 changes: 6 additions & 4 deletions content/zh-CN/api_references/report_device_firmware.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# 回报装置固件
# 回报装置固件版本

##描述

使用 **HTTPs PUT** 来向 MCS 平台回报装置使用之固件。
使用 **HTTPs PUT** 来向 MCS 平台回报装置的固件版本。


## 请求 URL
Expand All @@ -11,7 +11,9 @@
https://api.mediatek.com/mcs/v2/devices/:deviceId/firmwares
```
向 MCS 平台回報裝置正在使用的固件。請注意，您必須將此功能自行編碼於您的裝置中，方可使用。
装置可使用此 API 向 MCS 平台回报当前正在使用的固件版本。请注意，回报的版本号码，必须是先前已经上传至 MCS 平台的固件之一。

首次启用装置时，可透过呼叫此 API 来回报装置固件资讯，以方便后续装置版本的管理。此外，当装置完成固件更新时，亦可用来更新 MCS 平台上此装置的固件资讯，同时代表更新成功。


## 动作
Expand Down Expand Up @@ -56,7 +58,7 @@ JSON 格式的回覆内容会包含以下几个栏位：

|栏位名称|格式|描述|
| --- | --- | --- | --- |
| fwId | string | 装置所回报的固件 ID|
| fwId | string | 装置回报的固件版本所对应到的固件 ID|
|code| string|http 状态代码|
|message|string|系统讯息|

Expand Down
17 changes: 13 additions & 4 deletions content/zh-CN/api_references/retrieve_device_available_firmware.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# 取得装置所有韧体资讯
# 取得与此装置相容的固件列表


## 描述

使用 **HTTPs GET** 来从MCS平台取得该装置所有固件资讯清单。
使用 **HTTPs GET** 從 MCS 平台取得该装置可使用的所有固件列表。


## 请求 URL
Expand All @@ -12,7 +12,16 @@
https://api.mediatek.com/mcs/v2/devices/:deviceId/firmwares/available
```
取得装置所有固件资讯清单。
取得装置所有可使用的固件列表。

若您已将装置的固件版本回报至 MCS 平台，您可以使用此 API 获取相容的固件资讯，包含固件的下载网址。若您未曾回报装置的固件版本，其回传的固件资讯为无版本相容性限制的所有固件资讯。

### 查詢參數
可將下列參數帶入請求 URL

| Field Name | Type | Required |Description|
| --- | --- | --- | --- |
| url | 字串 | 布林值 | 为非必要的参数。加上 **url=true** 後，伺服器將會回傳各固件的下載網址|

## 动作
HTTPs GET
Expand Down Expand Up @@ -49,7 +58,7 @@ JSON 格式的回覆内容会包含以下几个栏位：

|栏位名称|格式|描述|
| --- | --- | --- | --- |
| results | array | 所有该装置的固件清单资讯 |
| results | array | 该装置所有可使用的固件列表，其中包含以下资讯 <br> 1. fwid: 固件 ID <br> 2. name <br> 3. description <br> 4. version <br> 5. URL: 固件的下载网址 (需在请求中加入 **url=true** 的查询参数) |
|code| string|http 状态代码|
|message|string|系统讯息|

Expand Down
Loading

0 comments on commit 18641ed

Please sign in to comment.