Device OTA Update

IoTaaP OTA Update gives you the possibility to deploy your new firmware to the device remotely.

Get all OTA Updates

Returns list of all OTA upgrades for the owned devices. Notice that system will return only last OTA upgrade information for the device.

URL : https://api.iotaap.io/v1/ota/device

Method : GET

Auth required : YES

URL Params

• search_value (string): filtering value string (filtering path parameter)
• offset (number): number of records to skip
• limit (number): number of records to return
• draw (string): value will be returned back in the response
• order_dir (string): asc/desc

Success Response

Code : 200 OK

Response example

{
    "otas": [
        {
            "_id": "5e1bc3cc5a5cde30ff0a1ed6",
            "device": "5e1b57808711f904f5df4bad",
            "__v": 0,
            "last_updated": "2020-01-21T22:59:29.940Z",
            "owner": "5e10fc5e77ba18070312e171",
            "path": "ota/device/5e1b57808711f904f5df4badFSXuSmJRiJ4v/firmware.bin",
            "version": "1.2.7"
        }
    ],
    "recordsTotal": 1,
    "recordsFiltered": 1,
    "draw": "warp"
}

Response Params

• otas (array): array of OTA upgrade objects
• recordsTotal (number): total number of records (OTA upgrades)
• recordsFiltered (number): number of records that match given filter
• draw (string): draw string from request

Error Response

Condition : If devices resources are not available at the moment

Code : 500 INTERNAL SERVER ERROR

Content :

{
    "message": "Error when getting device OTA's.",
    "error": "<Error information>"
}

Make new OTA Update

System will deploy new firmware.bin file to the secure Cloud location and trigger update process on the device.

Firmware version

Notice that the OTA Update will be triggered on the device if version parameter is different from the previous firmware!

URL : https://api.iotaap.io/v1/ota/device

Method : POST

Auth required : YES

Body Params (all are required)

• firmware (file): firmware.bin file (compiled Firmware)
• device (string): device ID
• token (string): valid device token
• version (string): firmware version (Semantic versioning, e.g.: 1.5.7)

Firmware

You must upload only firmware.bin file that is generated by PlatformIO. You have to keep device key, token and OTA information in the new firmware version otherwise you will loose the possibility to monitor, control or update your device remotely!

Body example (form-data)

Key	Value
firmware	[firmware.bin]
device	5e1b57808711ff04f5df4bbd
token	FSouSAJRiJ3v
version	1.2.7

Success Response

Code : 201 CREATED

Response example

{
    "message": "Firmware successfully deployed"
}

Error Responses

Condition : If mandatory parameter is missing, if Device ID is not valid, or if file is not uploaded

Code : 400 BAD REQUEST

Content :

{
    "message": "<field-name> is a mandatory field"
}

{
    "message": "Device ID is not valid"
}

{
    "message": "No file uploaded"
}

Condition : If device doesn't exist or current user is not the owner

Code : 404 NOT FOUND

Content :

{
    "message": "No such device"
}

Condition : If there was an issue during firmware deployment

Code : 500 INTERNAL SERVER ERROR

Content :

{
    "message": "Error when uploading firmware file",
    "error": "<Error information>"
}

Get latest firmware version

Returns the latest firmware version in jSON format. It is used to trigger device update

URL : https://ota.iotaap.io/v1/ota/device/latest/{device-id}

Method : GET

Auth required : NO

Path Params

• {device-id} (string): specific device ID

Success Response

Code : 200 OK

Response example

{
"ver": "1.0.1"
}

Response Params

• ver (string): latest firmware version available

Error Response

Condition : If devices resources are not available at the moment

Code : 404 NOT FOUND

Content :

{
    "message": "No such device",
    "error": "<Error information>"
}

Download latest firmware

Returns last firmware.bin

URL : https://ota.iotaap.io/v1/ota/device/download/{device-id}{device-token}

Method : GET

Auth required : NO

Path Params

• {device-id}{device-token} (string): specific device ID and token (no spacing)

Success Response

Code : 200 OK

Response example

• Starts firmware.bin download instantly

Error Response

Condition : If devices resources are not available at the moment

Code : 404 NOT FOUND

Content :

{
    "message": "No such device",
    "error": "<Error information>"
}