Irrigation System Manual

Version 2.3.1 — Last updated March 2026

1. System Overview 2. Hardware Setup 3. How It All Works 4. Crop Steering Phases (P0–P3) 5. Commissioning Guide 6. Day-to-Day Operation 7. Dashboard Guide 8. Tuning Your Parameters 9. AppDaemon Setup (Advanced) 10. Safety Systems 11. Troubleshooting 12. Entity Reference

1. System Overview

The irrigation system automates irrigation for 6 grow tables using sensor-driven decisions. It has three layers:

Layer 1 — Irrigation Package (runs now)

Time-based irrigation scheduling, environment control (AC, humidity, CO2), and safety watchdogs. This is the production workhorse. It runs entirely inside Home Assistant — no extra software needed.

Layer 2 — Crop Steering Integration (runs now)

Adds 90+ entities for sensor-driven irrigation decisions. Calculates shot sizes, tracks EC ratios, and provides per-zone controls. Installed as a custom component.

Layer 3 — AppDaemon (optional, not yet deployed)

Autonomous phase transitions, advanced dryback detection, and ML-based irrigation prediction. Needs separate setup (see Section 9).

The Data Flow

Physical probes (ESPHome)
    ↓
Raw sensor entities (e.g. sensor.substrate_1_substrate_1_vwc_coco_coir)
    ↓  [10_mapping.yaml averages + rounds values]
GW contract entities (e.g. sensor.irrigation_table_1_vwc)
    ↓  [crop_steering.env tells the integration where to look]
Crop Steering entities (e.g. sensor.zone_1_vwc)

2. Hardware Setup

What's Connected

Device	What It Does	Connection
KC868 E16S relay board	Controls all valves (6 tables + mains + mainline + manifold)	Ethernet (ESPHome)
6x Substrate probes	Measure VWC, EC, and temperature per table	SDI-12 via Ethernet (ESPHome)
4x Environmental sensors	Room temperature and humidity	Ethernet (ESPHome)
3x CO2 sensors	CO2 levels + VPD	Ethernet (ESPHome)
4x AC units	Temperature control	IR via ESPHome
CO2 solenoid	CO2 injection during lights-on	Solid state relay (ESPHome)
Humidifier	Raise humidity	Solid state relay (ESPHome)
4x Dehumidifier relays	Lower humidity	Relay board (ESPHome)
Grow lights	Light group for all tables	ESPHome

Water Flow Path

Nutrient Tank
    ↓
[switch.mainline opens] → Pressure switch auto-starts pump
    ↓
Mainline pipe
    ↓
[switch.table_N opens] → Water flows to table N's drippers
    ↓
Drippers → Plants → Substrate → Runoff

No pump switch needed. The pump starts automatically when the mainline valve opens (pressure switch). That's why PUMP_SWITCH is blank in the config.

Not Yet Connected

Sensor/Device	What It Does	Impact If Missing
Tank low float switch	Detects low water level	Tank-low safety abort won't trigger
Leak sensor	Detects water leaks	Leak safety abort won't trigger
Tank pH probe	Monitors nutrient pH	pH shows "Unavailable" on dashboard
Tank EC probe	Monitors nutrient EC	EC shows "Unavailable" on dashboard
Leaf temp sensor	Accurate VPD calculation	Falls back to room air temp

Safety Warning: Until the tank float switch and leak sensor are installed, the emergency abort automations for tank-low and leak detection are disabled (hardcoded to "safe"). Install these sensors before relying on the system unattended.

3. How It All Works

The Irrigation Cycle

Every cycle follows this sequence:

The scheduler checks: Is the system enabled? Is it within the irrigation window? Has enough time passed since the last run?

If yes, it opens the mainline valve (which auto-starts the pump via the pressure switch) and waits 2 seconds.

For each enabled table (1 through 6, one at a time): opens the table valve, runs water for the configured duration, closes the valve, waits 3 seconds.

After all tables are done, closes the mainline valve (pump stops).

Mains water and manifold are for tank filling and mixing only — they are NOT part of the irrigation cycle. Only the mainline valve opens during feeding.

