Controlar el llenado de un tanque

// Control de llenado de un tanque: el sensor ultrasónico HC-SR04 mide la
// distancia entre la tapa y la superficie del agua; cuando el agua llega
// a la altura de corte, un relé cierra la electroválvula de entrada.
// Menor distancia = tanque más lleno: el sensor mira al agua desde arriba.
//
// SEGURIDAD: agua y electricidad no se llevan bien. Todas las conexiones
// eléctricas van fuera y POR ENCIMA del nivel del agua, y el sensor no se
// debe mojar. La práctica se realiza con una electroválvula de baja
// tensión (12 V); la conexión a 220 V de la guía original queda reservada
// al docente o a una instalación supervisada, y nunca sobre la protoboard
// (desvío pedagógico acordado).
//
// Plataforma: Arduino UNO.
// Conexión (la del esquema original): TRIG del sensor → pin 8, ECHO → pin 9,
// entrada "S" del módulo relé de la válvula → pin 4.
//
// Basado en: Fragmento de código 1 — Sistema de Tanques,
// Saberes Digitales (INET/EDUCAR 2019)
// Modernización: (1) se reemplazó el código generado por mBlock3 (_delay,
// _loop, pinMode dentro de la función de medición) por C++ idiomático con
// constantes nombradas y pinMode en setup(). (2) Se agregó una histéresis
// de 5 cm: el original abría y cerraba la válvula en el mismo valor exacto
// (40 cm), y el ruido de medición del HC-SR04 (±1 cm típico) haría
// traquetear el relé justo en el borde.

// Sensor ultrasónico del tanque (TRIG dispara el pulso, ECHO lo recibe).
const int PIN_TRIG1 = 8;
const int PIN_ECHO1 = 9;

// Relé que controla la electroválvula de entrada de agua.
const int PIN_RELE_VALVULA = 4;

// Módulo relé activo-alto, como en el original (HIGH = válvula abierta).
// Si tu módulo es activo-bajo, invertí solo estas dos constantes.
const int RELE_ENCENDIDO = HIGH; // válvula abierta: entra agua
const int RELE_APAGADO   = LOW;  // válvula cerrada

// Altura de corte del original: si el agua queda a menos de 40 cm del
// sensor, el tanque está lleno. Este valor NO se inventa: sale de medir
// en tu maqueta la distancia entre el sensor y el nivel máximo deseado
// (5 a 10 cm por debajo del ingreso de agua, dice la guía).
const float DISTANCIA_MINIMA_CM = 40.0;

// Colchón de la histéresis: la válvula cierra a 40 cm pero recién vuelve
// a abrir cuando el agua baja más allá de 45 cm. Sin este margen, una
// medición que oscile entre 39.5 y 40.5 abriría y cerraría el relé sin
// parar (modernización, ver encabezado).
const float MARGEN_HISTERESIS_CM = 5.0;

// El original medía una vez por segundo (_delay(1)).
const unsigned long INTERVALO_MEDICION_MS = 1000;

// El eco tarda 58 microsegundos por cada centímetro de distancia (ida y
// vuelta del sonido a ~343 m/s). El timeout evita quedar esperando para
// siempre un eco que no llega.
const float MICROSEGUNDOS_POR_CM = 58.0;
const unsigned long TIMEOUT_ECO_US = 30000;

// Mide la distancia en cm entre el sensor y la superficie del agua.
// Si en 30 ms no llega el eco (sensor desconectado o fuera de rango),
// pulseIn devuelve 0 y la distancia da 0: el programa lo interpreta como
// "tanque lleno" y cierra la válvula. Es una falla SEGURA: ante la duda,
// que no entre agua.
float medirDistanciaCm(int pinTrig, int pinEcho) {
  digitalWrite(pinTrig, LOW);
  delayMicroseconds(2);
  digitalWrite(pinTrig, HIGH); // pulso de disparo de 10 microsegundos
  delayMicroseconds(10);
  digitalWrite(pinTrig, LOW);
  return pulseIn(pinEcho, HIGH, TIMEOUT_ECO_US) / MICROSEGUNDOS_POR_CM;
}

void setup() {
  pinMode(PIN_TRIG1, OUTPUT);
  pinMode(PIN_ECHO1, INPUT);
  pinMode(PIN_RELE_VALVULA, OUTPUT);

  // Arrancamos con la válvula cerrada hasta la primera medición:
  // el estado seguro de un tanque es "no entra agua".
  digitalWrite(PIN_RELE_VALVULA, RELE_APAGADO);
}

void loop() {
  float distancia = medirDistanciaCm(PIN_TRIG1, PIN_ECHO1);

  if (distancia < DISTANCIA_MINIMA_CM) {
    // El agua llegó a la altura de corte: cerrar la válvula.
    digitalWrite(PIN_RELE_VALVULA, RELE_APAGADO);
  } else if (distancia > DISTANCIA_MINIMA_CM + MARGEN_HISTERESIS_CM) {
    // Hay lugar de sobra: abrir la válvula para cargar el tanque.
    digitalWrite(PIN_RELE_VALVULA, RELE_ENCENDIDO);
  }
  // Entre 40 y 45 cm no escribimos nada: el relé conserva su último
  // estado. Esa franja "muerta" es la histéresis que evita el traqueteo.

  delay(INTERVALO_MEDICION_MS);
}

