🌱 GreenPulse

IoT Plant Monitoring & Smart Irrigation System

Professional-grade automated plant care through precision sensing and intelligent irrigation

Features • Hardware • Getting Started • Documentation • Contributing

---

📖 Overview

GreenPulse is an advanced IoT solution that revolutionizes plant care by combining real-time environmental monitoring with intelligent automated irrigation. Built on the ESP32-C6 Super Mini platform, it monitors soil moisture, temperature, humidity, and atmospheric pressure while synchronizing data to a cloud dashboard and maintaining reliable local control.

Key Innovation: Unlike traditional binary irrigation systems that waste up to 40% of water through oversaturation, GreenPulse implements an Exponential Control Value algorithm that tapers pump speed as soil moisture approaches the target threshold, preventing water waste and root damage.

🎯 Why GreenPulse?

• Water Conservation: Reduces water waste by ~40% through precision control
• Energy Efficient: Optimized network stack with sub-second connectivity
• Reliable: Redundant sensing and FreeRTOS multitasking for zero-latency response
• User-Friendly: OLED display with intuitive status indicators
• Scalable: Cloud synchronization with local fallback control

---

✨ Features

🔬 Advanced Sensing

• Dual Environmental Sensors: Two BME280 sensors provide redundant temperature, humidity, and pressure monitoring
• Capacitive Soil Moisture: Corrosion-resistant probes for long-term reliability
• Real-time Display: 0.96" OLED screen with dynamic status indicators

💧 Intelligent Irrigation

• Anti-Overshoot Control: Exponential tapering prevents water waste
• PWM Actuator Control: Variable-speed pumping through ESP32 LEDC peripheral
• Customizable Thresholds: Adjust moisture targets for different plant types

⚡ Power Optimization

• Static IP Configuration: Bypasses DHCP for sub-second network connection
• WiFi Power-Save Mode: Reduces idle current consumption
• Dual 18650 Batteries: 7-14 days runtime per charge
• Integrated Charging: USB Type-C charging module

🌐 Connectivity

• Cloud Synchronization: Real-time data logging to PythonAnywhere API
• Local Control: Operates independently if network unavailable
• Status Blobs: Visual WiFi and API sync confirmation on OLED
• Fast DNS: Hardcoded 8.8.8.8 for consistent endpoint resolution

🖥️ Software Architecture

• FreeRTOS Multitasking: Separate UI and control logic for responsive operation
• Modular Design: Clean separation between sensors, actuators, networking, and display
• Resource-First Philosophy: Optimized for both water and electrical efficiency

---

🛠️ Hardware Architecture

Core Components

Component	Specification	Purpose	Qty
Microcontroller	ESP32-C6 Super Mini	System brain & WiFi connectivity	1
Environmental Sensors	BME280 (I2C)	Temperature, humidity, pressure (redundant)	2
Soil Sensor	Capacitive Moisture Sensor	Soil hydration monitoring	2
Display	0.96" SSD1306 OLED (I2C)	Real-time dashboard with status blobs	1
Water Pump	5V DC Amphibious Motor	Irrigation execution	1
Motor Driver	DRV8833 / L293D	PWM pump speed control	1
Tubing	6/8mm silicone, 2m	Water delivery	1
Batteries	18650 Lithium-Ion	Portable power (parallel config)	2
Charging Module	Type-C Lithium Charger	Battery management	1
Power Switch	Latching Toggle Switch	System power control	1
Prototyping Board	Veroboard 9x15cm	Component mounting	1
Connectors	Female Headers (10x10 pins)	Modular connections	As needed
Wiring	22AWG wire, 5m	Electrical connections	1
Enclosure	Custom housing	Weather protection	1

Pin Configuration (ESP32-C6)

I2C Bus 0 (Sensors):
├─ SDA: GPIO 6
└─ SCL: GPIO 7
   ├─ BME280 Sensor 1
   └─ SSD1306 OLED Display

I2C Bus 1 (Redundant Sensor):
├─ SDA: GPIO 9
└─ SCL: GPIO 8
   └─ BME280 Sensor 2

Analog Inputs:
├─ GPIO 0: Soil Moisture Sensor 1 (ADC)
└─ GPIO 1: Soil Moisture Sensor 2 (ADC)

Pump Control (DRV8833):
├─ GPIO 19: Motor Input 1 (AIN1)
├─ GPIO 20: Motor Input 2 (AIN2)
└─ GPIO 18: PWM Control / Standby

