ESP32 Service Uptime Monitor

Who watches your monitoring server when the server itself goes down?

Turn any $4 ESP32 into a standalone, ultra-low-power (< 1 W) hardware uptime appliance. Periodically check HTTP/HTTPS services from an independent microcontroller, get instant Discord webhook alerts on status changes, monitor live telemetry over WebSockets, and see outages at a glance via RGB LED indicators — with zero cloud subscriptions and zero VM overhead.

Web Flasher Live Preview & Docs OpenAPI 3.0 License

Why a Dedicated Hardware Uptime Monitor?

Features

Hardware & Board Profiles

The project uses include/devices.h to define board pins and available hardware features (HAS_SD_CARD, HAS_STATUS_LED, HAS_RGB_LED) based on the active PlatformIO build environment:

Feature / Pin esp32-s3-cam esp32-s3 esp32 esp32-c3 esp32-c6 esp32-c5
Target Board ESP32-S3 CAM Dev Board ESP32-S3 DevKitC-1 / WROOM-1 ESP32-WROOM-32 / NodeMCU-32S ESP32-C3 SuperMini / DevKitM-1 ESP32-C6 DevKitM-1 / DevKitC-1 ESP32-C5 DevKitC-1
Architecture Dual-core Xtensa LX7 Dual-core Xtensa LX7 Dual-core Xtensa LX6 Single-core RISC-V Single-core RISC-V (Wi-Fi 6) Single-core RISC-V (2.4/5GHz Wi-Fi 6)
Storage Backend MicroSD Card (SD_MMC, 1-bit) Internal Flash (LittleFS, 16MB) Internal Flash (LittleFS, 4MB) Internal Flash (LittleFS, 4MB) Internal Flash (LittleFS, 4MB) Internal Flash (LittleFS, 4MB)
Status LED GPIO 2 (HAS_STATUS_LED) None GPIO 2 (HAS_STATUS_LED) GPIO 8 (HAS_STATUS_LED) None None
RGB LED (WS2812B) GPIO 48 (HAS_RGB_LED) GPIO 48 (HAS_RGB_LED) None None GPIO 8 (HAS_RGB_LED) GPIO 27 (HAS_RGB_LED)
Boot Button GPIO 0 (BOOT_BTN_PIN) GPIO 0 (BOOT_BTN_PIN) GPIO 0 (BOOT_BTN_PIN) GPIO 9 (BOOT_BTN_PIN) GPIO 9 (BOOT_BTN_PIN) GPIO 28 (BOOT_BTN_PIN)
SD CMD / DATA / CLK GPIO 38 / 40 / 39 N/A N/A N/A N/A N/A

Quick Start & Installation

Flash via USB (PlatformIO)

# Build and flash firmware for your board via USB
pio run -e esp32-s3-cam --target upload
# Or: esp32-s3 | esp32 | esp32-c3 | esp32-c6 | esp32-c5

# Production release build (disables File Manager & memory stats logging, sets log level to INFO):
# RELEASE=1 pio run -e esp32-s3-cam --target upload

# Monitor serial output (115200 8N1)
pio device monitor

Web Flasher & Improv Wi-Fi (ESP Web Tools): Pre-merged dist/<env>.bin images and dist/manifest.json can also be generated via pio run -t dist for one-click browser flashing and serial Wi-Fi provisioning via ESP Web Tools and Improv Wi-Fi.

Initial Setup

