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

Run the guided path: toolchain check, .env, fleet CA and certificates, build, tests, a local mTLS endpoint on https://localhost:8443, then a simulated machine or a board over USB. Idempotent; prompts only where ambiguous. make help lists the same stages as make targets.

./Quickstart

Put a board on a reachable endpoint (certificate, registration, flash, first handshake)

./Quickstart onboard <device> <owner> <host>

Install the endpoint on a Linux box as one static binary (when ready)

make deploy    # or scripts/install-endpoint.sh on the target

Infrastructure

One static binary, a systemd unit, three PEMs and a SQLite file on any Linux box (scripts/install-endpoint.sh, endpoint/deploy/). The reference box is one EC2 instance from endpoint/template-staging.yaml; nothing in the service depends on AWS.

Resource	Description	Scope
EC2 instance	t4g.micro, Amazon Linux 2023, bootstraps the release install	Staging
Elastic IP + Route53	A record for the box's hostname	Staging
Security group	443 only; SSM for a shell, no SSH	Staging
Let's Encrypt	Public server certificate via DNS-01 (certbot-dns-route53); devices pin the fleet CA + ISRG Root X1	Staging
GitHub release	Static musl tarballs (aarch64, x86_64) the installer verifies by sha256	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