04 - Registers

The Modbus side. Your variables sit at numbered addresses, and peers reach them
the way they would reach any Modbus device.

Three blocks:

The four lists

Modbus has four separate numbered lists. Address 40 in one is a different thing
from address 40 in another.

The rule of thumb: inputs are read-only, coils and holding registers are
writable. Put anything a peer should be able to change in a coil or a holding
register, and anything that is purely a reading in a discrete or input register.

Saying what you are passing

Every one of the three blocks has a single VALUE pin. Put the variable on it:

VALUE := iSetpoint        (* one value *)
VALUE := aTrend           (* ARRAY [0..99] OF WORD — a range of registers *)
VALUE := aValves          (* ARRAY [0..7] OF BOOL  — a range of coils *)
VALUE := CFG              (* a STRUCT — every member, one after the other *)

Nothing is wrapped. The pin carries the address, the type and — for a STRUCT —
its layout, so one block covers a single value, a whole range and a whole
STRUCT without different blocks for each.

TABLE is what says bits or registers, and it is a pin you were setting
anyway. A block reading TABLE := BEEBUS_MB_COIL knows it is dealing with bits; one
reading BEEBUS_MB_HOLDING_REG knows it is dealing with 16-bit values. The variable
does not have to say so a second time.

An array has to be declared with fixed bounds — ARRAY [0..99] OF WORD, not
ARRAY [*]. A variable-length array is a view rather than a variable, and views
travel on in-out pins only.

How a value is laid out

Every value takes the registers its type needs, from ADDRESS on, one after the
other in declaration order:

High word first is what a Modbus master or HMI calls "ABCD", "big-endian"
or "high word first" ("ABCDEFGH" for a 64-bit value). Set that on the far end
once and every 32- and 64-bit value reads right. A 32-bit value takes both its
registers in one write, a 64-bit one all four.

A register you mask is a WORD, not an INT. A register is sixteen raw
bits, and WORD is the type a program can work on bit by bit: myWord.6 is bit
6, and AND, OR, XOR, NOT, SHL, SHR, ROL and ROR take ANY_BIT,
which INT is not. A VFD control or status word belongs in a WORD. Use INT
for a signed reading and UINT for an unsigned one.

In BEEBUS_MB_COIL and BEEBUS_MB_DISCRETE_INPUT every member has to be a
BOOL, one address each. WSTRING is refused everywhere — a value quietly cut
down would be wrong rather than missing. A refused variable is refused whole, with LAST_ERROR naming
the member: skipping it would move every address after it.

Sharing your variables — BEEBUS_MB_MAP

mapSpeed( NODE := node, TABLE := BEEBUS_MB_HOLDING_REG, ADDRESS := 40,
          VALUE := iSpeed );

iSpeed is holding register 40 from that moment. A peer reading gets what
it holds now; a peer writing changes it. Nothing is copied, and there is no
request pin.

A range works the same way:

mapTrend( NODE := node, TABLE := BEEBUS_MB_HOLDING_REG, ADDRESS := 100,
          VALUE := aTrend );

aTrend : ARRAY[0..99] OF WORD at address 100 becomes addresses 100 to 199. The
array's lower bound maps to ADDRESS whatever that bound is.

Outputs

WRITTEN is the one to use. It tells you a peer changed the value rather
than your own program doing it:

IF mapSetpoint.WRITTEN THEN
    (* somebody sent us a new setpoint — act on it *)
    bNewSetpoint := TRUE;
END_IF;

When one write covers several members — an HMI sending a whole block — the
WRITTEN_* outputs name the first (lowest address) and WRITTEN_COUNT says how
many there were.

One instance, one mapping

TABLE, ADDRESS and VALUE are taken on the first scan the node is there.
Changing them later does nothing, and calling the same instance twice does not
map a second range. Two separate ranges are two instances — or one STRUCT.

A whole STRUCT of settings

This is what an HMI needs. Put every setting in one STRUCT:

TYPE PLANT_CFG : STRUCT
  levelHiMm   : REAL := 1500.0;   (* 0..1 *)
  levelLoMm   : REAL := 500.0;    (* 2..3 *)
  runTime     : TIME := T#2h;     (* 4..5   DINT ms *)
  pumpEnable  : BOOL := TRUE;     (* 6      0 / 1 *)
  siteName    : STRING(16);       (* 7..15  9 registers *)
END_STRUCT END_TYPE

cfgMap( NODE := node, TABLE := BEEBUS_MB_HOLDING_REG, ADDRESS := 0,
        VALUE := CFG );

The HMI writes straight into CFG. WRITTEN says a write happened and
WRITTEN_NAME which setting, so the program can check it and put the old value
back when it is out of range:

IF cfgMap.WRITTEN THEN
    IF CFG.levelLoMm >= CFG.levelHiMm THEN
        CFG.levelLoMm := levelLoInUse;                     (* refused *)
        sRefused := CONCAT('Setting refused: ', cfgMap.WRITTEN_NAME);
    END_IF;
