Crop Steering System Guide

Version 2.3.1 | 3-Zone Coco Coir | Athena Nutrients | F2 Veg Room

1. What This System Does

This is an automated irrigation controller for cannabis grown in coco coir. It reads VWC (volumetric water content) and pore-water EC from substrate probes, decides when and how much to water each zone, and actuates solenoid valves through Home Assistant.

The system runs a 4-phase daily irrigation cycle (P0-P3) independently per zone. It uses sensor fusion, dryback detection, EC ratio logic, and an ML predictor to make irrigation decisions. Every decision passes through multiple safety checks before a valve opens.

Hardware controlled: - 1 pump (switch.veg_main_pump) — primed 2s before the main line opens - 1 main line solenoid (switch.espoe_irrigation_relay_2_3) - 3 zone valve solenoids, one per row (switch.f2_row1, switch.f2_row2, switch.f2_row3)

Sensors read: - 3 fused VWC sensors (one per zone): sensor.crop_steering_zone_1..3_vwc - 3 fused EC sensors (one per zone): sensor.crop_steering_zone_1..3_ec - Source-water pH (sensor.aquaponics_kit_f4f618_ph) and EC (sensor.atlas_legacy_1_ec) for the irrigation-quality gate

2. Architecture

The system has two halves:

HA Custom Component (/config/custom_components/crop_steering/)

Creates all the entities in Home Assistant — switches, numbers, selects, sensors, and buttons. These are the knobs you turn on the dashboard. The component itself does not make irrigation decisions; it just holds state.

Files:

AppDaemon App (/addon_configs/.../apps/crop_steering/)

This is the brain. It reads entity states, runs the decision loop, and actuates hardware.

Files:

Entity Naming

The custom component sets _attr_object_id = f"crop_steering_{key}" on every entity. This means all entities created by the component have the crop_steering_ prefix:

The AppDaemon app tries both naming conventions (with and without prefix) when reading entity states. It uses a startup cache warm via the HA REST API to populate a switch_state_cache since get_state() returns None for custom component entities in AppDaemon.

Sensors created by AppDaemon (via set_state) do not have this issue — they use the exact entity ID passed (e.g., sensor.crop_steering_zone_1_phase).

Hardware entities from other integrations keep their own naming (e.g., switch.espoe_irrigation_relay_2_3, switch.f2_row1).

Communication Flow

crop_steering.env
       |
       v
Custom Component (creates HA entities with crop_steering_ prefix)
       |
       v
Home Assistant (holds entity state, fires events)
       |
       v
AppDaemon master_crop_steering_app (reads entities via listen_state + REST API fallback)
       |
       v
Hardware (valves, pump via HA switch services)

The AppDaemon app uses listen_state callbacks to populate an in-memory cache for sensor and switch values, because get_state() cannot see custom component entities. The REST API (_check_ha_entity_state) is a final fallback.

3. The Four Phases

Each zone runs its own independent phase cycle every day. Phases advance automatically based on sensor readings and time.

P0 — Morning Dryback

When: Lights turn on (10:00 by default). What: No irrigation. The substrate dries back from overnight saturation. The system records the peak VWC at lights-on and tracks how far VWC drops. Exits when (any of): - Dryback reaches the target percentage (default 50% of peak VWC lost) - VWC drops by at least p0_dryback_drop_percent (default 15%) - Maximum wait time exceeded (default 120 min) - Dryback rate is too slow (<0.1%/min after 1 hour) - Minimum wait time must be met first (default 30 min)

Emergency exception: If EC ratio exceeds 2.5x target during P0, a large flush shot (10% substrate volume) fires to prevent salt damage.

P1 — Ramp-Up

When: P0 ends. What: Progressive irrigation shots that increase in size to bring VWC back to target. The system starts with small shots and works up. Shot sizing: initial_shot_size + (shot_increment * shot_count), capped at max_shot_size, multiplied by the zone's shot_size_multiplier. Exits when: - VWC reaches p1_target_vwc (default 65%) AND minimum shots completed (default 3) - Maximum shots reached (default 6) — exits even if target not met Cooldown: p1_time_between_shots (default 15 min) between each shot. EC logic: Shots are adjusted by EC ratio — if EC is high, shots are larger (dilution); if EC is low, shots are smaller (conservation).

