AWS IoT Core ESP32 Example

A production-ready template for connecting ESP32 devices to AWS IoT Core using Rust. Demonstrates secure MQTT communications, automated cloud infrastructure provisioning, and clean firmware code.

✨ Key Features

• 🔒 Secure MQTT over TLS - End-to-end encrypted communication with AWS IoT Core
• 🏗️ Infrastructure as Code - Complete Terraform automation for AWS resources
• 🦀 Modern Rust Firmware - Clean, safe, and efficient ESP32 code using esp-idf-svc
• ⚡ Non-blocking Architecture - Efficient message processing without blocking main thread
• 🔧 Configuration-driven - No hardcoded secrets, all settings via TOML files
• 🔄 Automatic Certificate Management - Seamless certificate provisioning and loading

🚀 Quick Start Guide

Prerequisites

1. Development Environment

   • Follow the installation guide from the official ESP Rust Book
   • Install espflash using this book guide
   • Install aws-cli using the official docs
   • Install terraform using the official docs

2. AWS Credentials

   IAM user (static credentials):

   aws configure

   AWS IAM Identity Center / SSO (aws login): After logging in, Terraform requires a credential_process entry in ~/.aws/config so the AWS SDK can resolve credentials:

   [default]
   region = us-east-1
   credential_process = aws configure export-credentials --format process

   Verify with: aws sts get-caller-identity

Step 1: Clone and Setup

git clone <repository-url>
cd aws-iot-esp32-example

Step 2: Provision AWS Infrastructure

cd terraform
cp terraform.tfvars.example terraform.tfvars

Edit terraform.tfvars:

things = [
  {
    name         = "esp32s3"
    topic_prefix = "esp32"
  },
  {
    name         = "esp32c3"
    topic_prefix = "esp32"
  }
]

region = "us-east-1"
tags = {
  Project     = "ESP32-IoT-Multi-Device"
  Environment = "development"
  Owner       = "your-name"
}

Deploy:

terraform init
terraform plan
terraform apply  # Type 'yes' to confirm

This creates two IoT Things (esp32s3, esp32c3), each with its own certificate, policy, and a certs/<thing-name>/ directory.

Step 3: Configure Firmware

For ESP32-S3:

cd ../firmware/example
cp -r ../../terraform/certs/esp32s3/ ./certs/
cp cfg.toml.example cfg.toml

Edit cfg.toml:

[example]
wifi_ssid = "YOUR_WIFI_NETWORK"
wifi_pass = "YOUR_WIFI_PASSWORD"

# From Terraform output
mqtt_url = "mqtts://your-endpoint.iot.region.amazonaws.com"
mqtt_client_id = "esp32s3"
mqtt_topic_pub = "esp32/pub"
mqtt_topic_sub = "esp32/sub"

cert_ca  = "certs/AmazonRootCA1.pem"
cert_crt = "certs/[certificate-id]-certificate.pem.crt"
cert_key = "certs/[certificate-id]-private.pem.key"

For ESP32-C3:

cd ../exampleC3
cp -r ../../terraform/certs/esp32c3/ ./certs/
cp cfg.toml.example cfg.toml
# Edit cfg.toml same as above, changing mqtt_client_id = "esp32c3"

Step 4: Build and Flash

ESP32-S3 (Xtensa):

cd firmware/example
cargo build --release
cargo run --release

ESP32-C3 (RISC-V):

cd firmware/exampleC3
cargo clean  # Required when switching architectures
cargo build --release
cargo run --release

Note: Each firmware directory has a pre-configured .cargo/config.toml for its target. See all supported targets at esp-idf-svc examples.

📡 JSON Message Protocol

Command	Description	Request	Response
ping	Connectivity test	{"message": "ping"}	{"message": "pong"}
any other	Unknown command	{"message": "test"}	{"message": "Unknown action: test"}
plain text	Non-JSON fallback	Hello World	{"message": "Plain text: Hello World"}

📋 Configuration Reference

Setting	Description	Example
wifi_ssid	WiFi network name	"MyNetwork"
wifi_pass	WiFi password	"SecurePassword123"
mqtt_url	AWS IoT endpoint	"mqtts://abc123.iot.us-east-1.amazonaws.com"
mqtt_client_id	Unique device ID	"esp32s3"
mqtt_topic_pub	Publish topic	"esp32/pub"
mqtt_topic_sub	Subscribe topic	"esp32/sub"
cert_ca	Root CA certificate	"certs/AmazonRootCA1.pem"
cert_crt	Device certificate	"certs/device-certificate.pem.crt"
cert_key	Private key	"certs/private-key.pem.key"

🧪 Testing Your Setup

Monitor Device Output

espflash monitor

Success indicators:

I (1234) example: WiFi connected successfully
I (1235) example: MQTT client created successfully
I (1236) example: Subscribed to topic "sensors/commands"
I (1237) example: Starting main application loop

Test MQTT Communication

1. Go to AWS IoT Core → Test → MQTT test client
2. Subscribe to your publish topic (e.g. esp32/pub)
3. Publish {"message": "ping"} to your subscribe topic (e.g. esp32/sub)
4. Expect response: {"message": "pong from esp32s3"}

📄 License

GPL-3.0 License - see LICENSE file for details.

🆘 Support

• 📖 ESP-IDF Documentation
• 🦀 Rust on ESP Book

---

Built with ❤️ for the IoT community