END_IF;

Add new members at the end. One added in the middle moves every address
after it. A spare or two at the end costs nothing.

The address table is generated, not typed. A table generator
reads the .st file that declares the STRUCT and prints every member's
address, type and register count as Markdown, and as JSON for an HMI's
firmware.

Safe states

Never on a setting or a command. A safe value is for a live setpoint a peer
keeps driving; a setting or a command written by an HMI or SCADA must never
change because the link dropped — the PLC runs on its own.

A writable address has a problem: the peer that was driving it goes quiet, and
the last value it sent sits there forever. On a setpoint that can be dangerous.

mapSetpoint( NODE := node, TABLE := BEEBUS_MB_HOLDING_REG, ADDRESS := 40,
             ON_LOSS := BEEBUS_MB_RESET_TO_VALUE, SAFE_VALUE := 5,
             VALUE := iSetpoint );

SAFE_APPLIED pulses when it happens, so you can log it or raise an alarm.

Two things to know:

FAILSAFE := TRUE on the node block turns the whole mechanism on. Without
it, ON_LOSS does nothing.

Only a single value has a safe state. A range has no one safe value and a
string has no numeric one, so ON_LOSS applies to single-value bindings on a
writable table. Anything else ignores it.

Reading a peer — BEEBUS_MB_READ

readLevel( REQ := bReadNow, NODE := node, PEER := 20,
           TABLE := BEEBUS_MB_HOLDING_REG, ADDRESS := 40,
           VALUE := iRemoteLevel );

Edge-triggered. The read goes out on the rising edge of REQ. Holding
REQ high gives you one read, not a stream.

The usual shape:

readLevel( REQ := bReadNow, ... );

IF readLevel.DONE THEN
    (* iRemoteLevel is fresh this scan *)
END_IF;

IF readLevel.ERROR THEN
    eLastFault := readLevel.STATUS;
END_IF;

A range is the same with a different wrapper:

readTrend( REQ := bReadNow, NODE := node, PEER := 20,
           TABLE := BEEBUS_MB_HOLDING_REG, ADDRESS := 100,
           VALUE := aRemoteTrend );

LENGTH lets you move fewer values than the variable holds — LENGTH := 0 uses
all of it. Asking for more than it holds is refused rather than reading off the
end.

A STRUCT reads the same way, laid out exactly as BEEBUS_MB_MAP lays it out,
so reading a peer's whole settings block into a STRUCT of the same type lands
member for member — up to 125 registers in one request. The answers are
unpacked on the scan DONE is set, never half a value at a time.

Writing to a peer — BEEBUS_MB_WRITE

writeSetpoint( REQ := bSend, NODE := node, PEER := 20,
               TABLE := BEEBUS_MB_HOLDING_REG, ADDRESS := 40, CONFIRMED := TRUE,
               VALUE := iNewSetpoint );

Only two of the four lists can be written: BEEBUS_MB_COIL and BEEBUS_MB_HOLDING_REG.
There is no Modbus function code for writing a discrete input or an input
register, so naming one is refused with BEEBUS_INVALID_ARGUMENT rather than
sent and lost.

A range or a whole STRUCT writes the same way, and is one request rather than
one per address (up to 123 registers). To change one setting in a peer's
settings STRUCT, write a variable of that member's type to that member's
address — a REAL to its two registers, a STRING(16) to its nine. A peer
refuses a value its member cannot hold, and the write ends in ERROR.

writeValves( REQ := bSend, NODE := node, PEER := 20,
             TABLE := BEEBUS_MB_COIL, ADDRESS := 0, CONFIRMED := TRUE,
             VALUE := aValves );

CONFIRMED — the pin that matters

CONFIRMED := FALSE puts the value on the wire once and forgets it. DONE
means it was sent. Nothing is retried, and a lost frame is a lost value you
will not hear about. That is the right trade for a value you send every scan
anyway, where the next one is along shortly.

CONFIRMED := TRUE keeps it queued until the peer says it took it, retries
if nothing comes back, and reports failure. DONE means the peer has it.

Use CONFIRMED := TRUE for setpoints and commands. A lost setpoint looks
exactly like a delivered one otherwise, and you find out when the plant does
the wrong thing.

Use FALSE for a fast cyclic value where the next update fixes any loss.

Strings

A STRING maps like anything else:

mapStatus( NODE := node, TABLE := BEEBUS_MB_INPUT_REG, ADDRESS := 200,
           VALUE := sStatusText );

It is packed two characters to a register, then the terminator, so a
STRING(n) takes n/2 + 1 addresses: a STRING(32) takes 17 and carries all 32
characters. A peer reads it with BEEBUS_MB_READ into its own STRING and
gets the text back.

WRITTEN fires once for the whole string rather than once per register.

What can go wrong

BEEBUS_SUPERSEDED is not a fault. If you write the same address twice before
the first goes out, the newer value wins and the older one is reported rather
than vanishing.

Next: 05 - Topics, or 08 - Patterns for these
in a real program.