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

   1 ###############
   2  MQTT contract
   3 ###############
   4
   5 The ``protocol`` package defines schema 1 under ``onehouse/v1``. Device,
   6 command, and message IDs use canonical uppercase ULIDs. Capabilities and
   7 events use lowercase ASCII letters and digits, with single internal
   8 hyphen or period separators. Topic builders reject invalid addresses.
   9
  10 ``Address.Topic`` and ``ParseTopic`` cover device descriptor,
  11 availability, reported values, telemetry, events, commands, command
  12 batches, results, and Zigbee hub status. Subscription helpers supply the
  13 core input filters, each device's command filter, and hub status filter.
  14 The command filter includes the reserved ``$batch`` target.
  15
  16 ``EncodeEnvelope`` and ``ParseEnvelope`` validate schema, IDs, optional
  17 UTC timestamps, and a required object payload. Unknown envelope fields,
  18 trailing JSON, unsupported schema versions, and malformed topics are
  19 errors. A receiver checks expiry against its own clock. The message ID
  20 stays unchanged on retry. Its timestamp is not the observation time.
  21
  22 Measurements and online availability repeat at five-minute intervals.
  23 The device contact timeout is fifteen minutes. These constants do not
  24 run timers or implement publication suppression.