Zigbee2MQTT

Athena has no dedicated Zigbee2MQTT integration - and doesn't need one. Zigbee2MQTT publishes Home Assistant's own MQTT discovery convention by default, and Athena's MQTT integration already implements that same convention (the one Tasmota, Shelly, and ESPHome's own native MQTT component also speak) - so every Zigbee gateway and end device Zigbee2MQTT manages shows up automatically once both point at the same broker, with zero Athena-specific setup.

Running Zigbee2MQTT

Not bundled with Athena - run it as its own container, on whichever machine the Zigbee coordinator (a CC2531/CC2652/ConBee/Sonoff dongle, etc.) is physically plugged into. Athena's own repo already ships this as a ready-made docker-compose-zigbee2mqtt.yml (with a matching .env.zigbee2mqtt.example and configuration.yaml.example) - copy all three, fill in the .env, and skip straight to the configuration.yaml step below. Or save the snippet here as your own docker-compose.yml in a new folder:

# docker-compose.yml - zigbee2mqtt, standalone
services:
  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: ghcr.io/koenkk/zigbee2mqtt
    restart: unless-stopped
    volumes:
      - ./data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - '8080:8080'  # Zigbee2MQTT's own web frontend - device pairing, network map
    environment:
      - TZ=Europe/Helsinki
    devices:
      # Use /dev/serial/by-id/... (see `ls /dev/serial/by-id/`), not /dev/ttyACM0/ttyUSB0 - that
      # mapping can shift across reboots if more than one USB-serial adapter is plugged in.
      - '/dev/serial/by-id/<your-stick-here>:/dev/ttyACM0'

Before first start, create ./data/configuration.yaml pointing it at an MQTT broker and turning on Home Assistant-style discovery - this is the setting that makes devices appear in Athena automatically, the same convention already covered on the MQTT page:

# data/configuration.yaml
homeassistant: true
mqtt:
  server: 'mqtt://<your-broker-host>:1883'
  # user/password only if your broker requires auth - Athena's own docker-compose-mqtt.yml
  # (see Installation) allows anonymous access by default, so these can stay unset.

Run docker compose up -d (or docker compose -f docker-compose-zigbee2mqtt.yml up -d if you're using the ready-made file, which doesn't auto-discover the way a bare docker-compose.yml does), then open http://<that-host>:8080 to pair Zigbee devices onto the network. Point that same broker at Athena's own MQTT_BROKER_URL (see Installation) - if you're already running docker-compose-mqtt.yml for another MQTT device, Zigbee2MQTT can share that exact broker, no second one needed.

The devices: mapping above pins one specific stick to one fixed container-side device node - Docker resolves it once at container start, so unplugging the stick (or swapping it for a different one) isn't guaranteed to keep working without running docker compose up -d again. For real hot-plug support instead, bind-mount the whole host /dev and grant the relevant device class (the same tradeoff documented on Athena's own docker-compose.yml for its Zigbee EZSP mount), and point serial.port in configuration.yaml at the stable by-id path directly rather than a plain /dev/ttyACM0 - with the whole host /dev visible, that symlink (and whatever real device it points at after a replug) is visible inside the container too:

devices:
  - /dev:/dev
device_cgroup_rules:
  - 'c 188:* rmw'  # ttyUSB* - CP210x/CH340-style adapters (some CC2531 dongles)
  - 'c 166:* rmw'  # ttyACM* - USB CDC-ACM (CC2652/ConBee/Sonoff-style adapters)

What shows up

Whatever Athena's own MQTT integration already recognizes: sensors, binary sensors, switches, lights, and buttons, all with live state and control where applicable - see MQTT for the full list. This is exactly the same path Zigbee devices take through Home Assistant's own Zigbee2MQTT integration, so anything documented as working there over MQTT discovery works here too.