Option A: Browser Provisioning via Improv Wi-Fi (USB Serial)

  1. Flash the firmware from the Web Flasher (or connect an already flashed board via Connect in ESP Web Tools).
  2. Once the device boots, select Connect to Wi-Fi in the browser dialog, choose your Wi-Fi network from the scanned list, and enter the password.
  3. The device connects to your network, saves /config.json, returns a direct Visit Device link (http://<hostname>.local/), and reboots into normal monitoring mode.

Option B: Captive Portal Access Point

  1. Power on the device: If no configuration exists, the device boots into Access Point (AP) mode. On first boot (or if /web/index.html is missing), the firmware automatically unpacks its embedded web UI archive into storage (/web/), so no manual file uploading is required.
  2. Connect to AP:
  3. SSID: ESP32-Service-Uptime-Monitor
  4. Security: Open (no password required for initial setup)
  5. Captive Portal IP: 192.168.4.1
  6. Open browser: Navigate to http://192.168.4.1/ (most devices trigger the captive portal automatically).
  7. Configure Wi-Fi: Enter your network credentials and click Save.
  8. Configure Discord (optional): Add your Discord webhook URL to receive notifications.
  9. Device reboots: Reconnects to your Wi-Fi network and starts monitoring. The web dashboard will be available at http://esp32-service-uptime-monitor.local/ (or your configured hostname) or via its assigned DHCP IP address.

Usage

Web Interface

Access the dashboard at http://<hostname>.local/ (default: http://esp32-service-uptime-monitor.local/) or http://<device-ip>/.

Hostname & mDNS Compatibility: In accordance with RFC 1123, device hostnames only allow lowercase ASCII letters (a-z), digits (0-9), and hyphens (-). Any spaces, dots, or underscores entered via the web interface are automatically sanitized to hyphens to ensure seamless mDNS resolution across all operating systems, including Windows, macOS, iOS, Android, and Linux.

Configuration Protection & Factory Reset

The hardware BOOT button controls configuration mode and factory reset: - Short Press (< 5s): Toggles configuration access. When enabled, the Settings icon and a real-time countdown badge (10:00) appear in the web header/menu, and /config, entity editing, and management routes are unlocked. For security, configuration mode automatically times out after 10 minutes of inactivity (each interaction resets the timer). - Long Press (≥ 10s): Initiates an immediate Factory Reset — deletes stored configurations and entities (config.json, monitored_entities.json) and restarts the device into Open Setup AP mode.

API Overview

Full interactive request/response schemas and live testing are available in the Swagger UI at http://<device-address>/api/docs and in docs/api/openapi.yaml.

System & Monitoring

Method Endpoint Description
GET /api/health Health check ({"status":"UP"})
GET /api/sysinfo Basic system stats (heap, PSRAM, temperature, uptime, version, RSSI)
GET /api/sysinfo/details Detailed device, memory, storage, network, monitoring, and firmware diagnostics
GET /api/summary Monitoring summary (total, online, offline counts)
GET /api/monitoredentities List all monitored entities
GET /api/monitoredentity/{name} Retrieve details for a specific entity
POST /api/monitoredentity Add a new monitored entity
PUT /api/monitoredentity/{name} Update an existing entity
DELETE /api/monitoredentity/{name} Delete an entity
WS /ws WebSocket connection for real-time state updates and live log stream

Configuration & Updates

(Configuration endpoints require BOOT button unlock or AP mode; otherwise they return 403 Forbidden. Alternatively, OTA and web archive endpoints accept an X-PlatformIO-Upload HTTP header matching the configured otaToken.)

Method Endpoint Description
GET /api/config Retrieve current configuration (sensitive secrets masked as ******)
POST /api/config Update configuration parameters
GET /api/config/backup Download complete configuration and entity backup JSON (Cache-Control: no-store; contains Wi-Fi and webhook secrets)
POST /api/config/restore Restore configuration and entities from backup JSON (multipart/form-data)
POST /api/config/factoryReset Reset settings to factory defaults
POST /api/config/test-led Preview RGB LED brightness (cyan pulse)
GET /api/wifiscan Trigger/poll non-blocking Wi-Fi network scan
POST /api/testDiscord Send a test notification to a Discord webhook URL
POST /api/web/upload-archive Upload and unpack web.zip archive into /web
GET /ota/start Initialize native firmware OTA session (mode=fr, optional hash MD5)
POST /ota/upload Firmware binary upload handled natively via Update.h

Security Considerations

Status Indicators

RGB LED (HAS_RGB_LED)

Status LED (HAS_STATUS_LED)

Configuration Files

The device stores its persistent state in JSON format in the root of the filesystem:

/config.json

{
  "wifiSSID": "YourNetworkSSID",
  "wifiPassword": "YourPassword",
  "sntpServer": "pool.ntp.org",
  "offsetHours": 1,
  "checkInterval": 60,
  "discordWebhookURL": "https://discord.com/api/webhooks/...",
  "hostname": "esp32-service-uptime-monitor",
  "logLevel": 8,
  "logLevelName": "DEBUG",
  "ledBrightness": 50,
  "otaToken": "your-ota-token"
}

/monitored_entities.json

[
  {
    "name": "Router",
    "address": "http://192.168.0.1/",
    "icon": "mdi-router-wireless",
    "isOnline": true,
    "notification": true,
    "disabled": false,
    "lastChanged": 1700000000
  }
]

Development & Contributing

For multi-board builds, OTA targets, Web UI asset packing (packweb / uploadweb), OpenAPI doc generation flags (--strict, --include-internal), unit testing (pio test -e native, Vitest), and contribution guidelines, see CONTRIBUTING.md.

License

This project uses a Dual License (Personal & Commercial) — see LICENSE for the full terms:

Donations

If you find this project useful and would like to support its development: - Bitcoin: bc1qx4q5epl7nsyu9mum8edrvp2my8tut0enrz7kcn - EVM: 0x9F0a70A7306DF3fc072446cAF540F6766a4CC4E8