UT_ZONE_SEQ — Irrigation / wash-down zone sequencer

Runs a list of zones (irrigation blocks, pivots, wash-down stations, effluent
spreading) one after another, each by time or by volume. It opens the right valve,
runs the pump, sets each zone's pressure for the speed controller, and overlaps
valves so the pump never deadheads. It also handles cycle-and-soak, rain hold,
flow checks per zone (blocked dripper line, burst lateral), pause, skip and
manual zone runs.

Pins

Positions (ActiveZone, cmdRunZone) count from 1 = the first
element, whatever the array's lower bound.

Zone slot UT_ZONE

Record UT_ZONE_SEQ_DATA

How it works

• Order, so the pump never deadheads and never hammers: start = the valve opens,
  pumpStartDelay later PumpDemand comes on. Zone change = the next valve opens,
  valveOverlap later the previous one closes. End, pause or soak = PumpDemand goes
  off; the valves close once valveCloseDelay has passed and the pump has stopped.
• Zone time counts only while PumpRunning and not PumpFault. A pump trip keeps
  the valve open and the pump asked for, and the zone carries on when it recovers.
• How a zone ends (endBy): AUTO (the volume if it has one, else the time), TIME,
  VOLUME, or FIRST (whichever comes first, e.g. "50 m³ or 2 h"). Volume counts Flow
  integrated, units per flowPer. maxZoneTime caps any zone; a capped zone gives
  Warning and the program moves on.
• A pump that does not run: the zone waits (no water time). With maxPumpWait, a
  pump faulted or not running that long ends the program safely (endReason UT_STOP_PUMP_FAULT), or
  with pumpWaitSkips skips the zone; either is counted in trips with
  lastFault.
• Run while held (startIsLevel): Start held runs the program, dropping it stops
  it (endReason UT_STOP_REMOTE_OFF). A program that ends while Start is still held does not start
  again until Start cycles. After a power cut, see powerUp.
• Cycle and soak: each cycle is runTime / cycles (or volume / cycles). While a
  zone soaks, the next zones run; the program comes back to it after its soak. With
  nothing else to run the pump stops and the valves close until a soak is over.
• Flow check: a flow outside minFlow..maxFlow while one valve is open (not
  during an overlap) is the zone's flowCheck protection: after its delay, WARN keeps
  watering, TRIP ends the zone. Either sets flowAlarm and Warning.
• Pause keeps the zone's time. Disabled zones, and zones with no time and no
  volume, are passed over.
• Permit: Permit off holds back each start: the program's first zone, the next
  zone, and a zone coming back after a pause or a soak. A zone already watering
  carries on to its end; then the pump stops and the valves close as at the end, and
  the program waits (Not permitted, phase UT_ZS_HELD, Busy on). Permit on
  again carries on. To stop a zone that is watering, use Pause or Abort.
• Abort: ends the program as Stop does (pump off, then the valves), with
  endReason = AbortCode. While it is on a start is refused, and is not kept for
  later (Blocked: abort).
• Until stopped: a zone with endBy UT_ZE_UNTIL_STOP waters until it is stopped,
  the held Start drops (startIsLevel, a remote that holds the run), or cmdSkip
  moves on (status Running: until stopped, timeLeft 0). The zones after it run only
  after a cmdSkip. It is not counted in programRemaining.
• Power cut: every valve starts closed and the pump off (even if you declared the
  zones RETAIN); LATCH and MOTOR valves are driven closed (one close pulse / run);
  then powerUp decides, below.
• Start and Stop in the same scan: no start. Commands held on act once.
• A pump that never reports running holds the program (no water time), and a pump
  that never stops holds the valves open: both are what you want hydraulically, and
  the pump block reports the fault.

Valve drives

valveDrive sets how every zone valve is driven. valve is always "this zone should
be open"; wire the outputs for your valve:

• openCmd and closeCmd are never on together. A valve told the other way while it
  moves reverses at once and gets the full driveTime.
• A LATCH or MOTOR valve counts as open once its driveTime is over: the pump starts
  (after pumpStartDelay too) and the previous zone's valve closes only then. The
  status shows Starting with the time left.
