Environmental Control Automation~

AoT's env_coordinator (shown in the UI as Integrated Environment Control) is a 3-layer control system that coordinates every actuator in one facility — vents, exhaust/intake fans, heaters, coolers, misters, shade screens, thermal curtains, supplemental lights and CO₂ injectors.

Two things are decided in two different places, and mixing them up is the single most common source of confusion:

• What to aim for — VPD, CO₂, DLI and the rest — belongs to the plot that is growing in the facility, through the cultivation program attached to it.
• How to get there — which equipment exists, what lines must never be crossed, how eagerly to chase the target — belongs to this function.

Where Targets Come From~

A plot internalises the program it selects. Editing a stage target on the plot screen overrides that one item for that plot only; the program and every other plot using it stay untouched. Clearing the field returns the item to the program value — that is why there is no separate "revert" button.

Two limits are deliberate:

• The plot cannot invent new target items. The vocabulary is the program's (target_defs), so an unknown key is rejected rather than silently ignored.
• An item that follows a curve cannot be overridden with a number. The curve wins, and the plot screen shows that item as read-only.

What the coordinator reads each cycle~

Targets are matched to a control axis by measurement and shape, not by the key name — a user-named item such as "Indoor CO₂" still reaches CO₂ control as long as its measurement is CO₂. An item with no measurement selected reaches no axis at all and is shown as For reference.

When there is no plot~

The coordinator does not stop. With no plot, no program, an AI draft that has not been reviewed, or no stage running today, there are simply no targets: control keeps running inside its own guide ranges, which is already the defined behaviour — an empty greenhouse still needs heating.

Since 2026-09-01 the coordinator has no end-date option of its own. Whether growing continues is the plot's business. The previous behaviour was that a date set once in the function kept the facility stopped even after a new crop was planted.

More than one plot in scope~

Intercropping is normal, so the coordinator never guesses. With two or more plots in its facility/bay scope it says so and offers a Follow this one button; the same choice is stored in Reference Plot under Advanced Settings. If the pinned plot ends or leaves the scope, the value is not erased — the screen says the pinned plot is no longer there and the selection rules are applied again.

The program version recorded on a plot pins the version number, not the content. Editing a program does change the interpretation of plots already in progress.

VPD (Vapor Pressure Deficit)~

VPD is the key metric determining plant transpiration and water uptake.

VPD = SVP × (1 - RH/100)
SVP = 0.6108 × exp(17.27T / (T + 237.3))  [kPa]

env_coordinator Control Layers~

L1 — EnvTarget (setpoint)~

Resolves the targets described above into setpoints for this cycle. A target that follows a Method is evaluated with the plot's elapsed weeks and the facility's local timezone.

L2 — SituationReport (evaluation)~

Evaluates current deviation, limiting factors, and trend.

When VPD can be used, temperature and humidity are demoted to constraints — the range VPD is decomposed into, and the lines that must not be crossed. This function is not a thermostat.

L3 — Coordinator (actuator command)~

Applies PI control + slew rate limiting + anti-windup to command actuators.

e(t) = setpoint - measurement
u(t) = Kp × e(t) + Ki × ∫e dt
slew: |Δu| ≤ slew_rate_per_cycle
output → heater / vent / fan / mister / CO₂ supply

Actuator Domains~

Load sharing happens within a domain, and domains are separated by where the energy ends up — not by how similar the devices look. The settings screen follows the same split.

Because domains do not see each other's work, coordination between them is done by declared interlocks (see Ventilation), never by implicit accumulation of effects.

Roof vents and side vents behave differently~

Both are opening actuators, but the facility drawing distinguishes a ridge (roof) window from a side window, and the effect model uses it:

If the drawing does not say which form an opening is, it behaves exactly as before (no correction).

Function Configuration~

Navigate to Functions → Integrated Environment Control in the AoT UI. Actuators themselves are registered separately (see Registering Actuators) or auto-discovered from the linked facility.

Reading the settings screen~

The screen was rebuilt in 2026-08. Five things are worth knowing before reading the tables below.

A status header sits at the top. Under the facility picker the screen shows what control is doing right now — the current VPD against its target, the position of each device kind (Vents, Heating, Cooling, Misting, Shade …), and how long ago the last decision was made. Below it, a two-line summary names the plot being followed, the stage it is in, and the targets in effect. States where nothing can run are spelled out separately: no facility linked, control switched off, no recent decision. If the plot ends within two weeks, one extra line says so.

Settings are arranged in four layers, not by option type.

A key setting carries its details with it. Instead of asking for a number nobody can answer ("should the emergency multiplier be 3.0 or 4.0?"), the screen asks a question that can be answered and moves several values at once, the way a robot vacuum offers Quiet / Normal / Strong. Three such controls exist: Control Temperament, Ventilation and HVAC Teamwork, and Misting Frequency. The step name itself is never saved — only the real values are, and the current step is inferred back from them. If the values match no step, the control reads Custom.

