Ultrasonic water tank level monitor on an Arduino Uno

// Ultrasonic water tank level monitor and pump controller: an HC-SR04 looks
// down at the water from the lid, a 16x2 I2C LCD shows how full the tank is,
// and a relay runs the fill pump.
//
//   HC-SR04   TRIG pin 10, ECHO pin 9, VCC 5V, GND
//   LCD       I2C backpack at 0x27: SDA A4, SCL A5, VCC 5V, GND
//   relay     IN pin 4 (HIGH pulls it in), the pump on its NO contact,
//             with the pump's own supply on COM
//   buzzer    active buzzer on A0 (used as a digital pin), the overflow alarm
//
// HOW IT MEASURES. The sensor sits in the lid and times the echo off the
// water. The farther the echo, the emptier the tank:
//
//   distance  = echo time x 0.0343 cm per microsecond / 2
//   level %   = (EMPTY_CM - distance) / (EMPTY_CM - FULL_CM) x 100
//
// EMPTY_CM is the distance from the sensor to the bottom, FULL_CM the
// distance to the water when the tank is full. Here they are 110 cm and
// 10 cm, so every centimeter is one percent: an echo at 60 cm is 50 %.
// Measure your own tank and change the two numbers.
//
// THE PUMP has two marks, not one: it starts when the level falls below
// 20 % and keeps running until it reaches 90 %. One mark would switch the
// pump on and off every few seconds as ripples crossed it, and a pump
// (and its relay) wears out from starts. The gap between the marks is the
// hysteresis.
//
// THE ALARM: past 95 % the pump is stopped whatever it was doing and the
// buzzer beeps, because something else is filling the tank (or the pump
// relay has stuck). It stops when the level drops below 95 % again.
//
// A missing echo (a loose wire, the sensor knocked sideways) reads as an
// error, and the pump stops: a controller that cannot see the water must
// not run the pump.

#include <Wire.h>
#include <LiquidCrystal_I2C.h>

const int TRIG = 10;
const int ECHO = 9;
const int RELAY = 4;
const int BUZZER = A0;

const float EMPTY_CM = 110.0;  // sensor to the bottom of the tank
const float FULL_CM = 10.0;    // sensor to the water when the tank is full

const int PUMP_ON_BELOW = 20;   // percent
const int PUMP_OFF_AT = 90;     // percent
const int OVERFLOW_ABOVE = 95;  // percent

LiquidCrystal_I2C lcd(0x27, 16, 2);

bool pumping = false;
bool overflow = false;
bool beepOn = false;
unsigned long lastBeep = 0;
int lastPercent = -1;
unsigned long lastRead = 0;

// One distance in centimeters, or -1 when no echo came back in 30 ms.
float distanceCm() {
  digitalWrite(TRIG, LOW);
  delayMicroseconds(2);
  digitalWrite(TRIG, HIGH);
  delayMicroseconds(10);
  digitalWrite(TRIG, LOW);
  unsigned long us = pulseIn(ECHO, HIGH, 30000UL);
  if (us == 0) return -1;
  return us * 0.0343 / 2.0;
}

// The average of three readings, which smooths the ripples on the water.
// An HC-SR04 takes a new trigger only 60 ms after the last one started, so
// the readings are 60 ms apart.
float averageCm() {
  float sum = 0;
  for (int i = 0; i < 3; i++) {
    if (i > 0) delay(60);
    float d = distanceCm();
    if (d < 0) return -1;
    sum += d;
  }
  return sum / 3.0;
}

int percentOf(float cm) {
  float p = (EMPTY_CM - cm) / (EMPTY_CM - FULL_CM) * 100.0;
  if (p < 0) p = 0;
  if (p > 100) p = 100;
  return (int)(p + 0.5);
}

void setPump(bool on) {
  if (on == pumping) return;
  pumping = on;
  digitalWrite(RELAY, on ? HIGH : LOW);
  Serial.println(on ? "pump ON" : "pump OFF");
}

void show(int percent) {
  lcd.setCursor(0, 0);
  lcd.print("Level ");
  if (percent < 100) lcd.print(' ');
  if (percent < 10) lcd.print(' ');
  lcd.print(percent);
  lcd.print("% ");
  lcd.print(overflow ? "FULL!" : (pumping ? "PUMP " : "     "));
  // A bar of 16 blocks, one for every 6.25 percent.
  lcd.setCursor(0, 1);
  int blocks = (percent * 16 + 50) / 100;
  for (int i = 0; i < 16; i++) lcd.write(i < blocks ? (uint8_t)255 : (uint8_t)' ');
}

void setup() {
  Serial.begin(115200);
  pinMode(TRIG, OUTPUT);
  pinMode(ECHO, INPUT);
  pinMode(RELAY, OUTPUT);
  pinMode(BUZZER, OUTPUT);
  digitalWrite(RELAY, LOW);
  lcd.init();
  lcd.backlight();
  lcd.print("Tank level");
  Serial.println("tank level monitor ready");
}

void loop() {
  // While the alarm is on the buzzer beeps: it changes over every quarter
  // second, or at the first pass after one if a reading held the loop up.
  if (millis() - lastBeep >= 250) {
    lastBeep = millis();
    beepOn = !beepOn;
  }
  digitalWrite(BUZZER, overflow && beepOn ? HIGH : LOW);

  if (millis() - lastRead < 500) return;
  lastRead = millis();

  float cm = averageCm();
  if (cm < 0) {
    setPump(false);
    overflow = false;
    lcd.setCursor(0, 0);
    lcd.print("Sensor error    ");
    lcd.setCursor(0, 1);
    lcd.print("pump stopped    ");
    if (lastPercent != -2) Serial.println("sensor error: no echo, pump stopped");
    lastPercent = -2;
    return;
  }

  int percent = percentOf(cm);
  bool wasOverflow = overflow;
  overflow = percent > OVERFLOW_ABOVE;
  if (overflow) {
    setPump(false);
    if (!wasOverflow) Serial.println("ALARM: overflow");
  } else {
    if (wasOverflow) Serial.println("alarm cleared");
    if (percent < PUMP_ON_BELOW) setPump(true);
    else if (percent >= PUMP_OFF_AT) setPump(false);
  }

  if (percent != lastPercent) {
    Serial.print("level ");
    Serial.print(percent);
    Serial.print("%  (");
    Serial.print(cm, 1);
    Serial.println(" cm)");
    lastPercent = percent;
  }
  show(percent);
}