What Controls the Cycle

Setting	Where to Change It	Default
Irrigation window start	Schedule tab → Window Start	Set in HA
Irrigation window end	Schedule tab → Window End	Set in HA
Time between cycles	Schedule tab → Interval	60 minutes
Duration per table	Schedule tab → Duration	60 seconds
Which tables are active	Zone Control tab → Enabled toggle per table	All off
Master on/off	Command Center → GW System	Off

Environment Control

The system also manages grow room climate:

Dehumidifiers: Turn on when humidity is 5% above target, off when 2% below target. 4 relays stagger on with 10-second delays.
Humidifier: Turns on when humidity is 5% below target, off when 2% above.
CO2: Injects when CO2 is 50ppm below target, stops at 50ppm above. Only during lights-on. Auto-closes at lights-off.
Temperature: Managed by AC units. Day and night targets are separate.

4. Crop Steering Phases (P0–P3)

Crop steering divides each day into 4 phases based on substrate moisture and light cycle. The goal is to control how plants use water and nutrients.

P0 — Morning Dryback

When: Lights turn on → First irrigation shot

What happens: No watering. The substrate dries down from overnight levels.

Why: A controlled dry-down signals the plant to focus on root growth (vegetative) or fruit production (generative).

Moves to P1 when: VWC drops by the target percentage (vegetative: 50%, generative: 40%), or max wait time (120 min) expires.

P1 — Ramp-Up

When: After dryback target reached → VWC reaches field capacity target

What happens: Progressive irrigation shots. Starts small (2% of substrate volume), increases by 0.5% each shot.

Why: Gradually rehydrates the substrate without causing runoff or flushing nutrients.

Settings: 15 min between shots, max 10 shots, target VWC 65%.

Moves to P2 when: Target VWC reached or max shots hit.

P2 — Maintenance

When: Field capacity reached → Before lights-off

What happens: Fixed-size maintenance shots whenever VWC drops below threshold (60%).

Smart EC adjustment: If EC is too high (ratio > 1.2), the threshold rises — triggering more frequent irrigation to flush salts. If EC is too low (ratio < 0.8), threshold drops — letting the substrate dry more to concentrate nutrients.

Moves to P3 when: Approaching lights-off time.

P3 — Pre-Lights-Off

When: 2–3 hours before lights off → Lights off

What happens: No scheduled irrigation. Emergency-only shots if VWC drops below 40%.

Why: Allows a controlled overnight dryback for the next day's P0.

Moves to P0 when: Lights turn on next day.

Vegetative vs Generative steering: Vegetative mode uses longer drybacks and lower EC targets — encouraging root and leaf growth. Generative mode uses shorter drybacks and higher EC — pushing the plant toward flowering and fruit production.

5. Commissioning Guide

Follow these steps to get the system running from scratch.

Step 1: Verify Hardware Connections

Go to Settings → Devices & Services → ESPHome. Confirm all 6 substrate sensors, KC868 relay board, environmental sensors, and CO2 sensors show as "Online".

Go to Developer Tools → States. Search for sensor.irrigation_table_1_vwc. You should see a number (e.g. 47.4). Check all 6 tables.

Search for sensor.irrigation_room_1_temp. Should show room temperature. Also check sensor.irrigation_room_1_rh and sensor.irrigation_room_1_co2.

Test each valve manually: Go to Developer Tools → Services, select switch.turn_on, target switch.irrigation_table_1_valve. You should hear the valve click. Turn it off immediately after confirming. Repeat for all 6 tables.

Test infrastructure: Briefly toggle switch.irrigation_mainline on — you should hear the pump start. Turn off immediately.

Before testing valves: Make sure your nutrient tank has water and the system is plumbed correctly. Have someone at the tables to confirm water is reaching the right place.

Step 2: Configure the Irrigation Window

Go to the Irrigation → Schedule tab.

Set Window Start to when you want irrigation to be allowed (e.g. 08:30 — 30 min after lights on).

Set Window End to when irrigation should stop (e.g. 18:00 — 2 hours before lights off).