P2 — Maintenance

When: P1 target VWC reached. What: Steady-state irrigation. Fires a fixed-size shot whenever VWC drops below the threshold. Trigger: zone_vwc < p2_vwc_threshold (default 60%). Shot size: p2_shot_size (default 5% of substrate volume), adjusted by EC ratio: - EC ratio > p2_ec_high_threshold (1.2): shot increased 1.5x (flush excess salts) - EC ratio < p2_ec_low_threshold (0.8): shot decreased 0.7x (conserve nutrients) Exits when: ML/time-based prediction determines there isn't enough time before lights-off for the substrate to dry back overnight.

P3 — Pre-Lights-Off

When: Calculated by dryback rate prediction — the system estimates how long the substrate needs to dry to the overnight target, and starts P3 early enough. What: No irrigation unless emergency. The goal is to enter the dark period with the substrate at the right moisture level for generative steering. Emergency only: Fires a small shot if VWC drops below p3_emergency_vwc_threshold (default 40%) or EC ratio exceeds 2.0x target. Exits when: Lights turn on the next morning → P0.

Phase Cycle Summary

Lights ON → P0 (dryback) → P1 (ramp-up) → P2 (maintenance) → P3 (dry-down) → Lights OFF
                                                                                    |
                                                                          Next morning: P0

4. Daily Cycle — What Happens Automatically

Assuming lights 10:00–22:00, Cannabis_Athena profile, vegetative stage:

Actual timing varies per zone based on sensor readings. Zones operate independently.

Decision Loop

The main decision loop runs every 60 seconds (phase_check_interval). Each cycle:

1. Check all zone phase transitions
2. Read current system state (all VWC, EC, environmental sensors)
3. Load crop profile parameters (Cannabis_Athena defaults if none active)
4. Get dryback status from peak detector
5. Get ML irrigation predictions
6. Make irrigation decision per zone based on phase requirements
7. Execute irrigation if needed (one zone at a time, max 1 concurrent)
8. Update tracking sensors

Irrigation Execution Sequence

When a shot fires:

1. Prime the pump (switch.veg_main_pump), wait 2s
2. Turn on main line (switch.espoe_irrigation_relay_2_3), wait 1s
3. Turn on zone valve (switch.f2_rowN)
4. Wait for shot duration
5. Turn off zone valve, wait 1s
6. Turn off main line, then the pump
7. Wait 30s for sensor stabilization
8. Read post-irrigation VWC, calculate efficiency

Valve close is read-back verified; a failure triggers an emergency pump stop.

A finally block ensures all hardware is turned off even if an error occurs mid-shot.

5. Entity Reference

Switches (from custom component)

All have the crop_steering_ prefix in their actual entity ID.

Selects (from custom component)

Numbers (from custom component)

All have the crop_steering_ prefix. Listed by category.

Substrate & Hardware:

P0 Parameters:

P1 Parameters:

P2 Parameters:

P3 Parameters:

EC Targets (Vegetative):

EC Targets (Generative):

Per-Zone Numbers (N = 1–6):

A value of 0 on any per-zone target means "use the system-wide default."

Buttons (from custom component)

Sensors (created by AppDaemon)

These are written by the AppDaemon app at runtime. They do NOT have the naming conflict — they use exactly the entity ID shown.

Events

6. Configuration

crop_steering.env

The primary configuration file. Located at /config/crop_steering.env. Parsed during HA integration setup.

Zone definition (per zone):

ZONE_1_SWITCH=switch.f2_row1
ZONE_1_VWC_SENSORS=sensor.f2_row_1_vwc
ZONE_1_EC_SENSORS=sensor.f2_row_1_ec
ZONE_1_PLANT_COUNT=4
ZONE_1_MAX_DAILY_VOLUME=20.0
ZONE_1_SHOT_MULTIPLIER=1.0

Zones are auto-detected by scanning for ZONE_N_SWITCH entries. You can have up to 24 zones.

Multi-sensor support: Use comma-separated lists for zones with multiple probes:

