supervictor

An all-Rust IoT template: ESP32 edge device, axum cloud API, and mutual TLS authentication—wired together with a single CLI.

Rust ESP32-C3 AWS SAM mTLS

▶ Fleet dashboard demo API docs

Architecture

Edge

ESP32-C3

Rust / no_std / Embassy

→

Transport

mTLS

X.509 client certs

→

Cloud

Axum API

Rust / tokio / SQLite or DynamoDB

Repository Layout

supervictor/ device/ # ESP32-C3 firmware (no_std, Embassy) src/bin/embedded_main.rs # firmware entry point src/bin/desktop_main.rs # desktop mTLS test client src/app/ # application logic src/network/ # HTTP, TLS, DNS, TCP src/models/ # uplink message types endpoint/ # cloud API (axum + tokio) src/handlers.rs # request handlers src/routes.rs # axum router src/store/ # SQLite + DynamoDB backends template.yaml # SAM/CloudFormation docker-compose.yml # local dev with Caddy mTLS Quickstart # single entry point: build, test, deploy, fleet ops certs/ # generated certs (gitignored) docs/ # this page

API

GET /health Health check — returns { "status": "ok" }

GET / Greeting + mTLS subject (if present)

POST / Device uplink — accepts { id, current } payload

GET /devices List all registered devices

POST /devices Register a new device

GET /devices/{device_id} Get device details

GET /devices/{device_id}/uplinks Recent uplink history for a device

Pipeline

./Quickstart orchestrates build, test, deploy, and device management through progressive stages.

Command	What it does
./Quickstart dev	Unit tests, build endpoint, start local server, run integration tests
./Quickstart dev --serve	Same as above but keeps the server running for manual testing
./Quickstart edge	Build + flash ESP32-C3 firmware via espflash 3.3.0
./Quickstart staging	Dev gate → deploy to dev stack → integration tests against live endpoint
./Quickstart prod	Dev gate → staging gate → confirm → deploy prod → mTLS verification
./Quickstart certs ca	Initialize the root CA for mTLS
./Quickstart certs device <name>	Issue a device client certificate
./Quickstart certs server <name>	Issue a server/TLS certificate
./Quickstart certs verify	Verify the mTLS certificate chain
./Quickstart certs handshake	Simulate mTLS handshake against a running server
./Quickstart ping	mTLS GET to verify the server is reachable
./Quickstart onboard	End-to-end device onboarding (certs + flash + verify)

All commands accept -v (verbose) and --dry-run flags.

Testing Tiers

Unit

In-memory SQLite, no infra required. Validates handlers, models, and store logic.

cargo test --features sqlite

Local Integration

HTTP against the running endpoint. Requires Docker + Caddy for mTLS.

docker compose up

Remote / mTLS

HTTPS + client certs against the deployed production endpoint.

./Quickstart ping --certs certs/device/

Environments

Dev

Local endpoint via docker compose with Caddy mTLS reverse proxy

Staging

Deployed dev stack on execute-api, no mTLS enforcement

Production

Custom domain supervictor.advin.io with mTLS, Route53, ACM certificate

Certificate Management

The ./Quickstart certs subcommand manages the full mTLS certificate lifecycle.

./Quickstart certs ca                          # Create root CA
./Quickstart certs device esp32                # Issue device cert
./Quickstart certs server caddy                # Issue server cert
./Quickstart certs verify                      # Verify cert chain
./Quickstart certs handshake                   # Simulate mTLS handshake

Quick Start

Clone the repository

git clone git@github.com:JimothyJohn/supervictor.git
cd supervictor

Check the toolchain

./Quickstart install

Generate certificates and start the local endpoint

./Quickstart certs ca && ./Quickstart certs device esp32 && ./Quickstart certs server caddy
./Quickstart dev --serve

Flash the device

./Quickstart edge

Deploy to production (when ready)

./Quickstart prod

Infrastructure

Defined in endpoint/template.yaml using AWS SAM. Prod-only resources are gated behind a Condition: IsProd flag.

Resource	Description	Scope
API Gateway	Regional REST API with CORS	All
Lambda	Rust binary via Lambda Web Adapter, arm64	All
ACM Certificate	DNS-validated TLS for custom domain	Prod
Custom Domain	mTLS enforcement via S3 truststore	Prod
Route53	A-record alias to API Gateway	Prod
Application Insights	CloudWatch monitoring + X-Ray tracing	All

Tech Stack

Component	Crate	Purpose
device	esp-hal, embassy, esp-mbedtls	no_std firmware with async WiFi + TLS
endpoint	axum, tokio, rusqlite	Cloud API with feature-gated store backends
cli	clap, ureq, toml	Build/test/deploy orchestration