Added project plan

2025-07-20 12:04:32 -06:00
parent ba43d22a1a
commit 9ca88df1cb
1 changed files with 275 additions and 0 deletions
--- a/project_plan_v2.md
+++ 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