# 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, NTP time sync, Scheduling  
**Infrastructure**: Docker-based Mosquitto MQTT broker, local network deployment

## Project Status Summary
- **Phase 1**: Core Infrastructure ✅ COMPLETED
- **Phase 2**: Hardware Integration 🚧 75% COMPLETE (Motors done, Sensors pending)
- **Phase 3**: Automation Logic ✅ COMPLETED (via Scheduler)
- **Phase 4**: Enhanced Features 🚧 50% COMPLETE
- **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
- Comprehensive publish/subscribe implementation
- Topics implemented:
  - `plant_watering/status`
  - `plant_watering/moisture/[1-2]`
  - `plant_watering/pump/[1-2]/set`
  - `plant_watering/pump/[1-2]/state`
  - `plant_watering/pump/[1-2]/speed`
  - `plant_watering/schedule/*`
  - `plant_watering/system/*`
  - `plant_watering/commands/*`

---

## Phase 2: Hardware Integration 🚧 75% COMPLETE

### 2.1 Motor Control Module ✅ COMPLETED
**Files**: `motor_control.c/h`
- TB6612FNG driver implementation ✅
- PWM control for pump speed ✅
- Direction control ✅
- Safety features:
  - Maximum runtime limit ✅
  - Minimum interval between runs ✅
  - Soft start (500ms ramp) ✅
  - Emergency stop ✅
- Manual override via MQTT ✅
- State tracking and reporting ✅
- Runtime statistics with NVS persistence ✅
- Tested and working with hardware ✅

### 2.2 Moisture Sensor Module ⏸️ ON HOLD
**File**: `moisture_sensor.c/h`
- [ ] ADC configuration for 2 sensors
- [ ] Calibration system
- [ ] Reading stabilization
- [ ] Percentage conversion
- [ ] Sensor fault detection
**Note**: Awaiting hardware delivery

### 2.3 Hardware Integration Testing 🚧 PARTIAL
- [x] Pump operation verified
- [x] PWM speed control tested
- [x] Safety features validated
- [ ] Moisture sensor integration (pending hardware)
- [ ] Full system integration test

---

## Phase 3: Automation Logic ✅ COMPLETED (via Scheduler)

### 3.1 Time-Based Scheduling ✅ COMPLETED
**Files**: `scheduler.c/h`
- Multiple schedule types:
  - Interval-based (every X minutes) ✅
  - Time of day (daily at specific time) ✅
  - Day-specific (specific days at time) ✅
- Per-pump scheduling (4 schedules each) ✅
- NVS persistence ✅
- MQTT configuration ✅
- Holiday mode ✅
- Manual trigger for testing ✅

### 3.2 Time Synchronization ✅ COMPLETED
- NTP client implementation ✅
- Multiple NTP servers ✅
- Manual time setting fallback ✅
- Timezone support (MST default) ✅
- Time status reporting ✅

### 3.3 Schedule Management ✅ COMPLETED
- Create/update schedules via MQTT ✅
- View all schedules on demand ✅
- Enable/disable without deletion ✅
- Execution notifications ✅
- Error reporting ✅

### 3.4 Moisture-Based Automation ⏸️ PENDING
- Awaiting sensor hardware
- Will integrate with scheduler when available

---

## Phase 4: Enhanced MQTT & Monitoring 🚧 50% COMPLETE

### 4.1 Expanded MQTT Topics ✅ COMPLETED
Comprehensive topic structure implemented:
```
plant_watering/
├── status/esp32/*
├── pump/[1-2]/*
├── schedule/*
├── system/*
├── settings/*
├── alerts/*
└── commands/*
```

### 4.2 JSON Payloads ✅ COMPLETED
- Structured data for schedules ✅
- Status messages ✅
- Configuration updates ✅
- Built-in JSON parsing (no external deps) ✅

### 4.3 Alert System 🚧 PARTIAL
- [x] Pump malfunction alerts
- [x] Schedule execution errors
- [ ] Low moisture alerts (pending sensors)
- [ ] Water tank monitoring (future)

