Professional-grade grow room automation for Home Assistant. Control climate, lighting, irrigation, and hydroponics with VPD-based intelligence, AI optimization, and comprehensive analytics.
📖 Full Documentation | ⚙️ Quick Start Guide | 🐛 Troubleshooting
OpenGrowBox features a modular, production-ready architecture with clean separation of concerns:
- 🌡️ Core System: VPD controllers, climate management, and system orchestration
- 🔌 Device Layer: Universal device support via Home Assistant integration
- 🤖 Premium Features: AI optimization, advanced analytics, and research tools
- 💧 Hydroponics: Complete nutrient delivery and irrigation automation
- 🧪 Quality Assurance: Comprehensive testing with 100% smoke test success rate
- 🚀 Quick Start
- ✨ Key Features
- 🔧 Installation
- ⚙️ Configuration
- 📊 Supported Hardware
- 🔍 Recent Updates
- 📚 Documentation
- 🐛 Troubleshooting
- 🤝 Contributing
- 📄 License
- ✅ Home Assistant 2024.x+ running
- ✅ Python 3.9+ (included with HA)
- ✅ MQTT Broker (optional, for MQTT devices)
-
Install via HACS (recommended):
# In HA: Settings → Devices & Services → Add Integration # Search for "OpenGrowBox" and install
-
Basic Configuration:
# configuration.yaml opengrowbox: mainControl: "HomeAssistant"
-
Add Your First Room:
- Go to OGB Integration in HA
- Create a "Grow Room" area
- Add sensors and devices
- Set targets: 25°C, 60% RH, VPD 1.2
-
Done! Your grow room is now automated.
- VPD Automation: Maintain optimal Vapor Pressure Deficit automatically
- PID Controllers: Precision temperature, humidity, and CO₂ control
- Multi-Zone Support: Different settings per room/area
- Weather Integration: External weather compensation
- Any HA Device: Lights, sensors, switches, climate devices
- FridgeGrow Integration: Native Plantalytix controller support
- Modbus Devices: Industrial sensors and controllers
- ESPHome Devices: Custom firmware for unlimited possibilities
- AI Optimization: Machine learning for optimal grow conditions
- Yield Prediction: Harvest weight forecasting
- Anomaly Detection: Early problem identification
- Research Tools: A/B testing and experimental protocols
- Nutrient Automation: pH/EC monitoring and adjustment
- Irrigation Control: Timed and sensor-based watering
- Crop Steering: Dynamic nutrient profiles by growth stage
- Reservoir Management: Level monitoring and alerts
- Real-time Dashboards: Comprehensive grow metrics
- Historical Analytics: Long-term trend analysis
- Compliance Reporting: Regulatory documentation
- Alert System: Customizable notifications
- Temperature/Humidity: DHT11/22, SHT30, BME280, industrial sensors
- CO₂ Sensors: MH-Z19, SenseAir S8, industrial CO₂ monitors
- Soil Sensors: Capacitive moisture, pH/EC probes, temperature
- Light Sensors: PAR meters, lux sensors, spectrum analyzers
- Climate Control: Heaters, coolers, humidifiers, dehumidifiers
- Lighting: LED grow lights, dimmable ballasts, spectrum controllers
- Ventilation: Exhaust/intake fans, speed controllers, dampers
- Irrigation: Pumps, solenoids, peristaltic dosing pumps
- FridgeGrow: Plantalytix FridgeGrow 2.0, AIR, LIGHT, Smart Socket
- ESPHome: Custom firmware for ESP32/RPi
- Zigbee/Z-Wave: Wireless mesh networks
- WiFi: Shelly, Sonoff, Tuya devices
- MQTT: FridgeGrow, custom controllers
- Modbus: Industrial equipment
- Ethernet: BACnet, custom protocols
- Install HACS in Home Assistant
- Add Repository: Search for "OpenGrowBox"
- Install latest version
- Restart Home Assistant
# Download and install
cd /config
git clone https://github.com/OpenGrow-Box/OpenGrowBox-HA.git
cp -r OpenGrowBox-HA/custom_components/opengrowbox /config/custom_components/
# Restart HA
ha core restart# docker-compose.yml
version: '3'
services:
homeassistant:
image: homeassistant/home-assistant:latest
volumes:
- ./config:/config
- ./custom_components/opengrowbox:/config/custom_components/opengrowbox# configuration.yaml
opengrowbox:
mainControl: "HomeAssistant" # Required
updateInterval: 30 # Update frequency (seconds)# Define grow rooms
opengrowbox:
rooms:
main_tent:
area_id: "grow_room"
mode: "vegetative"
vpd_target: 1.2
temperature_target: 25.0
humidity_target: 60.0
co2_target: 800# Device mapping with labels
opengrowbox:
devices:
temperature_sensor:
entity_id: "sensor.grow_room_temperature"
capabilities: ["canMeasureTemp"]
heater:
entity_id: "switch.heater"
capabilities: ["canHeat"]
# FridgeGrow device (automatic recognition)
fridgegrow_heater:
entity_id: "number.fridgegrow_abc123_heater"
labels: ["fridgegrow", "heater"]
# OGB detects this automatically!- Native Support: Plantalytix FridgeGrow 2.0 controllers
- Auto-Discovery: Label-based device recognition
- MQTT Control: Direct device communication
- Range Scaling: Automatic 0-1 ↔ 0-100% conversion
- 32 Managers: Clean separation of concerns
- 100% Compatibility: All original features preserved
- Production Ready: Comprehensive testing and error handling
- Premium Features: AI, analytics, and research tools
- Quick Start Guide - 5-minute setup
- User Manual - Complete usage guide
- Configuration Guide - Advanced setup
- API Reference - Developer docs
- Supported Hardware - Compatible devices
- FridgeGrow Integration - Plantalytix support
- Modbus Integration - Industrial devices
- VPD Control - Climate automation
- Hydroponics - Nutrient management
- Crop Steering - Growth optimization
- AI & Analytics - Advanced capabilities
- Research Tools - Scientific features
- Deployment Guide - Production setup
- Troubleshooting - Problem solving
- Performance - Optimization
- Architecture - System design
- Testing - Quality assurance
- Debugging - Development tools
# Check HA logs
grep -i opengrowbox /config/home-assistant.logSolutions:
- Restart HA completely
- Check file permissions
- Verify Python dependencies
Causes:
- Devices not in HA areas
- Incorrect entity labels
- Missing device capabilities
Fix:
- Assign devices to HA areas
- Add proper labels (e.g.,
heater,sensor) - Check device configuration
Symptoms:
- "NO Sensors Found to calc VPD"
- Incorrect VPD values
Fix:
- Ensure temperature + humidity sensors are configured
- Check sensor calibration
- Verify sensor placement
We welcome contributions! Here's how to get started:
# Clone repository
git clone https://github.com/OpenGrow-Box/OpenGrowBox-HA.git
cd OpenGrowBox-HA
# Install development dependencies
pip install -r requirements-dev.txt
# Run tests
python3 smoke_test_modular.py- Linting:
flake8 custom_components/opengrowbox/ - Type Checking:
mypy custom_components/opengrowbox/ - Testing: 100% smoke test pass rate required
- Documentation: Update docs for new features
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests and documentation
- Submit PR with description
This project is licensed under the OGBCL (OpenGrowBox Community License).
Core functionality is free and open source. Premium features (AI, advanced analytics, research tools) require a commercial subscription and are subject to separate licensing terms.
- ✅ Free: Climate control, device management, hydroponics
- 🔒 Premium: AI optimization, compliance reporting, multi-site management
- 📧 Email: support@opengrowbox.com
- 💬 Discord: Join our community
- 🐛 Issues: GitHub Issues
- 📖 Wiki: Community Wiki
- 📧 Newsletter: Stay updated
Built with ❤️ for the growing community. Happy growing! 🌱