Status LED:
└─ GPIO 8: Internal RGB LED

Power:
├─ 5V: From battery management system
└─ GND: Common ground

Hardware Images

---

🚀 Getting Started

Prerequisites

Hardware Requirements:

• All components listed in Hardware Architecture
• Soldering iron and supplies
• Multimeter for testing
• USB-C cable for programming

Software Requirements:

• Arduino IDE 2.0 or later
• ESP32 board support package (v3.0.0+)
• Git for cloning the repository

Installation

1. Clone the Repository

git clone https://github.com/yourusername/greenpulse.git
cd greenpulse

2. Install Arduino Libraries

Open Arduino IDE and install the following libraries via Library Manager (Sketch > Include Library > Manage Libraries):

• Adafruit SSD1306 (for OLED display)
• Adafruit BME280 (for environmental sensors)
• Arduino_JSON (for API communication)
• WiFi (included with ESP32 core)

Alternatively, install via command line:

arduino-cli lib install "Adafruit SSD1306"
arduino-cli lib install "Adafruit BME280 Library"
arduino-cli lib install "Arduino_JSON"

3. Configure ESP32 Board

1. Open Arduino IDE
2. Go to File > Preferences
3. Add this URL to "Additional Board Manager URLs":

   https://espressif.github.io/arduino-esp32/package_esp32_index.json
   

4. Go to Tools > Board > Board Manager
5. Search for "esp32" and install version 3.0.0 or later
6. Select Tools > Board > ESP32C6 Dev Module

4. Configure Network Settings

Open Firmware/Config.h and Firmware/Wifi.cpp to update your network credentials:

In Firmware/Config.h:

#define SSID1 "YourNetworkName"
#define PASSWORD1 "YourPassword"
#define SSID2 "BackupNetwork"      // Optional second network
#define PASSWORD2 "BackupPassword"
#define API_ENDPOINT "dubemguy.pythonanywhere.com"  // Your API endpoint
#define PORT 80

In Firmware/Wifi.cpp:

// Static IP Configuration (adjust for your network)
IPAddress localIP(192, 168, 70, 137);    // Choose available IP in your subnet
IPAddress gateway(192, 168, 70, 166);    // Your router's IP address
IPAddress subnet(255, 255, 255, 0);      // Standard subnet mask
IPAddress dns(8, 8, 8, 8);               // Google DNS for reliability

Network Features:

• Primary and backup SSID support for redundancy
• Static IP bypasses DHCP for faster connection
• WiFi power set to 8.5dBm (balanced range and efficiency)
• Auto-reconnect with retry logic (7 attempts, 2-second intervals)

5. Configure API Endpoint (Optional)

The API endpoint is already configured in Firmware/Config.h:

#define API_ENDPOINT "dubemguy.pythonanywhere.com"
#define PORT 80

To use your own backend:

• Replace with your PythonAnywhere URL or custom server
• Keep PORT as 80 for HTTP (or 443 for HTTPS with appropriate SSL configuration)
• The system automatically handles connection, data upload (PUT), and remote control (GET)

If you don't want cloud sync, the system works fully offline using only the OLED display for monitoring.

6. Upload to ESP32-C6

1. Connect ESP32-C6 to your computer via USB-C
2. Select the correct port: Tools > Port > [Your ESP32 Port]
3. Click the Upload button (→) in Arduino IDE
4. Wait for compilation and upload to complete

---

🔧 Hardware Assembly

Step-by-Step Build Guide

Phase 1: Prepare the Veroboard

1. Plan Your Layout

   • Sketch component positions on paper first
   • Place ESP32-C6 centrally for optimal wire routing
   • Position power components (batteries, charging module) at one end
   • Keep sensors near the edge for easy external mounting

2. Cut Veroboard to Size

   • Recommended: 9cm x 15cm
   • Use a hacksaw or scoring tool
   • Smooth edges with sandpaper

Phase 2: Mount Core Components

3. Install the ESP32-C6

   • Solder female headers to the veroboard (2 rows of 10 pins)
   • Test fit the ESP32-C6 module
   • Ensure USB-C port is accessible from enclosure edge

4. Mount Power System

   • Solder the Type-C charging module
   • Install the latching power switch
   • Prepare battery holder or mounting for 18650 cells
   • Connect batteries in parallel (positive to positive, negative to negative)

   ⚠️ IMPORTANT: Parallel connection extends runtime. Series connection (NOT recommended) would provide 7.4V and damage 5V components!