Set Interval to how often cycles run (start with 60 minutes).

Set Duration to how long each table runs per cycle (start with 60 seconds).

Step 3: Enable the System

Go to the Command Center tab.

Turn Maintenance Mode OFF (the toggle should be off/grey).

Turn GW System ON.

Go to Zone Control tab. Enable each table you want to irrigate by toggling Enabled on.

Watch the System Ready indicator on the Command Center. It should show a green check mark.

Step 4: Test an Irrigation Cycle

Go to Developer Tools → Services.

Select service script.irrigation_run_irrigation_cycle.

Click Call Service.

Watch the Zone Control tab — you should see valves open and close one by one.

Check that water reached each enabled table.

Step 5: Set Environment Targets

Go to the Environment tab.

Set Day/Night Temperature targets (e.g. Day: 26°C, Night: 22°C).

Set Day/Night Humidity targets (e.g. Day: 60%, Night: 55%).

Set CO2 target (e.g. 1200 ppm).

Verify the AC units, dehumidifiers, and CO2 solenoid respond correctly.

Step 6: Configure Crop Steering (Optional)

Go to Command Center → Crop Steering section.

Set Steering Mode: "Vegetative" for veg growth, "Generative" for flower.

Set Crop Type: "Cannabis_Athena" is preconfigured with Athena nutrient targets.

Review shot calculations — P1/P2/P3 durations should show non-zero values. If they show 0.0s, check that substrate volume and dripper flow rate are set (see Tuning).

6. Day-to-Day Operation

Normal Operation Checklist

Check the Command Center — all 6 tables should show VWC values between 30-70%.
EC values should be in your target range (typically 2-6 mS/cm depending on stage).
Substrate temps should be 20-26°C.
Safety indicators should all be green/OK.
Check the Trends tab — VWC graphs should show a sawtooth pattern (gradual drop, sharp rise from irrigation).

Changing What Gets Watered

Go to Zone Control and toggle the Enabled switch for each table. Disabled tables are skipped during irrigation cycles.

Emergency Stop

If anything goes wrong:

Toggle Maintenance Mode ON in the Command Center — this immediately closes all valves.
Or call the script.irrigation_emergency_stop service from Developer Tools.
Or physically switch off the pump/relay board.

7. Dashboard Guide

Tab	What It Shows	When To Use It
Command Center	System status, crop steering settings, safety, infrastructure controls, all-table overview	Daily check-in, system on/off, changing steering mode
Zone Control	Per-table detail: sensors, valves, irrigation stats, crop profiles	Enabling/disabling tables, checking individual table health
Trends	24-hour graphs: VWC, EC, substrate temp, room environment	Spotting problems, checking irrigation patterns
Environment	Room climate gauges, temperature/humidity/CO2 targets, hardware switches	Adjusting climate targets, checking HVAC status
Schedule	Irrigation timing, valve controls, table enables, scripts	Changing irrigation timing, manual valve control

8. Tuning Your Parameters

Substrate & Hardware

These must match your physical setup. Find them in Settings → Devices → Crop Steering System or edit /config/crop_steering.env.

Parameter	What It Means	Default	How To Measure
Substrate Volume	Volume of growing media per pot (litres)	10.0 L	Check your pot size
Dripper Flow Rate	How fast each dripper delivers water (L/hr)	2.0 L/hr	Time how long to fill a measuring cup
Drippers Per Plant	Number of drippers in each pot	2	Count them
Field Capacity	Maximum VWC your substrate can hold	70%	Saturate substrate, read VWC when dripping stops

EC Targets (Athena Defaults)

Phase	Vegetative	Generative
P0 (Dryback)	3.0 mS/cm	4.0 mS/cm
P1 (Ramp-Up)	3.0 mS/cm	5.0 mS/cm
P2 (Maintenance)	3.2 mS/cm	6.0 mS/cm
P3 (Pre-Off)	3.0 mS/cm	4.5 mS/cm

Start conservative. Run the time-based scheduler for a week while monitoring VWC trends. Once you're confident in the sensor readings and hardware, switch to crop-steering-driven irrigation.

