UT_SPEED_CTRL — Constant pressure / flow / level with a speed drive

Holds a pressure, flow, level or temperature at a setpoint by varying a drive's
speed. Typical uses: irrigation and stock-water pumps on a VSD, booster sets,
constant-pressure town supply, borehole pumps, duct-pressure fans, cooling-tower fans.

It has the full set of field features: pipe fill (fill the mains gently before
regulating, which stops water hammer), sleep / wake (stop when demand stops and
restart on a pressure drop), a flow limit, and guard rails against a badly
tuned or failing loop: hunting detection with a fallback speed, a burst-pipe /
lost-prime check, an overpressure override, sensor-failure handling and output
rate limiting.

The control loop is inside the block, because pipe fill, sleep, overrides and
the fallback have to take the output away from the loop and hand it back without a
bump. If you'd rather use OpenPLC's PID, set loop := UT_LOOP_EXTERNAL; the block
then takes the speed from ExtSpeed (wire Data.spActive to the PID's setpoint) and
still applies every phase, limit and protection around it.

What the speed follows is a setting, control: the PID on Pv (pressure or level,
the default), the PID on the Flow pin, or a fixed speed. Each has three presets,
NORMAL, LOW and HIGH, chosen with preset by the operator, the HMI, SCADA or your
logic. For example a travelling irrigator working near the sump needs only a low
pressure: switch preset to LOW and the pump holds spLow instead of sp.

An operator can run the pump at a manual speed (cmdManual, manualSpeed) without
losing the overpressure and burst protections, which a drive's own Hand would bypass.

Chain: UT_SPEED_CTRL.Run → UT_PUMP.Demand; UT_PUMP.RunCmd → UT_MOTOR_VSD.AutoCmd;
UT_SPEED_CTRL.Speed → UT_MOTOR_VSD.AutoSpeed; UT_MOTOR_VSD.Running → Running.

Pins

Record UT_SPEED_CTRL_DATA

What the speed follows, and the presets

Setpoint and loop

Pipe fill pipeFill : UT_SC_FILL_DATA

The fill runs every time the pump starts from IDLE (Enable, or a restart after a
trip), not after a sleep. Leaving FALLBACK or MANUAL, a run whose line is not full
yet (no fill completed, and Pv never at the fill target since the start) fills
first, so a sensor that was bad at the start, or dipped during the fill, does not
skip it.

Sleep / wake sleep : UT_SC_SLEEP_DATA

Limits and overrides (independent of the loop)

Bit 0 of faultCode is configBad (no run). Bit 7 is a setting that is invalid but
has a safe fallback (a warning; it runs). faultId names the most important one:
UT_F_OVERPRESSURE, UT_F_SENSOR_BAD, UT_F_LOW_AT_MAX (burst), UT_F_PIPE_FILL,
UT_F_HUNTING, UT_F_NOT_REACHING, then the setting (bit 0: the setting named, below;
bit 7: UT_F_SETTING).

Invalid settings

• No run (configBad, bit 0, a warning while Enable): an unknown control; with
  PV or FLOW, the setpoint in use (by preset and spSource) 0, not a number or
  infinite (so FLOW needs flowSp); kp negative or not a number; minSpeed / maxSpeed not a number,
  min < 0, max ≤ 0 or min > max; startSpeed or fallbackSpeed not a number;
  rateLimit negative or not a number; an unknown rateUnit.
• Warning, safe value used (bit 7, Warning): sleep.wakeDrop not a number,
  infinite or negative → 0; atSpBand → 0; deadband → 0; spRamp → 0 (a step);
  td negative → 0; sleep.boost outside 0..100 → no boost; an unknown pvFail →
  STOP (the safe side). Warned only (the block already acts safely): an unknown
  spSource (record sp), loop (internal) or pipeFill.mode; ti negative (no
  integral); startSpeed / fallbackSpeed outside min..max (clamped); manualSpeed, or
  the fixed speed in use, not a number or outside 0..100 (minSpeed used); pipeFill.speed
  or sleep.speed outside 0..100; pipeFill.target, pipeFill.rate, sleep.flow,
  flowLimit, huntBand negative or not a number; huntCycles outside 1..15; a
  negative huntWindow, pvRecover, stageDelay or sleep time; a protection with a
  bad time or setpoint.

HMI

Each command acts once, on its rising edge, and is cleared by the block.

Manual speed (phase UT_SC_MANUAL, manual TRUE): the pump runs at manualSpeed,
reached at the rateLimit. Enable still starts and stops it (manual stays selected
while it is off), and these still act: the overpressure override and trip (highPv),
lowPvAtMax at the top speed (burst / lost prime), the flow limit, the rate limit and
a failed sensor with pvFail STOP (the overpressure check needs the sensor). No pipe
fill, sleep, hunting or notReaching in manual; MoreNeeded / LessNeeded stay
FALSE. Manual is not kept over a power cut: the loop is back in control.

Status fields

spActive (setpoint in use: ramped, fill ramp or boost), pv (the value under control
now: Pv, or Flow with FLOW control), error (in the acting direction), pTerm, iTerm, dTerm, speed, phase, huntCount (crossings in
about the last huntWindow, see Hunting), sleeping, flowLimiting,
pvBad, configBad (no run), fault, warning, faultCode : DWORD,
faultId : UT_FAULT, statusCode : UT_STATUS and statusText : STRING(30) (what the
loop is doing or what holds it back, below), and (at the end of the record):

Status

statusCode, faultId and statusText say the one main thing the loop is
doing, or what holds it back. The most important reason wins: configuration > fault >
held / waiting > warning > running > idle. Enabled and not running, or running with
no drive feedback, it always shows a held, fault or configuration status. The words
hold no numbers: the setpoint in use is spActive, the speed speed, and the time
left timeLeft. The text is rebuilt only when the status or the fault changes. The
numbers are in conventions.

<protection> is faultId, most important first: UT_F_OVERPRESSURE (highPv),
then (after a failed sensor with STOP) UT_F_LOW_AT_MAX (lowPvAtMax, low at max
speed: burst?), UT_F_PIPE_FILL (pipe fill time), UT_F_NOT_REACHING (below
setpoint), UT_F_HUNTING (loop hunting: a hunting trip runs on at the fallback speed
and shows here).

Hunting

A crossing is Pv passing the setpoint in use from more than huntBand/2 on one side to
more than huntBand/2 on the other. The block counts crossings in the huntWindow
under way, and starts a new window each time one has passed. huntCount is the
crossings of the window under way plus the last whole window's share of the time
still to go: just after a new window starts it is close to the last window's count,
and that part fades out as the new window runs. It drops to 0 once there has been no
crossing for a whole huntWindow. The hunting protection is raised while
huntCount is above huntCycles.

Control: PV, FLOW or FIXED, and the presets

• preset can change at any time; the new setpoint is reached at spRamp (a step
  when 0), and a new fixed speed at rateLimit.
• FLOW: the flow is the value under control (pv, spActive, AtSetpoint,
  notReaching, hunting, the pipe-fill target and lowPvAtMax work on it), and a
  failed flow signal (not a number) is the sensor failure (pvFail). highPv still
  watches the Pv pin, so wire the pressure there to keep the overpressure
  protection.
• FIXED: the PID is not used. The pump runs at the preset's fixed speed (phase
  UT_SC_MANUAL, status UT_ST_FIXED_SPEED), held inside minSpeed..maxSpeed and
  reached at rateLimit. PvGood FALSE does not stop it. highPv still watches
  Pv, and the other protections act as with the manual speed: lowPvAtMax at the
  top speed, the flow limit, the rate limit; a Pv that is not a number still counts
  as a failed sensor (pvFail). No fill, sleep, hunting or notReaching. The
  operator's manual speed (cmdManual, manualSpeed) wins over the fixed speed
  until cmdAuto.

