Conventions — how every block behaves

Read this once and every block will feel familiar.

Names

• Every block, record type and enum value starts with UT_.
• Pins are PascalCase plain English: Feedback, Overload, Interlock.
• Record fields are camelCase: feedbackDelay, overload.reset.
  • cmdXxx: an HMI command. The block acts on it once and clears it (see
    HMI commands).
  • grpXxx: written by a group block (station, duty). Don't write these yourself.
• Reserved words that can't be used as names: step, now, time, action, method, min, max, set.

Zero is off

The first value of every enum (0) is the off / none / safest choice, and every
mode starts at 0 = Off. A freshly loaded program does nothing until someone
chooses otherwise, and an enum left at its default never surprises anyone.

There are two exceptions, both about what happens after a power cut, where the
unattended plant carrying on is the safe default:

• UT_POWERUP, whose first value UT_PU_LAST keeps a device's mode over a power
  cut (see Power-up): a freshly loaded program still starts Off, and an
  unattended pump left in Auto carries on after a power cut.
• UT_RUN_POWERUP (UT_RUN_LIMIT, UT_ZONE_SEQ),
  whose first value UT_RPU_RESUME lets a run or zone program that was going at a
  power cut carry on with what it had left, as a commercial irrigation controller
  does (UT_RPU_RESTART and UT_RPU_NONE are the other choices). A freshly loaded
  program still starts nothing.

Pin order

1. The first input is the main signal and should always be wired.
2. The first output is the main result.
3. The record (Data, or an array such as Pumps) comes last.

Ladder / FBD rule (important)

Library blocks run on EN. If the rung feeding EN is false, the block doesn't
run and its outputs freeze. Give every library block its own unconditional
rung and wire commands into named pins. See ladder-rules.md.

Defaults

• Unwired permissives/interlocks default to TRUE (OK). Unwired fault inputs default to FALSE (healthy).
• Optional sensors are not installed until you say so (installed := FALSE).
• Every setting has a working default.

Inputs are TRUE = active

Inputs are TRUE = active; wire NC contacts through NOT at the pin. A fault
input is TRUE when tripped, a button TRUE when pressed, a switch TRUE when it
signals. The device blocks have no "NC" setting: a normally-closed contact (an overload
aux, a thermistor relay, a stop button, a flow switch) is inverted with NOT at
the pin or in the I/O mapping, e.g. Overload := NOT M1_OL_NC. A broken wire then
reads as tripped / pressed, the safe side.

Invalid settings

An invalid or out-of-range setting never runs anything that could damage
equipment. A setting that is not a number, infinite, negative where it can't be,
or out of range either falls back to a safe value and raises a warning
(wrnConfig, Warning), or, where no fallback is safe, keeps the device off with
a fault until it is fixed. Each block's doc lists its checks.

Interlock vs permissive

Neither is a fault. The device shows UT_STATE_INTERLOCKED.

Protections — every fault works the same way

Every protection in every block (overload, dry run, high pressure, travel
timeout…) is a UT_PROTECTION. Its response and how it resets are separate
choices, so latching is always optional:

UT_PROTECTION (settings + status in one)

Reset modes

Example: a sump pump overload. Overload uses UT_RST_AUTO. The maintenance
person resets the overload relay in the panel, the cause goes, and the pump goes
straight back into service. Nobody needs to touch an HMI.

Ways to reset a MANUAL fault (any one of these)

1. the block's Reset pin (a panel pushbutton);
2. the HMI command cmdReset;
3. switching the device to Off and back (resetByOff := TRUE, the default),
   so a selector switch is a reset.

Restart after a fault clears

• After an AUTO/RETRY recovery, the device resumes if it's still asked to run.
  That's the point of choosing auto recovery. A motor in Hand is not "still
  asked": a trip drops its hand start (as the interlock does), so the operator
  presses start again.
• After a MANUAL reset, a maintained run command must cycle (go FALSE and back to
  TRUE) before the device restarts, unless restartAfterReset := TRUE.

The status of a tripped device says how the trip will clear, by its prefix (see
Status): Fault: overload clears by itself, Retrying: no run feedback retries, Latched: overload needs a reset, Locked: no run feedback has used up its retries. The
wait still to run is in the record's timeLeft (and faultClearIn on the motors),
and in the protection's own timeLeft and retries.

Each block's record also has fault (any trip), warning (any warning),
faultCode : DWORD (one bit per protection), and faultId : UT_FAULT (the
highest-priority active one, by name). faultCode and faultId cover warnings
too: a protection set to WARN sets its bit and faultId while it is raised, as a
TRIP does.

UT_LEVEL — a protection with a setpoint

Used for analog alarm levels (HH/H/L/LL), current limits and so on: every
UT_PROTECTION field plus

UT_MEAS — a measurement that might be a switch, a transmitter, both, or nothing

Pumps and controllers watch measurements (pressure, flow, suction level) that
vary from site to site. Each one is a UT_MEAS:

