AWS Mbed OS example

The example project is part of the Arm Mbed OS Official Examples. It contains an application that connects to an AWS MQTT broker and publishes a message every 1 second for 10 seconds or until a message is received.

You can build the project with all supported Mbed OS build tools. However, this example project specifically refers to the command-line interface tool Arm Mbed CLI. (Note: To see a rendered example you can import into the Arm Online Compiler, please see our import quick start.)

Summary of steps:

1. Obtain the necessary keys and certificates to connect a device to AWS. This can be done in various ways after logging in to the AWS IoT console. You can refer to AWS documentation here. Follow the steps listed on AWS documentation to create an IoT policy for your device and attaching that policy to your device.
   NOTE: If you have an admin for your AWS account, please contact them to add a user to the account. You should obtain your login credentials from your admin in this case.
2. Once you have downloaded the credentials, you will need to place them in the aws_credentials.h file.
3. Once you have created the "thing", you will need to obtain the custom endpoint name from the console. At the time of writing this document, you can find it under "Settings" in the IoT console. In mbed_app.json file, set aws-endpoint.value to be that of the custom endpoint.
4. If using WiFi, you will also need to enter your network's SSID and password in mbed_app.json (see here).
5. You can then build the example and flash your target with the newly built binary using Arm Mbed CLI.
6. On the AWS console, you will then need to subscribe and publish to the topic created. At the time of writing this document, you can find this under "Test" on the console.
7. With the example running, you can monitor a serial terminal to see that the device connects to your network, exchanges some TLS handshakes, connects to AWS and publishes to the topic you just subscribed. This can be seen on the AWS console as incoming messages.
8. You can also publish to this topic from the AWS console. This example demonstrates a string being appended as "Hello <your string>!". You can "send" this from the AWS console and see the device responding with the received + appended string on the serial terminal of your device.

Downloading this project

1. Install Mbed CLI.

2. Clone this repository on your system, and change the current directory to where the project was cloned:

   $ git clone git@github.com:armmbed/mbed-os-example-aws && cd mbed-os-example-aws
   $ mbed deploy
   

   Alternatively, you can download the example project with Arm Mbed CLI using the import subcommand:

   $ mbed import mbed-os-example-aws && cd mbed-os-example-aws
   

Building and running

1. Configure the example using mbed_app.json and add your credentials in aws_credentials.h.
2. Connect a USB cable between the USB port on the board and the host computer.
3. Run the following command to build the example project, program the microcontroller flash memory, and open a serial terminal:

   $ mbed compile -m detect -t <TOOLCHAIN> --flash --sterm
   

Alternatively, you can manually copy the binary to the board, which you mount on the host computer over USB. The binary is located at ./BUILD/<TARGET>/<TOOLCHAIN>/mbed-os-example-aws.bin.

Depending on the target, you can build the example project with the GCC_ARM or ARM toolchain. After installing Arm Mbed CLI, run the command below to determine which toolchain supports your target:

$ mbed compile -S

Expected output

The application connects to an AWS MQTT broker and publishes a message every second for 10 seconds or until a message is received. On reception of a message, the application displays on the console the message prefixed with Hello␣.

Troubleshooting

If you have problems, you can review the documentation for suggestions on what could be wrong and how to fix it.

Related Links

• Mbed OS Stats API.
• Mbed OS Configuration.
• Mbed OS Serial Communication.
• Mbed OS bare metal.
• Mbed boards.
• AWS IoT Core
• AWS IoT Core - Embedded C SDK

License and contributions

The software is provided under Apache-2.0 license. Contributions to this project are accepted under the same license. Please see contributing.md for more info.

This project contains code from other projects. The original license text is included in those source files. They must comply with our license guide.