tutorial

Monitoring ESPHome with Vigilmon

ESPHome compiles and deploys firmware to your ESP32/ESP8266 devices — but if the dashboard goes down, your OTA update pipeline breaks. Here's how to monitor ESPHome uptime, API health, and OTA compilation status with Vigilmon.

ESPHome is the open-source firmware framework that turns ESP32 and ESP8266 microcontrollers into smart home sensors with a few lines of YAML — no custom code required. Its web dashboard manages firmware compilation and OTA updates for every configured device. When the dashboard goes offline, you lose visibility into your sensor network and the ability to push firmware fixes. Vigilmon keeps watch over the ESPHome dashboard, REST API, and OTA compilation pipeline so you know immediately when your IoT infrastructure has a problem.

What You'll Set Up

  • HTTP uptime monitor for the ESPHome dashboard (port 6052)
  • REST API health check via /version for version and service status
  • TCP port monitor for the ESPHome compiler service
  • SSL certificate alerts for HTTPS-proxied ESPHome dashboard deployments
  • Heartbeat monitor for OTA device update service health via the /devices endpoint

Prerequisites

  • ESPHome 2023.x+ running as a Docker container or Home Assistant add-on
  • ESPHome dashboard accessible on port 6052
  • A free Vigilmon account

Step 1: Monitor the ESPHome Dashboard

The ESPHome dashboard on port 6052 is the central hub for compiling firmware and tracking device status. Add an HTTP monitor to confirm it's reachable:

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter the URL: http://your-esphome-host:6052/
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Click Save.

If the dashboard is unreachable, your OTA update pipeline is broken and you'll have no visibility into which devices have failed compilations.

Step 2: Monitor the ESPHome Version API

ESPHome exposes a /version REST endpoint that returns the current ESPHome version as a JSON response. This is the lightest health check available — no authentication required:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter the URL: http://your-esphome-host:6052/version
  3. Set Check interval to 1 minute.
  4. Set Expected HTTP status to 200.
  5. Under Response body check, enter "version" to confirm the JSON version field is present.
  6. Click Save.

A successful response looks like:

{
  "version": "2024.2.0"
}

This check validates that the ESPHome Python process is alive and responding to API requests. If the dashboard UI check passes but this fails, the API layer has broken independently of the frontend.

Step 3: Add a TCP Port Monitor

A TCP monitor verifies that the ESPHome compiler service is accepting connections at the network layer:

  1. Click Add Monitor → TCP Port.
  2. Enter the host: your-esphome-host
  3. Set Port to 6052.
  4. Set Check interval to 1 minute.
  5. Click Save.

This is especially useful for Docker deployments where the container may be running but the port binding has broken due to a network configuration change or container restart policy issue.

Step 4: SSL Certificate Alerts for Proxied Deployments

If you expose ESPHome through a reverse proxy (nginx, Traefik, or Caddy) with HTTPS, SSL certificate expiry can cut off access to your firmware compilation pipeline.

  1. Open the HTTP / HTTPS monitor you created in Step 1.
  2. Update the URL to https://esphome.yourdomain.com if using a reverse proxy.
  3. Enable Monitor SSL certificate.
  4. Set Alert when certificate expires in less than 21 days.
  5. Click Save.

A minimal Traefik label set for ESPHome in Docker Compose:

services:
  esphome:
    image: ghcr.io/esphome/esphome
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.esphome.rule=Host(`esphome.yourdomain.com`)"
      - "traefik.http.routers.esphome.entrypoints=websecure"
      - "traefik.http.routers.esphome.tls.certresolver=letsencrypt"
      - "traefik.http.services.esphome.loadbalancer.server.port=6052"

Set a 21-day alert window so you have time to investigate Traefik's Let's Encrypt renewal before your OTA pipeline loses its HTTPS access.

Step 5: Heartbeat Monitoring for the OTA Update Pipeline

ESPHome devices can get stuck in a failed OTA update state — the device is unreachable, the compilation log shows errors, and there's no automatic recovery. Use Vigilmon's cron heartbeat to periodically verify that no devices are stuck.

  1. In Vigilmon, click Add Monitor → Cron Heartbeat.
  2. Set the expected ping interval to 10 minutes.
  3. Copy the heartbeat URL (e.g., https://vigilmon.online/heartbeat/abc123).

Create a heartbeat script on your ESPHome host:

#!/bin/bash
# /usr/local/bin/esphome-heartbeat.sh

ESPHOME_HOST="http://localhost:6052"
VIGILMON_URL="https://vigilmon.online/heartbeat/abc123"

# Fetch device list from ESPHome API
DEVICES=$(curl -sf "$ESPHOME_HOST/devices")

if [ $? -ne 0 ]; then
  echo "Failed to reach ESPHome API — not pinging Vigilmon"
  exit 1
fi

# Check for devices with compilation errors
ERRORS=$(echo "$DEVICES" | grep -c '"configuration_type":"yaml"' || true)

# Ping Vigilmon — ESPHome API is healthy
curl -sf "$VIGILMON_URL" > /dev/null

echo "ESPHome OTA pipeline heartbeat OK"

Schedule it with cron:

crontab -e
# Add:
*/10 * * * * /usr/local/bin/esphome-heartbeat.sh >> /var/log/esphome-heartbeat.log 2>&1

If the ESPHome API becomes unreachable, the script skips the Vigilmon ping and the heartbeat goes silent — triggering an alert after the 10-minute window expires.

Step 6: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon and add email, Slack, or a webhook.
  2. On HTTP monitors, set Consecutive failures before alert to 2 — ESPHome occasionally takes a few seconds to respond during heavy compilation jobs.
  3. On the heartbeat monitor, set the threshold to 1 missed ping — a missed heartbeat means the OTA pipeline check script failed entirely.

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP — Dashboard | http://host:6052/ | ESPHome dashboard crash | | HTTP — Version API | http://host:6052/version | API layer failure | | TCP Port | host:6052 | Compiler service not listening | | SSL Certificate | https://esphome.yourdomain.com | Let's Encrypt renewal failure | | Cron Heartbeat | Heartbeat URL | OTA pipeline failure, API unreachable |

ESPHome is often invisible until something breaks — a device offline, a failed firmware push, a dashboard that silently stopped compiling. With Vigilmon watching the dashboard, version API, TCP port, and OTA pipeline health, you'll catch failures before your sensor network starts reporting stale data.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles