X-Git-Url: https://git.giacomolli.uk/onehouse/blobdiff_plain/9b7392e6965fe1b2e858f63c52113899e4bf3fb4..refs/heads/master:/doc/m31.rst?ds=sidebyside

diff --git a/doc/m31.rst b/doc/m31.rst
index b9b714f..b0305e3 100644
--- a/doc/m31.rst
+++ b/doc/m31.rst
@@ -27,3 +27,104 @@ 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.