MQTT auto-discovery

Athena implements the widely-adopted MQTT discovery convention, so anything that already speaks it - Tasmota, Shelly's own MQTT+discovery firmware setting, Zigbee2MQTT, ESPHome's own native MQTT component - shows up with no Athena-specific setup on the device side.

What's recognized

Sensors, binary sensors, switches, lights, and buttons are all recognized. Switches and lights get a live On/Off toggle, buttons a Press action, both published straight to the entity's own command topic; everything else still lists with its raw state, read-only. State is live over a one-way WebSocket - a snapshot on connect, then one message per discovered, updated, or removed entity, so a device removing its own retained discovery message removes it here too.

Running a broker

Not bundled in either deploy shape - run docker-compose-mqtt.yml (a standalone Mosquitto broker, published on the LAN so real hardware can reach it directly) alongside whichever Athena compose file you're already using:

# docker-compose-mqtt.yml - Mosquitto, standalone
services:
  mosquitto:
    container_name: athena-mosquitto
    image: eclipse-mosquitto:2
    volumes:
      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf:ro,z
      - mosquitto-data:/mosquitto/data
    ports:
      - '1883:1883'
    restart: unless-stopped
volumes:
  mosquitto-data:

This exact file (plus its mosquitto.conf, anonymous access allowed by default) ships in Athena's own repo - docker compose -f docker-compose-mqtt.yml up -d. Point your devices at it and they'll be discovered the same as anything else. Set MQTT_BROKER_URL=tcp://<that-host>:1883 in Athena's own .env (blank by default, which disables the integration entirely) - or point it at your own already-running broker instead of this one.

Same treatment as everything else

MQTT entities are selectable in Dashboard cards, plots on the History page, and triggers/conditions/actions in Automations - the same as native, Shelly, or any other connected source.