ZONE_1_VWC_SENSORS=sensor.probe_a_vwc,sensor.probe_b_vwc,sensor.probe_c_vwc

The system averages all valid readings.

Legacy format (still supported):

ZONE_1_VWC_FRONT=sensor.probe_a
ZONE_1_VWC_BACK=sensor.probe_b

apps.yaml

AppDaemon configuration at /addon_configs/.../apps/apps.yaml. Defines the master app with hardware, sensor, timing, and threshold config.

Key settings:

master_crop_steering:
  module: crop_steering.master_crop_steering_app
  class: MasterCropSteeringApp
  hardware:
    pump_master: switch.veg_main_pump
    main_line: switch.espoe_irrigation_relay_2_3
    zone_valves:
      1: switch.f2_row1
      2: switch.f2_row2
      3: switch.f2_row3
  sensors:
    vwc:
      - sensor.f2_row_1_vwc
      # ... one per row
    ec:
      - sensor.f2_row_1_ec
      # ... one per row
    water:
      ph: sensor.aquaponics_kit_f4f618_ph
      ec: sensor.atlas_legacy_1_ec
  timing:
    phase_check_interval: 60     # Decision loop interval (seconds)
    ml_prediction_interval: 300  # ML update interval (seconds)
    sensor_health_interval: 120  # Sensor health check interval (seconds)
  thresholds:
    emergency_vwc: 40.0          # Below this = emergency irrigation

Lights Schedule

Set via number.crop_steering_lights_on_hour and number.crop_steering_lights_off_hour in the dashboard. These are system-wide (not per-zone). Current F2 setup: 10:00 on, 22:00 off. The P3→P0 transition and the daily water/shot counter reset both fire at lights-on.

The AppDaemon app also checks sun.sun entity elevation as a fallback for lights-on detection.

7. Dashboard Layout

The dashboard is at /config/dashboards/crop_steering.yaml, path crop-steering/crop-steering. It uses the HA sections view with max 4 columns.

Row 1 — System Controls + Infrastructure + Valves + AI Status

Top row gives you the master switches (system enabled, auto irrigation, EC stacking, analytics), crop type/growth stage selects, lights schedule, infrastructure switches (mainline, mains water, manifold, tank fill, waste, recirculation), all 3 row valves with last-changed timestamps, and AI status sensors.

Row 2 — Live Sensors + Phase Override + Trigger Shots

All 3 VWC readings, all 3 EC readings, per-zone phase control selects (Auto/P0/P1/P2/P3), and per-zone trigger shot buttons.

Row 3 — System Health + Manual Override + Zone Safety + AI Oversight

System health score, sensor health, daily water, fused VWC/EC, dryback percentage. Manual override switches for all 3 zones. Per-zone safety status. AI heartbeat and last action.

Row 4 — Water Usage + Zone Health

Daily water per zone, irrigation count per zone, zone health scores, zone efficiency scores.

Row 5 — Phase Parameters (P0, P1, P2, P3)

Four columns, one per phase. All tunable parameters for each phase.

Row 6 — EC Targets + Hardware Config

Vegetative EC targets (P0–P3), generative EC targets (P0–P3), max EC, substrate volume, dripper flow rate, drippers per plant, field capacity, lights schedule.

Row 7 — Zone Tuning

One card per zone (6 total). Each card has: group, priority, crop profile, shot multiplier, plant count, max daily volume, and the 4 per-zone target overrides (dryback, P1 VWC, P2 threshold, P3 emergency — all default 0 = use system).

Row 8 — Current Zone Phases + Zone Efficiency

Read-only zone phase sensors and efficiency scores.

Row 9 — Sensor Reliability + Sensor Health

Per-sensor reliability scores and health status from the sensor fusion module.

Row 10 — Instruction Manual

Embedded markdown card with operational reference.

8. Zone Management

Zone Enable vs Manual Override

These are two different switches with different purposes:

Manual override is an absolute lockout. When it's ON, the zone cannot be irrigated by any mechanism — not automatic, not emergency, not manual trigger shots. It is checked at three levels:

