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.