9. AppDaemon Setup (Advanced)

AppDaemon adds autonomous phase transitions — the system automatically moves through P0→P1→P2→P3 based on live sensor data instead of requiring manual phase selection.

You don't need AppDaemon to use the system. The GW Package handles time-based irrigation and the Crop Steering integration provides all the sensor entities and calculations. AppDaemon just adds autonomous decision-making.

Installation Steps

Install the AppDaemon add-on from Settings → Add-ons → Add-on Store. Search for "AppDaemon".

In the AppDaemon add-on config, add Python packages: scipy, numpy.

Start the AppDaemon add-on.

Copy the app files from the repo to your AppDaemon apps directory:

cp -r /config/repos/HA-Irrigation-Strategy/appdaemon/apps/crop_steering /config/appdaemon/apps/

Copy the AppDaemon configuration:

cp /config/repos/HA-Irrigation-Strategy/appdaemon/apps/crop_steering/apps.yaml /config/appdaemon/apps/crop_steering/

Edit /config/appdaemon/apps/crop_steering/apps.yaml and verify the entity IDs match your setup (they should reference irrigation_* entities).

Restart AppDaemon from the add-on page.

Check the AppDaemon log for errors: Settings → Add-ons → AppDaemon → Log.

Once running, new sensors will appear: sensor.crop_steering_app_status, sensor.crop_steering_app_current_phase, etc.

Verifying AppDaemon is Working

Check Developer Tools → States for sensor.crop_steering_app_status — should show "running".
The phase should auto-transition based on sensor data (watch for P0→P1 transition after lights-on dryback).
The AppDaemon log will show detailed decision-making output.

10. Safety Systems

The system has multiple layers of protection. These run independently — if one fails, others still protect your grow.

Protection	What It Does	Automatic?
Master Gate	Irrigation only runs when: system enabled + not in maintenance + no leak + tank OK + within time window	Yes
Valve Watchdog	If any table valve stays open longer than 3 minutes, force-closes it and alerts you	Yes
Mains Water Watchdog	Kills mains water if open for 24 minutes (8x valve limit)	Yes
Leak Abort	Emergency stop on leak detection (needs sensor installed)	Yes*
Tank Low Abort	Closes all valves if tank is low (needs float switch installed)	Yes*
Maintenance Mode	Closes all valves immediately when toggled on	Manual
Sensor Offline Alert	Alerts if temp/RH/CO2 sensors go offline for 10 min. Also closes CO2 if CO2 sensor lost.	Yes
Valve-Without-Permission	If the master gate goes false while valves are open, closes everything	Yes
Daily Audit (3 AM)	Force-closes all valves and CO2 solenoid as a safety reset	Yes
CO2 Lights-Off	CO2 solenoid always closes when lights turn off	Yes

* Requires physical sensor to be installed and mapped.

11. Troubleshooting

Irrigation won't run

Check Command Center → GW System is ON.
Check Maintenance Mode is OFF.
Check the current time is within your irrigation window (Schedule tab).
Check at least one table is enabled (Zone Control tab).
Check Developer Tools → States for binary_sensor.irrigation_irrigation_allowed — should be "on". If "off", check each condition above.

VWC/EC shows "Unavailable"

Go to Settings → Devices → ESPHome. Is the substrate sensor device online?
Check Developer Tools → States for the raw entity (e.g. sensor.substrate_1_substrate_1_vwc_coco_coir). If this shows a value but the irrigation_table_1_vwc doesn't, reload template entities: Developer Tools → YAML → Template Entities → Reload.
If the raw entity is also unavailable, the ESPHome device has lost connection. Check network/power to the probe.

Shot durations show 0.0 seconds

Check number.substrate_volume — should be your pot volume (e.g. 10.0 L).
Check number.dripper_flow_rate — should be your dripper output (e.g. 2.0 L/hr).
If these show values but shots are still 0.0, the integration has a known bug where it looks for entities with a crop_steering_ prefix. This will be fixed in a future update.

Valves won't close / stuck open

