UT_PUMP_STATION — Multi-pump station (wet well, sump, tank, booster)

Runs a station of any number of pumps from one level or pressure signal. It
handles staged start/stop points, duty rotation (alternation), failover to the
next pump, staggered starts, backup floats, random start-level variation (stops
fat rings forming), sump cleaning, a pump-down on request (Demand), an inhibit that
keeps the overflow backup, and inflow, outflow and overflow statistics.

There's no per-pump wiring. Give the station the array of pump records, and each
UT_PUMP uses one element as its Data.

Pins

Record UT_STATION_DATA

Settings

UT_STAGE (start, stop : REAL) defaults: stage 1 = 60 / 20, stage 2 = 75 / 25,
stage 3 = 85 / 30, stage 4 = 90 / 35 (same units as Level). Stations with more than 4
pumps: stage 4 calls every remaining pump. In FILL mode, set start below stop. Stage 1
must be usable: the wrong way round for the mode (or not a number) is a configuration
fault and no pump runs. Stages 2–4 whose points are the wrong way round are not used, so
in FILL mode the EMPTY defaults of the stages you don't set never call a pump (not a
number there: not used, and a warning).

Demand settings (at the end of the record)

HMI commands

cmdRotate (move the lead on now), cmdClean (clean now), cmdReset (clear latched
faults, as the Reset pin), cmdResetStats (cycles, highFloatEvents and
highFloatTime to 0; nothing else), cmdPumpDown (pump down now, as a new Demand).
Each acts once, on its rising edge, and is cleared.

Status fields

lead, runningCount, calledCount, availableCount, shortfall, highLevel,
floatControl (float/timer control active), transducerFault (as the pin),
configFault (as the pin), configBad (any invalid setting, configFault included),
cleaning, cleanFailed (cleaning timed out; until a reset or a clean that finishes),
warning (as the pin), cycles : UDINT,
highFloatEvents : UDINT, highFloatTime : TIME (overflow-risk duration),
inflow : REAL, startPointNow (stage 1 start including the variation),
statusCode : UT_STATUS, statusText : STRING(30) and statusUnit : DINT (what the
station is doing or what holds it back, and the pump it is about, see
Status), and at the end of the record:

Each pump's record shows its part: grpRank (1 = lead), grpRun (called),
grpSkipped (called but did not run; skipped until it has been unavailable or the next
cycle starts) and grpRunTime (its run time counted by the station since power-up,
for HOURS rotation).

Why the last cycle ended (stopReason):

Status

statusCode, faultId and statusText say the one main thing the station is
doing, or what holds it back. The most important reason wins: configuration > fault >
held / waiting > warning > running > idle. A station asked to run (the level or the
high float wants a pump) with no pump running or starting always shows a held, fault
or configuration status. UT_ST_STARTING (a called pump's run command is out, its
feedback not yet in) shows over a warning. statusUnit is the pump (its array index)
the status is about, for UT_ST_STARTING and UT_ST_PUMP_DELAY; one below the
array's first index when none. Each pump's own status says more (e.g. Waiting: min off time). The words hold no numbers: the level is the Level output, the counts are
runningCount, calledCount and availableCount, and the time left is in
timeLeft. The text is rebuilt only when the status or the fault changes. The
numbers are in conventions.

How it works

1. Ranking. Pumps are ranked by the rotation rule (grpRank). A pump is a
   candidate when it is available (healthy, motor ready, motor in Auto) and not
   skipped. Pumps running in Hand (or exercising) count toward the demand; a pump
   running down after a stop or a trip does not.
2. Staging. As the level rises past stage n's start, n pumps are wanted. Pumps are
   called one at a time, best rank first, at least stageDelay apart and only once
   the last one called is running. Each stage drops out at its own stop point, and
   pumps are released one at a time (worst rank first), at least destageDelay apart.
3. Failover. A called pump that isn't running within failoverDelay of its run
   command is skipped and the next is called (it rejoins next cycle: no retry storm). A
   pump still waiting out its own startDelay / minOffTime (after a power cut, or
   just stopped) hasn't failed: after failoverDelay it hands over if another pump can
   be called, and is called again once no other is left. A pump that trips, loses its
   motor or leaves Auto is released at once and replaced. It rejoins once it's
   available again (no needless swap of a pump already running). A pump whose
   StartHold is on (startHold, e.g. a stirrer pre-run) has not failed either: it
   stays called, with no failover, and starts when the hold ends.