// Control de llenado de un tanque: el sensor ultrasónico HC-SR04 mide la
// distancia entre la tapa y la superficie del agua; cuando el agua llega
// a la altura de corte, un relé cierra la electroválvula de entrada.
// Menor distancia = tanque más lleno: el sensor mira al agua desde arriba.
//
// SEGURIDAD: agua y electricidad no se llevan bien. Todas las conexiones
// eléctricas van fuera y POR ENCIMA del nivel del agua, y el sensor no se
// debe mojar. La práctica se realiza con una electroválvula de baja
// tensión (12 V); la conexión a 220 V de la guía original queda reservada
// al docente o a una instalación supervisada, y nunca sobre la protoboard
// (desvío pedagógico acordado).
//
// Plataforma: ESP32 (DevKit v1).
// Conexión: TRIG → GPIO 5, ECHO → GPIO 18 (¡leer nota!), relé de la
// válvula → GPIO 25.
// NOTA ELÉCTRICA (¡importante!): el ESP32 trabaja a 3,3 V. El HC-SR04
// clásico se alimenta con 5 V y su pin ECHO devuelve el eco a 5 V: eso
// dañaría el GPIO. Es OBLIGATORIO un divisor de tensión en ECHO
// (ECHO —1 kΩ— GPIO 18 —2 kΩ— GND), que baja los 5 V a ~3,3 V. Es la
// misma idea del divisor del LDR: dos resistencias que reparten la
// tensión. TRIG no necesita nada: los 3,3 V del GPIO alcanzan para
// dispararlo. Alternativa sin divisor: el modelo HC-SR04P, que puede
// alimentarse directamente con 3,3 V.
//
// Basado en: Fragmento de código 1 — Sistema de Tanques,
// Saberes Digitales (INET/EDUCAR 2019)
// Modernización: (1) se reemplazó el código generado por mBlock3 (_delay,
// _loop, pinMode dentro de la función de medición) por C++ idiomático con
// constantes nombradas y pinMode en setup(); se portó a ESP32 (el original
// usaba los pines 8/9/4 del UNO). (2) Se agregó una histéresis de 5 cm:
// el original abría y cerraba la válvula en el mismo valor exacto (40 cm),
// y el ruido de medición del HC-SR04 (±1 cm típico) haría traquetear el
// relé justo en el borde.

// Sensor ultrasónico del tanque (TRIG dispara el pulso, ECHO lo recibe).
const int PIN_TRIG1 = 5;
const int PIN_ECHO1 = 18; // con divisor de tensión 1 kΩ / 2 kΩ (ver nota)

// Relé que controla la electroválvula de entrada de agua.
const int PIN_RELE_VALVULA = 25;

// Módulo relé activo-alto, como en el original (HIGH = válvula abierta).
// Si tu módulo es activo-bajo, invertí solo estas dos constantes.
const int RELE_ENCENDIDO = HIGH; // válvula abierta: entra agua
const int RELE_APAGADO   = LOW;  // válvula cerrada

// Altura de corte del original: si el agua queda a menos de 40 cm del
// sensor, el tanque está lleno. Este valor NO se inventa: sale de medir
// en tu maqueta la distancia entre el sensor y el nivel máximo deseado
// (5 a 10 cm por debajo del ingreso de agua, dice la guía).
const float DISTANCIA_MINIMA_CM = 40.0;

// Colchón de la histéresis: la válvula cierra a 40 cm pero recién vuelve
// a abrir cuando el agua baja más allá de 45 cm. Sin este margen, una
// medición que oscile entre 39.5 y 40.5 abriría y cerraría el relé sin
// parar (modernización, ver encabezado).
const float MARGEN_HISTERESIS_CM = 5.0;

// El original medía una vez por segundo (_delay(1)).
const unsigned long INTERVALO_MEDICION_MS = 1000;

// El eco tarda 58 microsegundos por cada centímetro de distancia (ida y
// vuelta del sonido a ~343 m/s). El timeout evita quedar esperando para
// siempre un eco que no llega.
const float MICROSEGUNDOS_POR_CM = 58.0;
const unsigned long TIMEOUT_ECO_US = 30000;

// Mide la distancia en cm entre el sensor y la superficie del agua.
// Si en 30 ms no llega el eco (sensor desconectado o fuera de rango),
// pulseIn devuelve 0 y la distancia da 0: el programa lo interpreta como
// "tanque lleno" y cierra la válvula. Es una falla SEGURA: ante la duda,
// que no entre agua.
float medirDistanciaCm(int pinTrig, int pinEcho) {
  digitalWrite(pinTrig, LOW);
  delayMicroseconds(2);
  digitalWrite(pinTrig, HIGH); // pulso de disparo de 10 microsegundos
  delayMicroseconds(10);
  digitalWrite(pinTrig, LOW);
  return pulseIn(pinEcho, HIGH, TIMEOUT_ECO_US) / MICROSEGUNDOS_POR_CM;
}

void setup() {
  pinMode(PIN_TRIG1, OUTPUT);
  pinMode(PIN_ECHO1, INPUT);
  pinMode(PIN_RELE_VALVULA, OUTPUT);

  // Arrancamos con la válvula cerrada hasta la primera medición:
  // el estado seguro de un tanque es "no entra agua".
  digitalWrite(PIN_RELE_VALVULA, RELE_APAGADO);
}

void loop() {
  float distancia = medirDistanciaCm(PIN_TRIG1, PIN_ECHO1);

  if (distancia < DISTANCIA_MINIMA_CM) {
    // El agua llegó a la altura de corte: cerrar la válvula.
    digitalWrite(PIN_RELE_VALVULA, RELE_APAGADO);
  } else if (distancia > DISTANCIA_MINIMA_CM + MARGEN_HISTERESIS_CM) {
    // Hay lugar de sobra: abrir la válvula para cargar el tanque.
    digitalWrite(PIN_RELE_VALVULA, RELE_ENCENDIDO);
  }
  // Entre 40 y 45 cm no escribimos nada: el relé conserva su último
  // estado. Esa franja "muerta" es la histéresis que evita el traqueteo.

  delay(INTERVALO_MEDICION_MS);
}