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.
Printed from cropsteering.growlabs.nz/system-map, version 3.18.1.
Overview diagram
The full diagram, shrunk to fit. Open the SVG to zoom in, or use the layers below.
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.
01Your devicesProbes, valves, pumps, meters, tanks, lights
Required
Moisture (VWC) probe per zoneRequired
- 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
Valve switch per zoneRequired
- 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
If your plumbing has them
Pump and main-line valveIf 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
Waste valveOptional
- 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 probesRecommended
- 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 probesRecommended
- 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
Optional
Tank level or low floatOptional
- 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 metersOptional
- 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
Dosing pumps and batch tankOptional
- 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
LightsOptional
- 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 stateOptional
- 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 interlocksOptional
- 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 temperatureDisplay 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 → 02Ways into Home AssistantSet 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
ESPHomeBuilt 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.
ZigbeeBuilt 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-WaveBuilt in
- What it is
- Mesh radio devices.
- Needed
- Built in
- Entity types
- switches, valves, sensors
- What Crop Steering does
- Becomes ordinary entities.
MQTTBuilt 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.
ModbusBuilt 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 integrationsBuilt 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 templatesBuilt 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.
02Home AssistantTurns every device into an entity
What Crop Steering uses
EntitiesBuilt 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
HistoryBuilt 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
Notifications and Repairs cardsBuilt 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
03Crop SteeringThe 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 commissioningBuilt 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
Probe fusionBuilt 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 entitiesBuilt 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
Services APIBuilt 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
Stores and event journalBuilt 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
Sidebar dashboardBuilt 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
Controller (the only part that switches hardware)
Control loopBuilt 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
Steering engineBuilt 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 programsBuilt 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
Safety checksBuilt 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
Pump queueBuilt 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
Shot sequenceBuilt 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 checksBuilt 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
Dosing runnerBuilt 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
Optional AI judgesOptional
- 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
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.
04YouDashboard, phone alerts, optional AI
How you see and change it
DashboardBuilt 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
Alerts on your phonesBuilt 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
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
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 Minimum setup for one zone What is not supported
Table of all parts
Every part of the map in one table, for screen readers, search, or reading as text.
| 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
Safety features Entity reference The MCP connector Install guide