5. Install Motor Driver

   • Solder DRV8833 to veroboard
   • Leave space between driver and ESP32 for heat dissipation
   • Ensure output pins are accessible for pump wiring

Phase 3: Connect Sensors

6. Wire BME280 Sensors (I2C)

   Sensor 1 (Primary):

   BME280 Pin → ESP32-C6 Pin
   VCC        → 3.3V
   GND        → GND
   SDA        → GPIO 6
   SCL        → GPIO 7
   

   Sensor 2 (Redundant):

   BME280 Pin → ESP32-C6 Pin
   VCC        → 3.3V
   GND        → GND
   SDA        → GPIO 9
   SCL        → GPIO 8
   

7. Wire OLED Display (I2C)

   OLED Pin   → ESP32-C6 Pin
   VCC        → 3.3V
   GND        → GND
   SDA        → GPIO 6 (shared with BME280 Sensor 1)
   SCL        → GPIO 7 (shared with BME280 Sensor 1)
   

8. Connect Soil Moisture Sensors

   Sensor 1:
   VCC        → 3.3V
   GND        → GND
   AOUT       → GPIO 0
   
   Sensor 2:
   VCC        → 3.3V
   GND        → GND
   AOUT       → GPIO 1
   

Phase 4: Wire the Pump System

9. Connect DRV8833 Motor Driver

   DRV8833    → ESP32-C6
   VCC        → 5V (from battery system)
   GND        → GND
   AIN1       → GPIO 19
   AIN2       → GPIO 20
   STBY       → GPIO 18 (PWM control)
   
   Motor Outputs:
   AOUT1      → Water Pump (+)
   AOUT2      → Water Pump (-)
   

10. Attach Tubing

    • Connect 6/8mm silicone tubing to pump inlet
    • Route outlet tubing to plant location
    • Secure all connections with zip ties or clamps

Phase 5: Power Wiring

11. Wire Power Distribution

    Battery (+) → Power Switch → Charging Module (+) → Distribution Bus
    Battery (-) → Charging Module (-) → GND Bus
    
    From Distribution Bus:
    → ESP32-C6 VIN (5V)
    → DRV8833 VCC (5V)
    → Voltage divider → ESP32 ADC (for battery monitoring)
    
    All grounds connect to common GND bus
    

12. Add Decoupling Capacitors (Recommended)

    • 100µF electrolytic capacitor across 5V and GND near ESP32
    • 10µF ceramic capacitor across 3.3V and GND
    • Reduces noise and improves stability

Phase 6: Testing & Enclosure

13. Pre-Enclosure Testing

    • Connect USB-C and verify ESP32 powers on
    • Check OLED display shows boot screen
    • Verify WiFi connection in Serial Monitor
    • Test sensor readings appear on display
    • Manually trigger pump to confirm operation

14. Final Assembly

    • Mount completed board in enclosure
    • Drill holes for:
      • OLED display window
      • Power switch access
      • USB-C charging port
      • Sensor wire pass-throughs
      • Tubing exit
    • Use hot glue or mounting standoffs to secure board
    • Seal wire entry points with silicone (optional, for outdoor use)

15. External Connections

    • Route sensor wires through enclosure
    • Position BME280 sensors for ambient air monitoring
    • Insert soil moisture sensors into plant soil
    • Coil excess tubing neatly

Wiring Diagram

BreadBoard View

Schematic Diagram

---

📊 Software Architecture

Module Overview

greenpulse/
├── Firmware/
│   ├── Firmware.ino          # Main entry point, FreeRTOS task management
│   ├── Config.h              # Global configuration and constants
│   ├── Wifi.cpp              # Network stack (Static IP, WiFi Sleep, DNS)
│   ├── Networks.h            # Network configuration
│   ├── Sensors.h             # BME280 & moisture sensor fusion logic
│   ├── Actuator.cpp/.h       # Pump control with PWM and exponential tapering
│   ├── OledUI.cpp            # Display rendering and status blob indicators
│   ├── Display.h             # Display configuration
│   ├── Api.cpp               # Cloud synchronization (PythonAnywhere)
│   ├── Logger.cpp            # Logging utilities
│   ├── Utils.h               # Utility functions
│   ├── SoilMoistureSensor.cpp    # Soil moisture sensor interface
│   └── TempXHumiditySensor.cpp   # BME280 sensor interface
├── ApiService/               # Backend API code
├── Hardware/                 # Circuit diagrams and PCB layouts
├── Docs/                     # Documentation
└── README.md

