ESP32 Device Framework

A reusable ESP32 firmware base with Wi-Fi, web configuration UI, authentication, MQTT / Home Assistant integration, and factory reset. Add device-specific logic on top without re-implementing the boilerplate.

Table of contents

• Features
• Building and flashing
• First-time Wi-Fi setup
• Web UI
• MQTT / Home Assistant
• HTTP API
• Configuration reference
• Extending the framework

Features

• Wi-Fi via WiFiManager — captive-portal setup on first boot, credentials stored in flash
• mDNS — device reachable as <hostname>.local
• Web UI — responsive configuration page served from the device, with logo support
• Authentication — optional HTTP Basic Auth to protect the web UI
• MQTT — connects to any broker, publishes an availability topic, reconnects automatically without blocking the web server
• Home Assistant discovery — stub ready for your entities
• Factory reset — rapid power-cycling clears settings (5× config, 10× config + Wi-Fi credentials)
• Config persistence — all settings stored as JSON in LittleFS (/config.json)

Building and flashing

The project uses PlatformIO.

# Build
pio run -e esp32dev

# Flash firmware
pio run -e esp32dev --target upload

# Upload filesystem image (logo, etc.) — only needed when data/ changes
pio run -e esp32dev --target uploadfs

# Open serial monitor (115 200 baud)
pio device monitor

Note: close the serial monitor before uploading — it holds the serial port exclusively.

Board targets: esp32dev, esp32-s3-devkitc-1, esp32-C3-devkitm-1, esp32-c6-devkitc-1, rpipico2w

First-time Wi-Fi setup

On first boot (or when stored Wi-Fi credentials are missing), the device starts an access point named ESP32-Device. Connect to it with any phone or laptop — a captive portal will appear automatically.

1. Enter your Wi-Fi SSID and password.
2. Optionally change the Device hostname (default: esp32-device, max 63 characters).
3. Click Save. The device connects to your network and restarts.

After connecting, the device is reachable at:

• http://<hostname>.local (default http://esp32-device.local) — mDNS, works on most local networks
• http://<IP address> — shown in the serial monitor on boot

Factory reset

Power-cycle (or press EN) rapidly before the 3-second boot window expires. The reset counter accumulates across rapid reboots:

Serial output shows the accumulated count:

[BOOT] reset count 3
[BOOT] reset count 4
...
[BOOT] reset count 5, triggering factory reset
[BOOT] factory reset triggered (clearWifi=0)!
[BOOT] factory reset complete, restarting...

Web UI

Browse to the device address to open the configuration page.

Logo

Place a logo.png in the data/ directory and upload the filesystem image once. The logo appears in the top-left of the configuration page. The data/logo.png included in this repo is a 200×200 px transparent PNG.

Info panel

Shows the current hostname and IP address.

Hostname

Sets the mDNS name (<hostname>.local). Changing the hostname automatically restarts the device so mDNS re-registers with the new name.

Security

MQTT

Click Save to persist all settings. Click Reset Device to restart the device immediately.

MQTT / Home Assistant

Connection behaviour

On connect the device publishes online to <prefix>/status (retained) and sets offline as the LWT. If the broker is unreachable, the firmware probes the TCP port before attempting a full MQTT connect and retries every 30 seconds without blocking the web server.

Extending with discovery and topics

Three stubs in main.cpp are the intended extension points:

HTTP API

Configuration reference

Config is stored as JSON in LittleFS at /config.json.

{
  "hostname": "esp32-device",
  "mqtt": {
    "en": true,
    "host": "192.168.1.10",
    "port": 1883,
    "user": "ha",
    "pass": "secret",
    "prefix": "device"
  },
  "auth": {
    "en": true,
    "pass": "secret"
  }
}

The file is written by the web UI. To erase everything including flash, use pio run --target erase.

Extending the framework

1. Add your hardware setup in setup() after the framework initialises.
2. Add your per-loop logic in loop() alongside server.handleClient() and mqttLoop().
3. Fill in the three MQTT stubs to subscribe, receive, and publish discovery payloads.
4. Add extra web routes with server.on(...) in startServer() if you need device-specific endpoints.
5. Persist extra config fields by adding keys to loadConfig() and saveConfig().
6. Place static files (images, etc.) in data/ and upload the filesystem image with pio run --target uploadfs.