FishMaster is an IoT smart aquarium system using an ESP32 Microcontroller to monitor water quality and control fish feeding.
The system includes a web dashboard where users can view the aquarium condition and feed fish from a phone or computer via a Progressive Web App (PWA).
Simply put ... FishMaster is an IoT smart aquarium system that can monitor water conditions in a fresh-water home aquarium.
The system consists of two main parts:
- Web system (Spring Boot backend + React frontend)
- Embedded system based on ESP32 microcontroller
The ESP32 uses sensors to check three things:
- pH
- Water temperature
- Water turbidity (water clarity)
The sensor data is shown on a local 2.8" touch screen.
The ESP32 also controls a servo motor that is used as an automatic fish feeder.
The ESP32 can work without the internet. This means the aquarium can still be monitored and controlled even when the Wi-Fi is not working.
The web system lets users check the aquarium from a phone or computer.
The web dashboard can show:
- Current sensor readings
- Charts
- Sensor history
- Feeding controls
- Remote monitoring
- Fish species management (including custom species profiles)
- Alert configuration
If the internet connection is lost, the ESP32 can continue to monitor the aquarium, show data on the local screen, and trigger local alerts.
(●'◡'●)
FishMaster can work in two ways.
The ESP32 handles the aquarium directly.
It:
- Reads the sensors
- Shows the readings on the touch screen
- Controls the fish feeder
- Checks water quality
- Gives local alerts (buzzer)
- Stores local historical data on the ESP32
- Continues working when Wi-Fi is not available
- Accepts input from a local 1×4 keypad and wireless remote controller
When the ESP32 has an internet connection, it can send the sensor data to the web system.
Users can then:
- View the current water condition
- View old sensor data
- See charts
- Control feeding
- Monitor the aquarium remotely
- Manage fish species and custom profiles
- Set alert thresholds
Figure 1: FishMaster System Overview
How It Works
Think of FishMaster as three parts talking to each other in real-time:
- the physical aquarium hardware (ESP32)
- the brain in the cloud (Spring Boot & PostgreSQL)
- the user dashboard (React)
To bridge the gap between the hardware and the web, MQTT (via HiveMQ Cloud) is used. It is a fast, lightweight messaging protocol perfect for IoT devices.
The data flows in two main loops: Up (monitoring) and Down (controlling).
This is how water data gets from the fish tank to your screen:
- The ESP32 constantly reads data from the temperature, pH, and turbidity sensors.
- It bundles this data and publishes it to the HiveMQ MQTT Broker under a specific topic (e.g.
FishMaster/tank_1/sensor). - The Spring Boot backend is always listening to that topic. When new data arrives, Spring Boot processes it and saves it in a PostgreSQL database.
- The React frontend asks the backend for the newest data via REST API and updates the charts automatically.
This is how you trigger actions, such as feeding the fish from your phone:
- You log into the dashboard and click the "Feed Now" button.
- React sends a REST POST request to the Spring Boot backend.
- Spring Boot immediately publishes a command to the MQTT broker on the control topic (e.g.
FishMaster/tank_1/control). - The ESP32 is listening to that control topic, receives the command, and triggers the physical SG90 servo motor to drop the fish food.
Everything on the web side (React frontend + Spring Boot backend) is packaged as a single system (monolith) and hosted on Railway.
Figure 2: FishMaster Cloud Architecture
- Water Monitoring – Checks water temperature, pH, and turbidity in real time.
- Automatic Feeding – Uses an SG90 servo motor to release fish food.
- Feeding Schedule – Allows feeding at set times.
- Water Safety – Can stop or delay feeding when water condition is not safe.
- Alerts – Gives local (buzzer) and remote alerts when a reading is outside the safe range.
- Data History – Saves sensor readings so they can be viewed later (both locally and in the cloud).
- Local Display – Shows live sensor data on a 2.8" ILI9341 TFT touch screen.
- Remote Monitoring – Lets users check the aquarium through the web dashboard (PWA).
- Offline Mode – The ESP32 continues working when Wi-Fi is not available.
- Fish Species Management – Built-in fish species database with recommended water parameter ranges. Users can also create custom species profiles.
- Remote Controller – A 2.4 GHz wireless remote controller can be used for manual control.
- Local Keypad – 1×4 keypad for basic local input without the web interface.
| Component | Model / Details | Qty | Purpose |
|---|---|---|---|
| ESP32 | ESP32-DevKitC-32E (38-pin, CP2102) | 1 | Main microcontroller |
| Expansion Board | ESP32 38-pin GPIO Expansion Board (Type-C) | 1 | Makes wiring easier |
| pH Sensor | PH 0–14 Liquid Monitoring Sensor | 1 | Measures water pH |
| Turbidity Sensor | FARDUINO Water Turbidity Module | 1 | Checks water clarity |
| Temperature Sensor | DS18B20 Waterproof Probe | 1 | Measures water temperature |
| Display | 2.8" ILI9341 SPI Touch LCD (240×320) | 1 | Shows aquarium data |
| Keypad | 1×4 Membrane Keypad | 1 | Local input control |
| Audio Device | Active/Passive Piezo Buzzer | 1 | Gives local alerts |
| Servo Motor | SG90 180° Micro Servo | 1 | Controls the fish feeder |
| Breadboard | MB-102 830-point | 1 | Used for circuit testing |
| Jumper Wires | 140 / 560 pcs set (M-M, M-F, F-F) | 1 set | Connects the components |
| Resistors | 4.7 kΩ (0.25 W, 5%) | ~10 | Used with the temperature sensor |
| Multimeter | HABOTEST HT109L | 1 | Used for testing the circuit |
| USB Cable | USB Type-C | 1 | Power and programming |
| Power Supply Module | MB102 Breadboard 5 V / 3.3 V Power Supply | 1 | Provides power to the breadboard |
| Remote Controller | 2.4 GHz Wireless Remote Controller / Receiver | 1 | Wireless manual control |
| Component | Technology / Details | Function |
|---|---|---|
| Backend | Spring Boot (Java) | Receives and processes sensor data, handles alerts, authentication, and MQTT |
| Frontend | React (JavaScript) + PWA | Shows the dashboard and controls |
| Database | PostgreSQL | Stores users, sensor data, tanks, fish species, and feeding records |
| MQTT Broker | HiveMQ Cloud (Free Tier, QoS 1) | Sends messages between the ESP32 and backend |
Main dashboard
Sensor data and charts
The FishMaster prototype uses an ESP32 connected to the sensors, touch screen, fish feeder, wireless remote controller, and local keypad.
FishMaster breadboard prototype with wireless remote controller
The ESP32 has a 2.8-inch TFT touch screen.
The screen shows the current aquarium data without needing a computer or internet connection.
FishMaster TFT touchscreen display
This is the development version of FishMaster.
It is mainly used to test the website, sensor data, and communication between the ESP32 and web system.
(❁´◡`❁)
Made with 🐟 and care by Abdalla Elshiekh 💗ESP32 · Spring Boot · React · PostgreSQL · MQTT · HiveMQ · Railway