coreHTTP basic S3 download demo - FreeRTOS
IntroductionSource code organizationConfiguring the Amazon S3 HTTP server connectionFunctionality
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

coreHTTP basic S3 download demo

Important

This demo is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you start here 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.

Introduction

This demo shows how to use range requests to download files from the Amazon S3 HTTP server. Range requests are natively supported in the coreHTTP API when you use HTTPClient_AddRangeHeader to create the HTTP request. For a microcontroller environment, range requests are highly encouraged. By downloading a large file in separate ranges, instead of in a single request, each section of the file can be processed without blocking the network socket. Range requests lower the risk of having dropped packets, which require retransmissions on the TCP connection, and so they improve the power consumption of the device.

This example uses a network transport interface that uses mbedTLS to establish a mutually authenticated connection between an IoT device client running coreHTTP and the Amazon S3 HTTP server.

Note

To set up and run the FreeRTOS demos, follow the steps in Getting Started with FreeRTOS.

Single threaded versus multi threaded

There are two coreHTTP usage models, single threaded and multithreaded (multitasking). Although the demo in this section runs the HTTP library in a thread, it actually demonstrates how to use coreHTTP in a single threaded environment (only one task uses the HTTP API in the demo). Although single threaded applications must repeatedly call the HTTP library, multithreaded applications can instead send HTTP requests in the background within an agent (or daemon) task.

Source code organization

The demo project is named http_demo_s3_download.c and can be found in the freertos/demos/coreHTTP/ directory and on the GitHub website.

Configuring the Amazon S3 HTTP server connection

This demo uses a pre-signed URL to connect to the Amazon S3 HTTP server and authorize access to the object to download. The Amazon S3 HTTP server's TLS connection uses server authentication only. At the application level, access to the object is authenticated with parameters in the pre-signed URL query. Follow the steps below to configure your connection to Amazon.

  1. Set up an Amazon account:

    1. If you haven't already, create and activate an Amazon account.

    2. Accounts and permissions are set using Amazon Identity and Access Management (IAM). IAM allows you to manage permissions for each user in your account. By default, a user doesn't have permissions until granted by the root owner.

      1. To add a user to your Amazon account, see the IAM User Guide.

      2. Grant permission to your Amazon account to access FreeRTOS and Amazon IoT by adding these policies:

        • AmazonS3FullAccess

  2. Create a bucket in S3 by following the steps in How do I create an S3 Bucket? in the Amazon Simple Storage Service Console User Guide.

  3. Upload a file to S3 by following the steps in How do I upload files and folders to an S3 bucket?.

  4. Generate a pre-signed URL using the script located at FreeRTOS-Plus/Demo/coreHTTP_Windows_Simulator/Common/presigned_url_generator/presigned_urls_gen.py. For usage instructions, see FreeRTOS-Plus/Demo/coreHTTP_Windows_Simulator/Common/presigned_url_generator/README.md.

Functionality

The demo retrieves the size of the file first. Then it requests each byte range sequentially, in a loop, with range sizes of democonfigRANGE_REQUEST_LENGTH.

Source code for the demo can be found on the GitHub website.

Connecting to the Amazon S3 HTTP server

The function connectToServerWithBackoffRetries() attempts to make a TCP connection to the HTTP server. If the connection fails, it retries after a timeout. The timeout value will exponentially increase until the maximum number of attempts are reached or the maximum timeout value is reached. connectToServerWithBackoffRetries() returns a failure status if the TCP connection to the server cannot be established after the configured number of attempts.

The function prvConnectToServer() demonstrates how to establish a connection to the Amazon S3 HTTP server using server authentication only. It uses the mbedTLS-based transport interface that is implemented in the file FreeRTOS-Plus/Source/Application-Protocols/network_transport/freertos_plus_tcp/using_mbedtls/using_mbedtls.c.

The source code for prvConnectToServer() can be found on GitHub.

Creating a range request

The API function HTTPClient_AddRangeHeader() supports serializing a byte range into the HTTP request headers to form a range request. Range requests are used in this demo to retrieve the file size and to request each section of the file.

The function prvGetS3ObjectFileSize() retrieves the size of the file in the S3 bucket. The Connection: keep-alive header is added in this first request to Amazon S3 to keep the connection open after the response is sent. The S3 HTTP server does not currently support HEAD requests using a pre-signed URL, so the 0th byte is requested. The size of the file is contained in the response's Content-Range header field. A 206 Partial Content response is expected from the server; any other response status-code received is an error.

The source code for prvGetS3ObjectFileSize() can be found on GitHub.

After it retrieves the file size, this demo creates a new range request for each byte range of the file to download. It uses HTTPClient_AddRangeHeader() for each section of the file.

Sending range requests and receiving responses

The function prvDownloadS3ObjectFile() sends the range requests in a loop until the entire file is downloaded. The API function HTTPClient_Send() sends a request and receives the response synchronously. When the function returns, the response is received in an xResponse. The status-code is then verified to be 206 Partial Content and the number of bytes downloaded so far is incremented by the Content-Length header value.

The source code for prvDownloadS3ObjectFile() can be found on GitHub.