Key Algorithms

1. Variable-Speed Pump Control

The pump control system uses PWM (Pulse Width Modulation) for precise water delivery:

Algorithm:

• Speed is specified as a percentage (0-100%)
• System converts percentage to PWM duty cycle (0-255)
• Direction control: Forward pumps water into soil, reverse drains to reservoir
• Standby pin enables/disables pump operation
• Speed can be adjusted in real-time to prevent over-watering

Benefits:

• Gentle watering prevents soil erosion
• Variable flow rates allow precise moisture control
• Reversible pump can drain excess water if needed
• PWM frequency (10kHz) ensures quiet, smooth operation

2. Optimized WiFi Connection Stack

Power-efficient networking through multiple optimization techniques:

Static IP Configuration:

• Pre-configured IP address (192.168.70.137)
• Gateway and subnet mask hardcoded
• DNS server set to Google DNS (8.8.8.8)
• Bypasses DHCP handshake, saving 2-3 seconds per connection

WiFi Power Management:

• Power level set to 8.5dBm (balanced range and efficiency)
• WiFi sleep mode enabled between data transmissions
• Auto-reconnect disabled (manual control for better error handling)
• Hostname set to "GreenPulse" for easy network identification

Connection Retry Logic:

• Maximum 7 retry attempts with 2-second intervals
• Automatic reconnection if WiFi drops
• System restart after repeated failures
• Status indicators update display during connection process

Result: Achieves sub-second network readiness after initial connection, significantly reducing power consumption during idle periods.

3. FreeRTOS Dual-Task Architecture

Separates display rendering from sensor/control operations for responsive performance:

Display Manager Task:

• Updates OLED screen with current readings
• Refreshes sensor values every 1 second
• Updates WiFi and API status blobs in real-time
• Handles screen transitions (Home ↔ WiFi status)
• Runs independently to prevent UI freezing

Logic Manager Task:

• Reads soil moisture from dual capacitive sensors (averaged)
• Polls BME280 sensors for temperature, humidity, pressure
• Makes watering decisions based on moisture thresholds
• Executes pump control with variable speed
• Manages API synchronization cycles

Screen Management:

• HOME screen: Displays soil moisture %, temperature, humidity, and status blobs
• WIFI screen: Shows connection status ("Wi-Fi connected" or "you are offline")
• Automatic timeout returns to HOME after 4 seconds

Efficient Rendering:

• Only updates changed values (partial screen refresh)
• Status blobs toggle between filled (white) and empty (black) circles
• Reduces flicker and improves battery life

4. Dual-Sensor Averaging Algorithm

Increases reliability through sensor redundancy:

Soil Moisture Processing:

• Two capacitive sensors (GPIO 0 and GPIO 1) provide independent readings
• System averages both sensors for final moisture value
• Individual sensor readings available for troubleshooting
• Raw ADC values (0-4095) converted to percentage (0-100%)

Temperature & Humidity Fusion:

• Two BME280 sensors on separate I2C buses (Wire and Wire1)
• Primary sensor (Wire, GPIO 6/7) handles main readings
• Secondary sensor (Wire1, GPIO 8/9) provides backup
• Initialization retry logic (up to 5 attempts per sensor)
• Graceful degradation if one sensor fails

Calculation Method:

• Soil moisture: (Sensor1 + Sensor2) / 2 then scale to percentage
• Temperature/Humidity: Individual sensor or averaged based on availability
• Pressure reading available but primarily for environmental logging

Error Handling:

• Returns NULL if sensor initialization fails
• Serial debug messages indicate which I2C bus has issues
• System continues operating with remaining functional sensors

5. Cloud API Synchronization Protocol

Efficient data transmission to PythonAnywhere backend:

Data Upload (PUT Request):

• Collects current sensor readings (temperature, humidity, pressure, soil moisture)
• Packages data into JSON format
• Sends HTTP PUT request to API endpoint (dubemguy.pythonanywhere.com:80)
• Includes proper headers: Content-Type, Content-Length, User-Agent
• 5-second timeout prevents indefinite blocking
• Returns success/failure status for display blob update

Remote Control (GET Request):

• Fetches pump control commands from API
• Parses JSON response for pump state
• 3-second timeout for faster failure detection
• Validates HTTP 200 status code before processing
• Extracts JSON from response body (handles extra whitespace)

Connection Management:

• Creates new NetworkClient for each request
• Properly closes connections after data transfer
• Cleans up memory by deleting client objects
• Only attempts sync when WiFi is connected
• Fails gracefully if network unavailable

Status Indication:

• Updates updateApiState flag based on success/failure
• Display shows white blob when last sync succeeded
• Black blob indicates sync failure or timeout
• Allows local operation even if API is unavailable

---

📱 User Interface

OLED Display Layout

┌─────────────────────────┐
│ SOIL: 45%               │
│                      ●  │
│ TEMP: 24.50 C           │
│                      ●  │    
│ HUMD: 62.00 %           │
└─────────────────────────┘

[Status Blobs] ← API (top), WiFi (bottom)

Status Blob Indicators

Top Blob (API Sync):

• ⚪ White (Filled): Last cloud sync successful (updateApiState = true)
• ⚫ Black (Empty): Sync failed, timeout, or not attempted
• Position: Right side, aligned with temperature line

Bottom Blob (WiFi):

• ⚪ White (Filled): WiFi connected (wifiIsConnected = true)
• ⚫ Black (Empty): WiFi disconnected
• Position: Right side, aligned with humidity line

These provide instant visual confirmation without reading text, perfect for quick system checks from a distance.

WiFi Status Screen

When WiFi state changes, the display automatically switches to show connection status:

Connected:

┌─────────────────────────┐
│                         │
│     Wi-Fi connected     │
│                         │
│         Online          │
│                         │
└─────────────────────────┘

Disconnected:

┌─────────────────────────┐
│                         │
│       Looks like        │
│                         │
│     you are offline     │
│                         │
└─────────────────────────┘

Display automatically returns to HOME screen after 4 seconds.

---

🔬 Calibration Guide

Initial Setup (Required)

Soil Moisture Calibration

Each sensor requires calibration for your specific soil type:

1. Dry Reading

   • Remove sensor from soil completely
   • Let air dry for 5 minutes
   • Note the reading from Serial Monitor: Dry Value: XXXX

2. Wet Reading

   • Submerge sensor tip in water (not fully, just the sensing area)
   • Wait 30 seconds for reading to stabilize
   • Note the reading: Wet Value: XXXX

3. Update Code

   In Firmware/SoilMoistureSensor.cpp, the SoilMoistureTranslator() function converts raw ADC values (0-4095) to percentage (0-100%). The current implementation uses a simple linear scaling:

   Percentage = (RawValue × 100) / 4095
   

   For more accurate readings with your specific soil type, you may want to modify this function to use your calibration values with proper mapping.

4. Verify

   • Insert sensor in dry soil: should read ~0-20%
   • Water thoroughly: should read ~80-100%
   • Adjust map values if readings seem incorrect

Pump Flow Rate Testing

1. Measure Flow

   • Place pump outlet in measuring cup
   • Run at 100% PWM for 60 seconds
   • Measure water volume (ml)

2. Calculate Duration

   Example: 500ml in 60 seconds = 8.3ml/second
   
   For 100ml watering:
   Duration = 100ml ÷ 8.3ml/s = 12 seconds
   

3. Update Code

   In Firmware/Config.h, update the pump flow rate constants based on your measurements. This ensures accurate watering duration calculations.

---

🌐 API Integration (Optional)

GreenPulse can synchronize data to a cloud API for remote monitoring and historical analysis.

Setting Up PythonAnywhere Backend

1. Create Account

   • Sign up at pythonanywhere.com
   • Free tier supports up to 100k API requests/day

2. Deploy FastAPI Application

   Create main.py:

   from fastapi import FastAPI
   from pydantic import BaseModel
   from datetime import datetime
   
   app = FastAPI()
   
   class SensorData(BaseModel):
       device_id: str
       timestamp: str
       moisture: float
       temperature: float
       humidity: float
       pressure: float
       pump_status: bool
   
   @app.post("/api/data")
   async def receive_data(data: SensorData):
       # Store in database or log file
       print(f"Received from {data.device_id}: {data.moisture}% moisture")
       return {"status": "success", "received_at": datetime.now().isoformat()}
   
   @app.get("/api/status/{device_id}")
   async def get_status(device_id: str):
       # Return latest data for device
       return {"device_id": device_id, "online": True}

3. Configure ESP32

   Update Firmware/Config.h:

   #define API_ENDPOINT "https://yourusername.pythonanywhere.com/api/data"
   #define DEVICE_ID "greenpulse-001"
   #define SYNC_INTERVAL 60000  // milliseconds (60 seconds)