Ranges are asked as a band with two handles. Temperature and humidity have one question — what range to grow in — and the hard limits are derived from it by a fixed margin (±5 °C, ±5 %RH). One consequence is deliberate: the hard limit can never be tighter than the guide range, so "grow at 12–32 °C but never exceed 30 °C" cannot be expressed. That combination is what once had a heater and a cooler both driven to 100 % against each other.

One [Advanced] switch opens every numeric field. It turns each step scale into a step scale plus its number box, reveals every advanced-only row, and expands the folded groups in one go. The switch lives in the browser only — it is not part of the saved configuration, so two people never see the same function differently because of it. Settings whose parent toggle is off are hidden rather than disabled, so their stored values are still submitted and survive being toggled off and on.

Some settings are read only under a specific condition — the custom actuation period only when the profile is Custom, the night clock times only when night is measured by fixed times. The screen reports a value that was entered but is not being used, because otherwise it silently does nothing.

Commands~

Facility Settings~

Working Hours~

Only the toggle is visible until it is switched on. This is a switch, not a schedule: outside the window the coordinator stops entirely, heating and cooling included. Safety limits still act.

Target and Temperament~

Under [Advanced], each range band also shows the four numbers behind it (Guide T Min/Max, Min/Max Temperature, and the humidity equivalents), and Control Temperament shows its members:

Two further members sit in the same place but are not set by the step, because they are fine adjustments on the same axis: Custom Actuation Period (seconds) — used only when the profile is Custom — and Emergency Minimum Interval (seconds), default 60, the floor between two vent commands even during an emergency.

The actuation profile governs only how often side/roof vents are allowed to move. Sensing and computation always run every cycle period, curtains and shade screens are unaffected (they open or close in one motion), and sudden weather changes or a safety gate move the vents immediately regardless.

Ventilation~

Ventilation and HVAC Teamwork moves three toggles at once:

