Using MicroPython to get started with AWS IoT Core

Introduction

Customers ask how they can get started with AWS IoT using the devices and languages they are familiar with. To help address this need, AWS has published tutorials such as connecting a Raspberry Pi and creating a virtual device with Amazon EC2 in the AWS IoT Core Developer Guide. This blog walks you through how to configure an ESP32 based microcontroller to connect to AWS IoT Core using MicroPython.

MicroPython is a lean and efficient implementation of the Python 3 programming language. MicroPython is a high-level language that is intuitive and easy to read and write compared to embedded C or Java programs. You can use MicroPython and an ESP32 based microcontroller to quickly get started prototyping your AWS IoT project.

Prototyping your project allows you to quickly test a full IoT solution. MicroPython makes it easy to connect a device to AWS IoT Core and route messages to other AWS services. This blog demonstrates how you can use MicroPython to quickly prototype IoT devices with no prior embedded programming or IoT experience.

Walkthrough

In this blog, you will configure an ESP32 microcontroller to connect to AWS IoT Core over MQTT. You will complete the following tasks:

• Creating a policy
• Creating an AWS IoT thing
• Preparing the files for the microcontroller
• Using MicroPython to connect to AWS IoT
• Copying the files to your microcontroller
• Updating the device shadow

Prerequisites

To follow along with the blog, you will need an ESP32 based microcontroller. This blog has been tested using a FeatherS2 running MicroPython v1.19.1. If you use a different board, you may have to change some of the code for the built-in LED and light sensor, depending on your board’s features. We will use ampy, a command line tool to send files to MicroPython over its serial connection. You will need the following prerequisites:

• An AWS account with permissions to AWS IoT core.
• Install MicroPython from the MicroPython site.
• Configure ampy from the ampy GitHub repository.

Step 1: Creating a policy

In this step, you will create a policy to give permissions to our AWS IoT thing.

1. Navigate to the AWS IoT console.
2. In the navigation pane under security, choose Policies.
3. Choose Create policy.
4. For the policy name, enter BlogThing-Policy.

5. For the policy document, choose JSON and enter the following policy.

a. For <Region>, enter your Region code.

b. For <account_ID>, enter your account ID without dashes.

{
  “Version”: “2012-10-17”,
  “Statement”: [
    {
      “Effect”: “Allow”,
      “Action”: “iot:Connect”,
      “Resource”: “arn:aws:iot:<Region>:<account_ID>:client/BlogClient”
    },
    {
      “Effect”: “Allow”,
      “Action”: “iot:Publish”,
      “Resource”: “arn:aws:iot:<Region>:<account_ID>:topic/$aws/things/BlogThing/shadow/update”
    },
    {
      “Effect”: “Allow”,
      “Action”: “iot:Subscribe”,
      “Resource”: “arn:aws:iot:<Region>:<account_ID>:topicfilter/$aws/things/BlogThing/shadow/update/delta”
    },
    {
      “Effect”: “Allow”,
      “Action”: “iot:Receive”,
      “Resource”: “arn:aws:iot:<Region>:<account_ID>:topic/$aws/things/BlogThing/shadow/update/delta”
    }
  ]
}

Step 2: Creating an AWS IoT thing

In this step you will configure an AWS IoT thing and download the certificate files used for authentication.

1. Navigate to the AWS IoT console.
2. In the navigation pane, under the manage, all devices section, choose Things.
3. Choose Create things.
4. On the number of things to create page, select Create single thing and choose Next.
5. For thing name, enter
6. In the Device Shadow section, choose Unnamed shadow (classic).
7. Select the Edit shadow statement section to expand it. Enter the following:

{
    “state”:{}
}

8. Choose Next.

9. On the Device Certificate page, choose Auto-generate a new certificate (recommended).

10. On the Polices page, choose the BlogThing-Policy you created in step 1.

11. Choose Create thing.

12. On the Download certificates and keys window, download the Device certificate and Key files.

13. Choose Done.

Step 3: Preparing the files for the microcontroller

In this step, you will rename your device certificate and key files. You will download the library needed for MQTT. You will then download and review the example code.