1. Zone selection — overridden zones excluded from emergency candidate selection
2. Decision evaluation — overridden zones skipped in phase requirement evaluation
3. Valve actuation — defense-in-depth check right before the valve opens

Zone Groups

Zones can be assigned to Group A, B, C, or D (or Ungrouped). Groups coordinate irrigation:

• If >= 50% of zones in a group need water, ALL zones in that group irrigate
• Only 1 zone can irrigate at a time (pressure protection) — group zones are queued
• Group conflicts prevent a zone from irrigating if another zone in the same group is already watering

Zone Priority

Priority affects which zone waters first when multiple zones need irrigation:

Zone selection uses a composite score: Priority (40%) + VWC Need (40%) + Phase Urgency (20%). Phase urgency: P1=0.9 (highest), P3=0.8, P2=0.6, P0=0.1 (lowest).

Per-Zone Crop Profile

Each zone can follow the main system crop profile or have its own. Options: Follow Main, Cannabis_Athena, Cannabis_Indica_Dominant, Cannabis_Sativa_Dominant, Cannabis_Balanced_Hybrid, Tomato_Hydroponic, Lettuce_Leafy_Greens, Custom.

9. Phase Parameters — What Each One Does

P0 (Morning Dryback)

P1 (Ramp-Up)

P2 (Maintenance)

P3 (Pre-Lights-Off)

10. EC Targets and Ratio Logic

The system uses EC ratio (current_ec / target_ec) to adjust irrigation behavior. Each phase and growth stage has its own EC target.

How EC Ratio Works

EC Stacking Mode

When switch.crop_steering_ec_stacking_enabled is ON, the system reverses its EC behavior: instead of diluting when EC is high, it tries to build EC when it's below target (deficit > 0.5 mS/cm). This is used when you want to push EC higher intentionally.

Default EC Targets

11. Per-Zone Targets

Each zone has 4 override parameters. Set to 0 to use the system-wide default. Any value > 0 overrides the system default for that zone only.

Example: Zone 4 has a weaker root system and dries out faster. Set zone_4_p2_vwc_threshold to 65 (instead of system default 60) so it gets watered sooner. Leave all other zones at 0 to use defaults.

12. Manual Override

Absolute Lockout

When switch.crop_steering_zone_N_manual_override is ON:

• No automatic irrigation
• No emergency irrigation
• No manual trigger shots
• No ML-triggered irrigation
• Nothing opens that valve

This is a safety feature for maintenance — flushing substrate, unplugging a zone, fixing a leak, investigating a sensor.

How It's Detected

The system checks for manual override through 4 layers (in order):

1. In-memory dict — AppDaemon's internal tracking
2. Switch state cache — populated by listen_state callbacks
3. AppDaemon state cache — get_state() call
4. HA REST API — direct HTTP call to HA as final fallback

This multi-layer approach exists because AppDaemon cannot reliably read custom component entity states via get_state().

Timed Overrides

You can set a timed override via the crop_steering_manual_override event with action: enable_with_timeout and timeout_minutes. The override auto-disables when the timer expires and sends a notification.

Override Active > 24 Hours Warning

The AI heartbeat flags any zone with manual override active for more than 24 hours as a potential forgotten override.

13. Emergency Irrigation

When It Fires

Emergency irrigation triggers when any fused VWC reading drops below emergency_vwc (default 40%). This runs independently of the normal decision loop — it fires from the VWC sensor update callback.

Emergency Flow

1. 120-second startup grace period (no emergencies right after boot)
2. 300-second cooldown between emergency shots
3. Select zone with lowest VWC from sensor fusion cache
4. Skip zones with manual override ON
5. Skip zones with active emergency lockout
6. Check effective VWC ceiling (for non-responding sensors)
7. Fire 60-second emergency shot

Escalating Backoff

If a zone gets 4+ emergency shots in 30 minutes without VWC responding:

VWC Response Tracking

After emergency shots, the system checks if VWC actually rose. If the average lift across 3+ shots is less than 1%, it sets an effective_vwc_ceiling at max_observed_vwc + 2%. This prevents endless watering of a zone where the sensor is positioned badly or the dripper is blocked.

Resetting Emergency Lockouts

