ThingFlash

A CLI that scaffolds and manages ESP32 fleets on AWS IoT Core.

It handles:

• device provisioning
• MQTT connectivity
• signed OTA updates with automatic rollback

all inside your own AWS account.

Why

Developing and connecting ESP32 devices to AWS IoT Core involves a long manual checklist: creating Things and X.509 certificates, writing scoped IoT policies, configuring Device Shadows, setting up an S3 bucket and code-signing profile, and wiring IoT Jobs for OTA. Doing this by hand is error-prone and hard to reproduce across projects.

ThingFlash reduces that checklist to a few commands. It generates the AWS infrastructure (via CDK), the device configuration, and an ESP-IDF firmware template that are already wired to work together.

How it works

• The CLI deploys a CDK stack into your AWS account and registers devices as IoT Things with per-device certificates.
• Project state lives in thingflash.json and in thingflash:project tags on the AWS resources. There is no ThingFlash server, cloud, or database.
• OTA updates are signed with AWS Signer, distributed through S3 and IoT Jobs, and roll back automatically if a device fails to confirm the new firmware.

Install

npm install -g thingflash

Requirements:

1. Node ≥ 18
2. PlatformIO CLI
3. ESP-IDF toolchain
4. AWS credentials configured

Run thingflash doctor to verify your environment.

Quick start (~5 minutes)

thingflash init my-fleet      # wizard: project, region, boards, deploy
thingflash device add node-01 # register a Thing + certs
thingflash flash node-01      # build + upload over USB
thingflash logs node-01       # live MQTT tail
thingflash ota firmware.bin --version 1.0.1 --device node-01   # or --all

Commands

| Command | Purpose | |---|---| | init [name] | Wizard: scaffold project + optionally deploy the stack | | setup | Deploy the CDK stack into your AWS account | | teardown | Delete all created resources (discovered by tag) | | doctor | Check creds, region, Node, PlatformIO, ESP-IDF, CDK, ports | | device add/remove/list | Manage Things, certs, and generated config | | flash <id> | pio build + upload over USB | | logs <id> | Live MQTT tail over WSS | | ota <file> --version <v> | Sign → S3 → IoT Job → per-device progress, auto-rollback |

Global flags: --profile · --region · --json · --verbose · --help · --version.

What gets created in your AWS account

• IoT Thing Type
• IoT Policy (least privilege, scoped to project topics)
• Device Shadow
• IoT Jobs (OTA)
• S3 bucket (versioned, private)
• AWS Signer profile
• IAM roles for OTA jobs

All resources are tagged thingflash:project, so teardown can discover and remove them cleanly.

Typical cost: under $1/month for 10~100 devices.

Contributing

See CONTRIBUTING.md. Good first issues are labeled in the tracker.

License

Apache-2.0. See NOTICE.