### 4.4 Remote Configuration ✅ COMPLETED
- MQTT-based settings updates ✅
- Validation and bounds checking ✅
- Persistent storage in NVS ✅
- Runtime parameter changes ✅

---

## Phase 5: Production Features 📋 TODO

### 5.1 Web Dashboard 📋 TODO
- [ ] Real-time status display
- [ ] Historical graphs
- [ ] Manual control interface
- [ ] Schedule configuration UI
- [ ] 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 🚧 PARTIAL
- [x] Watchdog timer (system level)
- [ ] Enhanced error recovery
- [ ] Factory reset mechanism
- [ ] Diagnostic mode
- [x] Memory monitoring

---

## Current Capabilities

### Working Features
1. **Remote Control**: Full MQTT control of pumps
2. **Scheduling**: Time-based watering with multiple schedule types
3. **Safety**: Runtime limits, cooldown periods, emergency stop
4. **Monitoring**: Real-time status, statistics, time sync status
5. **OTA Updates**: Web-based firmware updates
6. **Persistence**: Settings and schedules survive reboots
7. **Time Management**: NTP sync with manual fallback

### Tested and Verified
- Motor control with PWM speed adjustment
- Schedule execution (time_of_day and days_time modes)
- MQTT command processing
- Safety features (max runtime, min interval)
- OTA firmware updates
- NVS persistence
- Time synchronization

---

## Hardware Connections (Reference)

### ESP32-S3 to TB6612FNG ✅ VERIFIED
```
ESP32-S3    TB6612FNG    Status
GPIO4    -> AIN1         ✅ Working
GPIO5    -> AIN2         ✅ Working
GPIO6    -> BIN1         ✅ Working
GPIO7    -> BIN2         ✅ Working
GPIO8    -> PWMA         ✅ Working
GPIO9    -> PWMB         ✅ Working
GPIO10   -> STBY         ✅ Working
GND      -> GND          ✅ Connected
3.3V     -> VCC          ✅ Connected
```

### Moisture Sensors ⏸️ PENDING
```
Sensor 1 -> GPIO1 (ADC1_CHANNEL_0) - Awaiting hardware
Sensor 2 -> GPIO2 (ADC1_CHANNEL_1) - Awaiting hardware
```

---

## Next Steps

### Immediate (This Week)
1. ✅ ~~Test interval scheduling mode~~
2. ⏸️ Install moisture sensors when they arrive
3. ✅ ~~Document all MQTT topics comprehensively~~
4. ⏸️ Create basic web dashboard mockup

### Short Term (Next Month)
1. Implement moisture sensor module
2. Integrate moisture readings with scheduler
3. Add moisture-based automation rules
4. Implement Home Assistant discovery

### Long Term
1. Multi-zone expansion (>2 pumps)
2. Weather API integration
3. Water usage analytics
4. Mobile app development

---

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

---

## Known Issues
1. None currently - system stable

## Risk Mitigation
- ✅ Implemented watchdog timers
- ✅ Added redundant safety checks
- ✅ Local schedule storage (survives network loss)
- ✅ Comprehensive error logging
- ⏸️ Sensor corrosion prevention (pending hardware)

---

## Version History
- **v2.2.0-scheduler**: Full scheduling system with NTP
- **v2.1.0-motor**: Motor control implementation
- **v2.0.0-mqtt**: MQTT integration
- **v1.0.1**: OTA-enabled base
- **v1.0.0**: Initial template

---

## Documentation Status
- ✅ README.md - Comprehensive project overview
- ✅ MOTOR_CONTROL_README.md - Motor control details
- ✅ SCHEDULER_README.md - Scheduling system guide
- ⏸️ MQTT_TOPICS.md - To be created
- ⏸️ API_REFERENCE.md - To be created

---

## Notes
- Scheduler tested with days_time mode - working correctly
- Time sync typically completes within 30 seconds of boot
- System handles DST transitions automatically
- All safety features have been validated with hardware