1. Navigate to your local disk where you downloaded the device certificate and key files.
2. The device certificate is the file ending in -certificate.pem.crt. Rename this the certificate to pem.crt.
3. The private key is the file ending in -private.pem.key. Rename this file to pem.key. We will not use the public key for this blog.
4. Next you will download the library needed for MQTT. Navigate to the GitHub repository and download it to your local disk.
5. Create a folder getting-started-micropython-esp32 to organize your files. Move the certificate and key file to this folder.
6. In the micropython-lib GitHub repository, navigate to micropython/umqtt.simple/umqtt/simple.py and copy it to a folder in getting-started-micropython-esp32 called umqtt.
7. Your folder should have the following files:

a. pem.crt

b. pem.key

c. umqtt/simple.py

Step 4: Using MicroPython to connect to AWS IoT

Next, we need to write the code to connect to AWS IoT Core over MQTT.

1. In your getting-started-micropython-esp32 folder, create a new file called py.
2. Copy the main.py code from the aws-iot-core-getting-started-micropython GitHub repository.
3. Enter the following code:

a. Replace wifi_ssid with your wireless network name.

b. Replace wifi_password with your wireless password.

c. Replace aws_endpoint with your AWS IoT endpoint. You can find it in settings page in your AWS IoT Core console.

Step 5: Copying the files to your microcontroller

Now we need to copy the files to the microcontroller. In this example, you will use the Adafruit MicroPython tool (ampy).

1. Connect your microcontroller board to your computer with a USB cable.
2. Open a command prompt or terminal and navigate to your getting-started-micropython-esp32
3. Copy the files by entering the following commands. Replace <port> with the port of your microcontroller.

ampy -p <port> put cert.pem.crt

ampy -p <port> put private.pem.key

ampy -p <port> put main.py

ampy -p <port> mkdir umqtt

ampy -p <port> put umqtt/simple.py umqtt/simple.py

4. Press the button RST to reset your board.

Step 6: Updating the device shadow

Now that your device is reporting to AWS IoT Core, update the desired state of the shadow to turn the onboard LED on.

1. Navigate to the AWS IoT console.
2. In the Manage section, under All devices, choose Things.
3. Select BlogThing you created in step 2.
4. Select the Device Shadows tab, and choose Classic Shadow.

5. The device shadow reports the onboard led status, client name, uptime, firmware, hardware, and the light sensor value. Choose edit and replace the device shadow with the following JSON to turn the LED on.

{
    "state": {
        "desired": {
            "led": {
                 "onboard" : 1
             }
           }
     }
}

6. It may take up to 10 seconds for the LED to turn on, since the board sleeps in between messages. Once the LED turns on, edit the JSON to set onboard to 0 to turn the LED off.

Cleaning Up

If you no longer need your device connected, you should clean up the resources creating during this blog to avoid charges.

Delete files from MicroPython

1. Connect your microcontroller board to your computer
2. Delete the files by entering the following commands. Replace <port> and <file> with the name of each file copied in step 5.

ampy -p <port> rm <file>

Delete AWS IoT thing

1. Navigate to the AWS IoT console.
2. In the navigation pane, under the manage, all devices section, choose Things.
3. Choose the AWS IoT thing you created in step 2.
4. Choose Delete.

Delete AWS IoT thing

1. Navigate to the AWS IoT console.
2. In the navigation pane under security, choose Policies.
3. Choose the AWS IoT policy you created in step 1.
4. Choose Delete.

Conclusion

You can use MicroPython to prototype new ideas. This same solution can be used to prototype your IoT projects and quickly evaluate AWS IoT services. In this blog, you followed the steps needed to connect an ESP32 microcontroller to AWS IoT Core using MQTT. You created an AWS IoT thing and an AWS IoT policy, prepared and copied files, and tested the device shadow. You were able to use MicroPython to quickly get started with AWS IoT Core.

Now that your sensor data is being sent to AWS IoT Core, you can experiment with some of the other features of AWS IoT Core. Consider creating AWS IoT rules to route device data to other services.

The monitoring river levels using LoRaWAN implementation guide provides an example on how to use MicroPython with LoRaWAN.

To learn more about the FeatherS2 used in this blog, visit the Unexpected Maker website.

To learn more about AWS IoT Core, you can review the documentation and workshops.

To learn more about AWS IoT Core, you can review the documentation and workshops.

About the Author