# First steps
**Important**
This is an archived version of the FreeRTOS User Guide for use with FreeRTOS release 202012.00. For the latest version of this document, see the [FreeRTOS User Guide](../../../latest/userguide/index.html).
To get started using FreeRTOS with Amazon IoT, you must have an Amazon account, an IAM user with permission to access Amazon IoT and FreeRTOS cloud services. You also must download FreeRTOS and configure your board's FreeRTOS demo project to work with Amazon IoT. The following sections walk you through these requirements.
**Note**
If you're using the Espressif ESP32-DevKitC, ESP-WROVER-KIT, or the ESP32-WROOM-32SE, skip these steps and go to [Getting started with the Espressif ESP32-DevKitC and the ESP-WROVER-KIT](getting_started_espressif.md).
If you're using the Nordic nRF52840-DK, skip these steps and go to [Getting started with the Nordic nRF52840-DK](getting_started_nordic.md).
1. [Setting up your Amazon account and permissions](#freertos-account-and-permissions)
1. [Registering your MCU board with Amazon IoT](#get-started-freertos-thing)
1. [Downloading FreeRTOS](#freertos-download)
1. [Configuring the FreeRTOS demos](#freertos-configure)
## Setting up your Amazon account and permissions
### Sign up for an Amazon Web Services account
If you do not have an Amazon Web Services account, use the following procedure to create one.
**To sign up for Amazon Web Services**
1. Open [http://www.amazonaws.cn/](http://www.amazonaws.cn/) and choose **Sign Up**.
1. Follow the on-screen instructions.
Amazon sends you a confirmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to [http://www.amazonaws.cn/](http://www.amazonaws.cn/) and choosing **My Account**.
### Secure IAM users
After you sign up for an Amazon Web Services account, safeguard your administrative user by turning on multi-factor authentication (MFA). For instructions, see [Enable a virtual MFA device for an IAM user (console)](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_credentials_mfa_enable_virtual.html#enable-virt-mfa-for-iam-user) in the *IAM User Guide*.
To give other users access to your Amazon Web Services account resources, create IAM users. To secure your IAM users, turn on MFA and only give the IAM users the permissions needed to perform their tasks.
For more information about creating and securing IAM users, see the following topics in the *IAM User Guide*:
+ [Creating an IAM user in your Amazon Web Services account](https://docs.amazonaws.cn//IAM/latest/UserGuide/id_users_create.html)
+ [Access management for Amazon resources](https://docs.amazonaws.cn/IAM/latest/UserGuide/access.html)
+ [Example IAM identity-based policies](https://docs.amazonaws.cn/IAM/latest/UserGuide/access_policies_examples.html)
To provide access, add permissions to your users, groups, or roles:
+ 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.amazonaws.cn//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.amazonaws.cn//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.amazonaws.cn//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*.
After you set up your Amazon account and permissions, continue to [Registering your MCU board with Amazon IoT](#get-started-freertos-thing).
## Registering your MCU board with Amazon IoT
Your board must be registered with Amazon IoT to communicate with the Amazon Cloud. To register your board with Amazon IoT, you must have:
An Amazon IoT policy
The Amazon IoT policy grants your device permissions to access Amazon IoT resources. It is stored on the Amazon Cloud.
An Amazon IoT thing
An Amazon IoT thing allows you to manage your devices in Amazon IoT. It is stored on the Amazon Cloud.
A private key and X.509 certificate
The private key and certificate allow your device to authenticate with Amazon IoT.
To register your board, follow the procedures below.
**To create an Amazon IoT policy**
1. To create an IAM policy, you must know your Amazon Region and Amazon account number.
To find your Amazon account number, open the [Amazon Management Console](https://console.amazonaws.cn/), locate and expand the menu beneath your account name in the upper-right corner, and choose **My Account**. Your account ID is displayed under **Account Settings**.
To find the Amazon region for your Amazon account, use the Amazon Command Line Interface. To install the Amazon CLI, follow the instructions in the [Amazon Command Line Interface User Guide](https://docs.amazonaws.cn/cli/latest/userguide/cli-chap-install.html). After you install the Amazon 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`.
1. Browse to the [Amazon IoT console](https://console.amazonaws.cn/iotv2/).
1. In the navigation pane, choose **Secure**, choose **Policies**, and then choose **Create**.
1. Enter a name to identify your policy.
1. 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 Amazon Region and account ID.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:Connect",
"Resource": "arn:aws-cn:iot:{{us-east-1}}:{{123456789012}}:*"
},
{
"Effect": "Allow",
"Action": "iot:Publish",
"Resource": "arn:aws-cn:iot:{{us-east-1}}:{{123456789012}}:*"
},
{
"Effect": "Allow",
"Action": "iot:Subscribe",
"Resource": "arn:aws-cn:iot:{{us-east-1}}:{{123456789012}}:*"
},
{
"Effect": "Allow",
"Action": "iot:Receive",
"Resource": "arn:aws-cn:iot:{{us-east-1}}:{{123456789012}}:*"
}
]
}
```
------
This policy grants the following permissions:
`iot:Connect`
Grants your device the permission to connect to the Amazon IoT message broker with any client ID.
`iot:Publish`
Grants your device the permission to publish an MQTT message on any MQTT topic.
`iot:Subscribe`
Grants your device the permission to subscribe to any MQTT topic filter.
`iot:Receive`
Grants your device the permission to receive messages from the Amazon IoT message broker on any MQTT topic.
1. Choose **Create**.
**To create an IoT thing, private key, and certificate for your device**
1. Browse to the [Amazon IoT console](https://console.amazonaws.cn/iotv2/).
1. In the navigation pane, choose **Manage**, and then choose **Things**.
1. 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**.
1. On the **Creating Amazon IoT things** page, choose **Create a single thing**.
1. On the **Add your device to the thing registry** page, enter a name for your thing, and then choose **Next**.
1. On the **Add a certificate for your thing** page, under **One-click certificate creation**, choose **Create certificate**.
1. Download your private key and certificate by choosing the **Download** links for each.
1. Choose **Activate** to activate your certificate. Certificates must be activated prior to use.
1. Choose **Attach a policy** to attach a policy to your certificate that grants your device access to Amazon IoT operations.
1. Choose the policy you just created and choose **Register thing**.
After your board is registered with Amazon IoT, you can continue to [Downloading FreeRTOS](#freertos-download).
## Downloading FreeRTOS
You can download FreeRTOS from the [FreeRTOS GitHub repository](https://github.com/aws/amazon-freertos).
**Note**
If you're getting started with the Cypress CYW954907AEVAL1F or CYW943907AEVAL1F development kits, you must download FreeRTOS from GitHub. See the [README.md](https://github.com/aws/amazon-freertos/blob/master/README.md) file for instructions. Configurations of FreeRTOS for these boards aren't currently available from the FreeRTOS console.
## Configuring the FreeRTOS demos
You must edit some configuration files in your FreeRTOS directory before you can compile and run any demos on your board.
**To configure your Amazon IoT endpoint**
You must provide FreeRTOS with your Amazon IoT endpoint so the application running on your board can send requests to the correct endpoint.
1. Browse to the [Amazon IoT console](https://console.amazonaws.cn/iotv2/).
1. In the navigation pane, choose **Settings**.
Your Amazon IoT endpoint is displayed in **Endpoint**. It should look like `{{1234567890123}}-ats.iot.{{us-east-1}}.amazonaws.com`. Make a note of this endpoint.
1. In the navigation pane, choose **Manage**, and then choose **Things**.
Your device should have an Amazon IoT thing name. Make a note of this name.
1. Open `demos/include/aws_clientcredential.h`.
1. Specify values for the following constants:
+ `#define clientcredentialMQTT_BROKER_ENDPOINT "{{Your Amazon IoT endpoint}}";`
+ `#define clientcredentialIOT_THING_NAME "{{The Amazon IoT thing name of your board}}"`
**To configure your Wi-Fi**
If your board is connecting to the internet across a Wi-Fi connection, you must provide FreeRTOS with Wi-Fi credentials to connect to the network. If your board does not support Wi-Fi, you can skip these steps.
1. `demos/include/aws_clientcredential.h`.
1. Specify values for the following `#define` constants:
+ `#define clientcredentialWIFI_SSID "{{The SSID for your Wi-Fi network}}"`
+ `#define clientcredentialWIFI_PASSWORD "{{The password for your Wi-Fi network}}"`
+ `#define clientcredentialWIFI_SECURITY` {{The security type of your Wi-Fi network}}
Valid security types are:
+ `eWiFiSecurityOpen` (Open, no security)
+ `eWiFiSecurityWEP` (WEP security)
+ `eWiFiSecurityWPA` (WPA security)
+ `eWiFiSecurityWPA2` (WPA2 security)
**To format your Amazon IoT credentials**
FreeRTOS must have the Amazon IoT certificate and private keys associated with your registered thing and its permissions policies to successfully communicate with Amazon IoT on behalf of your device.
**Note**
To configure your Amazon IoT credentials, you must have the private key and certificate that you downloaded from the Amazon IoT console when you registered your device. After you have registered your device as an Amazon IoT thing, you can retrieve device certificates from the Amazon IoT console, but you cannot retrieve private keys.
FreeRTOS is a C language project, and the certificate and private key must be specially formatted to be added to the project.
1. In a browser window, open `tools/certificate_configuration/CertificateConfigurator.html`.
1. Under **Certificate PEM file**, choose the `{{ID}}-certificate.pem.crt` that you downloaded from the Amazon IoT console.
1. Under **Private Key PEM file**, choose the `{{ID}}-private.pem.key` that you downloaded from the Amazon IoT console.
1. Choose **Generate and save aws\_clientcredential\_keys.h**, and then save the file in `demos/include`. This overwrites the existing file in the directory.
**Note**
The certificate and private key are hard-coded for demonstration purposes only. Production-level applications should store these files in a secure location.
After you configure FreeRTOS, you can continue to the Getting Started guide for your board to set up your platform's hardware and its software development environment, and then compile and run the demo on your board. For board-specific instructions, see the [Board-specific getting started guides](getting-started-guides.md). The demo application that is used in the Getting Started tutorial is the coreMQTT Mutual Authentication demo, which is located at `demos/coreMQTT/mqtt_demo_mutual_auth.c`.