• At power-up every LATCH or MOTOR valve gets a close pulse / run (its position is not
  known: it may have been open at the cut). The close pulse or run can still be on
  for driveTime after Busy goes off.
• LATCH or MOTOR with no driveTime, or an unknown valveDrive: Config: valve drive, nothing runs, both outputs stay off.
• On NO valves the valve opens when the output is off: also when the PLC is stopped
  or loses power.

Valve proven open

With a zone's useProven on, its valve must prove it has opened before water is
counted for it:

• The valve opens; the pump starts once pumpStartDelay has passed and proven is
  on. At a zone change, the previous valve stays open (the pump keeps running through
  it) until the new valve is proven and valveOverlap has passed. The new zone's time
  counts once it is proven. Status Waiting: valve proven, timeLeft = provenTime left.
• Use a signal that is valid with the pump off, e.g. the valve's open limit switch (a
  pressure switch behind the valve only proves once the pump runs: it works at a zone
  change, not at the first zone).
• Proven is checked while the valve opens; once seen it is not checked again while the
  zone waters (a flow or pressure check covers a valve that shuts while watering).
• Not proven within provenTime: lastFault UT_F_NOT_PROVEN, trips + 1, and the
  program ends (UT_STOP_FAULT) with the pump off, or with pumpWaitSkips the zone is
  skipped and the next one opens (at a zone change, while the previous valve still
  carries the flow, so the pump never deadheads).

After a power cut

Irrigation of sports fields and properties often runs with no operator: when the
power comes back (or the PLC is stopped and started) the program should carry on, as
a commercial irrigation controller does. powerUp chooses:

• The valves open again in the normal order: valve first, the pump pumpStartDelay
  later.
• Resume carries on with the zone that was watering: the zones before it count as
  done for this pass, the zone gets its water time, volume and cycles back, and the
  zones after it run in full. A zone that was soaking at the cut soaks again in full.
  programDelivered and an HMI pause (cmdPause) carry on too; a cmdRunZone run
  carries on with that zone only.
• With cycle and soak, a zone that was soaking while a later zone watered (other
  than the one cut off) is not tracked: if it is before the interrupted zone in the
  list its cycles left are not given; if after, it runs all its cycles again.
• Water time spent before the cut is not counted again, and a zone never gets more
  than its runTime / volume.
• The zone carries on from its last save: the progress is saved when the program
  starts and ends, when the zone, pass or cycle changes, on Start and HMI pause
  changes, and every progressSave (default 1 min) while it runs, never every scan
  (flash wear: a few hundred saves on a day of irrigation, none when idle). So up to
  progressSave of a zone's water can be given again after a cut.
• A held Start that was already on at the cut and had been dealt with (its
  program done, or stopped) does not start the program again after the power cut, in
  any mode: as without a power cut, it must go off and on again. Only a Start that
  came on while the power was off counts as a new request.
• Pause, RainHold, PumpFault and the settings act from the first scan, as they
  would without a power cut.
• Kept over a power cut (inside the block, for this only): whether a program is
  running, how it was started, whether Start is on, the HMI pause, the zone
  watering (position, cycles done, soaking, water time, volume), the pass, a
  cmdRunZone run, and programDelivered. runs counts from when the PLC started.

Status codes

statusCode is a UT_STATUS and faultId a UT_FAULT (an HMI reads their numbers);
statusText is the two in words, changed only when one of them changes. The one main
thing, in the order config, held, warning, normal, idle. The zone is in activeZone
(a position in the array), the countdown in timeLeft, a volume zone's progress in its
delivered of volume. Name the zones on the HMI, by position.

Bad settings

• Nothing runs (configBad, Warning; a program running ends safely: pump off, then the
  valves once it has stopped; ZoneSp 0): a negative valveOverlap, pumpStartDelay or
  valveCloseDelay, defaultSp negative or not a number, an unknown valveDrive, or
  LATCH / MOTOR with driveTime 0 or negative.
• Warning, safe values: an unknown rainAction (PAUSE), an unknown flowPer (per
  hour), repeats below 1 (1), a negative maxZoneTime (none), a negative
  provenTime (wait for ever); a zone with a negative
  runTime / soakTime, volume, sp, minFlow or maxFlow negative or not a number,
  or cycles below 1 (it runs on the safe value or is passed over).