306 lines
8.5 KiB
Markdown
306 lines
8.5 KiB
Markdown
# 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 |