Data Payload Structure

The ESP32 sends JSON data every minute:

{
    "soil_moisture": 45.2,
    "temperature": 24.5,
    "humidity": 62.3,
    "pressure": 1013.2,
    "pump": "on"
}

Local-Only Operation

If you prefer not to use cloud sync:

• Comment out updateAPI() calls in Firmware/Firmware.ino
• System operates fully offline
• All data visible on OLED display
• Serial Monitor shows detailed logs

---

🔋 Power Management

Battery Life Optimization

Expected Runtime:

• Normal operation: 7-14 days per charge
• With WiFi sleep enabled: Up to 3 weeks
• Deep sleep mode (optional): 1-2 months

Current Consumption:

Mode	Current Draw	Notes
Active (WiFi on)	~120mA	During API sync
Active (WiFi sleep)	~50mA	Normal sensing
Pump running (max)	~200mA	Brief periods
Deep sleep	~10µA	Not implemented by default

Charging

• Input: USB Type-C, 5V/1-2A
• Charging Time: 4-6 hours for dual 2500mAh cells
• LED Indicator: Red (charging), Green/Blue (complete)
• Protection: Built-in over-charge/discharge protection

Extending Battery Life

1. Reduce Sync Frequency

   #define SYNC_INTERVAL 300000  // 5 minutes instead of 1

2. Enable Deep Sleep (Advanced)

   For maximum battery life, implement deep sleep mode where the ESP32 wakes periodically to check sensors. Note: This disables WiFi and OLED between wake cycles.

3. Lower Display Brightness

   Enable the dim mode for the OLED display in Firmware/OledUI.cpp setup function.

---

🛠️ Troubleshooting

Common Issues & Solutions

Display Not Working

Symptom: OLED remains blank after power-on

Solutions:

1. Check I2C address

   Most SSD1306 displays use address 0x3C, but some use 0x3D. Check your display documentation or try the alternate address in Firmware/OledUI.cpp.

2. Run I2C scanner

   Upload the I2C scanner sketch (available in Arduino Examples > Wire > i2c_scanner) to detect the actual address of your display.

3. Verify wiring

   • SDA must connect to GPIO 6
   • SCL must connect to GPIO 7
   • VCC should be 3.3V (not 5V)
   • Check for cold solder joints

4. Check power

   • OLED requires stable 3.3V
   • Add 10µF capacitor across VCC/GND if flickering

---

Pump Not Activating

Symptom: Moisture drops but pump doesn't turn on

Solutions:

1. Verify DRV8833 connections

   Check:
   - VCC connected to 5V (not 3.3V)
   - GND connected
   - AIN1 → GPIO 19
   - AIN2 → GPIO 20
   - STBY → GPIO 18
   

2. Test pump separately

   Add test code to the setup() function to manually run the pump for 2 seconds and verify it's working independently of the moisture control logic.

3. Check motor driver

   • Measure voltage across motor outputs (should be ~5V when active)
   • If 0V, driver may be damaged
   • Ensure driver can handle pump current (typical: 200-500mA)

4. Verify PWM configuration

   Ensure the PWM peripheral is properly configured in the firmware setup. Check that GPIO 18 is correctly assigned to the LEDC channel.

---

Inconsistent Moisture Readings

Symptom: Moisture value jumps around or doesn't change

Solutions:

1. Re-calibrate sensor

   • Follow Calibration Guide
   • Ensure sensor fully inserted in soil (not just touching surface)

2. Clean sensor contacts

   • Power off system
   • Wipe sensor with isopropyl alcohol
   • Dry completely before reinserting

3. Check sensor power

   • Measure 3.3V between VCC and GND on sensor
   • Add 100µF capacitor across sensor power if unstable

4. Add averaging/smoothing

   If readings are still unstable, implement a moving average filter in the sensor reading code to smooth out fluctuations.

---

WiFi Connection Fails

Symptom: "WiFi Disconnected" or stuck connecting

Solutions:

1. Verify credentials

   Double-check your WiFi SSID and password in Firmware/Wifi.cpp. The SSID is case-sensitive!

2. Check network compatibility

   • ESP32-C6 only supports 2.4GHz WiFi
   • WPA2/WPA3 encryption required
   • Try disabling 5GHz on dual-band router temporarily

3. Move closer to router

   • During initial setup, place within 3 meters of router
   • Check signal strength in Serial Monitor

