Skip to content

Group OTA Update

IoTaaP Group OTA Update gives you the possibility to deploy your new firmware to the multiple devices remotely.

Get all OTA Updates

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

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

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": "5e1bc21cdfa10030ab7ea212",
            "group": "5e1b76bc4315b70eb242567a",
            "__v": 0,
            "last_updated": "2020-01-17T17:38:59.983Z",
            "owner": "5e10fc5e77ba18070312e171",
            "path": "ota/group/5e1b76bc4315b70eb242567aAATluvfLURijoH9d/firmware.bin",
            "version": "1.2.7"
        },
        {
            "_id": "5e21f24346211e2d8e0bdf3b",
            "group": "5e1dce30005a9652dbf0f7fd",
            "__v": 0,
            "last_updated": "2020-01-17T17:43:31.012Z",
            "owner": "5e10fc5e77ba18070312e171",
            "path": "ota/group/5e1dce30005a9652dbf0f7fdzuCbB5tL5pniMY3B/firmware.bin",
            "version": "1.2.7"
        }
    ],
    "recordsTotal": 2,
    "recordsFiltered": 2,
    "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 or groups resources are not available at the moment

Code : 500 INTERNAL SERVER ERROR

Content :

{
    "message": "Error when getting group 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 devices that are part of the group.

Firmware version

Notice that the OTA Update will be triggered on the devices if version parameter is different from the previous firmware! Also, if only a few devices in group have the different firmware version, only those devices will be upgraded. This is a great feature if you want to test your new firware only with a few devices, and then deploy it to the full fleet.

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

Method : POST

Auth required : YES

Body Params (all are required)

  • firmware (file): firmware.bin file (compiled Firmware)
  • group (string): group ID
  • token (string): valid group 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 group key, token and OTA information in the new firmware version otherwise you will loose the possibility to monitor, control or update your devices remotely!

Body example (form-data)

Key Value
firmware [firmware.bin]
group 5e1dce30005aff52dbf0f3fd
token zuCws5tL5ffiMY3B
version 2.3.6

Success Response

Code : 201 CREATED

Response example

{
    "message": "Firmware successfully deployed"
}

Error Responses

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

Code : 400 BAD REQUEST

Content :

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

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

{
    "message": "No file uploaded"
}

Condition : If user billing model type doesn't allow group OTA updates

Code : 403 FORBIDDEN

Content :

{
    "message": "Group OTA update is not available in free model. Please upgrade your account."
}

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

Code : 404 NOT FOUND

Content :

{
    "message": "No such group"
}

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 devices update

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

Method : GET

Auth required : NO

Path Params

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

Success Response

Code : 200 OK

Response example

{
"ver": "1.0.1"
}

Response Params

  • ver (string): latest firmware version available

Error Response

Condition : If group resources are not available at the moment

Code : 404 NOT FOUND

Content :

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

Download latest firmware

Returns last firmware.bin

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

Method : GET

Auth required : NO

Path Params

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

Success Response

Code : 200 OK

Response example

  • Starts firmware.bin download instantly

Error Response

Condition : If group resources are not available at the moment

Code : 404 NOT FOUND

Content :

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