08 - I2C expansion

More digital inputs and outputs, analog channels and temperature, on small I2C
modules beside the Node: the same bus as the board's own ADC (16#49) and DAC
(16#5F), brought out on the Grove connectors and the HAT header.

No chip drivers are built in yet. Everything here works today - the module
table, detection, the images, the not-present handling - and a fitted module is
found by its address answering. Until this firmware has a driver for its kind
it reads UIO_XS_NO_DRIVER and is not ok, so nothing trusts its channels.
The drivers come one family at a time, each with a bench test (below).

Pins first

UIO_EXPANSION

A row: UIO_XMOD

The kinds

A second ADS1115 must use 16#48, 16#4A or 16#4B: 16#49 is the board's.

The states

UIO_I2C_SCAN

A healthy board always shows 16#49 and 16#5F.

Wiring it into the IO map

The module table is a settings table like any other: retain it, let the HMI
edit it. The images are plain arrays the project's IO code copies into the
IO map's image, with the module's ok as each channel's quality:

VAR_GLOBAL RETAIN
  XMODS : ARRAY[1..4] OF UIO_XMOD;
END_VAR
VAR_GLOBAL
  XDI : ARRAY[1..32] OF BOOL;
  XAI : ARRAY[1..8] OF REAL;
END_VAR

expansion(MODULES := XMODS, XD := XDI, XA := XAI);

(* One row of the IO map's module table per expansion row (UT_IO_MAP):
   src I2C, module = the row, first / count into the IO map's image. *)
FOR m := 1 TO 4 DO
  mods[I2C_ROW0 + m].ok := XMODS[m].ok;
  FOR c := 0 TO XMODS[m].count - 1 DO
    di[I2C_FIRST + XMODS[m].first + c].q := XDI[XMODS[m].first + c];
    di[I2C_FIRST + XMODS[m].first + c].bad := NOT XMODS[m].ok;
  END_FOR;
END_FOR;

A function mapped to a module that is not ok takes its fail-safe, and the IO
map says why. A module that is not there is never read as OFF.

What it does on the bus

• One transaction per call, round the table, so the scan time stays flat
  however many modules there are.
• Missing modules are asked again every five seconds, so one plugged back
  in is found by itself. A working module that fails three transactions in a
  row is treated as missing and found again.
• One lock for the bus. The board's own ADC and DAC, UIO_EXPANSION and
  UIO_I2C_SCAN share Wire1 under one lock, whatever PLC task each runs in. A
  block that cannot have the bus within a few milliseconds tries again next
  scan rather than stalling its task.
• I2C is a cabinet bus. Keep modules within about a metre of the Node.
  Anything in the field belongs on RS485 (modbee-modbus), or behind a
  differential I2C extender.

Adding a chip driver

A driver is three small functions and one table entry - nothing else in the
library changes. The interface is in resources/node-uio/src/NodeUioExpansion.h:

struct UioXDriver {
  uint8_t kind;                                                    // UIO_XK_...
  bool (*start)(UioXBus& bus, uint8_t address);                    // identify + configure
  bool (*read)(UioXBus& bus, uint8_t address, UioXChannels& in);   // input kinds
  bool (*write)(UioXBus& bus, uint8_t address, const UioXChannels& out);  // output kinds
};

UioXBus gives probe, write, read and writeRead (a register write then
a read with a repeated start), each one complete transaction under the bus
lock. A driver never touches Wire1 itself.

1. Write the driver in a new file beside NodeUioExpansion.cpp, e.g.
   NodeUioDrvMcp23017.cpp:
   • start: check the chip's identity where it has one (an ID register,
     register defaults after reset) and configure it (port directions, pull-ups,
     gain, conversion rate). Return false if it is not that chip or does not
     configure.
   • read (input kinds): fill in.bits[0..count-1] or
     in.values[0..count-1] in channel order. For a slow converter (ADS1115,
     temperature) start a conversion on one call and read it on a later one
     rather than waiting: the scan must never stall.
   • write (output kinds): send out.bits or out.values. Writing only
     what changed is the driver's choice.
   • Every function returns false on a failed transaction; the engine counts
     them, and three in a row make the module missing until it answers again.
2. Append it to kDrivers[] in NodeUioExpansion.cpp.
3. Add a simulated chip to the expansion host test (the test has a PCF8574 example)
   and run it before going to the bench.
4. Bench test on a real Node with the module: present / unplugged / plugged
   back, every channel, and the scan time with all eight rows fitted.

A driver can also live in another library and be added at run time with
uioXRegisterDriver(&driver) (up to eight).

Families planned, in order: MCP23017 / PCA9555 (16-bit DI/DO), PCF8574 (8-bit
DI/DO), ADS1115 (AI), MCP4728 / GP8413 (AO), TMP117 / MCP9808 / SHT4x
(temperature). Each costs about 1-3 KB of flash; only the families in a
project's table are polled.