4. Disable Static IP temporarily

   In Firmware/Wifi.cpp, comment out the WiFi.config() line to use DHCP instead and see if that resolves the connection issue.

5. Check Serial Monitor

   Tools > Serial Monitor > 115200 baud
   Look for connection errors and IP address assignment
   

---

API Sync Failures

Symptom: API status blob stays black

Solutions:

1. Test endpoint manually

   curl -X POST https://yourusername.pythonanywhere.com/api/data \
   -H "Content-Type: application/json" \
   -d '{"device_id":"test","moisture":50}'

2. Check DNS resolution

   Try using Cloudflare DNS (1.1.1.1) instead of Google DNS (8.8.8.8) in the WiFi configuration.

3. Verify SSL certificate (if using HTTPS)

   • PythonAnywhere provides valid certificates
   • Ensure date/time set correctly on ESP32

4. Increase timeout

   Increase the HTTP client timeout value in Firmware/Api.cpp to allow more time for API responses.

5. Monitor Serial debug

   Add debug print statements in Firmware/Api.cpp to see the actual HTTP response and identify connection issues.

---

Battery Drains Quickly

Symptom: Less than 3 days runtime

Solutions:

1. Check for short circuits

   • Power off and measure resistance between V+ and GND
   • Should be >10kΩ
   • Look for solder bridges on board

2. Reduce sync frequency

   Change the SYNC_INTERVAL in Firmware/Config.h to sync every 5 minutes instead of every minute.

3. Enable WiFi sleep

   Verify that WiFi.setSleep(true) is called in Firmware/Wifi.cpp to enable power-saving mode.

4. Check pump isn't stuck on

   • Monitor pump status on OLED
   • Should only run when moisture < threshold

5. Measure current draw

   • Use multimeter in series with battery
   • Active (WiFi on): ~120mA
   • Idle (WiFi sleep): ~50mA
   • If higher, identify power-hungry component

---

Sensor Values Show "NaN" or "---"

Symptom: Display shows invalid sensor data

Solutions:

1. Check sensor power

   • BME280 requires stable 3.3V
   • Measure voltage at sensor VCC pin

2. Verify I2C connections

   • SDA and SCL must be connected
   • Check for reversed SDA/SCL

3. Scan I2C bus

   Use an I2C scanner sketch to verify the BME280 is detected at its expected address (0x76 or 0x77).

4. Check sensor initialization

   Add error checking in the sensor initialization code to halt and display an error if the BME280 fails to initialize.

---

Serial Monitor Debugging

Enable verbose logging for troubleshooting by setting debug flags in Firmware/Config.h. This will output detailed sensor readings, network status, and pump activity to the Serial Monitor at 115200 baud.

---

🌍 Environmental Impact & Efficiency

Water Conservation

The Problem: Traditional binary irrigation (ON/OFF) systems waste significant water due to "saturation lag" - the time delay between water application and sensor detection. By the time moisture sensors read "wet," excess water has already been applied, leading to:

• Root rot from over-watering
• Nutrient leaching into groundwater
• 30-50% water waste in typical systems

GreenPulse's Solution: The exponential tapering algorithm reduces flow rate as moisture approaches the target, giving soil time to absorb water gradually. This prevents overshoot and reduces water waste by an estimated 40%.

Real-World Impact:

Typical Plant Water Usage:
- Traditional system: 150ml per watering (50ml wasted)
- GreenPulse system: 100ml per watering (5ml wasted)

Annual savings per plant:
- Waterings per year: 120
- Water saved: 5,400ml (5.4 liters)
- For 10 plants: 54 liters saved annually

Energy Optimization

Network Efficiency: IoT devices spend most power in "Radio On" time during network operations. GreenPulse optimizes this through:

1. Static IP Configuration

   • Bypasses DHCP negotiation
   • Saves ~2-3 seconds per connection
   • Reduces energy per sync by 40%

2. Hardcoded DNS

   • Eliminates DNS lookup time
   • Consistent endpoint resolution
   • Additional 0.5-1 second savings

3. WiFi Sleep Mode

   • Radio enters low-power state between syncs
   • Reduces idle current from ~120mA to ~50mA
   • 58% power reduction during idle periods

Battery Life Comparison:

Standard ESP32 IoT device:
- Average current: 100mA
- 5000mAh battery: 50 hours (2 days)

GreenPulse optimized:
- Average current: 35mA
- 5000mAh battery: 142 hours (6 days)
- With reduced sync: up to 14 days

Sustainability Features

