# ESP32-S3 Plant Watering System - Project Plan v2.0
*Updated: January 2025*

## Project Overview
**Goal**: Automated plant watering system with remote monitoring/control  
**Hardware**: ESP32-S3-MINI-1, TB6612FNG motor driver, 2 pumps, 2 soil moisture sensors  
**Software**: ESP-IDF v6, MQTT communication, OTA updates  
**Infrastructure**: Docker-based Mosquitto MQTT broker, local network deployment

## Project Status Summary
- **Phase 1**: Core Infrastructure ✅ COMPLETED
- **Phase 2**: Hardware Integration 🚧 IN PROGRESS (Motor Control next)
- **Phase 3**: Automation Logic 📋 TODO
- **Phase 4**: Enhanced Features 📋 TODO
- **Phase 5**: Production Polish 📋 TODO

---

## Phase 1: Core Infrastructure ✅ COMPLETED

### 1.1 Development Environment ✅
- ESP-IDF v6 in Docker container
- Build system configured
- Project structure created

### 1.2 WiFi Manager ✅
- Auto-connect to configured network
- Credential storage in NVS
- Auto-reconnection on disconnect
- Event callbacks for state changes

### 1.3 OTA Server ✅
- HTTP server on port 80
- Web interface for firmware upload
- Progress tracking
- Version management
- Rollback capability

### 1.4 MQTT Client ✅
- Connection with authentication
- Auto-reconnect with exponential backoff
- Last Will and Testament
- NVS credential storage
- Basic publish/subscribe implementation
- Current topics:
  - `plant_watering/status`
  - `plant_watering/moisture/[1-2]`
  - `plant_watering/pump/[1-2]/set`
  - `plant_watering/pump/[1-2]/state`

---

## Phase 2: Hardware Integration 🚧 IN PROGRESS

### 2.1 Motor Control Module 🚧 NEXT
**File**: `motor_control.c/h`
- [ ] TB6612FNG driver initialization
- [ ] PWM control for pump speed
- [ ] Direction control (though pumps are unidirectional)
- [ ] Safety features:
  - [ ] Maximum runtime limit (30 seconds default)
  - [ ] Minimum interval between runs (5 minutes)
  - [ ] Overcurrent detection (if possible)
- [ ] Manual override commands via MQTT
- [ ] State tracking and reporting

### 2.2 Moisture Sensor Module 📋 TODO
**File**: `moisture_sensor.c/h`
- [ ] ADC configuration for 2 sensors
- [ ] Calibration system:
  - [ ] Dry value calibration
  - [ ] Wet value calibration
  - [ ] Store calibration in NVS
- [ ] Reading stabilization:
  - [ ] Multiple sample averaging
  - [ ] Outlier filtering
  - [ ] Trend detection
- [ ] Percentage conversion
- [ ] Sensor fault detection

### 2.3 Hardware Integration Testing 📋 TODO
- [ ] Verify pump operation at different PWM levels
- [ ] Test moisture sensor accuracy
- [ ] Validate power consumption
- [ ] Long-term reliability testing (24-hour test)

---

## Phase 3: Automation Logic 📋 TODO

### 3.1 Basic Automation 📋 TODO
**File**: `automation.c/h`
- [ ] Threshold-based watering:
  - [ ] Start when moisture < 30%
  - [ ] Stop when moisture > 70%
- [ ] Safety checks:
  - [ ] Maximum daily watering limit
  - [ ] Minimum interval enforcement
  - [ ] Pump runtime limits
- [ ] Zone independence (2 separate zones)

### 3.2 Advanced Scheduling 📋 TODO
- [ ] Time-based watering schedules
- [ ] Dawn/dusk watering preferences
- [ ] Weekly patterns
- [ ] Seasonal adjustments

### 3.3 Data Logging 📋 TODO
- [ ] Log watering events
- [ ] Track moisture trends
- [ ] Record pump runtime statistics
- [ ] Store in NVS with rotation

---

## Phase 4: Enhanced MQTT & Monitoring 📋 TODO

### 4.1 Expanded MQTT Topics 📋 TODO
Implement the comprehensive topic structure:
```
plant_watering/
├── status/esp32/*
├── pump/[1-2]/*
├── sensor/[1-2]/*
├── settings/*
├── alerts/*
└── commands/*
```

