git.giacomolli.uk - onehouse/blob - doc/alamo.rst

   1 #########################
   2  Alamo Slim HTTP gateway
   3 #########################
   4
   5 ``driver/alamo`` defines a raw ``Client`` contract and an ``HTTPClient``
   6 for the Slim gateway. The client uses ``GET /status`` for all
   7 thermostats and ``GET /acao?mac=...`` for one thermostat. An action
   8 changes power or target temperature, not both at once. Its response is
   9 the complete readback for the requested MAC. The caller owns the HTTP
  10 transport.
  11
  12 The address is an HTTP origin without a path, credentials, query, or
  13 fragment. Redirects are rejected. Each exchange has a five-second
  14 caller-derived timeout and a 64 KiB response limit. Records require all
  15 seven documented properties. Extra gateway properties are permitted.
  16 Errors omit request addresses, queries, and response bodies.
  17
  18 Configure thermostats through the manufacturer's application before use.
  19 The gateway exposes local heating activity, not independent load-current
  20 or contactor feedback. Fake HTTP tests do not verify a physical gateway,
  21 thermostat firmware, or electrical safety.
  22
  23 The driver request scheduler applies one minimum six-second
  24 request-start interval to status polls and actions together. Its
  25 operation timeout starts after the rate wait. Caller cancellation or a
  26 command deadline stops the wait without another exchange. A multi-step
  27 command can expire between actions. The gateway budget belongs to one
  28 driver owner.
  29
  30 The private control value uses ``settings.mode`` (``off`` or ``heat``),
  31 ``settings.target_temperature`` in degrees Celsius,
  32 ``current_temperature``, ``floor_temperature``, ``action`` (``off``,
  33 ``idle``, or ``heating``), and ``locked``. Commands contain the complete
  34 mode and target settings only. House-specific target bounds and steps
  35 belong to core validation. The driver accepts finite targets.
  36
  37 ****************
  38  Gateway driver
  39 ****************
  40
  41 ``New`` takes ``Settings``, the shared publisher and router, and a raw
  42 ``Client``. Settings list all stable thermostat IDs and their unique MAC
  43 values for one physical gateway. The default poll interval is fifteen
  44 seconds. An explicit interval is from ten seconds through five minutes.
  45 The caller runs the publisher, supplies command intake, and owns the
  46 HTTP transport. The command keeps its explicit empty driver list.
  47
  48 ``Run`` serializes polling and commands across the gateway. One status
  49 request supplies every configured thermostat. It publishes no startup
  50 availability before evidence. Three failed or missing observations mark
  51 a thermostat offline. A successful observation resets that count and
  52 restores online state. A command error does not count as a missed poll.
  53 Recoverable HTTP failures appear as missed polls or failed command
  54 results, not logs. Publication failures return to the framework runner.
  55 Shutdown does not publish an outage. ``Refresh`` coalesces a
  56 rate-limited status poll and asks the shared publisher to resend cached
  57 snapshots.
  58
  59 Each command reads a fresh action baseline, turns off before a target
  60 change, sets and verifies the target, and only then turns on if
  61 requested. Every action response is feedback. A failed intermediate
  62 readback stops later actions. A command can leave the thermostat off if
  63 a later action fails or expires. The driver publishes the last
  64 successful observation with its observation time and command causation.
  65 A completed result requires matching power and target readback. A
  66 complete no-change command still reads the gateway.
  67
  68 One queue consumer per thermostat preserves command order. Work from
  69 separate thermostats has no cross-device order guarantee. The shared
  70 ledger stores an outcome before feedback or result publication.
  71 Duplicate commands replay the first result without another gateway
  72 exchange, also after a failed publication. The ledger is memory-only
  73 with the framework limit of 256 results per device. Restart or eviction
  74 ends that duplicate protection. A gateway request can have an uncertain
  75 physical outcome when its response fails. The driver does not retry that
  76 command action.