Keep interrupted Modbus work a context stop

[onehouse] / doc / m31.rst

diff --git a/doc/m31.rst b/doc/m31.rst
index 5b374efbf5edd366939a95e174fcfecccc8b016f..9d9cc42e69cb4171bf54cd2158709cfd2de6a64c 100644 (file)
--- a/doc/m31.rst
+++ b/doc/m31.rst
@@ -72,3 +72,53 @@ 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.
 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.
+
+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.