UT_VALVE — Two-position valve, cylinder or damper

Opens and closes any two-position actuator and supervises its limit switches:

• solenoid valves and cylinders with spring return (one coil),
• double-solenoid valves held in position (two coils),
• bistable / latching solenoids that need only a pulse (two coils),
• motorised on/off valves and dampers (drive to the limit, then stop).

Hand/Off/Auto/OOS is built in, like the motors. The shared logic (mode, safe
position, protections, stroke count) is UT_VALVE_CORE.

Pins

Record UT_VALVE_DATA (shared by every UT_VALVE* block)

Settings

The three-position, modulating and floating blocks keep their own settings, commands
and status in a second record of their own (Pos3, Modul, Floating), so a
two-position valve carries none of them. See 3POS,
MOD and FLOAT. reversalDelay is in this
record and is used by every motorised or floating valve.

UT_VALVE_TYPE:

UT_SAFE_HOLD stops a motorised valve where it is; the coil types keep their
coils as they were.

Protections (each a UT_PROTECTION; response and reset set per protection)

faultId names the lowest-numbered protection tripped. A RETRY on a travel
timeout repeats the move, which often frees a sticky valve. A timeout set to
WARN keeps the valve where it was sent and warns until it arrives.

HMI commands

The three-position Hand position cmdPos is in UT_VALVE_3POS's record (Pos3), and
the floating valve's cmdHome in UT_VALVE_FLOAT's (Floating).

Every BOOL command acts once, on its rising edge, and is cleared by the block, also by
the valve blocks that don't use it: one held TRUE (a Modbus coil left on, a debugger
force) acts once, and a Hand valve closed by the interlock does not re-open when the
interlock returns with cmdOpen still held.
A command left in the record at power-up does not act. Commands outside Hand (and
Hand commands while interlocked, or not permitted away from safe) are ignored. A master
that rewrites a command every poll goes through UT_CMD.

Status fields

mode, state, isOpen, isClosed, moving, interlocked, position : REAL
(100 open, 0 closed, 50 between; measured / estimated for MOD and FLOAT; −1 = unknown,
FLOAT not homed),
lastOpenStroke / lastCloseStroke : TIME (measured limit-to-limit travel times,
a wear indicator; only with the limit fitted), strokes : UDINT (completed moves,
kept over a power cut as of the last saveEvery), fault, warning, configBad (a setting is
invalid, bit 8: see Bad settings),
faultCode : DWORD, faultId : UT_FAULT, statusCode : UT_STATUS and
statusText : STRING(30) (what it is doing or what holds it back, see
Status; every valve block has its own list). The variants keep their own
status in their own record: targetPos / actualPos (3POS), demand (MOD / FLOAT),
notHomed (FLOAT).

Added for time visibility and "why it stopped" (at the end of the record):

Why it went back to safe (stopReason, the common
stop reasons): it is set when the valve stops
being asked away from its safe position, from what held it in that scan, so the
record shows one scan after the move back starts.

How it works

• Mode (UT_MODE_SELECT): Off → safePosition. Hand → cmdOpen /
  cmdClose / cmdStop and the LocalOpen / LocalClose / LocalStop buttons.
  Auto → follows AutoOpen. OOS → every output off,
  protections suppressed, no fault or warning reported; the position is found again afterwards.
• Safe position on Off, interlock, or any trip. In Hand an interlock also
  puts the Hand request back to the safe position, so the valve does not move
  by itself when the interlock returns. In Auto it follows AutoOpen again.
• Permissive FALSE: no move away from the safe position starts (Auto waits, a
  Hand request away from safe is dropped, status UT_ST_NOT_PERMITTED, Not permitted); a move toward
  the safe position is always allowed, and a valve already away stays where it is
  (unlike the interlock, it never forces safe). When it returns, Auto follows
  AutoOpen again; Hand needs a new command.
• After a MANUAL reset the valve stays in the safe position until it gets a
  new command (AutoOpen changes, or a new Hand command), unless restartAfterReset.
  AUTO / RETRY recovery puts it back where it is asked to be.
• Moves: a move ends on its limit, or after the travel time when that limit
  isn't fitted. A limit that makes and drops again within the travel time is
  treated as a flicker: the valve carries on (a motorised one keeps driving)
  and only the real arrival counts as one stroke.
• Motorised: a reversal waits reversalDelay with both outputs off. Hand
  cmdStop stops it mid-travel (State ON, position 50).
• Power-up: the position comes from the limit switches, no false fault.
  In Hand the valve stays where it is (a spring valve is closed); in Off it goes
  to safePosition; in Auto it follows AutoOpen. With powerUp = UT_PU_OFF
  the mode comes back Off, so the valve goes to its safe position until the
  operator selects a mode again.
• OpenOut and CloseOut are never on together.

Status

statusCode, faultId and statusText say the one main thing the valve is
doing, or what holds it back, so a technician can see on the HMI why it is not where
it was asked to be. The most important reason wins: configuration > fault > held /
waiting > warning > position > Off. The words hold no numbers: the position is in position. The time left
(travel, a pause, a fault's recover / retry wait) is in timeLeft. The text is
rebuilt only when the status or the fault changes. Where the valve is (the rows
marked (this block)) comes from the block's last scan, so it shows one scan after
it changes. The numbers are in conventions.

<fault> is faultId, one of: UT_F_OPEN_TIMEOUT (open timeout) · UT_F_CLOSE_TIMEOUT (close timeout) · UT_F_BOTH_LIMITS (both limits) · UT_F_POS_LOST (position lost) · UT_F_NO_MOVEMENT (did not move) · UT_F_ACTUATOR (actuator fault).
<setting> with UT_ST_WARN_SETTING is one of: UT_F_SAVE_EVERY (save every) · UT_F_RETRY_WINDOW (retry window) · UT_F_MODE_SOURCE (mode source) · UT_F_SAFE_POSITION (safe position); with UT_ST_CONFIG one of: UT_F_VALVE_TYPE (valve type) · UT_F_TRAVEL_TIME (open / close time) · UT_F_REVERSAL_DELAY (reversal delay) · UT_F_PULSE_TIME (pulse time, must be above 0).

Using it

V1(AutoOpen := FillValveCmd, OpenLs := V1_Open, ClosedLs := V1_Closed,
   Interlock := NOT TankHigh, Data := Valve1);
V1_Solenoid := V1.OpenOut;

Bad settings

A setting that is not a number, negative or unknown never drives the valve somewhere
it could do damage. configBad is set and faultCode bit 8, and faultId names the
setting (the lowest priority). A negative saveEvery keeps nothing; a negative retryWindow
uses the default 1 h; an unknown modeSource uses the HMI (warnings).

• Refused (a fault, every output off): an unknown valveType; a negative openTime,
  closeTime or reversalDelay; a bistable pulseTime of 0 or less. It drives again
  once the setting is valid.
• Warning (a safe value is used): an unknown safePosition (closed).
• An unknown enum value can only come from a raw HMI write.