🌊 Advanced Water Pump Controller

A smart pump/induction motor controller with advanced features and protection systems

📑 Table of Contents

Important Information
Key Features & Capabilities
Hardware Requirements
Web Interface & API
Pictures & Schematics
Features
Data Logging System
Calibration & Setup
License

ℹ️ Important Information

• This project is an advanced version of the ESP8266 Water Pump Controller, offering enhanced features and capabilities.
• The tank level display utilizes a sophisticated stability algorithm, which may result in a slight delay in updates to minimize fluctuations and improve accuracy.
• This project is under active development. Features, documentation, and performance are continuously being improved and updated.

⚠️ Important Disclaimer

Project Status: Active Development & Testing
This is a new project under continuous development. Features, documentation, and test data will be updated regularly.

Safety Notice:
• This project uses hobby-grade components and is NOT designed for 24/7 commercial operation
• While safety features are implemented, they should not be considered fail-safe
• Use appropriate commercial-grade equipment for critical applications
• No liability is accepted for any damages resulting from using this project

🎯 Key Features & Capabilities

💪 Core Features

⚡ Dual Core ESP32 - One core for UI, one for sensor monitoring
🔄 OTA Updates - Over-the-air firmware updates via local network
📱 WiFi Manager - Easy device setup using smartphone
💾 Preferences - Persistent settings storage

🛡️ Protection Systems

🚱 Dry Run Protection - Prevents pump damage from running dry
⚠️ Overload Detection - Monitors current draw and shuts off if exceeded
🔌 Short Circuit - Advanced electrical protection features
📊 Load Monitoring - Real-time current and power monitoring

🎮 Smart Controls

🔘 One-Button System - Short press to navigate, long press to select
📟 OLED Display - 128x64 clear visual interface
🚥 RGB Indicators - Status and warning indicators
⏲️ Timer Controls - Scheduled operations

📊 Monitoring & Logging

💧 Water Level - Real-time tank level monitoring
📈 Google Sheets - Data logging and analysis
🔍 Diagnostics - Comprehensive system monitoring
⚡ Power Stats - Current and power consumption tracking

Note: Settings and parameters can be customized through an intuitive menu system.

🔧 Hardware

Item	Description	Notes
1.	Tested on: DOIT ESP32 DEVKIT V1 (30 pin)
2.	128x64 OLED Display
3.	~~ZMPT101B Voltage Sensor~~	Removed
4.	DS1307 RTC
5.	SCT013 30A/1V Current sensor	Check for Wiring
6.	AJ-SR04 Ultrasonic Sensor(Water Proof)	Check Mode 2 for connection
7.	WS2812B LED (Single LED Module)
8.	Any Push Button	I used metal one, feels sturdy
9.	Any desired float sensor
10.	Wires, connectors, etc	According to your need
11.	Fotek 100Amps SSR	Now that pump runs via contactor, a small 6A mechanical relay or 2A Omron solid state relay can be used instead
12.	Schneider LC1E1210M7 Contactor (220V AC coil)	Product Link - Upgraded from SSR for better reliability

🌐 Web Interface & API

The controller provides a comprehensive web-based interface and REST API for remote monitoring and configuration.

📱 Web Interface

Primary URL: http://<esp32-ip>/settings
Alternative URL: http://<esp32-ip>/ (root, serves settings)
Features:
- 🔌 Connectivity Status (checks every 4 seconds)
- 📊 Real-time Live Data Dashboard
- ⚙️ Settings Configuration
- 🕐 RTC Time Management
- 📦 OTA Firmware Updates
- 🔄 System Restart Control

🔌 REST API Endpoints

1️⃣ Connectivity Check `GET /api/ping`

Purpose: Check if ESP32 is online and responding
Method:	GET
Response:	`{"status": "ok"}`
Status Code:	200 (Success)
Polling Interval:	4 seconds
Example:	`curl http://192.168.1.100/api/ping`

2️⃣ Live Data `GET /api/live`

