En calidad de Afiliado de Amazon, obtengo ingresos por las compras adscritas que cumplen los requisitos aplicables. Si compras desde estos enlaces, el precio para ti es el mismo y Amazon me paga una pequeña comisión que ayuda a mantener Tecnoyfoto.
Actualizado el 1 de agosto de 2026.
El sensor HC-SR04 permite medir distancias sin contacto y enviar el resultado a Home Assistant mediante un ESP8266 con ESPHome. Es un proyecto económico y muy útil para saber el nivel aproximado de un depósito seco, detectar si hay un objeto en una estantería o conocer la posición de una puerta. Pero hay un detalle eléctrico importante: el HC-SR04 se alimenta a 5 V y su pin Echo puede entregar 5 V, mientras que los GPIO del ESP8266 trabajan a 3,3 V. En esta guía lo conectaremos de forma segura con un divisor de tensión.
También vamos a sustituir la configuración antigua que publicaba una distancia inventada cuando no había eco. Con el código actual, una medición fallida seguirá siendo una medición no disponible: es más honesto y evita automatizaciones peligrosas.
Qué necesitas
- Sensor ultrasónico HC-SR04Enlace de afiliado.
- Una placa ESP8266 NodeMCUEnlace de afiliado o Wemos D1 miniEnlace de afiliado. Si todavía no conoces estas placas, consulta mi guía del ESP8266 y la guía del Wemos D1 mini.
- Dos resistencias: 1 kΩ y 2 kΩ para proteger la entrada Echo.
- Protoboard y cables DupontEnlace de afiliado.
- Cable USB y una fuente USB estableEnlace de afiliado.
Los enlaces de Amazon son de afiliado: el precio para ti no cambia y ayudan a mantener el proyecto.
Cómo funciona el HC-SR04
El ESP8266 envía un pulso de al menos 10 microsegundos al pin Trig. El módulo emite ocho ciclos ultrasónicos a 40 kHz y mantiene Echo en nivel alto durante el tiempo que tarda el sonido en viajar hasta el objeto y regresar. ESPHome transforma ese tiempo en metros.
La ficha técnica del HC-SR04 anuncia 2 cm a 4 m, resolución de hasta 3 mm y un ángulo de medición aproximado de 15°. En una instalación real no conviene prometer esos 4 m: la documentación de ESPHome advierte que muchos módulos funcionan de forma fiable hasta unos 2 m. El alcance depende del tamaño, el ángulo y el material del objeto, además de la temperatura y el movimiento del aire.
Cableado seguro: el divisor de tensión es obligatorio
La documentación eléctrica de Espressif sitúa la alimentación y las entradas/salidas del ESP8266 dentro del dominio de 3,3 V, con 3,6 V como máximo. No conectes Echo directamente al ESP8266. Con una resistencia de 1 kΩ entre Echo y el GPIO, y otra de 2 kΩ entre ese GPIO y GND, los 5 V se reducen aproximadamente a 3,33 V:
Vsalida = 5 V × 2 kΩ / (1 kΩ + 2 kΩ) = 3,33 V| HC-SR04 | NodeMCU ESP8266 | Conexión |
|---|---|---|
| VCC | VU/VIN/5V | 5 V procedentes del USB de la placa |
| GND | GND | Masa común |
| Trig | D6 / GPIO12 | Conexión directa |
| Echo | D5 / GPIO14 | Echo → 1 kΩ → GPIO14; GPIO14 → 2 kΩ → GND |
Atención a los nombres: D5 es GPIO14 y D6 es GPIO12 en una NodeMCU. No escribas GPIO5 o GPIO6 en el YAML por copiar la serigrafía D5/D6. GPIO6, además, está reservado para la memoria flash en el ESP8266.
Desconecta el USB mientras montas el circuito. Revisa que VCC, GND, Trig y Echo estén en el orden correcto: existen clones con acabados distintos. La masa del sensor y la del ESP8266 deben estar unidas.
Instalar ESPHome y preparar los secretos
Si empiezas desde cero, primero lee qué es ESPHome. En Home Assistant crea un dispositivo nuevo desde el complemento ESPHome, selecciona una placa ESP8266 y sustituye su contenido por el YAML siguiente. Si aún no utilizas esta plataforma, mi explicación de qué es Home Assistant te ayudará a situar cada pieza.
Guarda las credenciales en secrets.yaml. No publiques ese archivo ni escribas tu contraseña Wi-Fi directamente en una captura o repositorio:
wifi_ssid: "NOMBRE_DE_TU_WIFI"
wifi_password: "CONTRASEÑA_DE_TU_WIFI"
hc_sr04_api_key: "CLAVE_BASE64_GENERADA_POR_ESPHOME"
hc_sr04_ota_password: "UNA_CONTRASEÑA_OTA_LARGA"Código ESPHome actualizado
substitutions:
device_name: hc-sr04-esp8266
friendly_name: "HC-SR04 ESP8266"
esphome:
name: ${device_name}
friendly_name: ${friendly_name}
esp8266:
board: nodemcuv2
logger:
api:
encryption:
key: !secret hc_sr04_api_key
ota:
- platform: esphome
password: !secret hc_sr04_ota_password
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
ap:
ssid: "HC-SR04 Fallback"
password: !secret hc_sr04_ota_password
captive_portal:
sensor:
- platform: ultrasonic
name: "Distancia HC-SR04"
id: hc_sr04_distance
trigger_pin: GPIO12
echo_pin: GPIO14
update_interval: 1s
timeout: 2.5m
accuracy_decimals: 2
filters:
- lambda: |-
if (isnan(x)) return {};
return x;
- median:
window_size: 5
send_every: 3
send_first_at: 3La plataforma Ultrasonic Sensor de ESPHome usa metros. Por eso timeout: 2.5m limita la espera a 2,5 m. Si el eco no llega, el componente produce un valor no numérico; la lambda devuelve {} y no publica una distancia falsa. El filtro de mediana reduce picos aislados sin convertir un fallo en una medición válida.
Si utilizas un Wemos D1 mini cambia board: nodemcuv2 por el modelo que te haya propuesto ESPHome, pero puedes mantener GPIO12 y GPIO14 si cableas a D6 y D5. Valida la configuración antes de instalarla. La primera carga puede hacerse por USB; las siguientes, por OTA.
Añadir el sensor a Home Assistant
- En Home Assistant abre Ajustes → Dispositivos y servicios.
- Acepta el dispositivo descubierto por ESPHome o pulsa Añadir integración y elige ESPHome.
- Asigna el dispositivo a una zona y comprueba la entidad
sensor.distancia_hc_sr04. El identificador exacto puede variar.
Una tarjeta sencilla para el panel es:
type: gauge
entity: sensor.distancia_hc_sr04
name: Distancia
min: 0.02
max: 2.5
needle: trueCalibración y pruebas
- Coloca una superficie plana y dura frente al sensor a 20, 50 y 100 cm.
- Compara el valor con una cinta métrica. No pruebes dentro de la zona muerta inferior a 2 cm.
- Gira ligeramente el objeto. Si la lectura desaparece, el eco se está desviando fuera del receptor.
- Ajusta
timeoutal alcance real que necesites. Un tiempo excesivo puede hacer que el propio final de espera del módulo parezca una lectura válida.
Para convertir distancia en porcentaje de un depósito debes medir la distancia con el depósito vacío y lleno. No uses directamente 0 y 4 m: la geometría y la zona muerta importan. En líquidos, la condensación puede dañar un HC-SR04 abierto; para ambientes húmedos es preferible un sensor ultrasónico impermeable compatible.
Problemas frecuentes
La entidad aparece como no disponible
Comprueba la masa común, la alimentación de 5 V y que Trig/Echo no estén intercambiados. Acerca una superficie plana a 30 cm. Una lectura no disponible es correcta cuando no regresa ningún eco; no la reemplaces por un número arbitrario.
La distancia salta demasiado
Evita telas, espuma, objetos pequeños o superficies inclinadas. Reduce cables, separa el montaje de ventiladores y comprueba que la fuente USB sea estable. El filtro de mediana incluido elimina muchos valores atípicos.
El ESP8266 no arranca
Verifica que has usado GPIO12 y GPIO14 y no pines de arranque. Desconecta el sensor, inicia la placa y revisa el registro serie. Confirma también que el divisor está en Echo, no en VCC.
Vídeo del proyecto
El vídeo muestra el proyecto original. Para reproducirlo hoy, utiliza el cableado seguro y el YAML actualizado de esta página, especialmente el divisor de tensión en Echo.
Conclusión
El HC-SR04 sigue siendo una forma barata de aprender medición ultrasónica, ESPHome y Home Assistant. La clave no está solo en conseguir un número: hay que proteger el GPIO de 3,3 V, elegir pines correctos, tratar un eco ausente como dato no disponible y probar el montaje en el entorno real. Para ampliar tu estación puedes añadir un BME280 con ESPHome y registrar también temperatura, humedad y presión.
Continúa leyendo
Siguiente guía relacionada · 3 min de lectura
Sensor de puerta magnético con ESPHome
Gracias al sensor de puerta magnético con ESPHome, podremos tener conectadas nuestras puertas y ventanas. Tener sus ventanas conectadas a Home Assistant abre muchas…
Continuar con este artículo