====== MOSH ↔ MQTT ↔ Home Assistant Integration ======

===== Overview =====

MOSH integrates with {{:software:home_assistant}} using MQTT as a bridge layer.

The integration works by:

  * Publishing MOSH element state to MQTT topics
  * Using Home Assistant MQTT Discovery to auto-create entities
  * Receiving commands from Home Assistant via MQTT and forwarding them into MOSH

This allows Home Assistant to control MOSH nodes without any custom integration code.

-----

===== Architecture =====

<code>
MOSH Core
   ↓
MOSH MQTT Module
   ↓
MQTT Broker (Mosquitto, etc.)
   ↓
Home Assistant (MQTT Integration)
</code>

-----

===== Requirements =====

  * Running MOSH bridge with MQTT module enabled
  * MQTT broker (e.g., Mosquitto)
  * {{:software:home_assistant}} with MQTT integration configured

-----

===== MQTT Topic Structure =====

MOSH uses a structured topic hierarchy:

<code>
mosh/<node_id>/<element_id>/state
mosh/<node_id>/<element_id>/set
mosh/<node_id>/<element_id>/availability
</code>

Example:

<code>
mosh/testnode1/relay1/state
mosh/testnode1/relay1/set
mosh/testnode1/relay1/availability
</code>

-----

===== MQTT Discovery =====

MOSH publishes discovery messages to:

<code>
homeassistant/<component>/<unique_id>/config
</code>

Example (switch):

<code>
homeassistant/switch/mosh_testnode1_relay1/config
</code>

-----

===== Example Discovery Payload (Switch) =====

<code json>
{
  "name": "Relay 1",
  "unique_id": "mosh_testnode1_relay1",
  "state_topic": "mosh/testnode1/relay1/state",
  "command_topic": "mosh/testnode1/relay1/set",
  "availability_topic": "mosh/testnode1/relay1/availability",
  "payload_on": "ON",
  "payload_off": "OFF",
  "state_on": "ON",
  "state_off": "OFF",
  "device": {
    "identifiers": ["mosh_testnode1"],
    "name": "Test Node 1",
    "manufacturer": "MOSH",
    "model": "Generic Node"
  }
}
</code>

-----

===== State Publishing =====

MOSH publishes element state changes to:

<code>
mosh/<node>/<element>/state
</code>

Example:

<code>
mosh/testnode1/relay1/state → ON
mosh/testnode1/relay1/state → OFF
</code>

State values should match Home Assistant expectations:

  * Switch: `ON` / `OFF`
  * Sensor: numeric or string
  * Binary sensor: `ON` / `OFF`

-----

===== Command Handling =====

Home Assistant sends commands to:

<code>
mosh/<node>/<element>/set
</code>

Example:

<code>
mosh/testnode1/relay1/set → ON
</code>

MOSH MQTT module must:

  * Subscribe to `*/set` topics
  * Translate payload into MOSH command
  * Call `core.EnqueueCommand(...)`

-----

===== Availability =====

MOSH should publish node availability:

<code>
mosh/<node>/availability → online/offline
</code>

Or per element:

<code>
mosh/<node>/<element>/availability
</code>

Home Assistant expects:

  * `online`
  * `offline`

-----

===== Supported Entity Types =====

MOSH elements should map to Home Assistant components:

^ MOSH Element Type ^ Home Assistant Component ^
| switch            | switch                   |
| sensor            | sensor                   |
| binary_sensor     | binary_sensor            |
| dimmer            | light                    |
| temperature       | sensor (device_class=temperature) |

-----

===== Example: Relay Integration =====

==== Step 1: MOSH publishes discovery ====

<code>
homeassistant/switch/mosh_testnode1_relay1/config
</code>

==== Step 2: MOSH publishes state ====

<code>
mosh/testnode1/relay1/state → OFF
</code>

==== Step 3: Home Assistant shows entity ====

``switch.relay_1`` appears automatically.

==== Step 4: User toggles switch ====

Home Assistant publishes:

<code>
mosh/testnode1/relay1/set → ON
</code>

==== Step 5: MOSH executes command ====

  * MQTT module receives message
  * Calls core:
    <code>
    EnqueueCommand(node=testnode1, element=relay1, payload={"state":"ON"})
    </code>

-----

===== MQTT Module Responsibilities =====

The MOSH MQTT module must:

  * Connect to broker
  * Publish discovery configs
  * Publish state updates
  * Subscribe to command topics
  * Translate MQTT → MOSH commands
  * Track node availability

-----

===== Configuration =====

Example MOSH config:

<code json>
{
  "modules": {
    "mqtt": {
      "enabled": true,
      "broker": "tcp://127.0.0.1:1883",
      "client_id": "moshbridge",
      "base_topic": "mosh"
    }
  }
}
</code>

-----

===== Naming Conventions =====

  * Topic prefix: `mosh/`
  * Unique ID: `mosh_<node>_<element>`
  * Device ID: `mosh_<node>`

-----

===== Debugging =====

==== Check MQTT traffic ====

<code bash>
mosquitto_sub -t "mosh/#" -v
</code>

==== Check discovery messages ====

<code bash>
mosquitto_sub -t "homeassistant/#" -v
</code>

==== Restart Home Assistant MQTT integration ====

Sometimes required after discovery changes.

-----

===== Common Issues =====

^ Issue ^ Cause ^ Fix ^
| Entity not appearing | Discovery not published | Check `homeassistant/.../config` |
| State not updating | Wrong topic | Verify `state_topic` |
| Commands not working | Not subscribed to `/set` | Fix MQTT module |
| Device unavailable | Missing availability topic | Publish `online/offline` |

-----

===== Future Improvements =====

  * Support for retained discovery messages
  * QoS configuration
  * Device class mapping
  * Light/dimmer brightness support
  * Auto-discovery refresh on reconnect

-----