Introduction

AWS IoT Jobs define a set of remote operations that can be sent to and run on one or more devices. Most commonly, jobs are used for performing software or firmware updates, but jobs can also be used to perform any arbitrary operation such as reboot, certificate rotation and more.

AWS IoT OTA update (also known as "FreeRTOS OTA update") is a feature built on top of AWS IoT Jobs that specifically implements a software/firmware update operation, and only that operation. An OTA update is a job, but with a pre-defined job document. It bundles common software update functionality such as code signing, making it quicker and easier for you to build your software update solutions.

Summary of the differences

The key differences between AWS IoT Jobs and AWS IoT OTA updates are summarized in Table 1. If your device software is built with FreeRTOS or the AWS IoT Device SDK for Embedded C (C-SDK), and your file sizes do not exceed 16MB, then you should probably use AWS IoT OTA to perform your device software or firmware updates.

For devices built with other AWS IoT device software, or files larger than 16MB, or if you want to perform operations other than software or firmware update, then AWS IoT Jobs is likely your best choice.

	AWS IoT Jobs	AWS IoT OTA updates
Also known as	"Custom jobs"	"FreeRTOS OTA updates"
Job document	Custom	Pre-defined
Creation API	CreateJob	CreateOTAUpdate
Code signing	Do-it-yourself	Integrated
HTTP or MQTT protocol selection	Do-it-yourself	Integrated
Supported operations	Any	Software/firmware update only
AWS IoT Device SDK support	C, C++, Python, Java, Javascript	C only
Platform Abstraction Layer (PAL)	No	Yes
Maximum file size	HTTP: 5GB (Amazon S3 limit), MQTT: 24MB (MQTT file stream limit)	16MB (OTA update limit)

Table 1: Differences between jobs and OTA updates

AWS IoT OTA updates

AWS IoT OTA updates are sometimes referred to as “FreeRTOS OTA updates” in the AWS documentation and in the AWS IoT console. Despite this naming, FreeRTOS is not mandatory and OTA updates can in fact be implemented on any IoT device that complies with the OTA design.

The AWS IoT Over-the-air Update library that is included in both FreeRTOS and in the AWS IoT Device SDK for Embedded C (C-SDK), is deprecated and should not be used in new device implementations. Instead, you should use the modular and composable OTA libraries to orchestrate OTA updates on your device.

The composable libraries are:

1. The Jobs library which you can use to parse and process AWS ioT OTA update jobs.
2. The MQTT Streaming library for file block downloads over MQTT.
3. The coreHTTP library for file block downloads over HTTP.

Since AWS IoT OTA is intended for resource-constrained devices, these libraries are only available in C. For the same reason, OTA file size is limited to 16MB.

AWS IoT OTA updates are created using the CreateOTAUpdate API operation. This is an integrated operation that bundles several API operations into a single call. Depending on the parameters you pass, CreateOTAUpdate may in turn call:

• Signer StartSigningJob to begin a code signing operation.
• IoT CreateStream to create an MQTT file stream.
• IoT CreateJob to create an AWS IoT Job with a job document that’s constructed from the passed parameters.

In the case of an OTA update that uses HTTP for the file transfer, the resulting job document will have the form of Figure 1, and include a presigned URL placeholder for the firmware binary.

{
  "afr_ota": {
    "protocols": [
      "HTTP"
    ],
    "files": [
      {
        "filepath": "my-filepath",
        "filesize": 366816,
        "fileid": 0,
        "certfile": "my-certfile",
        "update_data_url": "${aws:iot:s3-presigned-url:https://s3.region.amazonaws.com/my-bucket/SignedImages/deadbeef-
face-cafe-feed-fade12345678}",
        "auth_scheme": "aws.s3.presigned",
        "sig-sha256-ecdsa": "MEUCIQCuvl2R0oQKJC2AnWFlgoothCazY1iUL3daXLUDqLC6XQIgacYYeEa0+Njbce7JNe22oc9p+uwA0jLhjI9XgclJtf0="
      }
    ]
  }
}

Figure 1: Example job document for an OTA update using HTTP file transfer

In the case of an OTA update that uses MQTT for the file transfer, the resulting job document will have the form of Figure 2, and include the name of the MQTT file stream for the firmware binary.

{
  "afr_ota": {
    "protocols": [
      "MQTT"
    ],
    "streamname": "AFR_OTA-deadbeef-0123-4567-89ab-face1234cafe",
    "files": [
      {
        "filepath": "my-filepath",
        "filesize": 366816,
        "fileid": 0,
        "certfile": "my-certfile",
        "sig-sha256-ecdsa": "MEUCIHFAKQDS8TtrtG6Q32Vy9D9TPOPYmyc/y0SHvzdwhzbFAiEAxaejfdIGkPZAmCJRIlHKMVo4sohGOcRskUA2fhLxJjY="
      }
    ]
  }
}

Figure 2: Example job document for an OTA update using MQTT file transfer

To help you get started with AWS IoT OTA updates, you can explore the following resources:

• The Simple OTA Orchestrator which uses the FreeRTOS Labs - OTA Example for AWS IoT Core to demonstrate the OTA update process end-to-end, with a simple example device-side implementation.
• The OTA Agent Orchestrator which also uses the FreeRTOS Labs - OTA Example for AWS IoT Core to demonstrate the OTA update process end-to-end, but with the device-side implementation mimicking the OTA agent of the deprecated OTA library.

AWS IoT Jobs

AWS IoT OTA updates implement considerable undifferentiated heavy lifting for the particular use case of a software or firmware update, but it comes at the cost of flexibility. With AWS IoT Jobs, you will have more freedom to implement bespoke requirements in a custom job document. If required, you can take care of code signing and MQTT file stream creation yourself. You can transfer much larger files if you use HTTP, and you can build device software with SDKs for languages other than C.

AWS IoT OTA updates are primarily targeted towards constrained IoT devices, whereas AWS IoT Jobs are better suited to more powerful devices with software images exceeding 16MB.

As job documents are entirely custom, the contents can be whatever suits your device. However, if the job is performing a software or firmware update, the job document would typically contain at least one presigned URL placeholder as shown in Figure 3.

{
  "my_binary": "${aws:iot:s3-presigned-url:https://s3.region.amazonaws.com/my-bucket/firmware.bin}",
}

Figure 3: Example job document for a job using HTTP and a presigned URL

To help you get started with AWS IoT Jobs, you can explore the following resources:

• C-SDK demo of the jobs library.
• FreeRTOS demo of the jobs library.
• AWS IoT Device SDK samples of using the jobs library for C++, Python, Java and Javascript.
• AWS IoT Device Client reference implementation of jobs.

Related questions

• https://repost.aws/questions/QU4sp7QPk4RWqqxYKIJZPkGw/how-does-ota-agent-work-how-does-it-interface-with-ota-pal-what-is-a-file-context
• https://repost.aws/questions/QUy9YM7SAdTVOawkdXb2M5UQ/ota-update-of-a-specific-partition-on-device
• https://repost.aws/questions/QUQnO89syvQduayQHsK8kaug/freertos-ota-update-job-with-a-file-of-size-larger-than-16-mb
• https://repost.aws/questions/QU0ILvZg7zTkeIL6ekK7RQqw/what-freertos-boards-are-fully-supported-for-ota-updates