Queue device commands and replay first results

[onehouse] / doc / mqtt.rst

diff --git a/doc/mqtt.rst b/doc/mqtt.rst
index 55a9a67ebc2eaaa4992224ce7eb447a16a00029a..e0a2d6246a23f19295d68db48162f0ababcae3da 100644 (file)
--- a/doc/mqtt.rst
+++ b/doc/mqtt.rst
@@ -7,17 +7,17 @@ command, and message IDs use canonical uppercase ULIDs. Capabilities and
 events use lowercase ASCII letters and digits, with single internal
 hyphen or period separators. Topic builders reject invalid addresses.
 
 events use lowercase ASCII letters and digits, with single internal
 hyphen or period separators. Topic builders reject invalid addresses.
 

-``Address.Topic`` and ``ParseTopic`` cover device descriptor,
-availability, reported values, telemetry, events, commands, command
-batches, results, and Zigbee hub status. Subscription helpers supply the
-core input filters, each device's command filter, and hub status filter.
-The command filter includes the reserved ``$batch`` target.
-
-``EncodeEnvelope`` and ``ParseEnvelope`` validate schema, IDs, optional
-UTC timestamps, and a required object payload. Unknown envelope fields,
-trailing JSON, unsupported schema versions, and malformed topics are
-errors. A receiver checks expiry against its own clock. The message ID
-stays unchanged on retry. Its timestamp is not the observation time.
+Private topic helpers cover device descriptor, availability, reported
+values, telemetry, events, commands, command batches, results, and
+Zigbee hub status. Subscription helpers supply the core input filters,
+each device's command filter, and hub status filter. The command filter
+includes the reserved ``$batch`` target.
+
+Private envelope helpers validate schema, IDs, optional UTC timestamps,
+and a required object payload. Unknown envelope fields, trailing JSON,
+unsupported schema versions, and malformed topics are errors. A receiver
+checks expiry against its own clock. The message ID stays unchanged on
+retry. Its timestamp is not the observation time.

 
 Measurements and online availability repeat at five-minute intervals.
 The device contact timeout is fifteen minutes. These constants do not
 
 Measurements and online availability repeat at five-minute intervals.
 The device contact timeout is fifteen minutes. These constants do not


@@ -30,9 +30,12 @@ run timers or implement publication suppression.
 Each operation has a ``Build`` function and a ``Parse`` function, such
 as ``BuildReported`` and ``ParseReported``. Builders accept an ID, an
 optional target, metadata, and a typed payload. They validate the same
 Each operation has a ``Build`` function and a ``Parse`` function, such
 as ``BuildReported`` and ``ParseReported``. Builders accept an ID, an
 optional target, metadata, and a typed payload. They validate the same

-contract as the parsers. ``Parse`` selects the typed payload and address
-kind from an incoming topic. A caller does not split or join topics and
-does not build an envelope.
+contract as the parsers through shared typed validation. A builder
+encodes its validated payload without parsing it. Batch members use the
+same metadata and value validation without envelope encoding. Access
+flag presence checks apply to parsed JSON only. ``Parse`` selects the
+typed payload and address kind after one topic parse. A caller does not
+split or join topics and does not build an envelope.

 
 A ``Publication`` contains topic, JSON bytes, QoS, and retention. It
 also supplies the expiry deadline, response topic, and correlation data
 
 A ``Publication`` contains topic, JSON bytes, QoS, and retention. It
 also supplies the expiry deadline, response topic, and correlation data