Amazon FreeRTOS
User Guide

Prerequisites

To follow along with this tutorial, you need an AWS account, an IAM user with permission to access AWS IoT and Amazon FreeRTOS, and one of the supported hardware platforms.

AWS Account and Permissions

To create an AWS account, see Create and Activate an AWS Account.

To add an IAM user to your AWS account, see IAM User Guide. To grant your IAM user account access to AWS IoT and Amazon FreeRTOS, attach the following IAM policies to your IAM user account:

  • AmazonFreeRTOSFullAccess

  • AWSIoTFullAccess

To attach the AmazonFreeRTOSFullAccess policy to your IAM user

  1. Browse to the IAM console, and from the navigation pane, choose Users.

  2. Enter your user name in the search text box, and then choose it from the list.

  3. Choose Add permissions.

  4. Choose Attach existing policies directly.

  5. In the search box, enter AmazonFreeRTOSFullAccess, choose it from the list, and then choose Next: Review.

  6. Choose Add permissions.

To attach the AWSIoTFullAccess policy to your IAM user

  1. Browse to the IAM console, and from the navigation pane, choose Users.

  2. Enter your user name in the search text box, and then choose it from the list.

  3. Choose Add permissions.

  4. Choose Attach existing policies directly.

  5. In the search box, enter AWSIoTFullAccess, choose it from the list, and then choose Next: Review.

  6. Choose Add permissions.

For more information about IAM and user accounts, see IAM User Guide.

For more information about policies, see IAM Permissions and Policies.

Amazon FreeRTOS Supported Hardware Platforms

You need one of the supported MCU boards:

Registering Your MCU Board with AWS IoT

Your board must be registered with AWS IoT to communicate with the AWS Cloud.

If you are just getting started, you can use the Quick Connect workflow in the Amazon FreeRTOS console to quickly register your board with AWS IoT.

To register your board manually, you must create:

  • An AWS IoT policy.

    The AWS IoT policy grants your device permissions to access AWS IoT resources.

  • An IoT thing.

    An IoT thing allows you to manage your devices in AWS IoT.

  • A private key and X.509 certificate.

    The private key and certificate allow your device to authenticate with AWS IoT.

To create an AWS IoT policy

  1. To create an IAM policy, you need to know your AWS Region and AWS account number.

    To find your AWS account number, in the upper-right corner of the AWS Management Console, choose My Account. Your account ID is displayed under Account Settings.

    To find the AWS Region for your AWS account, use the AWS Command Line Interface. To install the AWS CLI, follow the instructions in the AWS Command Line Interface User Guide. After you install the AWS CLI, open a command prompt window and enter the following command:

    aws iot describe-endpoint

    The output should look like this:

    { "endpointAddress": "xxxxxxxxxxxxxx.iot.us-west-2.amazonaws.com" }

    In this example, the region is us-west-2.

  2. Browse to the AWS IoT console.

  3. In the navigation pane, choose Secure, choose Policies, and then choose Create.

  4. Enter a name to identify your policy.

  5. In the Add statements section, choose Advanced mode. Copy and paste the following JSON into the policy editor window. Replace aws-region and aws-account with your region and account ID .

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:Connect", "Resource":"arn:aws:iot:<aws-region>:<aws-account-id>:*" }, { "Effect": "Allow", "Action": "iot:Publish", "Resource": "arn:aws:iot:<aws-region>:<aws-account-id>:*" }, { "Effect": "Allow", "Action": "iot:Subscribe", "Resource": "arn:aws:iot:<aws-region>>:<aws-account-id>:*" }, { "Effect": "Allow", "Action": "iot:Receive", "Resource": "arn:aws:iot:<aws-region>:<aws-account-id>:*" } ] }

    This policy grants the following permissions:

    iot:Connect

    Grants your device the permission to connect to the AWS IoT message broker.

    iot:Publish

    Grants your device the permission to publish an MQTT message on the freertos/demos/echo MQTT topic.

    iot:Subscribe

    Grants your device the permission to subscribe to the freertos/demos/echo MQTT topic filter.

    iot:Receive

    Grants your device the permission to receive messages from the AWS IoT message broker.

  6. Choose Create.

To create an IoT thing, private key, and certificate for your device

  1. Browse to the AWS IoT console.

  2. In the navigation pane, choose Manage, and then choose Things.

  3. If you do not have any IoT things registered in your account, the You don't have any things yet page is displayed. If you see this page, choose Register a thing. Otherwise, choose Create.

  4. On the Creating AWS IoT things page, choose Create a single thing.

  5. On the Add your device to the thing registry page, enter a name for your thing, and then choose Next.

  6. On the Add a certificate for your thing page, under One-click certificate creation, choose Create certificate.

  7. Download your private key and certificate by choosing the Download links for each. Make a note of the certificate ID. You need it later to attach a policy to your certificate.

  8. Choose Activate to activate your certificate. Certificates must be activated prior to use.

  9. Choose Attach a policy to attach a policy to your certificate that grants your device access to AWS IoT operations.

  10. Choose the policy you just created and choose Register thing.

Installing a Terminal Emulator

A terminal emulator can help you diagnose problems or verify that your device code is running properly. There are a variety of terminal emulators available for Windows, macOS, and Linux.

You must connect your board to your computer before you attempt to establish a serial connection to your board with a terminal emulator.

Use the following settings to configure your terminal emulator:

Terminal Setting Value

BAUD rate

115200

Data

8 bit

Parity

none

Stop

1 bit

Flow control

none

If you do not know your board's serial port, you can issue one of the following commands from the command line or terminal to return the serial ports for all devices connected to your host computer:

Windows
chgport
Linux
ls /dev/tty*
macOS
ls /dev/cu.*