Poll and command shared Alamo thermostats

[onehouse] / doc / alamo.rst

diff --git a/doc/alamo.rst b/doc/alamo.rst
index 365f713c85ea26ad919c22a339d01da20d0461a6..8c02dce69f91418d706e69dd2e66a3a06b8ece2c 100644 (file)
--- a/doc/alamo.rst
+++ b/doc/alamo.rst
@@ -19,3 +19,58 @@ Configure thermostats through the manufacturer's application before use.
 The gateway exposes local heating activity, not independent load-current
 or contactor feedback. Fake HTTP tests do not verify a physical gateway,
 thermostat firmware, or electrical safety.
 The gateway exposes local heating activity, not independent load-current
 or contactor feedback. Fake HTTP tests do not verify a physical gateway,
 thermostat firmware, or electrical safety.

+
+The driver request scheduler applies one minimum six-second
+request-start interval to status polls and actions together. Its
+operation timeout starts after the rate wait. Caller cancellation or a
+command deadline stops the wait without another exchange. A multi-step
+command can expire between actions. The gateway budget belongs to one
+driver owner.
+
+The private control value uses ``settings.mode`` (``off`` or ``heat``),
+``settings.target_temperature`` in degrees Celsius,
+``current_temperature``, ``floor_temperature``, ``action`` (``off``,
+``idle``, or ``heating``), and ``locked``. Commands contain the complete
+mode and target settings only. House-specific target bounds and steps
+belong to core validation. The driver accepts finite targets.
+
+****************
+ Gateway driver
+****************
+
+``New`` takes ``Settings``, the shared publisher and router, and a raw
+``Client``. Settings list all stable thermostat IDs and their unique MAC
+values for one physical gateway. The default poll interval is fifteen
+seconds. An explicit interval is from ten seconds through five minutes.
+The caller runs the publisher, supplies command intake, and owns the
+HTTP transport. The command keeps its explicit empty driver list.
+
+``Run`` serializes polling and commands across the gateway. One status
+request supplies every configured thermostat. It publishes no startup
+availability before evidence. Three failed or missing observations mark
+a thermostat offline. A successful observation resets that count and
+restores online state. A command error does not count as a missed poll.
+Recoverable HTTP failures appear as missed polls or failed command
+results, not logs. Publication failures return to the framework runner.
+Shutdown does not publish an outage. ``Refresh`` coalesces a
+rate-limited status poll and asks the shared publisher to resend cached
+snapshots.
+
+Each command reads a fresh action baseline, turns off before a target
+change, sets and verifies the target, and only then turns on if
+requested. Every action response is feedback. A failed intermediate
+readback stops later actions. A command can leave the thermostat off if
+a later action fails or expires. The driver publishes the last
+successful observation with its observation time and command causation.
+A completed result requires matching power and target readback. A
+complete no-change command still reads the gateway.
+
+One queue consumer per thermostat preserves command order. Work from
+separate thermostats has no cross-device order guarantee. The shared
+ledger stores an outcome before feedback or result publication.
+Duplicate commands replay the first result without another gateway
+exchange, also after a failed publication. The ledger is memory-only
+with the framework limit of 256 results per device. Restart or eviction
+ends that duplicate protection. A gateway request can have an uncertain
+physical outcome when its response fails. The driver does not retry that
+command action.