docs: clarify MQTT read/write behavior for Firmware and Companion

astro.config.mjs

@@ -62,7 +62,14 @@ export default defineConfig({
             { slug: 'configuration/network' },
             { slug: 'configuration/settings' },
             { slug: 'configuration/hardware' },
-            { slug: 'configuration/mqtt' },
+          ],
+        },
+        {
+          label: 'MQTT',
+          items: [
+            { slug: 'configuration/mqtt', label: 'Overview' },
+            { slug: 'configuration/mqtt/firmware' },
+            { slug: 'configuration/mqtt/companion' },
           ],
         },
         {

src/content/docs/configuration/mqtt.md

@@ -18,6 +18,13 @@ mosquitto_sub -h homeassistant.local -u <username> -P <password> -v -t "espresen
 For configuration of the Companion App also check the [Companion MQTT](/companion/installation/#mqtt-setup) section
 :::
 
+## Direction of Data
+
+For a focused breakdown of which topics each component publishes and subscribes to, see:
+
+- [Firmware MQTT behavior](/configuration/mqtt/firmware)
+- [Companion MQTT behavior](/configuration/mqtt/companion)
+
 ## Reading Current Settings
 
 Example output when subscribing to a room:

src/content/docs/configuration/mqtt/companion.md

@@ -0,0 +1,22 @@
+---
+title: Companion
+---
+
+ESPresense Companion is also bidirectional on MQTT.
+
+## Companion Reads
+
+Companion subscribes to data coming from ESPresense nodes:
+
+- `espresense/devices/+` for BLE observations from nodes
+- `espresense/rooms/+/telemetry` for node telemetry
+- `espresense/rooms/+/status` for node availability
+
+## Companion Writes
+
+Companion publishes processed outputs and configuration changes:
+
+- Presence and location outputs for Home Assistant entities
+- Node optimization and configuration updates through room `.../set` topics, such as max distance tuning
+
+For the node topic reference and write examples, see [MQTT Overview](/configuration/mqtt).

src/content/docs/configuration/mqtt/firmware.md

@@ -0,0 +1,24 @@
+---
+title: Firmware
+---
+
+After Wi-Fi setup, each ESPresense node uses MQTT in two directions.
+
+## Firmware Writes
+
+Firmware publishes node state and BLE observations:
+
+- `espresense/rooms/<room>/status` for online or offline availability
+- `espresense/rooms/<room>/telemetry` for node health and configuration telemetry
+- `espresense/devices/<device_id>` for detected BLE device updates
+
+## Firmware Reads
+
+Firmware subscribes to configuration and command topics:
+
+- `espresense/rooms/<room>/+/set` for per-node setting updates
+- `espresense/rooms/*/+/set` for fleet-wide setting updates
+
+This is how nodes receive runtime config such as `max_distance`, `include`, `exclude`, `auto_update`, and LED commands.
+
+For the full topic reference and command examples, see [MQTT Overview](/configuration/mqtt).