So a site with just a high-pressure switch sets installed := TRUE,
sensor := UT_SENSOR_SWITCH, highSwitch := UT_LVL_HIHI, lowSwitch := UT_LVL_NONE.
A site with a transducer sets sensor := UT_SENSOR_ANALOG and the four setpoints.
H and L are warnings by default, so abnormal conditions can be dealt with
before they become trips.

Device modes — UT_MODE

• The mode starts at Off. Whatever the operator selects is retained inside the
  block. After a power cut it comes back as the device's powerUp says (see
  Power-up): by default in the mode it was left in.
• An HMI changes the mode by writing cmdMode (an INT): 0 Off, 1 Hand, 2 Auto,
  3 OOS. The block applies it once and sets cmdMode back to -1 ("no request");
  see HMI commands.
  The actual mode is in mode.

Where the mode comes from — modeSource : UT_MODE_SOURCE

Power-up

What a device's mode does after a power cut is a per-device setting,
powerUp : UT_POWERUP in its record (a PLC stop / start counts as a power-up too):

• A motor in Hand always needs a fresh start after a power cut (EN 60204-1),
  whatever powerUp says: the motor blocks never keep a Hand start.
• UT_HOA, whose Hand switches an output straight on, has handPowerUp : UT_HAND_POWERUP: UT_HPU_OFF (default) a Hand comes back Off; UT_HPU_KEEP
  Hand and its output come back.
• ForceOff on UT_MODE_SELECT holds a mode at Off
  without losing the choice (a plant-wide off, an isolator's auxiliary contact).
• Plant-level Off / Manual / Auto is UT_SYSTEM_MODE.

Device state — UT_STATE (one colour map for every device)

UT_STATE_OFF (0) · UT_STATE_STARTING · UT_STATE_ON · UT_STATE_STOPPING ·
UT_STATE_INTERLOCKED · UT_STATE_WARNING (running with a warning) · UT_STATE_FAULT ·
UT_STATE_INVALID · UT_STATE_OOS. For valves: OFF = closed, ON = open, STARTING/STOPPING = moving.

Status: every critical block says what it is doing and why

Any block that can stop equipment (motors, pumps, pump stations, duty and cascade
groups, speed control, valves, dosing, run limits, sequencers, interlocks, vessels)
has these status fields in its record, updated every scan:

The text never holds a number. The numbers that go with a status are in their own
fields: timeLeft for the countdown, statusUnit on the group blocks for the pump
or unit (its array index) the status is about, and counts such as runningCount.

HMIs and SCADA read the codes. UT_STATUS, UT_FAULT and UT_STOP are
enumerations. An HMI, Modbus or SCADA sees an enumeration as a number: the
member's position in its list, counting from 0, as in the tables below. The
debugger shows the name. Keep the words, alarm texts, colours and history in the
HMI or SCADA, keyed on the numbers. Each device has its own fields in its own
record: read them directly (Pump1.statusCode, Pump1.faultId).

The block always shows the most important reason, in this order (top first).
UT_STATUS_KIND gives the kind of any status:

Rules:

• The words start with their kind (Config:, Fault:, Retrying:, Latched:,
  Locked:, Warning:, Setting:, Waiting:, Blocked:, Not permitted,
  Hand:, Running, Starting, Stopping, Off, Idle; mode blocks show their
  mode: Auto, Manual: running (local)), then the detail.
• A device that is asked to run but is not running always says why.
• A status means the same in every block: UT_ST_RESTART_DELAY is a restart delay,
  UT_ST_INTERLOCK an interlock, wherever it appears. Each block's doc lists the
  statuses it uses.
• Show the status on the HMI next to the device; for a whole-site text line feed the
  statuses into UT_MSG_QUEUE.

Fault prefixes

A warning, fault or configuration status is a prefix followed by the words of the
fault or setting in faultId. The prefix tells you how the problem behaves:

For example Retrying: no run feedback, Latched: overload, Setting: full load current, Config: valve type. A setting with no words of its own reads a setting.

The numbers

The tables below give every member with its number, in list order from 0. These
numbers are fixed: a member added to the library later goes at the very end of its
list, so no number ever moves and an HMI's lists stay right after a library update.
The statuses up to UT_ST_CONFIG are grouped by kind; the ones after it (from
UT_ST_FIXED_SPEED) are not, so take a status's kind from the Kind column or from
UT_STATUS_KIND, never from its position.

UT_STATUS, UT_FAULT, UT_STOP and UT_KIND have the base type USINT (IEC 61131-3 Ed. 3,
UT_STATUS : USINT (UT_ST_IDLE, ...)): one byte each, and an HMI or SCADA reads them as
a USINT (0..255).

UT_STATUS: what the block is doing (statusCode)

UT_FAULT: which fault, warning or setting (faultId)

UT_STOP: why the last run ended (stopReason)

Time visibility

Every block that times something shows the time, so an HMI or SCADA can show a
countdown without parsing text:

They are in the block's record, or are outputs on blocks without one. Every
protection has its own timeLeft (UT_PROTECTION).
The status text holds no numbers: show timeLeft beside it.
UT_TIME_TEXT turns it into short text (1 h 20 m) for a
simple display.

Why it stopped

The motor, valve, pump, pump station, pump cascade, speed-control and dose records
keep why the last run ended and the last trip, so "what happened overnight" can be
read after the fact:

UT_RUN_LIMIT and UT_ZONE_SEQ keep endReason, and UT_STEP_SEQ lastResult, of the
same type. The numbers are in the UT_STOP table
above; UT_STOP_TEXT gives the words. The common ones:

The other members are used by the blocks named in their docs.

Signal quality — UT_QUALITY

UT_Q_BAD (0) · UT_Q_UNCERTAIN · UT_Q_GOOD · UT_Q_SIM. A block that isn't
running reports BAD, never a stale GOOD. This matches the BeeBus topic quality.

Other shared enums

Simulation

Device and signal blocks have simulate : BOOL. Feedbacks follow commands after a
realistic delay, signal blocks use simValue, and quality shows UT_Q_SIM. Use it
for commissioning and FAT. In the motor blocks simulation fakes only the run
feedback: the feedback checks (noFeedback, feedbackLost, stuck) see the
simulated one, and every other protection (overload, thermistor, drive fault,
driveNotReady, the current levels) still acts.

Retained data

Retain is kept to a minimum. Over a power cut the library keeps only, inside
the block:

1. The device's HMI mode (UT_MODE_SELECT: every motor and valve block, and
   UT_HOA; a pump's mode is its motor block's), and the plant mode and auto type
   of UT_SYSTEM_MODE. Whether the mode is used after a power cut is the device's
   powerUp setting.
