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