Fire the crop_steering_reset_emergency event: - With {zone: N} to reset a specific zone - Without a zone to reset all zones

This clears the abandonment count, lockout timer, and effective VWC ceiling.

14. AI Heartbeat

Runs every 15 minutes. Checks 6 anomaly conditions per zone and takes corrective action.

Anomaly Checks

Published Sensors

• sensor.crop_steering_ai_heartbeat — state: anomaly count. Attributes: zone summary, anomalies list, actions taken.
• sensor.crop_steering_current_decision — last corrective action description.

History

The heartbeat keeps a rolling buffer of 96 reports (24 hours at 15-minute intervals). EC trend detection uses a per-zone buffer of 12 readings (3 hours).

15. Safety Layers

Every irrigation shot passes through these checks in order. Any failure blocks the shot.

Watchdog

A 60-second watchdog checks for state mismatches: - irrigation_in_progress=True but all hardware OFF → resets flag - Hardware ON but irrigation_in_progress=False → emergency stop

Sensor Fail-Safe

If ALL VWC sensors go offline while irrigation hardware is ON, the system executes an emergency stop. (120-second startup grace period to allow sensors to connect.)

Clean Shutdown

When AppDaemon terminates, terminate() synchronously turns off the pump, main line, and all zone valves.

16. Sensor Fusion

The IntelligentSensorFusion module processes all sensor readings before they reach the decision logic.

What It Does

1. Outlier detection — Rejects readings that are physically impossible (VWC outside 0–100, EC outside 0–20) or statistically extreme (>4 sigma from mean). Uses minimum deviation thresholds to avoid rejecting valid data when readings are stable: VWC needs >5% deviation from mean before statistical checks apply, EC needs >1.0 mS/cm.

2. Reliability scoring — Each sensor gets a 0–1 reliability score based on outlier rate, data consistency, temporal stability, and recent performance.

3. Health classification — excellent, good, degraded, faulty, offline (no data for 30+ minutes).

4. Weighted fusion — When multiple sensors exist per zone, values are averaged weighted by reliability. Excellent sensors get 1.2x weight, degraded sensors get 0.8x.

5. Kalman filtering — Smooths fused values to reduce noise. Separate filters per sensor type (VWC and EC are never mixed).

Sensor Data Freshness

The system considers sensor data stale after 600 seconds (10 minutes). Stale readings are not used for zone VWC/EC calculations. The AI heartbeat flags sensors stale after 900 seconds (15 minutes).

17. Crop Profiles

Available Profiles

Growth Stages

Each profile has parameters for 3 growth stages: - Vegetative — Higher VWC targets, lower EC, more frequent irrigation - Early Flower — Moderate settings, transition period - Late Flower — Lower VWC targets, higher EC, less frequent irrigation (generative stress)

Change the growth stage via select.crop_steering_growth_stage. This affects all zones using that profile.

Adaptive Learning

The crop profile system tracks irrigation performance (efficiency, VWC response, target achievement) and slowly adjusts parameters over time: - Poor efficiency (<0.6) → raises VWC targets or dryback target - Good efficiency (>0.8) with high hit rate → lowers dryback target slightly - Poor plant response (<0.4) → lowers EC baseline - Excellent response (>0.8) → raises EC baseline slightly

Adaptation rate is intentionally slow (0.1 learning rate with 0.8 momentum smoothing). Requires minimum 10 samples before adapting.

18. Persistent State

The system saves state to a JSON file every 5 minutes and on every irrigation event. On restart, it restores:

• Zone phases — Each zone returns to its saved phase. If the saved state doesn't make sense (e.g., lights are on but zone is in P3), it's corrected.
• P0/P1 tracking — Peak VWC, dryback progress, P1 shot count and timing.
• Water usage — Daily totals restored if same day; weekly totals if within 7 days.
• Manual overrides — Active overrides restored with remaining timeout. Expired overrides are discarded.
• Last irrigation time — Used for cooldown calculations.

The state file has a 10MB size limit. Corrupt JSON files are backed up with a .corrupt.timestamp extension.

Downtime Recovery

On restart, the system logs how long it was down and validates all zone phases against the current light schedule. Zones in the wrong phase for the current time are corrected automatically.