• Close Vents When Ventilation Cannot Help — ventilation can only pull the inside toward the outside. When the target lies on the far side of the outdoor air, opening moves away from it no matter how wide; the classic case is dehumidifying at night, when outdoor air is wetter than indoor. With this on, vents and exhaust/intake fans park closed instead of holding a partial opening all night.
• Rest Heating and Cooling When Venting Can Reach the Target — when outdoor air is already past the target, ventilation alone gets there and running HVAC alongside pays for what the outside would do for free. Three conditions must all hold: the outdoor value is past the target by more than the tolerance, every controlled variable is, and the vents still have headroom (the last cycle's widest opening below 90 %). If the target is still not reached after 15 minutes, everything is handed back to heating and cooling — the prediction was wrong.
• Keep Vents Closed While Heating or Cooling Runs — venting against a running unit throws that heat or cold straight outside. In a season where outdoor air could help toward the target, this throws that help away too.

Detection of a running unit needs evidence, and there are only two sources: this coordinator commands the unit itself, or you point the signal field at a measurement that rises when the unit runs. Indoor temperature is deliberately not used to guess. It was tested against 30 days of real data from a house with no cooler installed: under 300 W/m² or more of sun the indoor-to-outdoor difference had a median of +0.03 °C and a minimum of −4.22 °C, so "indoor cooler than outdoor means cooling is on" misfired on 13 % of daytime samples even with a 1.5 °C margin.

If the signal has no freshness limit of its own, it is judged by its own measurement period (×2, floor 300 s). An expired signal counts as not running, and that is logged.

Night closing exists because humidity rises and dew forms at night: an opening that looked useful at dusk can leave the crop wet by morning. Its sub-settings appear only once the toggle is on.

Three guarantees hold: safety gates win (a summer night's heat still opens the vents), the hard temperature/humidity limits break the parking, and if no coordinates are available to compute solar time, nothing is parked at all. Times are read in the facility's local timezone, not the server's. On the facility popup, a device parked by this option reads Closed for the night — heating and cooling take over, kept separate from Nothing this device can change right now.

Heating, Cooling and Misting~

Misting valves are almost always on/off, so there is no way to reduce the flow: the only adjustable quantities are how long one run lasts and how long the next one waits. That is what this scale sets.

Sunburn protection is a separate decision from frequency — the two were briefly merged, which made "spray often but lock out in strong sun" impossible to express.

Even with protection off, a wetting-type mister is dosed in pulses rather than modulated continuously — 30 s maximum on, 180 s minimum off by default — because continuous modulation never lets the leaves dry.

Light and Shading~

Either end can be switched off, and off means different things at the two ends: the lower handle at 0 is no supplemental light, and the upper handle turned off is no shading. If the facility has no shade screen or no supplemental lighting registered, the screen says so rather than offering a handle that does nothing.

The underlying values are Min Light Threshold (Supplemental) (default 0) and Max Light Threshold (default 800), both visible under [Advanced].

Two related properties are not on this screen:

• Shade cloth transmittance belongs to the facility, under the shade curtain in the facility editor. It is used only when there is no indoor light sensor: indoor light is then estimated from outdoor irradiance and the screen position. An unset or out-of-range value falls back to 0.50, and a facility that declares no shade curtain uses 1.0. A single screen whose cloth differs can still override it in its own Action.
• The light saturation point is derived from the crop's K_L in the program, not from the shading threshold. When those two were the same field, lowering the shading threshold made the photosynthesis model conclude that light was already sufficient — two coordinators set to 250 never once saw a light limitation while measured irradiance was 542 and 650 W/m². With no K_L, the system default of 600 W/m² is used.

Advanced Settings~

This group is folded by default and is for engineers testing the function, not for growers.

Effect Calibration~

Forecast Feedforward~

Debug logging is no longer a separate option. It duplicated the framework's own debug switch, and almost everything it guarded was written at DEBUG level, so on its own it produced nothing. The one switch in the function's Advanced settings now does both. Critical events — safety gate, dispatch failure, runtime-state error — are always recorded regardless.

Registering Actuators~

Actuators drawn in the linked facility are discovered automatically. Anything else is registered with an Environment Control action on this function; add the action once per device. Manual actions are merged with the facility-derived list.

Automatic conversion by device type~

A command is always computed as 0–100 %. The adapter is chosen from the Output module's own metadata — no extra configuration:

A wetting-type mister is additionally wrapped in pulse dosing: one spray is cut at the maximum on-time, and nothing sprays at all until the drying interval has passed.

Irrigation flow is aggregated from the facility drawing — every emitter under a layer is summed into that actuator's flow_lpm, and the volumetric adapter and the fogger effect model use it directly. The fallback order is per-actuator flow, then the facility total, then 1.0 L/min.

Safe default~

Each actuator has a safe position it moves to when a safety gate fires, on emergency stop, or on an external force_safe_state() call. For actuators discovered from the facility this follows the device kind: thermal curtains and shade screens park at 100 %, everything else at 0 (off).

Methods (Setpoint Curves)~

A Method defines how a setpoint changes over time. Methods are attached to target items in the program, not to this function — an item with a curve shows as Follows a curve on the plot screen and cannot be overridden with a number.

• Daily — a setpoint per time of day (HH:MM)
• Duration — a setpoint per elapsed hour since start
• Daily Bezier — a smooth diurnal curve
• Repeating — a repeating pattern

Curves that progress by growth week are evaluated from the plot's start date, read at midnight in the facility's local timezone, and from the elapsed weeks that the plot screen and the plot journal also use.

Example crop stage schedule (tomato):

Methods prefixed with SEED: are seed presets and are read-only. Duplicate a preset before editing.

Safety Gates~

Safety runs outside the L1–L3 coordination algorithm — a Pre-Gate checked every cycle before L1–L3, and a Post-Gate that sanity-checks the L3 result before it is dispatched. Once triggered, a Pre-Gate stays active for at least 300 s after its last trigger (prevents rapid on/off flapping).

Pre-Gate (checked before L1–L3)~

Rain, Heat and Cold thresholds are fixed in code — the Wind threshold is the only one exposed as a function option. Multiple gates can be active at once (e.g. rain + strong wind); vents then close unconditionally regardless of direction.

A gated cycle is still a cycle. When a gate ends the cycle early, a reduced summary is written and the cycle is stamped, so the facility widget keeps showing what happened instead of reporting the coordinator as unresponsive. The reduced summary deliberately omits environment values that were not computed this cycle, and lists only the devices the gate actually forced — a device that was not touched carries no command at all, rather than 0 %.

Post-Gate (checked after L3, before dispatch)~

Emergency stop and safe state~

The next cycle is delayed 60 seconds after an emergency stop; actuators not moving immediately afterwards is that delay, not a fault.

Troubleshooting~

AI Integration~

The AI agent uses analyze_control_performance to diagnose control quality.

vpd_rmse         → VPD tracking error (lower is better)
oscillation_index → Control oscillation index (lower is more stable)
assessment       → "good" / "moderate" / "poor"

Based on diagnostics, suggest_setpoint_adjustment proposes a target adjustment. A suggestion is advice only — the target itself lives on the plot's stage plan, so applying it means editing that stage target on the plot screen, or, for a Method-curve target, calling update_method_point (with user approval) to change the relevant curve point.

Related Pages~

• AI Overview
• Functions Guide
• Methods Guide