### 4.2 JSON Payloads 📋 TODO
- [ ] Structured data for complex messages
- [ ] Batch updates for efficiency
- [ ] Schema versioning

### 4.3 Alert System 📋 TODO
- [ ] Low moisture alerts
- [ ] Pump malfunction detection
- [ ] Sensor fault alerts
- [ ] Water tank low (future)

### 4.4 Remote Configuration 📋 TODO
- [ ] MQTT-based settings updates
- [ ] Validation and bounds checking
- [ ] Persistent storage in NVS
- [ ] Configuration backup/restore

---

## Phase 5: Production Features 📋 TODO

### 5.1 Web Dashboard 📋 TODO
- [ ] Real-time status display
- [ ] Historical graphs
- [ ] Manual control interface
- [ ] Configuration portal
- [ ] Mobile-responsive design

### 5.2 Home Assistant Integration 📋 TODO
- [ ] MQTT Discovery implementation
- [ ] Device registry
- [ ] Entity configuration
- [ ] Automation examples

### 5.3 Advanced Features 📋 TODO
- [ ] Multi-zone support (>2 zones)
- [ ] Flow sensor integration
- [ ] Weather API integration
- [ ] Predictive watering
- [ ] Water usage tracking

### 5.4 Production Hardening 📋 TODO
- [ ] Watchdog timer implementation
- [ ] Brown-out detection
- [ ] Error recovery procedures
- [ ] Factory reset mechanism
- [ ] Diagnostic mode

---

## Hardware Connections (Reference)

### ESP32-S3 to TB6612FNG
```
ESP32-S3    TB6612FNG
GPIO4    -> AIN1 (Pump 1 Direction)
GPIO5    -> AIN2 (Pump 1 Direction)
GPIO6    -> BIN1 (Pump 2 Direction)
GPIO7    -> BIN2 (Pump 2 Direction)
GPIO8    -> PWMA (Pump 1 Speed)
GPIO9    -> PWMB (Pump 2 Speed)
GPIO10   -> STBY (Standby)
GND      -> GND
3.3V     -> VCC
```

### Moisture Sensors
```
Sensor 1 -> GPIO1 (ADC1_CHANNEL_0)
Sensor 2 -> GPIO2 (ADC1_CHANNEL_1)
```

---

## Development Guidelines

### Commit Strategy
- Complete one module at a time
- Test thoroughly before moving to next module
- Tag releases for each completed phase

### Testing Protocol
1. Unit test each module independently
2. Integration test with MQTT broker
3. Hardware-in-the-loop testing
4. 24-hour reliability test
5. Edge case validation

### Documentation Requirements
- Update README with each feature
- Document MQTT topics as implemented
- Include calibration procedures
- Add troubleshooting guides

---

## Current Sprint Focus
**Sprint Goal**: Complete Phase 2 Hardware Integration
1. Implement motor_control.c ← **CURRENT**
2. Test with actual pumps
3. Implement moisture_sensor.c
4. Calibrate sensors
5. Integration testing

**Definition of Done**:
- Code compiles without warnings
- Hardware responds to MQTT commands
- Sensor readings are accurate and stable
- No memory leaks (monitor heap)
- Documentation updated

---

## Risk Mitigation

### Technical Risks
- **Power supply issues**: Add capacitors, monitor voltage
- **Sensor corrosion**: Use capacitive sensors, implement sleep modes
- **Network reliability**: Implement offline mode with local rules
- **Flash wear**: Minimize NVS writes, implement wear leveling

### Mitigation Strategies
- Implement watchdog timers
- Add redundant sensors
- Local automation fallback
- Comprehensive error logging

---

## Success Metrics
- ✅ Reliable WiFi/MQTT connectivity
- ⏳ Accurate moisture readings (±5%)
- ⏳ Precise watering control
- ⏳ 30-day uptime without intervention
- ⏳ < 100mA average power consumption
- ⏳ OTA updates without service interruption
- ⏳ Response time < 1 second for commands

---

## Next Actions
1. **Create motor_control.c/h** with TB6612FNG driver
2. **Wire up hardware** on breadboard
3. **Test pump control** via MQTT commands
4. **Implement safety features** (timeouts, limits)
5. **Document findings** and update plan