🌱 OpenGrowBox - Advanced Home Assistant Grow Control

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

🏗️ Architecture Overview

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

---

📋 Table of Contents

• 🚀 Quick Start
• ✨ Key Features
• 🔧 Installation
• ⚙️ Configuration
• 📊 Supported Hardware
• 🔍 Recent Updates
• 📚 Documentation
• 🐛 Troubleshooting
• 🤝 Contributing
• 📄 License

---

🚀 Quick Start

Prerequisites

• ✅ Home Assistant 2024.x+ running
• ✅ Python 3.9+ (included with HA)
• ✅ MQTT Broker (optional, for MQTT devices)

5-Minute Setup

1. Install via HACS (recommended):

   # In HA: Settings → Devices & Services → Add Integration
   # Search for "OpenGrowBox" and install

2. Basic Configuration:

   # configuration.yaml
   opengrowbox:
     mainControl: "HomeAssistant"

3. 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

4. Done! Your grow room is now automated.

Detailed Setup →

---

✨ Key Features

🌡️ Climate Intelligence

• 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

🔌 Universal Device Support

• 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 & Analytics (Premium)

• 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

💧 Complete Hydroponics

• 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

📊 Professional Monitoring

• Real-time Dashboards: Comprehensive grow metrics
• Historical Analytics: Long-term trend analysis
• Compliance Reporting: Regulatory documentation
• Alert System: Customizable notifications

Full Feature List →

---

📊 Supported Hardware

🌡️ Sensors

• 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

🔌 Actuators & Controllers

• 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

🔧 Integration Methods

• 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

Hardware Compatibility →

---

🔧 Installation

Method 1: HACS (Recommended)

1. Install HACS in Home Assistant
2. Add Repository: Search for "OpenGrowBox"
3. Install latest version
4. Restart Home Assistant

Method 2: Manual Installation

# 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

Method 3: Docker

# docker-compose.yml
version: '3'
services:
  homeassistant:
    image: homeassistant/home-assistant:latest
    volumes:
      - ./config:/config
      - ./custom_components/opengrowbox:/config/custom_components/opengrowbox

Detailed Installation →

---

⚙️ Configuration

Basic Setup

OpenGrowBox requires logger diagnostics and Home Assistant history support in configuration.yaml. This does not require default_config:; if default_config: is already present, it satisfies the history requirement. For custom icons on Home Assistant's default dashboard, also register the frontend icon module shown below. You can manage the YAML manually, or enable Update configuration.yaml automatically during setup or from the integration's Configure screen. When enabled, OpenGrowBox adds only missing OpenGrowBox YAML entries and creates a .ogb_config_bak backup before writing. The setup and Configure screens block on missing logger/history YAML, but not on the icon module. After setup, the same setting is also available as the OGB Auto Configure HA switch entity for each OpenGrowBox room. If required YAML is missing, OpenGrowBox creates a persistent notification in Home Assistant.

# configuration.yaml
history:

# Needed for custom icons on Home Assistant's default dashboard.
frontend:
  extra_module_url:
    - /local/opengrowbox/ogb_icons.js

logger:
  default: info
  logs:
    homeassistant.config_entries: debug
    homeassistant.setup: debug
    homeassistant.loader: debug
    custom_components.opengrowbox: debug
    custom_components.ogb-dev-env: debug

Room Configuration

# 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 Setup

# 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!

Advanced Configuration →

---

🔍 Recent Updates

✅ FridgeGrow Integration (Latest)

• 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

✅ Modular Architecture (v1.4.x)

• 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

---

📚 Documentation

📖 Core Documentation

• Quick Start Guide - 5-minute setup
• User Manual - Complete usage guide
• Configuration Guide - Advanced setup
• API Reference - Developer docs

🔧 Device Management

• Supported Hardware - Compatible devices
• FridgeGrow Integration - Plantalytix support
• Modbus Integration - Industrial devices

⚡ Specialized Systems

• VPD Control - Climate automation
• Hydroponics - Nutrient management
• Crop Steering - Growth optimization

🧪 Premium Features

• AI & Analytics - Advanced capabilities
• Research Tools - Scientific features

🛠️ System Management

• Deployment Guide - Production setup
• Troubleshooting - Problem solving
• Performance - Optimization

🧑‍💻 Development

• Architecture - System design
• Testing - Quality assurance
• Debugging - Development tools

---

🐛 Troubleshooting

Common Issues

"Integration not loading"

# Check HA logs
grep -i opengrowbox /config/home-assistant.log

Solutions:

• Restart HA completely
• Check file permissions
• Verify Python dependencies

"No devices found"

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

"VPD calculations failing"

Symptoms:

• "NO Sensors Found to calc VPD"
• Incorrect VPD values

Fix:

• Ensure temperature + humidity sensors are configured
• Check sensor calibration
• Verify sensor placement

Full Troubleshooting →

---

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Setup

# 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

Code Standards

• Linting: flake8 custom_components/opengrowbox/
• Type Checking: mypy custom_components/opengrowbox/
• Testing: 100% smoke test pass rate required
• Documentation: Update docs for new features

Pull Request Process

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests and documentation
5. Submit PR with description

Contributing Guidelines →

---

📄 License

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

---

🌟 Star History

---

📞 Support & Community

• 📧 Email: support@opengrowbox.net
• 💬 Discord: Join our community
• 🐛 Issues: GitHub Issues
• 📖 Wiki: Community Wiki
• 📧 Newsletter: Stay updated

---

Built with ❤️ for the growing community. Happy growing! 🌱

---