Firmware · Hardware · Web

Nivel de agua con ESP32: tinaco y cisterna en Home Assistant

Firmware completo para medir el nivel de tinacos y cisternas con ultrasonido: dashboard web, portal cautivo, MQTT con Home Assistant, sensores remotos por ESP-NOW y actualizaciones OTA.

Año: 2025–2026
Estado: Publicado en GitHub
Rol: Firmware, web embebida y pruebas
Repositorio: GitHub

01 · Problema

Saber cuánta agua queda en el tinaco o la cisterna sin subir a revisar, y que la casa sepa cuándo se está llenando, con hardware económico y sin depender de una app en la nube de un fabricante.

02 · Enfoque

Firmware modular en C++ con PlatformIO para una Heltec WiFi Kit 32 y un sensor HC-SR04: lecturas promediadas, intervalos adaptativos según el tipo y volumen del contenedor, detección de llenado y vaciado, y una web embebida que se minifica y comprime con gzip en cada compilación.

03 · Resultado

Dashboard con el contenedor animado en SVG, portal cautivo en español, inglés y francés, sensores remotos por ESP-NOW sin router, autodescubrimiento en Home Assistant (incluye el switch de la bomba) y OTA. Tiene 206 pruebas automatizadas (141 en C++ con Unity y 65 en JavaScript); la web pasa de 342 KB a 60 KB servidos.

04 · Stack

C++
ESP32 (Heltec WiFi Kit 32)
PlatformIO
ESPAsyncWebServer
MQTT
Home Assistant
ESP-NOW
ElegantOTA
Unity

Arquitectura

El punto de entrada es un AppManager (singleton) que coordina módulos independientes. Cada pieza vive en su librería y se comunica por interfaces:

Patrón	Dónde
Singleton	`AppManager`, coordinador único
Facade	`ApplicationConfig` simplifica 5 configuraciones de dominio
Strategy	`ISensor`: sensores intercambiables
Factory	`SensorManager` crea sensores en tiempo de ejecución
Observer	Callbacks de MQTT y ESP-NOW
Adapter	`UnifiedLogger` unifica Serial y WebSerial

Integración con Home Assistant

El equipo se anuncia solo por MQTT Discovery. Publica el estado como JSON y escucha comandos; cuando Home Assistant enciende la bomba, el sensor cambia a un intervalo de lectura rápido para seguir el llenado.

nivel_tinaco/{mac}/state       ESP32 → HA   datos del sensor (JSON)
nivel_tinaco/{mac}/cmd         HA → ESP32   FILLING_ON / FILLING_OFF
nivel_tinaco/{mac}/pump_state  ESP32 → HA   estado de la bomba
nivel_tinaco/{mac}/status      ESP32 → HA   online / offline

La web cabe en el chip

Las páginas viven en LittleFS. Un script previo a la compilación minifica HTML, CSS y JS y genera la versión .gz que se sirve al navegador:

fuente 342 KB  →  minificado 248 KB  →  gzip 60 KB   (82.5 % menos)

La tabla de particiones reserva dos ranuras de aplicación (una activa y otra para OTA); el firmware usa el 89.4 % de su ranura de 1.5 MB.