UT_DOSE — Dosing and batching (batch, flow-paced, timed)

Doses chemical, fertiliser or product three ways:

• Batch: deliver a target quantity, with fast/slow (dribble) stages and in-flight
  compensation (stops early by the amount still flowing after the stop), which can be
  learned automatically. Used for tank filling, recipe ingredients and irrigation shots.
• Flow-paced (proportional): dose in proportion to the water flow. Used for
  fertigation, chlorination, pH correction feed-forward and stock-water additives.
  It drives a dosing pump by speed (%) or by stroke pulses.
• Timed: X seconds on every Y minutes while enabled.

Pins

Record UT_DOSE_DATA

Every cmdXxx acts once, on its rising edge, and is cleared by the block. A SCADA
master that rewrites cmdStart every poll would start a new batch after each one
finishes (an overdose): put UT_CMD in front of it.
| Status | | | |
| phase | UT_DOSE_PHASE | | UT_DP_IDLE, UT_DP_FAST, UT_DP_SLOW, UT_DP_SETTLE, UT_DP_HELD, UT_DP_DONE, UT_DP_ABORTED, UT_DP_DOSING, UT_DP_WAITING (FLOW below minFlow or paused, TIMED off part) |
| modeActive, targetActive | | | The dose in progress |
| delivered, lastDelivered, lastError | REAL | | This dose; the last one; last batch delivered − target |
| preactActive | REAL | | Preact in use (learned) |
| required, rate | REAL | | FLOW: product rate needed (units per flowPer); Rate % |
| pulses | UDINT | | Stroke pulses given |
| doses | UDINT | | Batch doses completed (aborted ones are not counted) |
| dosedTotal | REAL | | Everything dosed (batch, flow and timed), kept as of the last save |
| held | BOOL | | Paused (Hold, cmdHold, Interlock, a trip) |
| configBad, fault, warning, faultCode : DWORD | | | Bit 0 = configBad |
| statusCode | UT_STATUS | | What it is doing, or what holds it back (see Status codes) |
| faultId | UT_FAULT | | The fault, warning or setting the status is about (UT_F_NONE when none) |
| statusText | STRING(30) | | statusCode and faultId in words, e.g. Dosing fast. The quantities are in delivered / targetActive, the speed in rate |
| doseTime | TIME | | How long the dose in progress has run, holds included (the last dose's once it ends) |
| timeLeft | TIME | | The countdown the status shows: TIMED on / off time left, the settle time left, the maxTime left while a batch doses (maxTime in use), a fault's recover / retry wait |
| stopReason | UT_STOP | | Why the last dose ended (see below; UT_STOP_NONE = none since power-up), kept until the next one ends |
| lastFaultCode | DWORD | | The faultCode bits of the last trip, kept after it clears, until the next trip |
| lastFault | UT_FAULT | | The last trip, e.g. UT_F_DOSE_NO_FLOW, kept the same way |
| trips | UDINT | | Trips since power-up (not kept over a power cut) |

Why the dose ended (stopReason, a UT_STOP; an HMI reads its number):

An interlock, Hold or a trip (no flow) pauses a dose; they do not end it.

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, fault, held, warning, normal, idle. The quantities are in
delivered and targetActive, the pump speed in rate, the countdown in timeLeft.

The protection is UT_F_DOSE_NO_FLOW (no dose flow), UT_F_DOSE_TOO_LONG (dose too long),
UT_F_PUMP_TOO_SMALL (pump too small) or UT_F_TOLERANCE (out of tolerance), the first
tripped in that order.

Power cut

Kept: doses and dosedTotal, as of the last save (saveEvery). Not kept: a dose
in progress and the learned preact. After a power-up a batch doser is idle and nothing
starts by itself, even with Start still on: a new Start edge (or cmdStart)
starts a new dose of the full target; a batch is never resumed. The preact in use
starts again from the preact setting. FLOW and TIMED are different: Start is a
level (dose while TRUE), so if Start is still on at power-up the flow-paced or timed
dosing carries on at once (from the start of a fresh on-time). A cmdStart latch is not
kept: after a power cut it needs Start or a new cmdStart.

Bad settings

• Nothing doses: an unknown doseMode (taken only when idle); TIMED with a negative
  onTime or offTime (a negative off time would never stop). configBad, status UT_ST_CONFIG.
• Warning, safe values (configBad, bit 0, status Setting: a setting): preact negative or not a
  number (0: stops at the target); slowAt, tolerance, ratio, pumpCapacity,
  pulseVolume, minFlow negative or not a number; maxRate outside 0..100 or not a
  number (clamped, NaN = 0); a negative settleTime, pulseWidth (0) or saveEvery
  (nothing kept); a negative retryWindow (the default 1 h); an unknown flowPer (per
  hour).
• A pulseVolume so small that more than a million stroke pulses would be owed: the
  extra pulses are dropped (the pulse count never overflows).