Immediate: Toggle Maintenance Mode ON. This force-closes everything.
If that doesn't work: Go to Developer Tools → Services, call switch.turn_off targeting the specific valve entity (e.g. switch.table_1).
If the valve won't respond to software commands, physically disconnect power to the relay board.
The valve watchdog should have caught this — check Settings → Automations for the watchdog automation and verify it's enabled.

Dashboard shows "Entity not found"

Check if the Crop Steering integration is loaded: Settings → Devices & Services, look for "Crop Steering System".
If it's there but entities are missing, try removing and re-adding the integration.
If it's not there, add it: Add Integration → Search "Crop Steering". Choose "Load from .env file".

Environmental controls not working

Check that temperature, humidity, and CO2 targets are set (Environment tab).
Verify the relay/switch entities are online in Developer Tools.
For CO2: Confirm lights are ON — CO2 injection is disabled during lights-off.
Check the automations are enabled: Settings → Automations, search for "irrigation_".

12. Entity Reference

Key Sensors

Entity	What It Shows
`sensor.irrigation_table_N_vwc`	Table N volumetric water content (%)
`sensor.irrigation_table_N_ec`	Table N pore water EC (mS/cm)
`sensor.irrigation_table_N_substrate_temp`	Table N substrate temperature (°C)
`sensor.irrigation_room_1_temp`	Room temperature (averaged from 4 sensors)
`sensor.irrigation_room_1_rh`	Room humidity (averaged)
`sensor.irrigation_room_1_co2`	Room CO2 (averaged from 3 sensors)
`sensor.irrigation_room_1_vpd`	Room VPD (averaged)
`sensor.irrigation_average_vwc`	Average VWC across all tables
`sensor.irrigation_average_ec`	Average EC across all tables

Key Switches

Entity	What It Controls
`input_boolean.irrigation_enable`	Master system on/off
`input_boolean.irrigation_maintenance_mode`	Maintenance mode (closes all valves)
`input_boolean.irrigation_table_N_enabled`	Enable/disable table N for irrigation
`switch.irrigation_table_N_valve`	Table N solenoid valve
`switch.irrigation_mainline`	Mainline valve (starts pump)
`switch.irrigation_mains_water`	Mains water solenoid
`switch.irrigation_manifold`	Manifold valve

Key Scripts

Script	What It Does
`script.irrigation_run_irrigation_cycle`	Runs a full irrigation cycle (all enabled tables)
`script.irrigation_run_table`	Runs a single table for configured duration
`script.irrigation_emergency_stop`	Emergency stop — closes ALL valves, disables system

Irrigation System Manual v2.3.1 — Generated March 2026

Irrigation System Manual

Table of Contents

1. System Overview

Layer 1 — Irrigation Package (runs now)

Layer 2 — Crop Steering Integration (runs now)

Layer 3 — AppDaemon (optional, not yet deployed)

The Data Flow

2. Hardware Setup

What's Connected

Water Flow Path

Not Yet Connected

3. How It All Works

The Irrigation Cycle

What Controls the Cycle

Environment Control

4. Crop Steering Phases (P0–P3)

P0 — Morning Dryback

P1 — Ramp-Up

P2 — Maintenance

P3 — Pre-Lights-Off

5. Commissioning Guide

Step 1: Verify Hardware Connections

Step 2: Configure the Irrigation Window

Step 3: Enable the System

Step 4: Test an Irrigation Cycle

Step 5: Set Environment Targets

Step 6: Configure Crop Steering (Optional)

6. Day-to-Day Operation

Normal Operation Checklist

Changing What Gets Watered

Emergency Stop

7. Dashboard Guide

8. Tuning Your Parameters

Substrate & Hardware

EC Targets (Athena Defaults)

9. AppDaemon Setup (Advanced)

Installation Steps

Verifying AppDaemon is Working

10. Safety Systems

11. Troubleshooting

Irrigation won't run

VWC/EC shows "Unavailable"

Shot durations show 0.0 seconds

Valves won't close / stuck open

Dashboard shows "Entity not found"

Environmental controls not working

12. Entity Reference

Key Sensors

Key Switches

Key Scripts