MOSH ↔ MQTT ↔ Home Assistant Integration

MOSH integrates with 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.

MOSH Core
   ↓
MOSH MQTT Module
   ↓
MQTT Broker (Mosquitto, etc.)
   ↓
Home Assistant (MQTT Integration)

• Running MOSH bridge with MQTT module enabled
• MQTT broker (e.g., Mosquitto)
• home_assistant with MQTT integration configured

MOSH uses a structured topic hierarchy:

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

Example:

mosh/testnode1/relay1/state
mosh/testnode1/relay1/set
mosh/testnode1/relay1/availability

MOSH publishes discovery messages to:

homeassistant/<component>/<unique_id>/config

Example (switch):

homeassistant/switch/mosh_testnode1_relay1/config

{
  "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"
  }
}

MOSH publishes element state changes to:

mosh/<node>/<element>/state

Example:

mosh/testnode1/relay1/state → ON
mosh/testnode1/relay1/state → OFF

State values should match Home Assistant expectations:

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

Home Assistant sends commands to:

mosh/<node>/<element>/set

Example:

mosh/testnode1/relay1/set → ON

MOSH MQTT module must:

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

MOSH should publish node availability:

mosh/<node>/availability → online/offline

Or per element:

mosh/<node>/<element>/availability

Home Assistant expects:

• `online`
• `offline`

MOSH elements should map to Home Assistant components:

homeassistant/switch/mosh_testnode1_relay1/config

mosh/testnode1/relay1/state → OFF

``switch.relay_1`` appears automatically.

Home Assistant publishes:

mosh/testnode1/relay1/set → ON

• MQTT module receives message
• Calls core:

    EnqueueCommand(node=testnode1, element=relay1, payload={"state":"ON"})
    

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

Example MOSH config:

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

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

mosquitto_sub -t "mosh/#" -v

mosquitto_sub -t "homeassistant/#" -v

Sometimes required after discovery changes.

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