On the HMI

Every PID value is in the record, for a tuning or overview screen: the settings
kp, ti, td, deadband, minSpeed, maxSpeed, rateLimit and rateUnit (the
ramp), control and preset; and the status spActive, pv, speed, error,
pTerm, iTerm, dTerm and phase.

The speed goes to the drive through UT_MOTOR_VSD: Speed to its
AutoSpeed, and its SpeedRef (%) or SpeedRefRaw (raw) to the analog output, or
through UT_IO_MAP_OUT. The drive's run, fault and ready relays are
UT_MOTOR_VSD's Feedback, DriveFault and DriveReady.

How it works

1. Enable → Run with Speed = startSpeed, held there until Running. With the
   fill on, the fill phase runs until Pv reaches the fill target (or times out).
2. The loop is the standard PID form (as the IEC / CODESYS PID):
   Speed = kp · (e + 1/ti · ∫e dt + td · de/dt), e = sp − Pv (Pv − sp reverse acting).
   It takes over bumplessly: the integral is loaded so it carries on from the speed
   it is given (after the start, the fill, an override or the fallback). The output is
   clamped to min/max and rate-limited. Anti-windup: the integral never integrates
   past the output limits, and stops while the output is held by a limit or by the
   rate limit.
3. Overrides act outside the loop: overpressure → min speed or stop; flow limit →
   speed capped. Each takes priority, and the loop follows without winding up.
4. Sleep when the demand has gone (boost, then stop); wake on a pressure drop. Hunting,
   a failed sensor or lost pressure at max speed trigger the protections above.
5. A trip that stops the pump goes to IDLE; it restarts (with the fill) when the trip
   clears by itself (AUTO / RETRY). After a MANUAL reset, Enable must go FALSE and
   back (unless restartAfterReset), like every device in the library.

Time comes from TIME() in whole milliseconds (the rest carried to the next scan),
so the loop, the ramps and every delay behave the same at any task interval.

For block builders: UT_SPEED_CTRL_RUN

The loop is also a function, UT_SPEED_CTRL_RUN, which UT_SPEED_CTRL and
UT_PUMP_CASCADE run inside. A function has no instance of its
own, so the record is not copied: the block that owns the loop keeps its working state
in a UT_SPEED_CTRL_ST and passes it with the record every scan.