4. Rotation. FIXED: fixedLead. EACH_START: the lead moves on when a cycle ends
   (all pumps released). HOURS: at each cycle start the pump with the least run time
   leads (each pump's grpRunTime, counted by the station; every pump counts). INTERVAL: every
   rotateInterval. Rotate/cmdRotate move the lead on now. A rotation while
   running starts the new lead before stopping the old one, never dropping below the
   demand; at maxRunning the old one stops first, so the limit is never passed.
5. Backup floats (EMPTY). HighFloat runs every available pump (or the lead)
   whatever the transmitter says, and keeps them running highFloatHold after it
   clears. LowFloat and Enable off release every pump at once.
   Transducer check. If the high float is made while the transmitter reads below
   highLevelAlarm for longer than floatCheckDelay, the transmitter is suspect
   (stuck, drifted, fouled): TransducerFault, and with the default TRIP, float/timer
   control. It does not latch for ever: build-up round a sensor clears. A healthy
   transmitter shows the high level as the well refills, before or as the float
   makes; once it reads a valid value at or above highLevelAlarm, the fault clears
   after transducer.recover (AUTO). A transmitter still stuck never shows it, so the
   float catches it again. With MANUAL it also needs Reset / cmdReset. A reset
   clears it at any time (refused while the float is made and the reading is still
   low); so does a power cut.
   Float/timer control (a transducer fault, LevelBad, or a level that is not a
   number): the level is ignored. When the high float makes, the pumps run while it
   stays made (never stopped during a real flood) and floatRunTime after it clears.
   After they stop, the high float can't start them again for floatLockout. The
   low float stops them at once and ends the run (the lockout follows).
   FILL mode: HighFloat (tank full) and a bad level release every pump;
   LowFloat still cuts out.
   Float-only control (floatsOnly, EMPTY, no transmitter): the normal control,
   not a fault. HighFloat (the start float) calls the lead pump; it runs until
   LowFloat (the stop float) makes, or floatRunTime after the high float clears
   (0 = the low float only). No lockout, no transducer check, HighLevel is not
   set by the start float (wire a high-level float to its own alarm), and level
   stages, Demand, cleaning and the inflow estimate are not used. Failover and
   rotation work as usual; a second pump is called only by failover. Inhibit stops
   it (it is the level control).
6. Cleaning and variation. These reduce grease build-up in sewage wells. A clean
   cycle runs a pump down to cleanLevel, then cleanTime more. A pump that trips
   during the clean (its own dry-run protection) ends it. A clean not finished within
   maxCleanTime ends with cleanFailed (a warning) and the pumps running only for
   it stop at once; if the level still wants a pump, it runs on as normal.
   levelVariation must be less than the gap between stage 1's start and stop.
7. Inflow. While no pump runs, the level rise × wellArea, averaged since the
   pumps stopped (published after 2 s, a fresh window every minute). Held while
   pumps run.
8. Invalid settings. A configuration fault (ConfigFault, until fixed): an
   unknown stationMode (no pump at all); stage 1 the wrong way round for the mode or
   not a number (no level control: an EMPTY station drops to float/timer control so
   the high float still protects the well; a FILL station calls no pump, and must set
   stage 1). A
   warning (configBad, Warning) with a safe value: maxRunning negative (as
   0, no limit); failoverDelay 0 or negative (10 s: 0 would skip every pump before
   it could start); levelVariation negative, not a number or not below the stage 1
   gap (no variation); cleanEvery negative, cleanLevel not a number, a negative
   cleanTime or maxCleanTime (no cleaning); an unknown rotation; fixedLead out
   of range with FIXED (the first pump); pumpsUsed negative or more than the array
   (every pump); stages 2–4 not a number (not used); a negative
   time (as 0); highLevelAlarm not a number; wellArea negative or not a number
   (inflow off); transducer with an unknown response (as TRIP) or reset (as AUTO),
   or a bad time.
9. Resets. Reset (rising edge) and cmdReset clear latched faults (a MANUAL or
   used-up RETRY transducer fault, cleanFailed); cmdResetStats clears the
   statistics. Neither does the other's job.

Demand and inhibit

• Demand (or cmdPumpDown, once) pumps down now, e.g. a SCADA "empty the
  sump before the rain" or a timed draw-off: demandPumps pumps run until the level
  reaches demandStop (0 = stage 1's stop point), status UT_ST_RUN_DEMAND. Every station protection
  still acts: the low float, the transducer check (no demand while the level is not
  trusted), maxRunning, failover and staging. At demandStop the pumps stop
  (stopReason UT_STOP_DONE); a Demand still held waits (UT_ST_IDLE_LEVEL_REACHED) and runs again once the
  level is back at the stage 1 start point, or on a new rising edge. Refused on the low
  float, a level that is not trusted, Enable off or Inhibit. In FILL mode it fills
  up to demandStop instead.
• Inhibit holds the level control off (no level, demand or cleaning start; a
  pump running for the level is released, stopReason UT_STOP_INHIBITED) while the high float still
  runs the pumps: the overflow backup stays. Enable FALSE is everything off, the
  high float included (stopReason UT_STOP_SWITCHED_OFF).

Power cut: only the lead is kept (saved at once when it changes, so after
frequent power cuts the first pump does not always lead). With HOURS a tie in run
time goes to the kept lead,
cycles, highFloatEvents, highFloatTime and the pumps' grpRunTime at 0 (also when the pump records are RETAIN), and a transducer
fault and cleanFailed are cleared. Every
grpRun starts cleared and the pumps are called one at a time again, even if your
pump records are RETAIN.

Using it

VAR Pumps : ARRAY[1..3] OF UT_PUMP_DATA; END_VAR
Station(Level := WetWell.Value, LevelBad := NOT WetWell.Good,
        HighFloat := HiFloat, LowFloat := LoFloat, Pumps := Pumps, Data := StationCfg);
P1(Demand := HiFloat, Running := M1.Running, MotorReady := M1.Ready, MotorAuto := M1.Auto,
   DryRun := LoFloat, Data := Pumps[1]);
(* … P2, P3 … *)

Each pump's Demand is only its fallback: while the station runs, the station decides.
If the station block stops being called, each pump is back on its own control (here:
run on the high float) from the next scan.