# OTA update prerequisites
To use over-the-air (OTA) updates, do the following:
+ Check the [Prerequisites for OTA updates using HTTP](ota-http-freertos.md) or the [Prerequisites for OTA updates using MQTT](ota-mqtt-freertos.md).
+ [Create an Amazon S3 bucket to store your update](dg-ota-bucket.md).
+ [Create an OTA Update service role](create-service-role.md).
+ [Create an OTA user policy](create-ota-user-policy.md).
+ [Create a code-signing certificate](ota-code-sign-cert.md).
+ If you are using Code Signing for AWS IoT, [Grant access to code signing for AWS IoT](code-sign-policy.md).
+ [Download FreeRTOS with the OTA library](ota-download-freertos.md).
# Create an Amazon S3 bucket to store your update
OTA update files are stored in Amazon S3 buckets.
If you're using Code Signing for AWS IoT, the command that you use to create a code-signing job takes a source bucket (where the unsigned firmware image is located) and a destination bucket (where the signed firmware image is written). You can specify the same bucket for the source and destination. The file names are changed to GUIDs so the original files are not overwritten.
**To create an Amazon S3 bucket**
1. Sign in to the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).
1. Choose **Create bucket**.
1. Enter a **bucket name**.
1. Under **Bucket settings for Block Public Access** keep **Block all public access** selected to accept the default permissions.
1. Under **Bucket Versioning**, select **Enable** to keep all versions in the same bucket.
1. Choose **Create bucket**.
For more information about Amazon S3, see [Amazon Simple Storage Service User Guide](https://docs.aws.amazon.com/AmazonS3/latest/userguide/).
# Create an OTA Update service role
The OTA Update service assumes this role to create and manage OTA update jobs on your behalf.
**To create an OTA service role**
1. Sign in to the [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. From the navigation pane, choose **Roles**.
1. Choose **Create role**.
1. Under **Select type of trusted entity**, choose **AWS Service**.
1. Choose **IoT** from the list of AWS services.
1. Under **Select your use case**, choose **IoT**.
1. Choose **Next: Permissions**.
1. Choose **Next: Tags**.
1. Choose **Next: Review**.
1. Enter a role name and description, and then choose **Create role**.
For more information about IAM roles, see [IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html).
**Important**
To address the confused deputy security issue, you must follow instructions in the [AWS IoT Core](https://docs.aws.amazon.com/iot/latest/developerguide/cross-service-confused-deputy-prevention.html) guide.
**To add OTA update permissions to your OTA service role**
1. In the search box on the IAM console page, enter the name of your role, and then choose it from the list.
1. Choose **Attach policies**.
1. In the **Search** box, enter "AmazonFreeRTOSOTAUpdate", select **AmazonFreeRTOSOTAUpdate** from the list of filtered policies, and then choose **Attach policy** to attach the policy to your service role.
**To add the required IAM permissions to your OTA service role**
1. In the search box on the IAM console page, enter the name of your role, and then choose it from the list.
1. Choose **Add inline policy**.
1. Choose the **JSON** tab.
1. Copy and paste the following policy document into the text box:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iam:GetRole",
"iam:PassRole"
],
"Resource": "arn:aws:iam::111122223333:role/your_role_name"
}
]
}
```
------
Make sure that you replace *your\$1account\$1id* with your AWS account ID, and *your\$1role\$1name* with the name of the OTA service role.
1. Choose **Review policy**.
1. Enter a name for the policy, and then choose **Create policy**.
**Note**
The following procedure isn't required if your Amazon S3 bucket name begins with "afr-ota". If it does, the AWS managed policy `AmazonFreeRTOSOTAUpdate` already includes the required permissions.
****To add the required Amazon S3 permissions to your OTA service role****
1. In the search box on the IAM console page, enter the name of your role, and then choose it from the list.
1. Choose **Add inline policy**.
1. Choose the **JSON** tab.
1. Copy and paste the following policy document into the box.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObjectVersion",
"s3:GetObject",
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::example-bucket/*"
]
}
]
}
```
------
This policy grants your OTA service role permission to read Amazon S3 objects. Make sure that you replace *example-bucket* with the name of your bucket.
1. Choose **Review policy**.
1. Enter a name for the policy, and then choose **Create policy**.
# Create an OTA user policy
You must grant your user permission to perform over-the-air updates. Your user must have permissions to:
+ Access the S3 bucket where your firmware updates are stored.
+ Access certificates stored in AWS Certificate Manager.
+ Access the AWS IoT MQTT-based file delivery feature.
+ Access FreeRTOS OTA updates.
+ Access AWS IoT jobs.
+ Access IAM.
+ Access Code Signing for AWS IoT. See [Grant access to code signing for AWS IoT](code-sign-policy.md).
+ List FreeRTOS hardware platforms.
+ Tag and untag AWS IoT resources.
To grant your user the required permissions, see [IAM Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html). Also see [Authorizing users and cloud services to use AWS IoT Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iam-policy-users-jobs.html).
To provide access, add permissions to your users, groups, or roles:
+ Users and groups in AWS IAM Identity Center:
Create a permission set. Follow the instructions in [Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) in the *AWS IAM Identity Center User Guide*.
+ Users managed in IAM through an identity provider:
Create a role for identity federation. Follow the instructions in [Create a role for a third-party identity provider (federation)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) in the *IAM User Guide*.
+ IAM users:
+ Create a role that your user can assume. Follow the instructions in [Create a role for an IAM user](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) in the *IAM User Guide*.
+ (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in [Adding permissions to a user (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*.
# Create a code-signing certificate
To digitally sign firmware images, you need a code-signing certificate and private key. For testing purposes, you can create a self‐signed certificate and private key. For production environments, purchase a certificate through a well‐known certificate authority (CA).
Different platforms require different types of code-signing certificates. The following sections describe how to create code-signing certificates for different FreeRTOS-qualified platforms.
**Topics**
+ [
# Creating a code-signing certificate for the Texas Instruments CC3220SF-LAUNCHXL
](ota-code-sign-cert-ti.md)
+ [
# Creating a code-signing certificate for the Espressif ESP32
](ota-code-sign-cert-esp.md)
+ [
# Creating a code-signing certificate for the Nordic nrf52840-dk
](ota-code-sign-cert-nordic.md)
+ [
# Creating a code-signing certificate for the FreeRTOS Windows simulator
](ota-code-sign-cert-win.md)
+ [
# Creating a code-signing certificate for custom hardware
](ota-code-sign-cert-other.md)
# Creating a code-signing certificate for the Texas Instruments CC3220SF-LAUNCHXL
**Important**
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) when you create a new project. If you already have an existing FreeRTOS project based on the now deprecated Amazon-FreeRTOS repository, see the [Amazon-FreeRTOS Github Repository Migration Guide](github-repo-migration.md).
The SimpleLink Wi-Fi CC3220SF Wireless Microcontroller Launchpad Development Kit supports two certificate chains for firmware code signing:
+ Production (certificate-catalog)
To use the production certificate chain, you must purchase a commercial code-signing certificate and use the [TI Uniflash tool](http://www.ti.com/tool/UNIFLASH) to set the board to production mode.
+ Testing and development (certificate-playground)
The playground certificate chain allows you to try out OTA updates with a self‐signed code-signing certificate.
Use the AWS Command Line Interface to import your code-signing certificate, private key, and certificate chain into AWS Certificate Manager. For more information see [ Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) in the *AWS Command Line Interface User Guide*.
Download and install the latest version of [SimpleLink CC3220 SDK](http://www.ti.com/tool/download/SIMPLELINK-CC3220-SDK). By default, the files you need are located here:
`C:\ti\simplelink_cc32xx_sdk_version\tools\cc32xx_tools\certificate-playground` (Windows)
`/Applications/Ti/simplelink_cc32xx_version/tools/cc32xx_tools/certificate-playground` (macOS)
The certificates in the SimpleLink CC3220 SDK are in DER format. To create a self‐signed code-signing certificate, you must convert them to PEM format.
Follow these steps to create a code-signing certificate that is linked to the Texas Instruments playground certificate hierarchy and meets AWS Certificate Manager and Code Signing for AWS IoT criteria.
**Note**
To create a code signing certificate, install [ OpenSSL](https://www.openssl.org/) on your machine. After you install OpenSSL, make sure that `openssl` is assigned to the OpenSSL executable in your command prompt or terminal environment.
**To create a self‐signed code signing certificate**
1. Open a command prompt or terminal with administrator permissions.
1. In your working directory, use the following text to create a file named `cert_config.txt`. Replace *test\$1signer@amazon.com* with your email address.
```
[ req ]
prompt = no
distinguished_name = my dn
[ my dn ]
commonName = test_signer@amazon.com
[ my_exts ]
keyUsage = digitalSignature
extendedKeyUsage = codeSigning
```
1. Create a private key and certificate signing request (CSR):
```
openssl req -config cert_config.txt -extensions my_exts -nodes -days 365 -newkey rsa:2048 -keyout tisigner.key -out tisigner.csr
```
1. Convert the Texas Instruments playground root CA private key from DER format to PEM format.
The TI playground root CA private key is located here:
`C:\ti\simplelink_cc32xx_sdk_version\tools\cc32xx_tools\certificate-playground\dummy-root-ca-cert-key` (Windows)
`/Applications/Ti/simplelink_cc32xx_sdk_version/tools/cc32xx_tools/certificate-playground/dummy-root-ca-cert-key` (macOS)
```
openssl rsa -inform DER -in dummy-root-ca-cert-key -out dummy-root-ca-cert-key.pem
```
1. Convert the Texas Instruments playground root CA certificate from DER format to PEM format.
The TI playground root certificate is located here:
`C:\ti\simplelink_cc32xx_sdk_version\tools\cc32xx_tools\certificate-playground/dummy-root-ca-cert` (Windows)
`/Applications/Ti/simplelink_cc32xx_sdk_version/tools/cc32xx_tools/certificate-playground/dummy-root-ca-cert` (macOS)
```
openssl x509 -inform DER -in dummy-root-ca-cert -out dummy-root-ca-cert.pem
```
1. Sign the CSR with the Texas Instruments root CA:
```
openssl x509 -extfile cert_config.txt -extensions my_exts -req -days 365 -in tisigner.csr -CA dummy-root-ca-cert.pem -CAkey dummy-root-ca-cert-key.pem -set_serial 01 -out tisigner.crt.pem -sha1
```
1. Convert your code-signing certificate (`tisigner.crt.pem`) to DER format:
```
openssl x509 -in tisigner.crt.pem -out tisigner.crt.der -outform DER
```
**Note**
You write the `tisigner.crt.der` certificate onto the TI development board later.
1. Import the code-signing certificate, private key, and certificate chain into AWS Certificate Manager:
```
aws acm import-certificate --certificate fileb://tisigner.crt.pem --private-key fileb://tisigner.key --certificate-chain fileb://dummy-root-ca-cert.pem
```
This command displays an ARN for your certificate. You need this ARN when you create an OTA update job.
**Note**
This step is written with the assumption that you are going to use Code Signing for AWS IoT to sign your firmware images. Although the use of Code Signing for AWS IoT is recommended, you can sign your firmware images manually.
# Creating a code-signing certificate for the Espressif ESP32
**Important**
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) when you create a new project. If you already have an existing FreeRTOS project based on the now deprecated Amazon-FreeRTOS repository, see the [Amazon-FreeRTOS Github Repository Migration Guide](github-repo-migration.md).
The Espressif ESP32 boards support a self-signed SHA-256 with ECDSA code-signing certificate.
**Note**
To create a code signing certificate, install [ OpenSSL](https://www.openssl.org/) on your machine. After you install OpenSSL, make sure that `openssl` is assigned to the OpenSSL executable in your command prompt or terminal environment.
Use the AWS Command Line Interface to import your code-signing certificate, private key, and certificate chain into AWS Certificate Manager. For information about installing the AWS CLI, see [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html).
1. In your working directory, use the following text to create a file named `cert_config.txt`. Replace *test\$1signer@amazon.com* with your email address:
```
[ req ]
prompt = no
distinguished_name = my_dn
[ my_dn ]
commonName = test_signer@amazon.com
[ my_exts ]
keyUsage = digitalSignature
extendedKeyUsage = codeSigning
```
1. Create an ECDSA code-signing private key:
```
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -pkeyopt ec_param_enc:named_curve -outform PEM -out ecdsasigner.key
```
1. Create an ECDSA code-signing certificate:
```
openssl req -new -x509 -config cert_config.txt -extensions my_exts -nodes -days 365 -key ecdsasigner.key -out ecdsasigner.crt
```
1. Import the code-signing certificate, private key, and certificate chain into AWS Certificate Manager:
```
aws acm import-certificate --certificate fileb://ecdsasigner.crt --private-key fileb://ecdsasigner.key
```
This command displays an ARN for your certificate. You need this ARN when you create an OTA update job.
**Note**
This step is written with the assumption that you are going to use Code Signing for AWS IoT to sign your firmware images. Although the use of Code Signing for AWS IoT is recommended, you can sign your firmware images manually.
# Creating a code-signing certificate for the Nordic nrf52840-dk
**Important**
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) when you create a new project. If you already have an existing FreeRTOS project based on the now deprecated Amazon-FreeRTOS repository, see the [Amazon-FreeRTOS Github Repository Migration Guide](github-repo-migration.md).
The Nordic nrf52840-dk supports a self-signed SHA256 with ECDSA code-signing certificate.
**Note**
To create a code signing certificate, install [OpenSSL](https://www.openssl.org/) on your machine. After you install OpenSSL, make sure that `openssl` is assigned to the OpenSSL executable in your command prompt or terminal environment.
Use the AWS Command Line Interface to import your code-signing certificate, private key, and certificate chain into AWS Certificate Manager. For information about installing the AWS CLI, see [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html).
1. In your working directory, use the following text to create a file named `cert_config.txt`. Replace *test\$1signer@amazon.com* with your email address:
```
[ req ]
prompt = no
distinguished_name = my_dn
[ my_dn ]
commonName = test_signer@amazon.com
[ my_exts ]
keyUsage = digitalSignature
extendedKeyUsage = codeSigning
```
1. Create an ECDSA code-signing private key:
```
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -pkeyopt ec_param_enc:named_curve -outform PEM -out ecdsasigner.key
```
1. Create an ECDSA code-signing certificate:
```
openssl req -new -x509 -config cert_config.txt -extensions my_exts -nodes -days 365 -key ecdsasigner.key -out ecdsasigner.crt
```
1. Import the code-signing certificate, private key, and certificate chain into AWS Certificate Manager:
```
aws acm import-certificate --certificate fileb://ecdsasigner.crt --private-key fileb://ecdsasigner.key
```
This command displays an ARN for your certificate. You need this ARN when you create an OTA update job.
**Note**
This step is written with the assumption that you are going to use Code Signing for AWS IoT to sign your firmware images. Although the use of Code Signing for AWS IoT is recommended, you can sign your firmware images manually.
# Creating a code-signing certificate for the FreeRTOS Windows simulator
The FreeRTOS Windows simulator requires a code-signing certificate with an ECDSA P-256 key and SHA-256 hash to perform OTA updates. If you don't have a code-signing certificate, follow these steps to create one.
**Note**
To create a code-signing certificate, install [ OpenSSL](https://www.openssl.org/) on your machine. After you install OpenSSL, make sure that `openssl` is assigned to the OpenSSL executable in your command prompt or terminal environment.
Use the AWS Command Line Interface to import your code-signing certificate, private key, and certificate chain into AWS Certificate Manager. For information about installing the AWS CLI, see [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html).
1. In your working directory, use the following text to create a file named `cert_config.txt`. Replace *test\$1signer@amazon.com* with your email address:
```
[ req ]
prompt = no
distinguished_name = my_dn
[ my_dn ]
commonName = test_signer@amazon.com
[ my_exts ]
keyUsage = digitalSignature
extendedKeyUsage = codeSigning
```
1. Create an ECDSA code-signing private key:
```
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -pkeyopt ec_param_enc:named_curve -outform PEM -out ecdsasigner.key
```
1. Create an ECDSA code-signing certificate:
```
openssl req -new -x509 -config cert_config.txt -extensions my_exts -nodes -days 365 -key ecdsasigner.key -out ecdsasigner.crt
```
1. Import the code-signing certificate, private key, and certificate chain into AWS Certificate Manager:
```
aws acm import-certificate --certificate fileb://ecdsasigner.crt --private-key fileb://ecdsasigner.key
```
This command displays an ARN for your certificate. You need this ARN when you create an OTA update job.
**Note**
This step is written with the assumption that you are going to use Code Signing for AWS IoT to sign your firmware images. Although the use of Code Signing for AWS IoT is recommended, you can sign your firmware images manually.
# Creating a code-signing certificate for custom hardware
Using an appropriate toolset, create a self-signed certificate and private key for your hardware.
Use the AWS Command Line Interface to import your code-signing certificate, private key, and certificate chain into AWS Certificate Manager. For information about installing the AWS CLI, see [ Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html).
After you create your code-signing certificate, you can use the AWS CLI to import it into ACM:
```
aws acm import-certificate --certificate fileb://code-sign.crt --private-key fileb://code-sign.key
```
The output from this command displays an ARN for your certificate. You need this ARN when you create an OTA update job.
ACM requires certificates to use specific algorithms and key sizes. For more information, see [Prerequisites for Importing Certificates](https://docs.aws.amazon.com/acm/latest/userguide/import-certificate-prerequisites.html). For more information about ACM, see [Importing Certificates into AWS Certificate Manager](https://docs.aws.amazon.com/acm/latest/userguide/import-certificate.html).
You must copy, paste, and format the contents of your code-signing certificate into the `vendors/vendor/boards/board/aws_demos/config_files/ota_demo_config.h` file that is part of the FreeRTOS code you download later.
# Grant access to code signing for AWS IoT
To provide access, add permissions to your users, groups, or roles:
+ Users and groups in AWS IAM Identity Center:
Create a permission set. Follow the instructions in [Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) in the *AWS IAM Identity Center User Guide*.
+ Users managed in IAM through an identity provider:
Create a role for identity federation. Follow the instructions in [Create a role for a third-party identity provider (federation)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) in the *IAM User Guide*.
+ IAM users:
+ Create a role that your user can assume. Follow the instructions in [Create a role for an IAM user](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) in the *IAM User Guide*.
+ (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in [Adding permissions to a user (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*.
# Download FreeRTOS with the OTA library
You can clone or download FreeRTOS from [GitHub](https://github.com/freertos/freertos). See the [README.md](https://github.com/freertos/freertos/blob/main/README.md) file for instructions.
For information about setting up and running the OTA demo application, see [Over-the-air updates demo application](ota-demo.md).
**Important**
In this topic, the path to the FreeRTOS download directory is referred to as `freertos`.
Space characters in the `freertos` path can cause build failures. When you clone or copy the repository, make sure the path you that create doesn't contain space characters.
The maximum length of a file path on Microsoft Windows is 260 characters. Long FreeRTOS download directory paths can cause build failures.
Because the source code may contain symbolic links, if you're using Windows to extract the archive, you may have to:
Enable [ Developer Mode](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) or,
Use a console that is elevated as administrator.
In this way, Windows can properly create symbolic links when it extracts the archive. Otherwise, symbolic links will be written as normal files that contain the paths of the symbolic links as text or are empty. For more information, see the blog entry [ Symlinks in Windows 10\$1](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/).
If you use Git under Windows, you must enable Developer Mode or you must:
Set `core.symlinks` to true with the following command:
```
git config --global core.symlinks true
```
Use a console that is elevated as administrator whenever you use a git command that writes to the system (for example, **git pull**, **git clone**, and **git submodule update --init --recursive**).
# Prerequisites for OTA updates using MQTT
This section describes the general requirements for using MQTT to perform over-the-air (OTA updates).
## Minimum requirements
+ Device firmware must include the necessary FreeRTOS libraries (coreMQTT Agent, OTA update, and their dependencies).
+ FreeRTOS version 1.4.0 or later is required. However, we recommend that you use the latest version when possible.
## Configurations
Beginning with version 201912.00, FreeRTOS OTA can use either the HTTP or MQTT protocol to transfer firmware update images from AWS IoT to devices. If you specify both protocols when you create an OTA update in FreeRTOS, each device will determine the protocol used to transfer the image. See [Prerequisites for OTA updates using HTTP](ota-http-freertos.md) for more information.
By default, the configuration of the OTA protocols in [https://github.com/aws/amazon-freertos/blob/main/vendors/vendor/boards/board/aws_demos/config_files/ota_config.h](https://github.com/aws/amazon-freertos/blob/main/vendors/vendor/boards/board/aws_demos/config_files/ota_config.h) is to use the MQTT protocol.
## Device specific configurations
None.
## Memory usage
When MQTT is used for data transfer, no additional memory is required for the MQTT connection because it's shared between control and data operations.
## Device policy
Each device that receives an OTA update using MQTT must be registered as a thing in AWS IoT and the thing must have an attached policy like the one listed here. You can find more information about the items in the `"Action"` and `"Resource"` objects at [AWS IoT Core Policy Actions](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policy-actions.html) and [AWS IoT Core Action Resources](https://docs.aws.amazon.com/iot/latest/developerguide/iot-action-resources.html).
**Notes**
+ The `iot:Connect` permissions allow your device to connect to AWS IoT over MQTT.
+ The `iot:Subscribe` and `iot:Publish` permissions on the topics of AWS IoT jobs (`.../jobs/*`) allow the connected device to receive job notifications and job documents, and to publish the completion state of a job execution.
+ The `iot:Subscribe` and `iot:Publish` permissions on the topics of AWS IoT OTA streams (`.../streams/*`) allow the connected device to fetch OTA update data from AWS IoT. These permissions are required to perform firmware updates over MQTT.
+ The `iot:Receive` permissions allow AWS IoT Core to publish messages on those topics to the connected device. This permission is checked on every delivery of an MQTT message. You can use this permission to revoke access to clients that are currently subscribed to a topic.
# Prerequisites for OTA updates using HTTP
This section describes the general requirements for using HTTP to perform over-the-air (OTA) updates. Beginning with version 201912.00, FreeRTOS OTA can use either the HTTP or MQTT protocol to transfer firmware update images from AWS IoT to devices.
**Note**
Although the HTTP protocol might be used to transfer the firmware image, the coreMQTT Agent library is still required because other interactions with AWS IoT Core use the coreMQTT Agent library, including sending or receiving job execution notifications, job documents, and execution status updates.
When you specify both MQTT and HTTP protocols for the OTA update job, the setup of the OTA Agent software on each individual device determines the protocol used to transfer the firmware image. To change the OTA Agent from the default MQTT protocol method to the HTTP protocol, you can modify the header files used to compile the FreeRTOS source code for the device.
## Minimum requirements
+ Device firmware must include the necessary FreeRTOS libraries (coreMQTT Agent, HTTP, OTA Agent, and their dependencies).
+ FreeRTOS version 201912.00 or later is required to change the configuration of the OTA protocols to enable OTA data transfer over HTTP.
## Configurations
See the following configuration of the OTA protocols in the [https://github.com/aws/amazon-freertos/blob/main/vendors/vendor/boards/board/aws_demos/config_files/ota_config.h](https://github.com/aws/amazon-freertos/blob/main/vendors/vendor/boards/board/aws_demos/config_files/ota_config.h) file.
**To enable OTA data transfer over HTTP**
1. Change `configENABLED_DATA_PROTOCOLS` to `OTA_DATA_OVER_HTTP`.
1. When the OTA updates, you can specify both protocols so that either MQTT or HTTP protocol can be used., You can set the primary protocol used by the device to HTTP by changing `configOTA_PRIMARY_DATA_PROTOCOL` to `OTA_DATA_OVER_HTTP`.
**Note**
HTTP is only supported for OTA data operations. For control operations, you must use MQTT.
## Device specific configurations
**ESP32**
Due to a limited amount of RAM, you must turn off BLE when you enable HTTP as an OTA data protocol. In the [https://github.com/aws/amazon-freertos/blob/main/vendors/espressif/boards/esp32/aws_demos/config_files/aws_iot_network_config.h](https://github.com/aws/amazon-freertos/blob/main/vendors/espressif/boards/esp32/aws_demos/config_files/aws_iot_network_config.h) file, change `configENABLED_NETWORKS` to `AWSIOT_NETWORK_TYPE_WIFI` only.
```
/**
* @brief Configuration flag which is used to enable one or more network interfaces for a board.
*
* The configuration can be changed any time to keep one or more network enabled or disabled.
* More than one network interfaces can be enabled by using 'OR' operation with flags for
* each network types supported. Flags for all supported network types can be found
* in "aws_iot_network.h"
*
*/
#define configENABLED_NETWORKS ( AWSIOT_NETWORK_TYPE_WIFI )
```
## Memory usage
When MQTT is used for data transfer, no additional heap memory is required for the MQTT connection because it's shared between control and data operations. However, enabling data over HTTP requires additional heap memory. The following is the heap memory usage data for all supported platforms, calculated using the FreeRTOS `xPortGetFreeHeapSize` API. You must make sure there is enough RAM to use the OTA library.
****Texas Instruments CC3220SF-LAUNCHXL****
Control operations (MQTT): 12 KB
Data operations (HTTP): 10 KB
TI uses significantly less RAM because it does SSL on hardware, so it doesn't use the mbedtls library.
****Microchip Curiosity PIC32MZEF****
Control operations (MQTT): 65 KB
Data operations (HTTP): 43 KB
****Espressif ESP32****
Control operations (MQTT): 65 KB
Data operations (HTTP): 45 KB
BLE on ESP32 takes about 87 KB RAM. There's not enough RAM to enable all of them, which is mentioned in the device specific configurations above.
****Windows simulator****
Control operations (MQTT): 82 KB
Data operations (HTTP): 63 KB
****Nordic nrf52840-dk****
HTTP is not supported.
## Device policy
This policy allows you to use either MQTT or HTTP for OTA updates.
Each device that receives an OTA update using HTTP must be registered as a thing in AWS IoT and the thing must have an attached policy like the one listed here. You can find more information about the items in the `"Action"` and `"Resource"` objects at [AWS IoT Core Policy Actions](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policy-actions.html) and [AWS IoT Core Action Resources](https://docs.aws.amazon.com/iot/latest/developerguide/iot-action-resources.html).
**Notes**
+ The `iot:Connect` permissions allow your device to connect to AWS IoT over MQTT.
+ The `iot:Subscribe` and `iot:Publish` permissions on the topics of AWS IoT jobs (`.../jobs/*`) allow the connected device to receive job notifications and job documents, and to publish the completion state of a job execution.
+ The `iot:Receive` permissions allow AWS IoT Core to publish messages on those topics to the current connected device. This permission is checked on every delivery of an MQTT message. You can use this permission to revoke access to clients that are currently subscribed to a topic.