06 - Diagnostics

Two blocks, and neither of them puts anything extra on the bus except when you
ask it to.

MODBUS_STATUS — how the link is doing

health( NODE := node );

No inputs at all. It reports and changes nothing, which is why it is safe to
drop onto a diagnostic page anywhere.

The three error counters, and what each one means

This is the part worth putting on a screen, because the difference between
them says which fault you have, and none of them looks any different from the
application's point of view:

All three flat while a device does not answer means the bytes are not
arriving at all: wrong port, wrong wires, transmit and receive swapped, or the
device is off. That is a useful negative result and it takes two seconds to
check.

SENT and RECEIVED are frames, both directions. On a healthy client they
track each other. SENT climbing while RECEIVED stays put is nobody
answering.

PENDING is requests queued and not yet concluded. It should hover near zero
and come back down. One that climbs steadily is a program issuing requests
faster than the bus can carry them — see 10 - Scan rate.

To zero the counters, pulse RESET_STATS on the node that owns the link.

FRAMING_REASON

The first thing to read when frames go missing, and the answer to the commonest
question asked of any Modbus library: why is my RTU splitting frames.

RTU marks the end of a frame with silence — three and a half character times of
it. A USB adapter, a virtual serial port or a busy PLC scan can all destroy
that silence by delivering bytes in clumps. So the library measures the line and
picks a rule, and this pin says which rule and why, in a sentence you can read
off the screen.

On a TCP link it says so and stops there — the header carries the length, so
there is nothing to predict and nothing to measure. On an RTU-over-TCP link
it reports the RTU rule instead, which is how you tell from one pin which of
the two a terminal server actually gave you.

MODBUS_DEVICE — how one device is doing

drive( NODE := node, UNIT := 2, IDENTIFY := askOnce );

ANSWERING, SILENT and ROUND_TRIP are read off traffic you are
already making. With POLL at 0 this block sends nothing at all, so a
screen showing thirty devices you already read costs not one extra frame.

Which means a device nobody asks anything reads as not answering. That is
literally true and thoroughly unhelpful — the device may be in perfect health
and simply have nothing to say, because nothing has spoken to it. If this block
is the only thing pointed at a device, give it a POLL:

standby( NODE := node, UNIT := 5, POLL := T#2s );

It sends the standard link test, function code 8: whatever goes out comes back
unchanged, and no register is touched. A device that does not implement FC 8
answers with an exception — which still proves it is alive and still counts
as answering, because a unit that is transmitting is a unit that is there. So
the check works even on devices that refuse it.

SILENT = -1 is not a long silence

It means this device has never answered at all, which is a different fault
from one that has gone quiet — and the two send an engineer to opposite ends of
the site:

An alarm list that shows both as "no comms" throws that away. Keep them apart:

deviceMissing := (drive.SILENT < 0);              (* never there *)
deviceLost    := (drive.SILENT > 5000);           (* was, is not *)

ANSWERING is the simple form: TRUE while the device has answered within
GONE, which defaults to five seconds.

ROUND_TRIP

The number to quote when somebody asks whether a device is slow or the bus is.
It is measured, not configured.

A drive answering in 45 ms on a bus whose other devices answer in 6 ms is a
slow drive, and no amount of changing the baud rate will help. A bus where
everything answers slowly is a bus problem. Without this number the two
arguments go round for an afternoon.

IDENTIFY — the device's own nameplate

A rising edge asks the device who it is, using function code 43 — the same
information a handheld tool shows:

drive( NODE := node, UNIT := 2, IDENTIFY := askOnce );

IF drive.IDENTIFIED THEN
    (* one scan, when the nameplate arrived *)
    logLine := CONCAT(drive.VENDOR, drive.PRODUCT);
    askOnce := FALSE;
END_IF;

Ask once at start-up and keep what comes back. It does not change.

Not every device implements it. One that does not answers with an exception,
which arrives as MODBUS_REFUSED — that is a normal answer, not a fault worth
alarming on.

Every status code

STATUS is on every block. MODBUS_OK when fine.

Accepted

Refused before anything reached the wire

These are your program's mistakes, and being told immediately is the point —
you can fix a bad request, and you cannot tell a bad request from an absent
device once it has timed out.

Concluded on the wire

Link faults

MODBUS_REFUSED is the most encouraging failure on this list. It means
frames are going out, arriving, being understood and being answered. Everything
below the application layer works, and you are arguing about an address.

Next: 07 - Block reference