From 9ca88df1cbecd96ea477ec06bfeef7ee49079f52 Mon Sep 17 00:00:00 2001 From: Stephen Minakian Date: Sun, 20 Jul 2025 12:04:32 -0600 Subject: [PATCH] Added project plan --- project_plan_v2.md | 275 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 275 insertions(+) create mode 100644 project_plan_v2.md diff --git a/project_plan_v2.md b/project_plan_v2.md new file mode 100644 index 0000000..5eb9ab0 --- /dev/null +++ b/project_plan_v2.md @@ -0,0 +1,275 @@ +# 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 \ No newline at end of file