Beginner guide · Raspberry Pi and Intel NUC · Updated 18 October 2026

# Build a grow controller
with Home Assistant

Connect your sensors, irrigation and room equipment to Home Assistant. Start with one zone, check that it works, then add more zones.

[I have a Raspberry Pi](#raspberry-pi) [I have an Intel NUC](#intel-nuc) [I already have Home Assistant](#sensors)

[![Crop Steering Status showing All rooms with every sample room and its zones](https://cropsteering.growlabs.nz/feature-img/workspace-dark.webp)](https://cropsteering.growlabs.nz/feature-img/workspace-dark.webp)

***Synthetic demo screenshot.** Status opens All rooms. These are synthetic demo readings, not recommended targets. Choose this browser’s starting page in Settings › Dashboards & display. Click to enlarge.*

## Chapters

1. [01 How the parts fit together](#overview)
2. [02 What you need to start](#minimum)
3. [03 Install on Raspberry Pi](#raspberry-pi)
4. [04 Install on Intel NUC](#intel-nuc)
5. [05 First start and backups](#first-start)
6. [06 Add your sensors](#sensors)
7. [07 Connect valves and pumps](#equipment)
8. [08 Install Crop Steering](#crop-steering)
9. [09 Set up your first zone](#mapping)
10. [10 Test before watering](#commission)
11. [11 Daily use and updates](#operate)
12. [12 Troubleshooting](#troubleshooting)

[Download the commissioning checklist](https://cropsteering.growlabs.nz/tutorials/grow-controller/commissioning-checklist.txt)

## How the parts fit together

Home Assistant runs on a computer at your own site. It connects compatible equipment from different manufacturers and gives you a dashboard you can open on your phone or laptop. You decide what to measure and what to automate.

The dashboard shows air temperature and humidity next to substrate moisture and EC, with each irrigation event and how moisture responded. You can add tank levels, power readings and alerts later. You can swap or add parts from different manufacturers without rebuilding the system.

1. **Sensors take readings.** A substrate probe connects through a supported gateway, such as an Atom Lite running ESPHome. Other devices use their own supported integrations.
2. **The network sends readings to Home Assistant.** Wi-Fi or Ethernet connects the devices to Home Assistant on one Pi or NUC.
3. **Crop Steering runs irrigation.** Its Controller checks the zone's readings, current phase, settings and safety checks, then switches the assigned equipment in order.
4. **Relays switch the equipment.** Suitable relay controls switch the valves and pump. A physical test confirms water is delivered.
5. **Your phone shows the dashboard.** Open the dashboard, review settings and get the alerts you set up. The controller keeps running when the app is closed.

Home Assistant can also connect lighting, HVAC and dehumidification through supported integrations. For a first build, keep your existing climate controllers or set up separate HA automations. Crop Steering's irrigation controller does not replace a full HVAC control system.

The software is free and open source. Hardware, installation and optional services still cost money. Local devices keep working without a cloud connection, as long as the host, local network and equipment are working. Downloads, remote push notifications and online AI need the internet.

The screenshots below are real captures of the software, not mockups. Setup examples use the public demo and sample data. Check hardware wiring and water delivery on your own installation.

## What you need to start

Build one room and one irrigation zone first. Both host options use Home Assistant OS and follow the same device and Crop Steering steps.

*Starter software: where each part is installed and what it does*

| Component | Where it goes | Its job |
| --- | --- | --- |
| Home Assistant OS | Pi or NUC | Hosts Home Assistant and its managed apps. |
| ESPHome Device Builder | HA app store | Builds and updates DIY sensor firmware. Not required to receive readings once devices are flashed. |
| ESPHome integration | Devices & services | Connects ESPHome sensors to Home Assistant. |
| HACS | Community installer | Downloads the Crop Steering integration and its updates. |
| Crop Steering integration | HACS, then Devices & services | Rooms, configuration, entities and the dashboard. |
| Crop Steering Controller | Project's HA app repository | Irrigation decisions and equipment sequencing. |
| Device integrations | Devices & services | The specific route for your switches and instruments. |
| History, automations and backups | Built into Home Assistant | Recent records, supporting room jobs and recovery. |
| Companion App | Operator's phone | Dashboard access and tested notification delivery. |

**Apps to install for the DIY build:** Device Builder and Crop Steering Controller. MQTT, Node-RED, InfluxDB, Grafana, custom dashboard cards and AI are optional. Add ZHA and a supported coordinator only if you choose Zigbee equipment. A prebuilt ESPHome device can join through its native API without an MQTT broker.

### Hardware to have ready

- One always-on host, its suitable supply, storage, Ethernet cable and a router/network.
- A tested air temperature/humidity sensor and a compatible VWC/EC substrate probe for the first zone.
- A suitable valve/switch and a pump if the plumbing requires one, plus known drippers and a measuring jug.
- Working lighting and climate controls. Suitable electrical protection, pump dry-run protection and a means to isolate water and power.
- Feed-quality checks and any tank/leak instruments needed by your design. An estimated tank level is not a physical low-water interlock.
- A backup destination outside the host and an operator phone for alerts.

**Before continuing:** Check the exact device models, electrical ratings and integration support before buying. A matching connector or familiar brand name does not prove compatibility.

## Install Home Assistant on a Raspberry Pi

Use a Pi 4 or 5 with a matching power supply, suitable case/cooling, Ethernet and an A2 microSD card of at least 32 GB. Home Assistant's official baseline is at least 2 GB RAM. A Pi with 4 GB or more gives the DIY build more room. This is not a claim about how large a facility it can run.

1. Install [Raspberry Pi Imager](https://www.raspberrypi.com/software/) on your computer.
2. Choose **Other specific-purpose OS → Home automation → Home Assistant**, then the image for your Pi model.
3. Select the intended card by its name/capacity. Writing the image erases it. Let writing and verification finish, then eject it.
4. Insert the card, connect Ethernet to your network, then connect the correct supply.
5. Open `http://homeassistant.local:8123` from the same network. If the name fails, find the host's IP in your router and use that address with port 8123.

[Open the official Pi installation walkthrough and its current screenshots →](https://www.home-assistant.io/installation/raspberrypi/)

**Before continuing:** The Home Assistant welcome screen loads. Continue at [First start and backups](#first-start); skip the NUC chapter.

## Install Home Assistant on an Intel NUC

Use a dedicated 64-bit UEFI-capable NUC or mini PC with a suitable internal SSD, Ethernet, a temporary screen/keyboard and an Ubuntu live USB. This installs Home Assistant OS onto the selected drive and replaces its existing contents. Back it up first.

1. Use the [official generic x86-64 guide](https://www.home-assistant.io/installation/generic-x86-64/) to check UEFI, Secure Boot and drive compatibility for your machine.
2. Boot the Ubuntu live USB and choose **Try Ubuntu**.
3. Download the generic x86-64 HAOS image. In Ubuntu's Disks tool, identify the destination internal drive and choose **Restore Disk Image**. Confirm its model/capacity before writing.
4. After writing finishes, shut down and remove the live USB. Boot from the internal drive with Ethernet connected.
5. Open `http://homeassistant.local:8123`, or the assigned IP and port 8123.

The official walkthrough includes BIOS and disk-restore screenshots. Menu appearance differs between NUC models. It also covers missing boot entries and supported storage sector sizes.

**Before continuing:** The NUC starts Home Assistant with the USB removed. From here, both hosts follow the same steps.

## First start, backups and the phone app

1. Complete [Home Assistant onboarding](https://www.home-assistant.io/getting-started/onboarding/): create your administrator account and verify location, time zone and units.
2. Give the host a stable address with a router DHCP reservation where available. Keep sensor boards and HA on networks that can communicate.
3. Open **Settings → System → Backups**. Create a backup, set a schedule and save a copy outside this computer. Store any backup recovery/encryption information safely.
4. Install the [Home Assistant Companion App](https://companion.home-assistant.io/) and connect it to your instance. Verify a notification reaches the actual phone.
5. Note the host and HA versions. Restart the host once and check the dashboard comes back before adding irrigation.

**Before continuing:** You can sign in, the time is right and you have an off-host backup you can recover. A backup kept only on the host does not protect against losing that host.

## Add your sensors

### Start with an air sensor

1. Install **ESPHome Device Builder** from Home Assistant's app store. Follow the [ESPHome getting-started guide](https://esphome.io/install/getting-started/).
2. Select the configuration for your exact board and sensor. Keep all included files together, use a unique device name and put Wi-Fi credentials in local secrets.
3. Validate, build and flash over a USB data cable. A verified factory image is another route for devices that publish one.
4. In **Settings → Devices & services**, add the discovered ESPHome device. If discovery fails, add the ESPHome integration using its IP. Supply its API encryption key if configured.
5. Check temperature/RH units, freshness and comparison with a trusted reference. Position the sensor away from spray and direct equipment heat.

A supported finished air sensor can use its native integration instead. Select a model with a documented configuration; this guide does not imply every ESP32 board has an air sensor built in.

### Add a substrate probe with an Atom Lite

The project owner uses an SDI-12 probe (a TEROS 12, as one example) with an Atom Lite, wired as described here. That does not mean every SDI-12 probe works the same way. Check the probe label, manual, electrical interface and measurement format.

1. Inspect the [sensor compatibility notes](https://github.com/JakeTheRabbit/TDR-Sensor/blob/main/docs/SENSORS.md) and choose the correct parser/calibration for your exact probe. The stock MT22 RAW conversion must not be assumed correct for another probe.
2. For the repository's Atom Lite build, the configured data pin is GPIO26. Confirm power, ground, data and any required SDI-12 interface against the exact hardware; wire colours differ by probe. Half-duplex software does not provide voltage protection.
3. Use the [flashing guide](https://github.com/JakeTheRabbit/TDR-Sensor/blob/main/docs/FLASHING.md) and [configuration guide](https://github.com/JakeTheRabbit/TDR-Sensor/blob/main/docs/CONFIG.md). Keep the board's framework and package structure. Check that a published firmware asset actually matches the desired version.
4. Confirm probe responses in logs, add the ESPHome device to HA, and verify VWC, conductivity and temperature units. Distinguish bulk EC, pore EC and feed EC.
5. Use probe-specific placement and calibration guidance, record a reference comparison and check the observed wetting/drying response before using it to control water.

[![Crop Steering public demo showing probe values and diagnostics](https://cropsteering.growlabs.nz/feature-img/probes-dark.webp)](https://cropsteering.growlabs.nz/feature-img/probes-dark.webp)

***Synthetic demo screenshot.** Use Sensors to inspect values and units. Example devices and data are synthetic; the firmware and wiring are configured separately in ESPHome. Click to enlarge.*

**Before continuing:** The intended sensors report fresh, plausible readings with the right units. Keep irrigation disabled if a required reading is missing or the probe conversion is unverified.

## Connect valves and pumps, one at a time

Add switches using their actual integration, such as [Shelly](https://www.home-assistant.io/integrations/shelly/), ESPHome or [ZHA](https://www.home-assistant.io/integrations/zha/). A professional pump, compressor or lighting circuit needs switching appropriate to its electrical load and starting current, with suitable contactors or manufacturer control inputs where required.

1. Label each switch by the equipment it really operates. Verify ON and OFF with a harmless load before connecting the operating equipment.
2. Identify the plumbing: **Zone valves only** for an already pressurised supply, or **A pump, then zone valves** when water requires the shared pump.
3. With safe test discharge, check one zone and any pump sequence. Confirm water stops and cannot continue siphoning.
4. Catch a dripper's output for a measured duration. Record actual flow, drippers per plant, plant count and substrate litres per plant.
5. Check any low-water, leak and feed-quality devices and how their states will be used. Keep physical protections that work without any network command.

Leave mains wiring to a qualified installer. Do not open mains smart plugs to flash them as part of this beginner guide. Each output should be switched by one controller only. A second timer or automation must not also switch it.

[![Public demo equipment mapping for a pump and mainline](https://cropsteering.growlabs.nz/feature-img/pump-mainline-dark.webp)](https://cropsteering.growlabs.nz/feature-img/pump-mainline-dark.webp)

***Synthetic demo screenshot.** Equipment mappings describe the existing installation. A diagram or an ON state cannot verify the plumbing or water flow. Click to enlarge.*

**Before continuing:** Know exactly which switch runs which device. Measured delivery, physical stop and isolation are checked before the irrigation engine is enabled.

## Install the integration and the Controller

This guide covers integration **3.18.1** and Controller **3.18.1**. Install matching stable versions of both. The dashboard comes with the integration; no custom Lovelace card pack is needed.

1. Create another backup. Install HACS using its [official download instructions](https://www.hacs.xyz/docs/use/download/download/), then complete its Home Assistant integration setup and GitHub authorisation. Restart when instructed.
2. [Open Crop Steering in HACS](https://my.home-assistant.io/redirect/hacs_repository/?owner=JakeTheRabbit&repository=HA-Irrigation-Strategy&category=integration). Download the stable integration, then restart Home Assistant.
3. [Add the Crop Steering integration](https://my.home-assistant.io/redirect/config_flow_start/?domain=crop_steering). Select manual setup, enter a generic room name and initial zone count.
4. [Add the project's app repository](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2FJakeTheRabbit%2FHA-Irrigation-Strategy). Install **Crop Steering Controller** at the same version. Review its options with irrigation engine flags OFF.
5. Start the Controller, keep **Start on boot** enabled and enable **Watchdog**. HAOS gives the Controller its access to Home Assistant. Don't put access tokens in public device configurations.
6. Open **Crop Steering** in the HA sidebar. Verify the Controller heartbeat and displayed versions. Keep watering disabled while mapping.

The My Home Assistant links open the relevant screens in your own instance; they still require your confirmation. If the Controller starts before a room exists, the current release waits for setup. [The full installation guide](https://cropsteering.growlabs.nz/install) includes upgrades, Docker alternatives and rollback.

[![Public demo showing setup and controller acknowledgement status](https://cropsteering.growlabs.nz/feature-img/setup-status-dark.webp)](https://cropsteering.growlabs.nz/feature-img/setup-status-dark.webp)

***Synthetic demo screenshot.** Saving the configuration is not the same as the Controller acknowledging it; check both. Mapping, sizing and the room’s hardware settings are in Equipment › Setup. Click to enlarge.*

**Before continuing:** Both parts are installed at matching versions, the heartbeat is current, and watering remains disabled.

## Assign sensors and valves to your first zone

1. Open **Equipment → Setup: pumps & valves**. Select your room and name the first zone.
2. Choose its valve and VWC/EC entities. Check friendly names, entity IDs, units and current values. You can assign more than one probe; if they disagree, find out why.
3. Choose the room's plumbing layout and map the shared pump only where the topology requires it. Add the other required hardware and any supported interlocks.
4. Enter substrate litres **per plant**, plant count, drippers per plant and dripper flow. Use the catch-test result.
5. Select **Review configuration**, inspect the proposed mappings, then **Save configuration**. Wait for **Mapping acknowledged**.
6. Set the lighting schedule and review each zone's phase settings, shot sizes, emergency floor and water limits. Demo values are examples, not crop recommendations.

[![Public demo zone setup form for sensor and valve mapping](https://cropsteering.growlabs.nz/feature-img/setup-zone-dark.webp)](https://cropsteering.growlabs.nz/feature-img/setup-zone-dark.webp)

***Synthetic demo screenshot.** Map your own entities. The example names and values are sample data, not a configuration to copy into a live room. Click to enlarge.*

[![Catch-test calculator for comparing measured water with configured delivery](https://cropsteering.growlabs.nz/feature-img/catch-test-dark.webp)](https://cropsteering.growlabs.nz/feature-img/catch-test-dark.webp)

***Synthetic demo screenshot.** Measure actual output. The calculator proposes a correction for review; a computed volume is not measured delivery. Click to enlarge.*

**Before continuing:** The Controller acknowledges the mapping. All required readings are fresh, the correct equipment is assigned and your catch test agrees with the configured flow.

## Test one zone before turning on watering

Do these checks with someone present, using safe discharge or bench equipment. Don't test faults on a live crop.

1. Run a short supervised test shot using the supported manual control. Observe which valve and pump operate, measure delivery and confirm they stop.
2. Test the kill switch, configured holds, water limits and hardware OFF readback against the installed release. Record expected and observed results.
3. On the bench, test loss of the required sensor, network connection and host power. Verify actual equipment behaviour, not just HA state. Provide device-local timeouts or independent protections where the equipment can otherwise remain on.
4. Check lighting and climate control have a clear owner and recover as intended. Irrigation testing does not prove the rest of the room is controlled.
5. Test notifications on the actual phone and confirm who will respond. Record the fallback for failed internet or push delivery.
6. Enable only the tested zone, attend its first cycles and follow the moisture response. Expand by repeating the same checks for the next zone.

[![Public demo safety settings and irrigation limits](https://cropsteering.growlabs.nz/feature-img/safety-limits-dark.webp)](https://cropsteering.growlabs.nz/feature-img/safety-limits-dark.webp)

***Synthetic demo screenshot.** Review the installed release's safeguards. Example limits in this screenshot do not establish safe values for your crop or equipment. Click to enlarge.*

**Before continuing:** Complete the [commissioning checklist](https://cropsteering.growlabs.nz/tutorials/grow-controller/commissioning-checklist.txt). Saving the setup, passing the physical tests and being ready to run unattended are separate steps.

## Daily use, alerts and updates

Each time you check the room, start with controller status, sensor availability and any hold or alert. On Status › Today, see the phase and what will trigger the next watering; open a zone to see its history. Don't confuse measured values with calculated delivery or projected trends.

[![Public demo zone chart with recorded VWC and EC](https://cropsteering.growlabs.nz/feature-img/zone-day-chart-dark.webp)](https://cropsteering.growlabs.nz/feature-img/zone-day-chart-dark.webp)

***Synthetic demo screenshot.** Read the recorded moisture/EC response beside irrigation events. Projections and example data are labelled in the app. Click to enlarge.*

Configure the operator's phones in **Settings → Notifications**. Choose rooms and alert categories, then check the alerts arrive. Lighting and climate automations should not switch any output that Crop Steering controls.

[![Public demo notification configuration for operator phones and alert categories](https://cropsteering.growlabs.nz/feature-img/notifications-dark.webp)](https://cropsteering.growlabs.nz/feature-img/notifications-dark.webp)

***Synthetic demo screenshot.** Send only the relevant rooms and alert types to each operator. A saved destination needs a real delivery test. Click to enlarge.*

Back up before updates, update the integration and Controller together, and check versions, heartbeat, mappings and settings afterwards. Keep an off-host copy and rehearse recovery on spare hardware. Add longer history, additional sensors or AI only when there is a specific job for them.

### Moving from an existing grow controller

Inventory exact devices, wiring, settings and exportable records first. Verify which equipment has a reusable interface. Build separately, move one tested zone during an attended change window and keep a rollback path. Do not connect two active controllers to one output or assume two gateways can share a probe bus.

[Explore released features](https://cropsteering.growlabs.nz/features) · [Try the isolated demo](https://cropsteering.growlabs.nz/demo)

The Irrigation page shows Current day and Calendar next to the same VWC and EC planning canvas. Review current-day drafts before applying them; calendar plans have their own save, review and arm controls. History holds grow records and the full explorer. Capabilities lists the available functions; each setting is changed on the page it links to.

## Troubleshooting

*Common setup problems*

| What you see | What to check |
| --- | --- |
| Home Assistant does not open | Power, Ethernet, matching HAOS image and router IP. Try the IP with port 8123 if the local hostname fails. |
| No USB device to flash | Use a USB data cable, correct port and the board manufacturer's serial driver if needed. |
| ESPHome is not discovered | Verify its IP and network reachability, then add it manually under Devices & services. Check the encryption key. |
| Probe values are unknown or implausible | Exact probe/board, safe electrical interface, pin, address, framework, parser and units. Keep irrigation off until resolved. |
| No Controller heartbeat | Controller app started, matching version, logs and access to Home Assistant. Installing only the integration is insufficient. |
| Saved but not acknowledged | Controller freshness, validation errors and mapping revision. Do not enable watering just because Save succeeded. |
| Watering is held | Read the zone's waiting reason and error code. Resolve the cause; do not bypass safeguards to make the display green. |
| Switch says ON but no water arrives | Isolate safely and check the actual valve, pump, supply, plumbing and drippers. A reported state is not a flow measurement. |

For current field meanings, release limits and error codes, use the [project documentation](https://cropsteering.growlabs.nz/docs). This guide has not been independently tested from a blank host or on every hardware combination. The screenshots show the software's interface; they do not show that every device is compatible.

Sources: official Home Assistant installation, onboarding and backup guides; ESPHome and HACS documentation; the Crop Steering installation/user guides; TDR-Sensor compatibility, wiring and flashing notes. Screenshots: the current dashboard with synthetic sample data. No AI-generated dashboard images are used in this guide. A grow-control tutorial is not facility compliance certification.

Source: https://cropsteering.growlabs.nz/tutorials