UT_IO_MAP_IN — Input IO map: terminals to functions

Your plant logic reads functions ("well float HH", "pump 1 overload"), never a
terminal. The IO map connects each function to a channel from its settings, so
re-wiring a site, or moving a signal to an I2C module or a remote device, is a
setting, not a program change. It also tells your logic whether each value can be
trusted, gives a fail-safe value when it can't, and lets a commissioning engineer
force an input for a set time.

UT_IO_MAP_IN does the inputs; UT_IO_MAP_OUT does the outputs.
The two share the module table and the force slots. The IO types (UT_IO_…) are
described on this page.

Call order in the scan:

1. Your IO code copies the hardware into the input image (DigImg[n].q,
   AnaImg[n].v) and sets each module's ok.
2. UT_IO_MAP_IN.
3. Your logic, which reads Dig[n].q, Dig[n].ok, Ana[n].v.
4. UT_IO_MAP_OUT.
5. Your IO code copies the output image to the hardware.

Pins

Number every array from 1 (ARRAY[1..n]). The row number of a function is its
number on the IO page, and 0 means "none" in the image's fn.

Using it

VAR
  IoIn    : UT_IO_MAP_IN;
  DiFn    : ARRAY[1..16] OF UT_IO_DI;    (* 1 = well float HH, 2 = pump 1 overload, ... *)
  AiFn    : ARRAY[1..4] OF UT_IO_AI;     (* 1 = sump level, ... *)
  DiImg   : ARRAY[1..16] OF UT_IO_DCH;   (* board DI 1..8, I2C module DI 9..16 *)
  AiImg   : ARRAY[1..4] OF UT_IO_ACH;
  IoMods  : ARRAY[1..6] OF UT_IO_MOD;
  IoForce : ARRAY[1..4] OF UT_IO_FORCE;
  IoInSt  : UT_IO_MAP_DATA;
END_VAR

(* 1. your IO code: terminals into the image *)
DiImg[1].q := %IX0.0;
DiImg[2].q := %IX0.1;
AiImg[1].v := INT_TO_REAL(%IW0);
IoMods[1].ok := TRUE;                  (* the board always answers *)
IoMods[3].ok := I2cDiModuleOk;         (* from the I2C driver *)

(* 2. the IO map *)
IoIn(ReleaseAll := NOT HmiLinkOk, Dig := DiFn, Ana := AiFn, DigImg := DiImg, AnaImg := AiImg,
     Mods := IoMods, Force := IoForce, Data := IoInSt);

(* 3. your logic reads functions *)
Pump1(Demand := DiFn[1].q, ...);
Level(In := AiFn[1].v, Data := LevelData);

The settings, for example: IoMods[1] is kind := UT_IOK_DI, src := UT_IOS_BOARD,
module := 1, first := 1, count := 8. DiFn[2] (the pump 1 overload, an NC aux
on board input 2) is src := UT_IOS_BOARD, module := 1, ch := 2, nc := TRUE,
failSafe := TRUE.

Addresses

A channel's address is three numbers:

UT_IO_SRC: where a channel is

UT_IO_KIND: what a module's channels are

The module table UT_IO_MOD

One row per module. UT_IO_MAP_IN looks after the DI and AI rows, UT_IO_MAP_OUT the
DO and AO rows.

A function's module is the first row with the same kind, src and module.
Channel ch is image row first + ch - 1.

The image UT_IO_DCH, UT_IO_ACH

One row per terminal. The input image (DigImg, AnaImg here) and the output
image (on UT_IO_MAP_OUT) are separate arrays.

The input image always keeps the real terminal value, also while it is forced: the
IO page can show both.

Digital input function UT_IO_DI

Analog input function UT_IO_AI

Quality UT_IO_Q

The why of a function, the state of a module or of a force slot. A function's
ok is TRUE only for OK and FORCED.

Force slot UT_IO_FORCE

One row per force. A slot names a channel, not a function, so a spare terminal can
be forced too. Declare the slots without RETAIN.

The commands act once, on their rising edge, and the block clears them. A command
held on (a Modbus coil, a debugger force) acts once. How a slot runs is on
UT_IO_FORCE_RUN.

Record UT_IO_MAP_DATA

One per map (one for inputs, one for outputs). Status only.

Status

statusCode, faultId and statusText give the most important problem, in the
order below. The text is rebuilt only when the code or the fault changes. The
numbers are in conventions.

A Config: status here does not stop the block: the other functions carry on, and
the function with the wrong address reads its failSafe.

How it works

1. Each scan, for each function row, the block finds its module in the table and its
   row in the image, and checks in this order: not fitted (src NONE), no module,
   no channel, forced, module not fitted, module missing, channel bad, else OK.
2. Good or forced: q / v is the terminal (or the forced value), ok TRUE.
   Digital: inverted when nc is set, then debounced.
3. Not good: q / v reads the function's failSafe, never a plain "off", and
   ok is FALSE. Your logic decides what a lost signal means: a high-level float
   with failSafe := TRUE reads "high" when its module drops off the bus.
4. Not fitted (src NONE): reads failSafe, or FALSE / 0.0 with UnusedOff.
   ok stays FALSE and why UNUSED. Use UnusedOff when an option that is not
   installed must read "not active", while a fitted signal that is lost still reads
   its failSafe. A function on a module that is not fitted (fitted FALSE) always
   reads its failSafe.
5. A channel that comes back (good again after not fitted, missing, bad or a wrong
   address, and on the first scan): q follows it at once, with no debounce. When a
   force ends, the real value comes back through the debounce.
6. Debounce: a new state must hold debounce before q changes, on and off. A
   shorter pulse is ignored.
7. One input channel can feed several functions (no warning). The image's fn shows
   the first one.
8. The status and counts are worked out last. Modules of kind DO and AO, and force
   slots of kind DO and AO, are left to UT_IO_MAP_OUT.

Forcing an input (commissioning)

• Fill a slot with kind (DI or AI), the address and the value (q or v), then
  set cmdForce. Inputs can be forced at any time (no permit).
• The force goes on the terminal, before the NC setting and before scaling, as a
  test wire would. An NC function sees a forced q TRUE as "contact made", which is
  inactive. A forced analog raw value goes through UT_ANALOG_IN's checks: force
  2.0 mA to test its wire-break alarm.
• The debounce is skipped while forced. A forced channel on a missing or not-fitted
  module reads as good (why FORCED) while forced; the module still shows its state.
• Each force ends by itself after ForceTime (5 s by default, at most 10 min).
  cmdForce again starts the time again. cmdRelease, or ReleaseAll, ends it at
  once. A shorter ForceTime cuts a running force's time at once.
• A slot whose address does not exist is refused (state NO_MODULE or NO_CHANNEL).
  Setting a slot's kind to NONE ends its force.
• Changing the address of a slot that is forcing moves the force to the new channel
  (if it exists). Release it first.
• These slots are separate from the debugger's force.

Invalid settings

• A wrong address or a module not fitted: that function reads its failSafe,
  ConfigBad and a Config: status. The rest of the map carries on.
• ForceTime 0 or negative: 5 s is used; over 10 min: 10 min. Setting: force time.

Power cut

Nothing is kept: every force ends at a power cut, a PLC stop or a program download.
The functions start again on the first scan, with no debounce. To keep the settings
(src, module, ch, nc, debounce, failSafe, the module table), write them
from your program or declare those arrays RETAIN. Never declare the force slots
RETAIN.