02 - Block reference

Sixteen blocks. UIO is the one every project needs; the rest are there when
you want what they do.

Nothing takes a bitmask or a bare channel number: where a block picks something,
it picks it by name.

UIO

Brings the board up and services it. First in the program, once per scan.

DIGITAL_IN

Sampled by UIO, so the value does not change during a scan. An input that
cannot be read reads false. No debounce and no inversion — R_TRIG, F_TRIG
and TON do that in your own program.

DIGITAL_OUT

Driven on the next UIO call. No fault feedback exists: the board has no
readback, so a shorted output looks exactly like a working one.

ANALOG_IN

ANALOG_OUT

ANALOG_CAL

One channel at a time, named rather than numbered.

HAT_POWER

This drives the HAT power enable, which each HAT uses to switch its own supply
through its own MOSFET — the base board has no switch of its own. Takes effect
immediately, not at the next UIO call. There is no sense line, so POWERED
reports the request, not what the HAT did with it.

NETWORK

The radio is shared. If something else brought the network up first — Modbus
TCP in the firmware, or a protocol library — this block reports it and changes
nothing, so the credentials here are only applied to a radio that is down, or
to one this block brought up itself. By the same rule, clearing ENABLE will
not switch off a radio this block did not start.

SSID and PASSWORD may change while connected (a settings page): on a radio
this block brought up, it leaves the network and joins again with the new ones.
CONNECTED drops while it joins; MQTT and Sparkplug come back by themselves.

Clearing ENABLE powers the radio down rather than merely disconnecting it,
which is the saving worth having on a battery. WIFI_SLEEP drives this pin to
duty-cycle it.

BUILTIN_BUTTON

The button built into the board, beside the antenna, also on the HAT header.

Use one instance. SHORT_PRESS and LONG_PRESS are consumed as they are read,
so a second instance would take presses the first never saw.

WIFI_SLEEP

Duty-cycles the radio, for a board on a battery.

btn();
wifiSleep(ENABLE := TRUE, WAKE := btn.SHORT_PRESS, AWAKE := T#5m);
net(ENABLE := wifiSleep.RADIO_ON, SSID := 'plant', PASSWORD := 'secret');

WAKE takes any signal, not only the button — a shift starting, a fault, a
level switch. Clearing ENABLE hands the radio back and stops duty-cycling it.

SLEEP

Deep sleep saves the retained values first, so the board goes to sleep about
10 to 50 ms after TRIGGER; light sleep does not need to. See
04 Sleep, particularly about DO05 to DO08.

RESTART

For a site that has to recover by itself: a link supervisor that has tried the
modem and the HAT power asks for one controlled restart, and this does it. It
saves the retained values first, so nothing the store was still holding is lost;
the restart waits for that save, about 10 to 50 ms. A REQ already TRUE at
start-up is not an edge.

sup( LinkOk := sp.BORN, RebootAllowed := NOT pumpRunning, Data := supCfg );
reboot( REQ := sup.RebootReq );

PULSE_COUNT

A flow meter, or any pulse output, on a digital input — counted in hardware.

VAR RETAIN flowTotal : LREAL; END_VAR
flow( TOTAL := flowTotal, CHANNEL := 3, K_FACTOR := 100.0, RATE_PER := T#1h );

See 07 Pulses and diagnostics.

SYS_INFO

How the controller itself is doing. No inputs; refreshed once a second.

UIO_EXPANSION

I2C expansion modules on the board's I2C bus: which are fitted, which answer,
and their channels in two images.

UIO_XMOD: kind (UIO_XKIND), address (BYTE), fitted (BOOL, default
TRUE) and first (INT, the image row of channel 1) are settings; count,
present, ok, state (UIO_XSTATE) and errors are status.

No chip drivers are built in yet: a fitted module that answers reads
UIO_XS_NO_DRIVER and is not ok. See 08 I2C expansion.

UIO_I2C_SCAN

The I2C addresses that answer, for commissioning.

The enumerations

UIO_MODE — UIO_VOLTAGE, UIO_CURRENT.

UIO_CHANNEL — UIO_AI01..UIO_AI04, UIO_AO01, UIO_AO02.

UIO_SLEEP — UIO_LIGHT_SLEEP, UIO_DEEP_SLEEP.

UIO_WAKE — UIO_WAKE_NONE, UIO_WAKE_TIMER, UIO_WAKE_INPUT, UIO_WAKE_RESET.

UIO_RESULT — UIO_OK, UIO_NOT_READY, UIO_INVALID_ARGUMENT, UIO_IO_ERROR,
UIO_NO_DATA, UIO_TOO_LARGE, UIO_UNSUPPORTED.

UIO_RESET — UIO_RST_UNKNOWN, UIO_RST_POWER_ON, UIO_RST_EXTERNAL,
UIO_RST_SOFTWARE, UIO_RST_PANIC, UIO_RST_INT_WDT, UIO_RST_TASK_WDT,
UIO_RST_OTHER_WDT, UIO_RST_DEEP_SLEEP, UIO_RST_BROWNOUT, UIO_RST_SDIO,
UIO_RST_USB, UIO_RST_JTAG, UIO_RST_EFUSE, UIO_RST_PWR_GLITCH,
UIO_RST_CPU_LOCKUP (the ESP-IDF reset reasons, in order).

UIO_XKIND — UIO_XK_NONE, UIO_XK_MCP23017_DI, UIO_XK_MCP23017_DO,
UIO_XK_PCF8574_DI, UIO_XK_PCF8574_DO, UIO_XK_PCA9555_DI,
UIO_XK_PCA9555_DO, UIO_XK_ADS1115_AI, UIO_XK_MCP4728_AO,
UIO_XK_GP8413_AO, UIO_XK_TMP117_T, UIO_XK_MCP9808_T, UIO_XK_SHT4X_TH.

UIO_XSTATE — UIO_XS_UNUSED, UIO_XS_OK, UIO_XS_NOT_FITTED,
UIO_XS_MISSING, UIO_XS_NO_DRIVER, UIO_XS_FAILING, UIO_XS_BAD_ADDRESS,
UIO_XS_IN_USE, UIO_XS_NO_ROOM.