coreHTTP basic Amazon S3 upload 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 Amazon S3 upload 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 example demonstrates how to send a PUT request to the Amazon Simple Storage Service (Amazon S3) HTTP server and upload a small file. It also performs a GET request to verify the size of the file after the upload. 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 Get 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 in this demo uses the HTTP API. 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 source file is named http_demo_s3_upload.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 an Amazon account.

    2. Accounts and permissions are set using Amazon Identity and Access Management (IAM). You use IAM 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 this policy:

        • AmazonS3FullAccess

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

  3. Upload a file to Amazon 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 the FreeRTOS-Plus/Demo/coreHTTP_Windows_Simulator/Common/presigned_url_generator/presigned_urls_gen.py file.

    For usage instructions, see the FreeRTOS-Plus/Demo/coreHTTP_Windows_Simulator/Common/presigned_url_generator/README.md file.

Functionality

The demo first connects to the Amazon S3 HTTP server with TLS server authentication. Then, it creates an HTTP request to upload the data specified in democonfigDEMO_HTTP_UPLOAD_DATA. After uploading the file, it checks that file was successfully uploaded by requesting for the size of the file. The source code for the demo can be found on the GitHub website.

Connecting to the Amazon S3 HTTP server

The connectToServerWithBackoffRetries function 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. The connectToServerWithBackoffRetries function returns a failure status if the TCP connection to the server can't be established after the configured number of attempts.

The prvConnectToServer function demonstrates how to establish a connection to the Amazon S3 HTTP server by using server authentication only. It uses the mbedTLS-based transport interface that is implemented in the FreeRTOS-Plus/Source/Application-Protocols/network_transport/freertos_plus_tcp/using_mbedtls/using_mbedtls.c file. The definition of prvConnectToServer can be found on the GitHub website.

Upload data

The prvUploadS3ObjectFile function demonstrates how to create a PUT request and specify the file to upload. The Amazon S3 bucket where the file is uploaded and the name of file to upload are specified in the pre-signed URL. To save memory, the same buffer is used for both the request headers and to receive the response. The response is received synchronously using the HTTPClient_Send API function. A 200 OK response status code is expected from the Amazon S3 HTTP server. Any other status code is an error.

The source code for prvUploadS3ObjectFile() can be found on the GitHub website.

Verifying the upload

The prvVerifyS3ObjectFileSize function calls prvGetS3ObjectFileSize to retrieve the size of the object in the S3 bucket. The Amazon S3 HTTP server doesn't 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 is an error.

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