• Rechargeable Power: No disposable batteries
• Long Component Life: Capacitive sensors don't corrode
• Modular Design: Easy repair and component replacement
• Open Source: Prevents e-waste through community repair support
• Local Control: Functions without constant cloud dependency

---

📚 Documentation

Additional Resources

• Hardware Schematics: Detailed circuit diagrams
• Calibration Guide: Sensor calibration procedures
• API Documentation: Backend integration guide
• 3D Printable Enclosure: STL files for custom housing
• Troubleshooting Wiki: Community solutions

---

🔮 Future Enhancements

Planned Features

• Mobile App (iOS/Android)

  • Real-time monitoring
  • Push notifications for low battery/watering events
  • Remote threshold adjustments

• Machine Learning Optimization

  • Learn optimal watering schedules per plant
  • Predict moisture trends
  • Adapt to seasonal changes

• Multi-Plant Support

  • Support 4-8 plants with individual sensors
  • Separate pump control per plant
  • Centralized dashboard

• Weather API Integration

  • Adjust watering based on forecast
  • Reduce watering before expected rain
  • Temperature-based scheduling

• Solar Charging

  • 6V/2W solar panel option
  • Outdoor deployment capability
  • Infinite runtime in sunny climates

• Advanced Sensors

  • Nutrient level monitoring (NPK sensors)
  • Soil pH measurement
  • Light intensity tracking

• Voice Assistant Integration

  • Alexa/Google Home support
  • Voice queries: "How's my plant doing?"
  • Voice control: "Water my plant now"

Community Requested Features

Vote on features in our GitHub Discussions!

---

🤝 Contributing

We welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or sharing your builds, your help is appreciated.

How to Contribute

1. Fork the Repository

   git clone https://github.com/yourusername/greenpulse.git
   cd greenpulse
   git checkout -b feature/amazing-feature

2. Make Your Changes

   • Follow existing code style
   • Comment complex algorithms
   • Test thoroughly on hardware

3. Commit Your Changes

   git add .
   git commit -m "Add amazing feature: detailed description"

4. Push and Create Pull Request

   git push origin feature/amazing-feature

   Then open a Pull Request on GitHub with:

   • Clear description of changes
   • Before/after photos for hardware mods
   • Test results and performance data

Contribution Ideas

• Code: Bug fixes, optimizations, new features
• Hardware: Alternative sensor/pump recommendations, PCB designs
• Documentation: Tutorials, translations, troubleshooting guides
• Testing: Try on different plant types, report results
• Design: 3D printable enclosures, mounting brackets

Code Style Guidelines

• Use descriptive variable names: currentMoisture not cm
• Comment non-obvious code blocks
• Keep functions under 50 lines when possible
• Follow Arduino style guide for C++

Reporting Issues

Found a bug? Open an issue with:

• GreenPulse version
• ESP32 board version
• Steps to reproduce
• Expected vs actual behavior
• Serial Monitor output
• Photos of setup (if hardware-related)

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

TL;DR: You can freely use, modify, and distribute this project, even commercially, as long as you include the original license and copyright notice.

---

👥 Authors & Acknowledgments

Author

Onyilimba Dubemchukwu

• Firmware & Hardware Engineering
• Email: onyilimbadubem@gmail.com
• GitHub: @Dubemchukwu

Acknowledgments

• Adafruit: For excellent sensor libraries and documentation
• ESP32 Community: Development support and forum assistance
• Open Source Contributors: Everyone who has shared IoT knowledge
• Beta Testers: Early adopters who provided valuable feedback

Special Thanks

• Espressif for the amazing ESP32-C6 platform
• PythonAnywhere for free hosting tier
• Arduino team for accessible development tools

---

📞 Support & Community

Get Help

• GitHub Issues: Report bugs or request features
• Discussions: Ask questions and share projects
• Email: onyilimbadubem@gmail.com
• Discord: Join our community server (coming soon)

Stay Updated

• ⭐ Star this repo to follow updates
• 👁️ Watch for release notifications
• 🍴 Fork to create your own variant

Show Your Build!

Built a GreenPulse? We'd love to see it!

• Tag us on Twitter: @GreenPulseIoT
• Use hashtag: #GreenPulseBuild
• Submit to our Community Gallery

---

📊 Project Stats

---

🌱 Happy Growing with GreenPulse! 🌱

Built with ❤️ for sustainable IoT solutions

⬆ Back to Top

---

If you find this project helpful, please consider giving it a ⭐ star!