# System map

Four layers, left to right: your devices, Home Assistant, Crop Steering, and you. Select a layer to see its parts. This map is based on the code of version 3.18.1.

## Overview diagram

The full diagram, shrunk to fit. Open the SVG to zoom in, or use the layers below.

*Solid squares are required or built in; dashed are optional. Red dashed lines with a lock mark actions that are never allowed. [Open the SVG on its own](https://cropsteering.growlabs.nz/system-map.svg).*

## Parts of each layer

Open a layer, then a part, to see what it is, whether you need it, which entity types and units it accepts, and what Crop Steering does with it.

**01 Your devices Probes, valves, pumps, meters, tanks, lights**

### Required

**Moisture (VWC) probe per zone Required**

**What it is**
: A probe in the substrate that reports how wet it is.
**Needed**
: Required
**Entity types**
: sensor
**Units**
: %, m³/m³
**What Crop Steering does**
: Several probes in a zone become one reading (median by default). Silent or out-of-range probes are left out.
**Read more**
: [Hardware: what you need, by role](https://cropsteering.growlabs.nz/hardware#roles)

**Valve switch per zone Required**

**What it is**
: The valve, relay or smart plug that lets water into one zone.
**Needed**
: Required
**Entity types**
: switch, valve, input_boolean
**What Crop Steering does**
: Opened and closed for each shot, then read back to confirm it switched.
**Read more**
: [Hardware: what you need, by role](https://cropsteering.growlabs.nz/hardware#roles)

### If your plumbing has them

**Pump and main-line valve If your plumbing has it**

**What it is**
: The irrigation pump and the valve on the main line, when the room has them.
**Needed**
: If your plumbing has it
**Entity types**
: switch, valve, input_boolean
**What Crop Steering does**
: Pump on first, main line next, zone valve last; off in reverse. The plumbing layout you choose must match the switches you map.
**Read more**
: [Water supply, pump queue and flow checks](https://cropsteering.growlabs.nz/docs/water-supply)

**Waste valve Optional**

**What it is**
: A valve to drain, on rooms that have one.
**Needed**
: Optional
**Entity types**
: switch
**What Crop Steering does**
: Only ever switched off (closed) for a shot.

### Recommended

**Substrate EC probes Recommended**

**What it is**
: Probes that read the salt level in the root zone.
**Needed**
: Recommended
**Entity types**
: sensor
**Units**
: mS/cm, dS/m, µS/cm
**What Crop Steering does**
: EC steering. Without them, watering runs on moisture and the EC rules pause.

**Feed EC and pH probes Recommended**

**What it is**
: Probes on the water you feed.
**Needed**
: Recommended
**Entity types**
: sensor
**Units**
: EC units above; pH
**What Crop Steering does**
: Safety checks on the feed before a shot.
**Read more**
: [What gets checked before each shot](https://cropsteering.growlabs.nz/safety#checks)

### Optional

**Tank level or low float Optional**

**What it is**
: A distance sensor or a float switch on the feed tank.
**Needed**
: Optional
**Entity types**
: sensor (distance), binary_sensor
**What Crop Steering does**
: Holds watering below the tank minimum.

**Flow meters Optional**

**What it is**
: A meter on a pump or a zone line.
**Needed**
: Optional
**Entity types**
: sensor
**What Crop Steering does**
: Each shot is checked against the meter, and water with no zone open raises a leak alert. Alerts only; it never holds a shot.
**Read more**
: [Water supply, pump queue and flow checks](https://cropsteering.growlabs.nz/docs/water-supply)

**Dosing pumps and batch tank Optional**

**What it is**
: Up to 8 dosing pumps per room that time their own doses.
**Needed**
: Optional
**Entity types**
: number (volume) + button or script (start)
**What Crop Steering does**
: Batch-tank dosing and opt-in pH correction. Watering holds during a batch.
**Read more**
: [Batch-tank dosing](https://cropsteering.growlabs.nz/docs/dosing)

**Lights Optional**

**What it is**
: The grow light, read as a light or a switch.
**Needed**
: Optional
**Entity types**
: light, switch
**What Crop Steering does**
: Checked against your schedule. Opt-in dimming when the substrate is dry: never off, never below 30 %.

**Air temperature, humidity, VPD; AC and dehumidifier state Optional**

**What it is**
: Climate readings you already have.
**Needed**
: Optional
**Entity types**
: sensor, climate, switch
**What Crop Steering does**
: Read only, for records and the runoff estimate. Never controlled.

**External interlocks Optional**

**What it is**
: Any entity you want to pause watering, such as a maintenance switch.
**Needed**
: Optional
**Entity types**
: any entity
**What Crop Steering does**
: Shots hold while one is on.

### Shown on the dashboard only

**CO2, light level, camera, leaf and root-zone temperature Display only**

**What it is**
: Readings you want to see beside your zones.
**Needed**
: Display only
**Entity types**
: sensor, camera
**What Crop Steering does**
: Shown on the dashboard. The controller reads none of them.

**01 → 02 Ways into Home Assistant Set up in Home Assistant, not in Crop Steering**

These are Home Assistant's ways of connecting devices, not Crop Steering features. Home Assistant's own documentation covers pairing and setup.

### Routes

**ESPHome Built in**

**What it is**
: Wi-Fi boards running local firmware.
**Needed**
: Built in
**Entity types**
: sensors, switches, valves, dosing number + button
**What Crop Steering does**
: Many grow sensors and relays reach Home Assistant this way.

**Zigbee Built in**

**What it is**
: Low-power mesh radio devices.
**Needed**
: Built in
**Entity types**
: switches, plugs, valves, leak and float sensors
**What Crop Steering does**
: Some plugs report their state slowly; the controller allows up to 6 seconds, then sends off again and waits 10 seconds more before it holds the room.

**Z-Wave Built in**

**What it is**
: Mesh radio devices.
**Needed**
: Built in
**Entity types**
: switches, valves, sensors
**What Crop Steering does**
: Becomes ordinary entities.

**MQTT Built in**

**What it is**
: Devices that publish to a message broker.
**Needed**
: Built in
**Entity types**
: any type the device declares
**What Crop Steering does**
: Becomes ordinary entities.

**Modbus Built in**

**What it is**
: Wired industrial meters and controllers.
**Needed**
: Built in
**Entity types**
: sensors, switches, binary sensors
**What Crop Steering does**
: Common for wired industrial meters.

**Vendor integrations Built in**

**What it is**
: The device maker's own Home Assistant integration.
**Needed**
: Built in
**Entity types**
: whatever it exposes
**What Crop Steering does**
: Prefer local integrations: a cloud dependency is a reliability risk for watering.

**Helpers and templates Built in**

**What it is**
: Home Assistant's built-in helpers.
**Needed**
: Built in
**Entity types**
: input_boolean, input_number, template sensors
**What Crop Steering does**
: A virtual switch can stand in for a valve while you test.

**02 Home Assistant Turns every device into an entity**

### What Crop Steering uses

**Entities Built in**

**What it is**
: Sensors, switches, valves, numbers and buttons: one per thing Home Assistant can read or switch.
**Needed**
: Built in
**What Crop Steering does**
: Crop Steering checks two things about each: the kind of entity and its unit.
**Read more**
: [Entity reference](https://cropsteering.growlabs.nz/docs/entities)

**History Built in**

**What it is**
: Home Assistant's recorder, plus an optional long-term history database.
**Needed**
: Built in
**What Crop Steering does**
: Feeds the dashboard's charts and History pages.
**Read more**
: [Long history](https://cropsteering.growlabs.nz/docs/long-history)

**Notifications and Repairs cards Built in**

**What it is**
: Home Assistant's own alerts and phone pushes.
**Needed**
: Built in
**What Crop Steering does**
: Every alert arrives here with its code.
**Read more**
: [Notifications](https://cropsteering.growlabs.nz/docs/notifications)

**03 Crop Steering The integration and the controller**

### Integration (inside Home Assistant)

This part never switches hardware: Only the controller does, and only after the safety checks pass.

**Setup and commissioning Built in**

**What it is**
: Rooms, zones, valve and probe mapping, plumbing layout and unit checks.
**Needed**
: Built in
**What Crop Steering does**
: For a new room, the setup wizard does not offer Switch on until every valve reads off, each probe reports a usable unit and a person has confirmed a test shot.
**Read more**
: [Install guide](https://cropsteering.growlabs.nz/docs/install)

**Probe fusion Built in**

**What it is**
: Many probes become one moisture and one EC reading per zone.
**Needed**
: Built in
**What Crop Steering does**
: Silent, out-of-range and outlier probes are left out; calibration offsets are applied.

**Settings entities Built in**

**What it is**
: Every target, limit and switch as a Home Assistant entity.
**Needed**
: Built in
**What Crop Steering does**
: The kill switch, room switch and zone switches live here.
**Read more**
: [Entity reference](https://cropsteering.growlabs.nz/docs/entities)

**Services API Built in**

**What it is**
: Documented Home Assistant services for setup, plans, timers, alerts and history.
**Needed**
: Built in
**What Crop Steering does**
: Response services can return a versioned envelope with revision, read-back and typed errors.
**Read more**
: [MCP and the API envelope](https://cropsteering.growlabs.nz/docs/mcp)

**Stores and event journal Built in**

**What it is**
: Plans, presets, timers, alert rules, dosing, calibration, runs and harvests, and one journal of events.
**Needed**
: Built in
**What Crop Steering does**
: Every shot, hold, dose and phase change is recorded, and every setting change records who made it.
**Read more**
: [History and changes](https://cropsteering.growlabs.nz/docs/history-and-changes)

**Sidebar dashboard Built in**

**What it is**
: The Crop Steering page in the Home Assistant sidebar.
**Needed**
: Built in
**What Crop Steering does**
: Serves the dashboard; no dashboard YAML to write.
**Read more**
: [Home Assistant sidebar](https://cropsteering.growlabs.nz/docs/dashboards-and-display#inside-home-assistant)

### Controller (the only part that switches hardware)

**Control loop Built in**

**What it is**
: Every minute: read each zone, decide, check, water, publish.
**Needed**
: Built in
**What Crop Steering does**
: Runs as a Home Assistant app or a Docker container.
**Read more**
: [The controller](https://cropsteering.growlabs.nz/docs/controller)

**Steering engine Built in**

**What it is**
: Finds each zone's phase, P0 to P3, and decides whether and how much to water.
**Needed**
: Built in
**What Crop Steering does**
: Sizes each shot from the substrate volume and plant count, adjusted for pore EC; times it from the dryback.

**Timer programs Built in**

**What it is**
: Zones set to water by timer follow their program.
**Needed**
: Built in
**What Crop Steering does**
: Timer shots go through the same safety checks.
**Read more**
: [Timer programs and modes](https://cropsteering.growlabs.nz/docs/timers-and-modes)

**Safety checks Built in**

**What it is**
: A fixed, ordered list of checks before every shot.
**Needed**
: Built in
**What Crop Steering does**
: If any check fails, the shot is held and the reason is logged with an alert code.
**Read more**
: [What gets checked before each shot](https://cropsteering.growlabs.nz/safety#checks)

**Pump queue Built in**

**What it is**
: Orders zones that share a pump.
**Needed**
: Built in
**What Crop Steering does**
: It only orders shots; it never cancels one. One zone opens at a time.
**Read more**
: [Water supply, pump queue and flow checks](https://cropsteering.growlabs.nz/docs/water-supply)

**Shot sequence Built in**

**What it is**
: Pump, main line, zone valve, in order.
**Needed**
: Built in
**What Crop Steering does**
: Re-checks the kill switch and holds every 2 seconds during the shot, then closes in reverse.

**Read-back and shot checks Built in**

**What it is**
: Every switch is read back on and then off.
**Needed**
: Built in
**What Crop Steering does**
: Water is counted, compared with a flow meter if you have one, and the moisture response is checked.
**Read more**
: [How it checks each shot actually happened](https://cropsteering.growlabs.nz/safety#prove)

**Dosing runner Built in**

**What it is**
: Batches, doses, mix checks and opt-in pH correction.
**Needed**
: Built in
**What Crop Steering does**
: Holds watering during a batch; every dosing switch is read back.
**Read more**
: [Batch-tank dosing](https://cropsteering.growlabs.nz/docs/dosing)

**Optional AI judges Optional**

**What it is**
: Answers to questions the controller asks, such as 'Is the substrate full?'.
**Needed**
: Optional
**What Crop Steering does**
: Code checks every answer against hard limits. It can never run a pump or a valve.
**Read more**
: [What the AI does](https://cropsteering.growlabs.nz/how-it-works#ai)

AI cannot run a pump or valve: Neither the AI judges inside the controller nor an AI assistant connected through MCP can switch hardware, start a shot or stop a safety action.

Fail-safe: An unreadable kill switch or room switch counts as off, so nothing waters.

**04 You Dashboard, phone alerts, optional AI**

### How you see and change it

**Dashboard Built in**

**What it is**
: All rooms, then a room, then a zone with every shot on its day chart.
**Needed**
: Built in
**What Crop Steering does**
: Edits stay a draft until you review and apply them; each value is read back.
**Read more**
: [User guide](https://cropsteering.growlabs.nz/docs/user-guide)

**Alerts on your phones Built in**

**What it is**
: Pushes by alert kind, chosen per phone, with quiet hours.
**Needed**
: Built in
**What Crop Steering does**
: Each alert carries a code with its meaning and fix.
**Read more**
: [Alerts](https://cropsteering.growlabs.nz/docs/alerts)

**Optional AI assistant (MCP) Optional**

**What it is**
: An AI assistant on your computer, connected through the MCP connector.
**Needed**
: Optional
**What Crop Steering does**
: Reads your setup and prepares changes you approve. It has no tool to run pumps or valves.
**Read more**
: [AI and MCP setup](https://cropsteering.growlabs.nz/docs/ai-setup)

AI cannot run a pump or valve: Neither the AI judges inside the controller nor an AI assistant connected through MCP can switch hardware, start a shot or stop a safety action.

## Device roles, the minimum kit and what isn't supported

Crop Steering does not connect to devices directly. It uses them through Home Assistant. The hardware guide lists each role with its entity types and units, the minimum setup for one zone, and what is not supported.

[Required and optional hardware](https://cropsteering.growlabs.nz/hardware#roles) [Minimum setup for one zone](https://cropsteering.growlabs.nz/hardware#minimum) [What is not supported](https://cropsteering.growlabs.nz/hardware#will-not-work)

## Table of all parts

Every part of the map in one table, for screen readers, search, or reading as text.

*Every part of the system map, layer by layer*

| Layer | Part | Needed | Entity types | What Crop Steering does |
| --- | --- | --- | --- | --- |
| Your devices | Moisture (VWC) probe per zone | Required | sensor | Several probes in a zone become one reading (median by default). Silent or out-of-range probes are left out. |
| Your devices | Valve switch per zone | Required | switch, valve, input_boolean | Opened and closed for each shot, then read back to confirm it switched. |
| Your devices | Pump and main-line valve | If your plumbing has it | switch, valve, input_boolean | Pump on first, main line next, zone valve last; off in reverse. The plumbing layout you choose must match the switches you map. |
| Your devices | Waste valve | Optional | switch | Only ever switched off (closed) for a shot. |
| Your devices | Substrate EC probes | Recommended | sensor | EC steering. Without them, watering runs on moisture and the EC rules pause. |
| Your devices | Feed EC and pH probes | Recommended | sensor | Safety checks on the feed before a shot. |
| Your devices | Tank level or low float | Optional | sensor (distance), binary_sensor | Holds watering below the tank minimum. |
| Your devices | Flow meters | Optional | sensor | Each shot is checked against the meter, and water with no zone open raises a leak alert. Alerts only; it never holds a shot. |
| Your devices | Dosing pumps and batch tank | Optional | number (volume) + button or script (start) | Batch-tank dosing and opt-in pH correction. Watering holds during a batch. |
| Your devices | Lights | Optional | light, switch | Checked against your schedule. Opt-in dimming when the substrate is dry: never off, never below 30 %. |
| Your devices | Air temperature, humidity, VPD; AC and dehumidifier state | Optional | sensor, climate, switch | Read only, for records and the runoff estimate. Never controlled. |
| Your devices | External interlocks | Optional | any entity | Shots hold while one is on. |
| Your devices | CO2, light level, camera, leaf and root-zone temperature | Display only | sensor, camera | Shown on the dashboard. The controller reads none of them. |
| Ways into Home Assistant | ESPHome | Built in | sensors, switches, valves, dosing number + button | Many grow sensors and relays reach Home Assistant this way. |
| Ways into Home Assistant | Zigbee | Built in | switches, plugs, valves, leak and float sensors | Some plugs report their state slowly; the controller allows up to 6 seconds, then sends off again and waits 10 seconds more before it holds the room. |
| Ways into Home Assistant | Z-Wave | Built in | switches, valves, sensors | Becomes ordinary entities. |
| Ways into Home Assistant | MQTT | Built in | any type the device declares | Becomes ordinary entities. |
| Ways into Home Assistant | Modbus | Built in | sensors, switches, binary sensors | Common for wired industrial meters. |
| Ways into Home Assistant | Vendor integrations | Built in | whatever it exposes | Prefer local integrations: a cloud dependency is a reliability risk for watering. |
| Ways into Home Assistant | Helpers and templates | Built in | input_boolean, input_number, template sensors | A virtual switch can stand in for a valve while you test. |
| Home Assistant | Entities | Built in | — | Crop Steering checks two things about each: the kind of entity and its unit. |
| Home Assistant | History | Built in | — | Feeds the dashboard's charts and History pages. |
| Home Assistant | Notifications and Repairs cards | Built in | — | Every alert arrives here with its code. |
| Crop Steering | Setup and commissioning | Built in | — | For a new room, the setup wizard does not offer Switch on until every valve reads off, each probe reports a usable unit and a person has confirmed a test shot. |
| Crop Steering | Probe fusion | Built in | — | Silent, out-of-range and outlier probes are left out; calibration offsets are applied. |
| Crop Steering | Settings entities | Built in | — | The kill switch, room switch and zone switches live here. |
| Crop Steering | Services API | Built in | — | Response services can return a versioned envelope with revision, read-back and typed errors. |
| Crop Steering | Stores and event journal | Built in | — | Every shot, hold, dose and phase change is recorded, and every setting change records who made it. |
| Crop Steering | Sidebar dashboard | Built in | — | Serves the dashboard; no dashboard YAML to write. |
| Crop Steering | Control loop | Built in | — | Runs as a Home Assistant app or a Docker container. |
| Crop Steering | Steering engine | Built in | — | Sizes each shot from the substrate volume and plant count, adjusted for pore EC; times it from the dryback. |
| Crop Steering | Timer programs | Built in | — | Timer shots go through the same safety checks. |
| Crop Steering | Safety checks | Built in | — | If any check fails, the shot is held and the reason is logged with an alert code. |
| Crop Steering | Pump queue | Built in | — | It only orders shots; it never cancels one. One zone opens at a time. |
| Crop Steering | Shot sequence | Built in | — | Re-checks the kill switch and holds every 2 seconds during the shot, then closes in reverse. |
| Crop Steering | Read-back and shot checks | Built in | — | Water is counted, compared with a flow meter if you have one, and the moisture response is checked. |
| Crop Steering | Dosing runner | Built in | — | Holds watering during a batch; every dosing switch is read back. |
| Crop Steering | Optional AI judges | Optional | — | Code checks every answer against hard limits. It can never run a pump or a valve. |
| You | Dashboard | Built in | — | Edits stay a draft until you review and apply them; each value is read back. |
| You | Alerts on your phones | Built in | — | Each alert carries a code with its meaning and fix. |
| You | Optional AI assistant (MCP) | Optional | — | Reads your setup and prepares changes you approve. It has no tool to run pumps or valves. |

## Where to go from here

[Check your hardware](https://cropsteering.growlabs.nz/hardware) [How it works](https://cropsteering.growlabs.nz/how-it-works)

[Safety features](https://cropsteering.growlabs.nz/safety) [Entity reference](https://cropsteering.growlabs.nz/docs/entities) [The MCP connector](https://cropsteering.growlabs.nz/docs/mcp) [Install guide](https://cropsteering.growlabs.nz/docs/install)

Source: https://cropsteering.growlabs.nz/system-map