First steps

To sign up for Amazon Web Services

1. Open http://www.amazonaws.cn/ and choose Sign Up.

2. Follow the on-screen instructions.

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, 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. After you install the Amazon CLI, open a command prompt window and enter the following command:

   aws iot describe-endpoint --endpoint-type=iot:Data-ATS

   The output should look like this:

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

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

   Note

   We recommend using ATS endpoints as seen in the example.

2. Browse to the Amazon 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 Amazon Region and account ID.

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

   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.

6. Choose Create.

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

1. Browse to the Amazon 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 Amazon 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.

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 Amazon IoT operations.

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

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.

2. In the left navigation pane, choose Settings.

   Your Amazon IoT endpoint is displayed in Device data endpoint. It should look like 1234567890123-ats.iot.us-east-1.amazonaws.com. Make a note of this endpoint.

3. 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.

4. Open demos/include/aws_clientcredential.h.

5. 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.

2. 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.

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.

2. Under Certificate PEM file, choose the ID-certificate.pem.crt that you downloaded from the Amazon IoT console.

3. Under Private Key PEM file, choose the ID-private.pem.key that you downloaded from the Amazon IoT console.

4. 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.