2. Run hours, starts and valve strokes: UT_RUN_HOURS (total, service, today,
   yesterday), UT_STARTS (lifetime, today, yesterday) and the valves' stroke count.
3. Flow / volume totals and dose totals: UT_TOTALISER (every total, with what
   it needs to stay correct and never count twice) and UT_DOSE (doses,
   dosedTotal).
4. The progress of a run or zone program in progress, for its powerUp
   (UT_RPU_RESUME carries it on): UT_RUN_LIMIT (whether
   a run is active, how it started, whether RunHeld is on, its running time and
   volume) and UT_ZONE_SEQ (whether a program is running, how
   it started, the zone watering with its water time, volume and cycles, the pass,
   the HMI pause). Also UT_RUN_LIMIT's last-run summary, saved once per run end.

Nothing else is kept. Protection trips are not kept: a latched or MANUAL trip
is forgotten at power-up, and if the fault is still there it trips again. Inhibits,
retries, a dose in progress, a learned preact, alarm
states, leads, statistics, diagnostic counters and toggles all start fresh. (UT_TONR, like Siemens TONR and
Rockwell RTO, keeps its time only while the PLC is powered.) This needs only
Persistent Storage switched on in the project. To keep your settings across
power loss, declare your record variable RETAIN.

How often values reach storage. The controller saves all retained values
together, and only when something changed: a change after a quiet spell at once,
then at most once per period (default 10 s runtime, 1 min ESP32, 10 min other
boards). So what a block retains decides how hard it works the flash or EEPROM:

Blocks that count keep the live value in normal memory and copy it to their
retained snapshot every saveEvery. saveEvery = T#0s means the count is not
kept over a power cycle at all. At one save per 12 h even an STM32's 10,000-erase flash lasts about
13 years.

Totals and hours are accumulated as 64-bit integers with a fractional remainder,
not as REAL, so they stay exact on every target. On an AVR board LREAL is only 32-bit.

Timing

All timing uses real elapsed time (TIME(), 64-bit, constant within a scan), so
behaviour is identical at any task interval. Pulse inputs are limited by the scan rate (each doc states the limit).

No blocking code

No WHILE or REPEAT: every loop has a fixed bound. A loop is a FOR over an
array's bounds or over a small fixed count (leaving early with EXIT), or the
work is done with arithmetic. A scan can never hang, and its longest time is known.

HMI commands

• A BOOL cmdXxx acts once, on its rising edge. The block keeps the value it
  read the scan before, acts when it goes from FALSE to TRUE, and clears it to
  FALSE. A command that is held or forced TRUE (a Modbus coil left on, a debugger
  force) acts once, not every scan, and acts again only after it has been FALSE.
• An INT request (cmdMode, …) acts when a valid value arrives (a value that
  differs from the one read the scan before) and is set back to -1. An invalid
  value is ignored and also set back to -1.
• Stop / Off always wins over a start in the same scan.
• A master that rewrites a value every poll (a SCADA writing its whole register
  block each cycle), or two masters (a panel HMI and SCADA) commanding the same
  device, must not write the record's cmdXxx directly: put
  UT_CMD in front. Each master then writes its own variables,
  which nobody clears; UT_CMD reacts only to changes, applies local / remote
  (RemoteEnabled), lets stop win and passes one-scan requests into the record.
• Settings written by an HMI or SCADA can be checked before use with
  UT_SETTING_CHECK.

Names

IEC names are case-insensitive: Count and count in one block clash.
tools/check-names.py checks this, the reserved words and the names of every
installed library block.

Groups

A group block takes an array of member records, and each member block uses one
element. See UT_PUMP_STATION and UT_DUTY.