Install
Starting without Home Assistant? Follow the illustrated grow-controller tutorial for Raspberry Pi or Intel NUC, sensors and your first irrigation zone.
Check the minimum hardware first →
You install two parts. The integration runs inside Home Assistant. The controller makes the watering decisions and runs as a Home Assistant app or a Docker container. Below the version box, this page shows the project's own install text.
Terms used here: integration, controller, entity, kill switch (Watering). Full glossary
This release
- Integration
- 3.18.1
- Controller
- 3.18.1
- Home Assistant
- 2024.10+
Requirements
- Home Assistant 2024.10 or newer. Python requirements follow your HA version; HA 2024.10 requires Python 3.12.
- HACS for the guided integration download, or access to copy a custom integration manually.
- Home Assistant OS/Supervised with the app store for the guided controller install. Container/Core users run the controller as a Docker container instead; see Home Assistant Container or Core.
- An HA administrator account for Equipment › Setup: pumps & valves and its configuration services.
- Existing HA entities for the actual pump and zone valves, fresh VWC/EC probes, feed-water probes and any configured interlocks. This integration maps entities; it does not provision sensor firmware or pair devices.
Install the integration and the controller app at the same version: from 2.21.0 both carry one version number, and each release names the pair in the changelog. The public demo uses isolated synthetic data; its sample plans and records are not installation settings.
Step-by-step install
Three steps have a button that opens the right screen in Home Assistant. The rest are done on the Crop Steering page.
Open this repository in HACS. Download the integration and restart HA. If HACS is absent, install HACS first or use the manual path below. To add the repository manually, go to HACS → ⋮ → Custom repositories. Add
https://github.com/JakeTheRabbit/HA-Irrigation-Strategywith the type Integration.Open in HACSOpens this project in HACS in Home Assistant. You confirm the download there, then restart Home Assistant.
Start the Crop Steering config flow. Select manual setup for a new installation. Enter a room name and initial zone count. Existing environment-import installations remain supported.
Add Crop SteeringOpens Devices & services and starts the Crop Steering setup. Home Assistant asks you to confirm first.
Add the app repository. In the app store, install Crop Steering Controller. Keep the Watering switch of each room (the engine enable flags) OFF, review the app options, then start the app so it can publish its heartbeat and discover configuration. From then on it starts with the host (Start on boot is on unless you turn it off); turn on Watchdog as well, so Supervisor restarts it if it stops. Supervisor supplies the internal HA token; do not paste a token into a repository file.
Add the app repositoryOffers to add the app repository in Home Assistant. You confirm, then install and start the controller from the app store.
Open Crop Steering in the HA sidebar. The integration serves its bundled dashboard automatically; no manual dashboard YAML or custom Lovelace card installation is required. The controller's ingress can also serve the same dashboard. In supported HA shells, use the workspace's Home Assistant or house button to reopen the temporarily collapsed HA sidebar; see sidebar behavior.
In Equipment › Setup: pumps & valves, select or add a room. Name its zones. Search HA entities by friendly name or ID and check their units/current states while mapping valves, VWC probes, EC probes and room equipment. Multiple probes can be selected per zone. Every zone needs its valve. Under Shared room hardware, say how the room is plumbed: a tent with one smart plug or solenoid is Zone valves only and maps that switch as the zone's valve and nothing else; a room where water only flows while a pump runs is A pump, then zone valves and must have the pump chosen. The switches have to match the answer, and the controller holds a room whose switches stop matching rather than watering it with no pump.
Enter substrate litres per plant, plant count, drippers per plant and each dripper's L/hour. Catch-test actual output using Equipment › Setup: pumps & valves. The calculator proposes a value; it does not write it automatically.
Choose Review configuration, then Save configuration. Setup validates entity domains, moisture/EC units, duplicate valve assignments, revision conflicts and readable OFF states of the affected engine/equipment. A saved configuration and controller acknowledgement are shown separately; wait for Mapping acknowledged instead of assuming a save has already reached the controller.
Steps 2 and 3 can be done in either order. A controller started before any room exists waits, invents no zones, and picks the room up by itself within a minute of setup finishing; no restart is needed. On earlier versions that order produced errors for zones that did not exist and a Repairs card asking for a kill-switch helper: do not create that helper, update instead.
See the step-by-step mapping workflow for field meanings, revision conflicts and controller adoption.
Room and zone removal means archive. Archived IDs remain reserved, so restoring or adding a zone cannot silently point an old recipe at different hardware. Changing names preserves entity identity. The default room retains its legacy IDs.
Install the integration and controller together. HACS, the HA integration config flow and the Supervisor app store are separate steps. The guided links open those screens; they cannot pair devices, prove flow or bypass HA confirmations.