Purpose: Fetch real-time sensor readings and system status
Method:	GET
Response:	{ "tankPercent": 75, // Tank level percentage (0-100) "ultrasonicDistance": 65, // Distance in cm from sensor "liveAmp": 2.45, // Current consumption in Amperes "floatSensor": true, // Float switch state "pumpRunning": true, // Pump status "tankLow": 300, // Tank empty threshold (cm) "tankFull": 100, // Tank full threshold (cm) "time": "14:30:45", // Current time "dateTime": "2024-06-17 14:30:45", // Full timestamp "wifiRSSI": -65, // WiFi signal strength (dBm) "wifiConnected": true // WiFi connection status }
Status Code:	200 (Success)
Update Rate:	1 second (frontend polling)

3️⃣ Get Settings `GET /api/settings`

Purpose: Retrieve all system settings and configuration
Method:	GET
Response:	{ "tankLow": 300, // Tank empty distance (cm) "tankFull": 100, // Tank full distance (cm) "ampLow": 0.5, // Minimum current threshold (A) "ampMax": 5.0, // Maximum current threshold (A) "useUltrasonic": true, // Enable ultrasonic sensor "useSensors": true, // Enable current sensor "useFloat": true, // Enable float sensor "useWifi": true, // Enable WiFi connectivity "autoRun": false, // Enable auto-run schedule "apiKey": "your-key", // Google Sheets API key "ssid": "network-name", // WiFi SSID "password": "wifi-password", // WiFi password "onTime1": 615, // Schedule 1 ON time (HHMM) "offTime1": 730, // Schedule 1 OFF time (HHMM) "onTime2": 1229, // Schedule 2 ON time (HHMM) "offTime2": 1330, // Schedule 2 OFF time (HHMM) "onTime3": 1615, // Schedule 3 ON time (HHMM) "offTime3": 1715 // Schedule 3 OFF time (HHMM) }
Status Code:	200 (Success)

4️⃣ Save Settings `POST /api/settings`

Purpose: Update and persist system settings
Method:	POST
Content-Type:	application/json
Request Body:	Same structure as GET /api/settings response
Response:	`"Settings Saved"` (plain text)
Content-Type:	text/plain
Status Code:	200 (Success)
Example:	curl -X POST http://192.168.1.100/api/settings \ -H "Content-Type: application/json" \ -d '{"tankLow": 300, "tankFull": 100}'

5️⃣ Get Firmware Version `GET /api/version`

Purpose: Retrieve firmware version information
Method:	GET
Response:	`{"version": "1.4.2", "fw_version": "1.4.2"}`
Status Code:	200 (Success)

6️⃣ Sync RTC - Browser Time `POST /api/rtc/sync`

Purpose: Synchronize ESP32 RTC with browser time
Method:	POST (OPTIONS preflight supported)
Content-Type:	application/json
Request Body:	{ "year": 2024, "month": 6, "day": 17, "hour": 14, "minute": 30, "second": 45 }
Response:	`"Received by ESP32"` (plain text)
Status Code:	200 (Success)

7️⃣ Sync RTC - WiFi NTP `POST /api/rtc/update`

Purpose: Synchronize ESP32 RTC with NTP server via WiFi
Method:	POST
Request Body:	Empty (no parameters required)
Success Response:	`"RTC synchronized successfully"`
Error Response:	`"RTC synchronization failed"`
Status Code:	200 (Success) / 500 (Error)
Requirements:	WiFi must be connected to Internet

8️⃣ Restart Device `POST /api/restart`

Purpose: Trigger ESP32 system restart
Method:	POST
Request Body:	Empty
Response:	`"Device restarting..."`
Status Code:	200 (Success)
⚠️ Note:	Device will be unavailable for ~5 seconds

🔗 Usage Examples

JavaScript Fetch:

// Check connectivity
const response = await fetch('http://192.168.1.100/api/ping');
const data = await response.json();
console.log(data.status); // "ok"

// Get live data
const liveData = await fetch('http://192.168.1.100/api/live');
const live = await liveData.json();
console.log(`Tank Level: ${live.tankPercent}%`);

Python Requests:

import requests

# Get settings
response = requests.get('http://192.168.1.100/api/settings')
settings = response.json()

# Save settings
new_settings = settings.copy()
new_settings['tankLow'] = 320
response = requests.post('http://192.168.1.100/api/settings', json=new_settings)

cURL:

# Ping device
curl http://192.168.1.100/api/ping

# Get live data
curl http://192.168.1.100/api/live | jq

# Restart device
curl -X POST http://192.168.1.100/api/restart

🚀 Upcoming Features

Check Issues

Latest Changes: See v1.3.0 Release for information about contactor upgrade and recent improvements.

📸 Pictures & Schematics

Circuit Schematic	Front View	Front View 2	Front View 3
Full View	Ultra Sonic	Ultra Sonic USB	Complete Setup
Full View with Contactr Open	Full View with Contactr Covered	OLED View	WebUI Desktop
WebUI Mobile	USonic Module

⭐ Features

🎛️ System Architecture

🧮 Dual Core Processing
- 🖥️ Core 1: User Interface & Display
  - 🎨 UI Rendering
  - 📱 Menu System
  - 🔄 Display Updates
- 🤖 Core 2: Sensor & Safety
  - 📊 Real-time Monitoring
  - ⚡ Power Management
  - 🛡️ Protection Systems
💾 Memory System
- 🎚️ Dynamic Sensor Configuration
- 📦 Persistent Settings Storage
- 🔧 Resource Optimization

🛡️ Protection Systems

💧 Pump Safety
- 🚱 Dry Run Prevention
  - 🔍 Continuous Monitoring
  - 🛑 Auto Shutdown
- ⚡ Overload Protection
  - 📈 Current Monitoring
  - 🚨 Threshold Alerts
- 🔌 Short Circuit Guard
  - ⚠️ Fault Detection
  - 🚫 Emergency Cutoff

🎮 Smart Controls

🔘 One-Button Interface
- 👆 Short Press Navigation
- 👇 Long Press Selection
- 🌈 RGB Status Feedback
📟 Display System
- 📱 1.3" OLED Screen
- 📊 Real-time Stats
- 🚦 Status Indicators
- 🔊 Audio Alerts

💧 Water Management

📏 Level Monitoring
- 🎚️ Float Sensor (Primary)
  - ✅ Reliable Detection
  - 🛑 Overflow Prevention
- 📡 Ultrasonic Sensor
  - 📊 Real-time Monitoring
  - 📈 Level Tracking
- 🧮 Volume Calculation
  - 💧 Approximate water volume in liters
  - 🔧 Customizable tank capacity

🌐 Connectivity

📡 WiFi Features
- 📱 Smart Device Setup
- 🔄 OTA Updates
- ⏰ Auto Time Sync
- 📊 Remote Monitoring

⏱️ Time Management

🕒 RTC Features
- 📅 Scheduling
- ⚡ Power Monitoring
- 🔄 Auto Recovery
- 📊 Time Tracking

📊 Data Analytics

☁️ Cloud Integration
- 📈 Google Sheets Logging
- 📊 Performance Analytics
- 📉 Usage Statistics
- 🔍 System Diagnostics

💡 Pro Tips:

🔧 Configure sensors based on your setup

⚙️ Adjust thresholds for optimal performance

📱 Use WiFi features for remote monitoring

🔄 Keep firmware updated for best results

📊 Data Logging System

📡 Overview

This project offers two methods for logging pump data to Google Sheets:

🌟 Using PythonAnywhere as middleware (Recommended, Advanced)
🔗 Direct Google Sheets integration (Comparatively Simpler, Not Recommended)

Method 1: Using PythonAnywhere 🚀

🔧 Setup Process

🌐 Google Cloud Setup
- Follow this guide up to step 2
- 🔑 Obtain necessary Google Cloud credentials
- 📊 Set up your Google Sheet for data reception
⚙️ PythonAnywhere Configuration
- 🔄 Deploy provided Flask code to PythonAnywhere
- 📂 Code available in /resources folder
- 📡 Handles JSON data from ESP32
- 📝 Manages Google Sheets communication
📊 Data Collection
- ⏱️ Records fill time duration
- 📈 Logs sensor parameters
- 📊 Tracks system performance
- 💾 Stores historical data

Method 2: Direct Integration ⚡

ℹ️ Important Notes

📂 Located in /resources folder
💻 Requires different partition scheme
🔧 Higher memory usage
📋 Check header comments for configuration

📈 Logged Parameters

⏱️ Duration

💧 Water Level

⚡ Power Usage

🔄 System Status

💡 Tip: Choose Method 1 for better memory management and system stability. Use Method 2 only if you need direct integration and have configured the appropriate partition scheme.

Data Analysis

Track system efficiency
Monitor fill patterns
Identify potential issues
Analyze performance trends

⚡ What's New

V1.2.2

Water Volume Display:
- Approx. Water available in Litres is live now.

⚙️ Calibration & Setup

📡 Core Sensors

⚡ Current Sensor

SCT013

💧 Float Sensor

Water Level

📏 Distance Sensor

Ultrasonic

🔌 Current Sensor Calibration

1️⃣ Initial Setup

📊 Default Value: 27
🔧 Adjustable via program
📈 Reference: Home electricity meter
🎯 Goal: Match readings

2️⃣ Expected Readings (1HP Pump)

⚡ Voltage	📊 Current
220-240V AC	2.6A - 3.3A

3️⃣ Calibration Steps

1. 🏃 Run pump normally
2. 📊 Compare readings
3. 🔧 Adjust values
4. ✅ Verify results

🔧 Tank Volume Configuration

To enable the approximate water volume display:

Locate the TANK_VOLUME definition in the code.
Set its value to your tank's capacity in liters.
Example: #define TANK_VOLUME 1000 // for a 1000-liter tank

💡 Note: The accuracy of the volume estimation depends on the precision of your ultrasonic sensor calibration and the TANK_VOLUME setting.

⚡ Important Notes

🔌 Voltage Protection: External voltage protection is recommended
📊 Current-Voltage Relationship:
- 📈 Current increases when voltage drops
- 📉 Current decreases when voltage rises
- 🔍 This relationship helps detect power quality issues

🛡️ Safety Recommendations

🛡️ Always have external circuit protection
📊 Monitor initial readings carefully
📝 Document your calibration values
🔄 Perform periodic calibration checks

💡 Pro Tip: The relationship between current and voltage provides indirect power quality monitoring even without dedicated voltage sensors.

⚠️ Safety First

- External Protection
- Regular Checks
- Documentation

📊 Monitoring

- Track Readings
- Record Changes
- Verify Values

🔧 Maintenance

- Regular Calibration
- Keep Records
- Update Settings

📝 License

This project is licensed under the GNU General Public License v3.0 - see below for details.

                    GNU GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007

 Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

                            Preamble

  The GNU General Public License is a free, copyleft license for
  software and other kinds of works.

  When we speak of free software, we are referring to freedom, not
  price. Our General Public Licenses are designed to make sure that
  you have the freedom to distribute copies of free software (and
  charge for them if you wish), that you receive source code or can
  get it if you want it, that you can change the software or use
  pieces of it in new free programs, and that you know you can do
  these things.

  To protect your rights, we need to prevent others from denying
  you these rights or asking you to surrender the rights. Therefore,
  you have certain responsibilities if you distribute copies of the
  software, or if you modify it: responsibilities to respect the
  freedom of others.

For the complete license text, see the LICENSE file in this repository or visit GNU GPL v3.

Made with ❤️ for the IoT Community

Empowering smart homes, one pump at a time! 🏠💧

⭐ Star Us on GitHub 🐛 Report Issues

Name		Name	Last commit message	Last commit date
Latest commit History 82 Commits
.github		.github
data		data
resource		resource
.gitattributes		.gitattributes
.gitignore		.gitignore
Advanced-Water-Pump-Controller.ino		Advanced-Water-Pump-Controller.ino
LICENSE		LICENSE
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation