Skip to content

Adding instructions for setting up device from AWS IoT #27

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: development
Choose a base branch
from
Open

Adding instructions for setting up device from AWS IoT #27

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d558782
Merge pull request #21 from ARMmbed/development
adbridge Sep 16, 2020
3cef89e
Adding instructions for setting up device from AWS IoT
spartacoos Oct 19, 2020
4db0e4e
Update README.md
spartacoos Oct 19, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 48 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
![](./resources/official_armmbed_example_badge.png)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please do not remove the badge

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Understood, that was a mistake.

# Mbed OS example for AWS cloud

The example project is part of the [Arm Mbed OS Official Examples](https://os.mbed.com/code/). 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](https://os.mbed.com/docs/mbed-os/latest/tools/index.html). However, this example project specifically refers to the command-line interface tool [Arm Mbed CLI](https://github.com/ARMmbed/mbed-cli#installing-mbed-cli).
(Note: To see a rendered example you can import into the Arm Online Compiler, please see our [import quick start](https://os.mbed.com/docs/mbed-os/latest/quick-start/online-with-the-online-compiler.html#importing-the-code).)

## Downloading this project
**Note**: To see a rendered example you can import into the Arm Online Compiler, please see our [import quick start](https://os.mbed.com/docs/mbed-os/v6.3/quick-start/build-with-the-online-compiler.html#importing-the-code).


# Downloading this project

1. [Install Mbed CLI](https://os.mbed.com/docs/mbed-os/latest/quick-start/offline-with-mbed-cli.html).

1. Clone this repository on your system, and change the current directory to where the project was cloned:
Expand All @@ -23,22 +23,50 @@ You can build the project with all supported [Mbed OS build tools](https://os.mb
$ mbed import mbed-os-example-for-aws && cd mbed-os-example-for-aws
```

# Establishing AWS IoT Core service

1. Create an AWS account if you don’t have one, and login to it.

**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. Set up device credentials and policy via the AWS IoT console. You can refer to the AWS documentation [here](https://docs.aws.amazon.com/iot/latest/developerguide/iot-gs.html). After having logged into your AWS account. Follow the steps there to
1. Create an IoT policy
- Click on **IoT Core**
![AWS_Core](https://raw.githubusercontent.com/COTASPAR/AWS_base_guide/master/images/step1-IoT_Core.jpg)
- On the left panel click on **Secure > Policies**
![AWS_Core](https://raw.githubusercontent.com/COTASPAR/AWS_base_guide/master/images/secure_policies_pic2.jpg)
- Click on **Create**
![Create Policies](https://raw.githubusercontent.com/COTASPAR/AWS_base_guide/master/images/step7-create-policy.jpg)
- Click on **Advanced mode**
![Policies](https://raw.githubusercontent.com/COTASPAR/AWS_base_guide/master/images/creating_policy_click_advanced_mode.jpg)
- Fill in your policy as shown below then click **Create**
![Policies](https://raw.githubusercontent.com/COTASPAR/AWS_base_guide/master/images/aws_policy_advanced_mode_example.jpg)
**note:** you will need to substitute the **Resource** value above with your actual value from your **Thing** (which we will create next) by editing the policy after registering your **Thing**.

2. Register a **Thing**
- Click on **Manage > Things > Create**
![Things](https://raw.githubusercontent.com/COTASPAR/AWS_base_guide/master/images/step2-Things-Create.jpg)
- Click on **Create a single thing**
![Create](https://raw.githubusercontent.com/COTASPAR/AWS_base_guide/master/images/step3-create-single-thing.jpg)
- Fill in registry
![step4](https://raw.githubusercontent.com/COTASPAR/AWS_base_guide/master/images/create_thing.jpg)
**note**: no need to specify a type

3. Generate a device certificate and keys
- Click on **Create certificate**
![step4](https://raw.githubusercontent.com/COTASPAR/AWS_base_guide/master/images/certificate_option.jpg)
- Download the public key, private key, and the certificate for this **Thing** then click on **Activate**
![step4](https://raw.githubusercontent.com/COTASPAR/AWS_base_guide/master/images/download_certificates.jpg)
- Click on **Attach a policy**
![step4](https://raw.githubusercontent.com/COTASPAR/AWS_base_guide/master/images/attach_policies.jpg)
- Ensure the correct policy is selected then click on **Register Thing**
![step4](https://raw.githubusercontent.com/COTASPAR/AWS_base_guide/master/images/attach_policy_register_thing.jpg)
Comment on lines +34 to +64
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the detailed step-by-step guide. But it's effectively the same as this official page: https://docs.aws.amazon.com/iot/latest/developerguide/create-iot-resources.html. It's better not to maintain our own guide, as the service may change over time. Instead, maintain a link to an official one, and update the link as needed.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I hadn't encountered that link before on the example docs. The links we had linking to AWS were this and this. But I agree that it would be helpful to include that new link on the docs. I suppose we could include the pictures so that people can quickly get things running by looking at the screenshots and if something has changed they could still roughly know what to look for or use the link. @LDong-Arm What do you think?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I hadn't encountered that link before on the example docs. The links we had linking to AWS were this and this.

Yea the links we had previously were not helpful, so the new link is needed.

But I agree that it would be helpful to include that new link on the docs. I suppose we could include the pictures so that people can quickly get things running by looking at the screenshots and if something has changed they could still roughly know what to look for or use the link. @LDong-Arm What do you think?

Pictures put extra maintenance on us, as the UI of AWS (as an external website) may change over time. The AWS doc (new link) is quite short and provides the exact steps incl. every button to click.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should update the link. I agree with @ARMmbed/billing-old that pictures put extra maintenance on us and we don't want to repeat what the AWS doc already describes.


## Configuring the AWS IoT Core service

1. Create an AWS account if you don't have one, and login to it.

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

1. Set up device credentials and policy via the AWS IoT console. You can refer to the AWS documentation [here](https://docs.aws.amazon.com/iot/latest/developerguide/iot-gs.html). Follow the steps there to
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This linked page has changed since we created this README initially. The new, useful one is https://docs.aws.amazon.com/iot/latest/developerguide/create-iot-resources.html - shall we simply point users to this new page.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, we should point to the new page.


* create a thing
* generate a device certificate and keys
* create an IoT policy and attach that policy to your device.

Also download "Amazon Root CA 1" from [here](https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html#server-authentication-certs).

Once you have downloaded the credentials, you will need to place them in the [`aws_credentials.h`](./aws_credentials.h) file of this example.
Once you have downloaded the credentials, you will need to place them in the [`aws_credentials.h`](https://github.com/ARMmbed/mbed-os-example-for-aws/blob/master/aws_credentials.h) file of this example.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This link was correct.


The example includes a python script to automate converting the credentials you downloaded from AWS into C-compatible arrays/strings. First, create a new folder in the project to store your credential files, eg: `mkdir aws-credentials`. Copy the previously-downloaded credential files into this subdirectory.

Expand All @@ -52,15 +80,15 @@ You can build the project with all supported [Mbed OS build tools](https://os.mb

The above command will read your credential files and place them into a C header file for you: `aws_credentials.h`

1. 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.
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.
Copy link
Contributor

@LDong-Arm LDong-Arm Nov 4, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't change the line number. Using 1. for every item is a special syntax (not a mistake) - Markdown automatically renumbers them, so we don't need to maintain those numbers. Same comment for numbers below.


In [`mbed_app.json`](./mbed_app.json) file, set `aws-endpoint.value` to be that of the custom endpoint.

1. Set a topic that both your device and the cloud can publish messages to.
4. Set a topic that both your device and the cloud can publish messages to.

In [`mbed_app.json`](./mbed_app.json) file, set `aws-mqtt-topic.value` to a name you prefer, or use the default one. On the AWS console, you will then need to subscribe to the same topic name. At the time of writing this document, you can find this under "Test" on the console.

1. Give your device a name by setting `aws-client-identifier` in [`mbed_app.json`](./mbed_app.json).
5. Give your device a name by setting `aws-client-identifier` in [`mbed_app.json`](./mbed_app.json).

## Building and running

Expand Down