###############
 Ebyte M31 I/O
###############

The ``driver/m31`` package defines one host and up to fifteen expansion
modules. A module's slice index is its slot. The host has eight digital
inputs and eight digital outputs. Mixed expansions add eight of each,
input expansions add sixteen inputs, output expansions add sixteen
outputs, and analog expansions add eight voltage outputs.

Each point uses ``m{slot}.di{channel}``, ``m{slot}.do{channel}``, or
``m{slot}.ao{channel}``. Inputs, coils, and analog registers have
independent zero-based address ranges that continue across modules.
Configure every physical analog output channel for zero through ten
volts before operation. The driver does not configure the module's
output range. Analog registers represent zero through ten volts as zero
through 10000. Hardware pulse widths are whole milliseconds from 50
through 65535. Their width registers start at ``0x30d4`` and their
output-mode registers start at ``0x32c8``, both indexed by coil address.
Mode zero is level control and mode one is pulse control.

Descriptors use manufacturer ``ebyte`` and firmware ``unknown``. The
package does not read the host identity registers. Pulse capabilities
accept commands but do not report transient coil state. Input
capabilities are read-only.

Tests verify topology and descriptor values without a physical module.
They do not confirm physical expansion limits or relay timing under
load. The conservative sixteen-module limit includes the host.

***************
 Modbus client
***************

``NewTCPClient`` supplies a caller-owned, serialized connection through
``Client``. Connect selects the configured unit and has a one-second
timeout. Each write has a one-second deadline. Each response has a
two-second deadline measured after the request write. Caller deadlines
and cancellation can stop it earlier. Each response must match the
transaction, unit, function, length, and write acknowledgement.
Supported functions are 01, 02, 03, 05, 15, and 16. No external Modbus
package is required.

In-memory stream tests check request bytes, response validation,
exceptions, truncation, cancellation, and timeouts. They do not verify a
physical host or TCP network behavior.

*******************
 Polling lifecycle
*******************

``New`` validates ``Settings`` and takes a shared publisher and a
client. The caller runs both the publisher and the integration through
``driver.Run``. The command keeps its explicit driver list empty and
does not open hardware connections.

Every connection writes and reads back all digital output modes. Pulse
outputs also write and verify their widths before online. The first
complete read establishes a baseline without events. A later input
change sends retained state followed by a pressed or released event. All
events from one input read share its completion time, before coil and
analog reads. A steady output or analog change sends reported state.
Pulse coils do not send transient feedback.

A device error publishes offline and retries after one second, doubling
to thirty seconds until a complete baseline succeeds. Device failures do
not log inside the integration. Publication and cleanup failures return
to the runner. Cancellation closes the client without a false offline
publication. Refresh requests cached snapshots through the shared
publisher without repeating events or physical work.

Polling can miss an edge that starts and ends between reads. It does not
expose input counters. A configured poll interval is a target, not a
guaranteed edge latency. Tests use fake clients and simulated time for
baseline, transitions, pulse verification, reconnect, refresh, shutdown,
and error propagation. Physical timing remains unverified.

*****************
 Output commands
*****************

The shared router supplies one device FIFO for singles and batches. The
driver checks ownership, output access, value type, and expiry before
physical work. Steady outputs accept Boolean values. Pulse outputs
accept only true and complete after the function 05 acknowledgement,
without coil readback or transient reports. Analog outputs accept JSON
numbers from zero through ten volts and round them to millivolts. Exact
range checks precede floating-point conversion.

A batch accepts steady digital outputs only. It sorts eligible targets
by coil address, writes each contiguous range with function 15, and uses
function 05 for an isolated target. Gaps remain unchanged. It reads the
complete coil range once after all writes. A transport failure fails all
pending members, including those in an earlier successful range. A
mismatch fails only that member. Commands that expire before their write
are rejected. Physical writes also have the earliest member deadline. If
an expiry rejection cannot be sent after an earlier range is written,
the driver reads back that range and records its outcomes before it
returns the publication failure. A readback failure records failed
outcomes, so replay cannot repeat the earlier physical writes.

Changed feedback is sent before results. Each changed commanded point
has its command ID as causation. Unrelated output changes have no
command cause. Equal feedback needs no second report. The framework
ledger records all outcomes before feedback or result publication, so a
failed send cannot cause another physical action on replay. A repeated
command reuses its first result ID, time, status, and reason. The ledger
is memory-only and bounded to 256 records for the assembly. An eviction
or process restart removes that duplicate protection.

Commands received during device backoff are rejected if invalid or
expired, and fail as unavailable otherwise. No command executes before
the connection setup and baseline complete. Shutdown does not retry a
physical action. Results use fixed failure reasons without transport
addresses or untrusted response data. Drivers return errors and do not
log them. Publication and independent cleanup failures stop the driver
through the runner.

Fake tests cover single writes, cross-bank batches, gaps, partial
transport failure, mismatches, pulses, analog boundaries, expired work,
cancellation, duplicate replay, and failed feedback or result sends.
They do not verify electrical simultaneity, contact timing, hardware
interlocks, or physical pulse width. Local motor protection remains
necessary when network commands control moving equipment.

A caller cancellation interrupts blocked transport work through its
deadline. A timeout caused only by that interruption is a context stop
for the runner. A joined independent transport or cleanup failure stays
a failure. Operation timeouts while the worker context is active remain
device failures and enter reconnect recovery.