19. Failure Modes and Troubleshooting

Symptoms and Causes

AppDaemon Logs

The master app logs to the crop_steering_master log (configured in apps.yaml). Key log messages to watch:

• "Zone N: Transitioning P0 -> P1" — phase change (INFO)
• "Emergency irrigation: Zone N" — emergency shot fired (WARNING)
• "Zone N abandoned: escalating backoff" — emergency lockout (WARNING)
• "ABSOLUTE LOCKOUT" — manual override blocking irrigation (INFO)
• "AI Heartbeat:" — 15-minute oversight report (INFO)
• "Warmed switch cache: X/15" — startup cache status (INFO)
• "All sensors offline while irrigation active" — fail-safe triggered (ERROR)

Restarting

• Restart HA — needed after changing custom component files or crop_steering.env. All entity states persist across restarts.
• Restart AppDaemon — needed after changing master_crop_steering_app.py or other AppDaemon modules. State is restored from persistent file. 120-second startup grace period prevents false emergencies.

20. Known Issues

Entity Naming Mismatch

The custom component produces entity IDs with the crop_steering_ prefix (e.g., switch.crop_steering_system_enabled). The AppDaemon app and dashboard reference some entities without this prefix (e.g., switch.system_enabled). The AppDaemon app works around this with dual-naming lookups in the switch cache warm, but the dashboard cards may show "Entity not found" for custom component entities that it references without the prefix.

get_state() Returns None

AppDaemon's get_state() cannot see custom component entities. The system works around this by: 1. Using listen_state callbacks to populate an in-memory cache 2. Falling back to the HA REST API via _check_ha_entity_state() 3. Warming the switch cache at startup

This means entity values are not available until the first state change after AppDaemon starts, or until the REST API cache warm completes.

P3 Early Transition

The _should_zone_start_p3() calculation can trigger too early if the predicted dryback rate is very slow. A substrate volume of 10L with a dryback target of 50% and a slow rate (e.g., 0.2%/hour) calculates 250 hours needed — which exceeds any lights-on period and causes immediate P3 transition. This typically self-corrects once the dryback detector has enough data for accurate rate prediction.

Duplicate Method Definitions

_get_phase_icon(), _get_zone_group(), and _get_zone_priority() are defined twice in the master app. The second definition overrides the first. No functional impact, but the icon set differs between the two _get_phase_icon() definitions.

Hardcoded Irrigation Count

_get_irrigation_count_24h() returns a hardcoded value of 8 instead of querying actual history. This affects ML training sample quality but not irrigation decisions.

Hardcoded Lights-Off Fallback

_get_lights_off_time() has a hardcoded 22:00 fallback instead of reading from the lights_off_hour entity. The main phase transition logic does read from the entity correctly.

21. Hardware Map

Current Installation — F2 veg room

Raw per-row sensors are fused into the crop_steering_zone_N_* entities; the live hardware/sensor map lives in appdaemon/apps/apps.yaml.

Irrigation Sequence Timing

Shot Duration Calculation

Duration in seconds = (shot_size_percent / 100) * substrate_volume_L * 1000 / (dripper_flow_rate_Lph * drippers_per_plant * 1000 / 3600)

With defaults (10L substrate, 2 L/hr drippers, 2 drippers/plant): - 2% shot (P1 initial) = 180 seconds (3 minutes) - 5% shot (P2 maintenance) = 450 seconds (7.5 minutes) - 10% shot (P0 EC flush) = 900 seconds (15 minutes)

Water Volume Calculation

Per shot: plant_count * drippers_per_plant * dripper_flow_rate * (duration_seconds / 3600) * shot_multiplier

With defaults (4 plants, 2 drippers, 2 L/hr, multiplier 1.0): - 180s shot = 0.8L - 450s shot = 2.0L - 900s shot = 4.0L

Notifications

Notifications are sent via notify.mobile_app_damians_iphone (configured in .env as NOTIFICATION_SERVICE). Events that trigger notifications: - Emergency lockout escalation - Manual override enabled/disabled/timeout - Critical EC levels - AI heartbeat anomalies (critical only)