The setup required for this guide is a bit lengthy (about 15-30 minutes if you already have an Amazon Web Services account). However, it's mostly setup and you do not need to repeat the entire guide each time you start a new project.

You'll need an AWS account to access the Amazon AWS platform. Head over to and click Create an AWS Account to create an account.

Please note: Amazon AWS IoT is a PAID IoT service - you will be charged for usage. For non-production usage, keep track of the billing & make sure that you disable any running services if you're not using them.

Create an AWS IoT Policy

AWS uses IoT policies to "give devices permissions to access AWS IoT resources". These resources range from data, such as information stored in MQTT topics, to actions such as publishing/subscribing to AWS IoT MQTT topics.

Each AWS IoT policy is tied to a device-specific X.509 certificate, which authenticates your CircuitPython device with the AWS IoT server. It's a good security practice to have a separate AWS IoT Policy and X.509 certificate for each CircuitPython device you're connecting to AWS IoT.

From the AWS Management Console, search for the "IoT Core" service.

The AWS IoT monitor page should open. From here, click Secure on the left-hand sidebar.

You should be directed to the AWS IoT Monitor page.

Click Secure on the left-hand sidebar. 

From the dropdown, click Policies

You'll be directed to the AWS IoT Policies page. Click the Create button on the header of this page.

Set the name of the policy to PyPortal-Policy

Set the Action to iot:*

Set the Resource ARN to *

Under Effect, Click Allow to allow all clients using this policy to connect to AWS IoT.

Click Create. You should see the new policy appear under Policies and a green dialog stating that you've successfully created a policy.

Create an AWS IoT Thing

In AWS IoT terms, we're going to register your PyPortal as an AWS IoT Thing. Each device registered to AWS IoT is called a thing and tracked/managed in a thing registry.

You'll be creating an AWS IoT Thing named PyPortal.

From the AWS IoT sidebar, click Manage

You should be brought to your Things registry page.

From the Things registry, click the Create button.

You'll be registering a thing, your PyPortal, in your registry.

Click the Create a single thing button.

Name the thing PyPortalClick Next.

Next, you'll need to create (or add) a certificate to your PyPortal. This helps authenticate its connection with the AWS IoT server.

  • Click One-click certificate creation.
  • After the certificate has been created. Download the device's certificate and private key to your desktop.
    • You may also download the public key, but it's not required for this guide.
  • Then, click Activate to activate the root CA for AWS IoT.  If successfully activated, the text for the button should change to Deactivate.
    • You do not need to download the root CA. This certificate, along may other root CA certificates is already burned into your PyPortal's ESP32 already.
  • Click Attach a policy

Select the PyPortal-Policy you made earlier. You can click view to verify your policy against the policy in the screenshot below. This step attaches the policy you created to the PyPortal's X.509 certificate.

If everything looks correct, click Register Thing.

One last thing - certificates are inactive by default. You'll need to activate yours.

  • From the AWS IoT sidebar, navigate to Secure -> Certificates
  • Your newly generated certificate should appear below as INACTIVE. 
  • Click the three-bubble icon to bring up a dropdown menu.
  • Click Activate, your certificate should show up on this page as ACTIVE.

With your AWS IoT Device, policy, and certificate created, you can move on.

Create an Amazon SNS Topic/Subscription

Amazon's Simple Notification Service (SNS) is a way to send notification topics to an endpoint. In this project, you'll be writing to Amazon AWS IoT topics and using Amazon SNS to send notification messages from a topic to your inbox.

From the AWS Management Console, use the search-box to search for the Simple Notification Service

From the Amazon SNS sidebar, click Topics. Then, click Create Topic.

  • Name the topic moisture
  • Set the Display name to PyPortal Moisture Sensor Topic

Click the Create Topic button.

Next, you'll need to create a subscription to this topic. This subscription will be updated whenever the topic receives new data (i.e. whenever your PyPortal's moisture sensor sends an update to AWS IoT).

  • From the moisture topic page, click Create Subscription
  • Set the protocol to Email
  • Set the Endpoint to your email address

Click Create Subscription

Check the inbox of the email you entered as an endpoint. You should receive an email to confirm your topic subscription.

Click Confirm Subscription

Check the inbox of the email you entered as an endpoint. You should receive an email to confirm your topic subscription.

  • If you did not receive an email, check your spam folder.

Click Confirm SubscriptionYou should be redirected to an AWS link notifying you that your subscription has been confirmed. 

Create an AWS IoT Rule

One of the advantages of using AWS IoT is the ability to send data from your devices with other AWS services such as S3, Lambda or Amazon ML. You are going to create a rule to send data to the Amazon SNS topic, from AWS IoT.

For more information about AWS IoT Rules, visit the AWS IoT docs.

To set up a new rule:

  • Navigate to your AWS IoT Console and click Act
  • Click the Create button
  • Name the rule MoistureSensorRule
  • Set the description to what the rule does when invoked
    • For example, this rule will send an email when the plant's moisture sensor is too low.

Under Rule query statement, make sure you're Using SQL version 2016-03-23.

Copy and paste the SQL statement below into the Rule query statement field: 

SELECT * FROM '$aws/things/PyPortal/shadow/update/accepted' WHERE state.reported.moisture < 400

AWS IoT rules use a SQL statement to filter messages received on a MQTT topic. This SQL statement selects everything on the AWS IoT MQTT topic $aws/things/PyPortal/shadow/update/accepted. Then, it filters the data points on this topic for where the moisture level is less than 400.

For more information about AWS IoT's SQL rules, visit the AWS IoT SQL Reference page.

Next, let's select and configure an action to be invoked when this rule is satisfied.

  • Click Add action.
  • From Select an action, click Send a message as an SNS push notification.

On the Configure action page, 

  • Select moisture as the SNS target.
  • Set the message format to RAW.

We'll want to create a role to grant AWS access to perform the action.

Click Create Role and name this role PyPortalMoistureTopicRole.

Click the Add action button.

You should be brought back to the Create a rule page. Click Create Rule.

The MoistureSensorRule should appear in your AWS IoT Console's Rules page.

Congrats, you've set up AWS IoT, configured a device, and configured AWS IoT to send an email when a AWS IoT MQTT topic is updated with a value below a set threshold.

This guide was first published on Oct 16, 2019. It was last updated on Mar 02, 2024.

This page (AWS IoT Setup) was last updated on Oct 14, 2019.

Text editor powered by tinymce.