Matter

Connects Athena to an already-running matter-server instance (matterjs-server, or its archived predecessor python-matter-server) to read and control devices already commissioned onto your Matter fabric - the same "bridge to a companion process" architecture Athena's own Z-Wave integration already uses, since no production-ready native Matter controller exists to embed directly.

Running matter-server

Not bundled with Athena's own compose files - run it as its own container, anywhere on your LAN (needs real network visibility for Matter's own device commissioning/discovery, so network_mode: host, not a bridge network). Save this as its own docker-compose.yml in a new folder:

# docker-compose.yml - matterjs-server, standalone
services:
  matter-server:
    container_name: matter-server
    image: ghcr.io/matter-js/matterjs-server:stable
    restart: unless-stopped
    network_mode: host  # required - Matter commissioning/discovery needs real mDNS visibility
    volumes:
      - matter-data:/data
volumes:
  matter-data:

Run docker compose up -d. Its WebSocket API listens on port 5580 by default - that's the address/port Athena's own "Add gateway" form needs.

Adding a gateway

Devices & Services > Matter > "Add gateway" takes your matter-server instance's address and port (default 5580). Once connected, "Add device" shows every node already commissioned onto that server's fabric, picked from the list rather than typed in - the same flow Z-Wave's own device picker already uses.

What's supported

• Switches - on/off, from the OnOff cluster.
• Dimmers - the LevelControl cluster's 0-254 range, shown and set as a 0-100% slider, matching every other dimmable light in Athena.
• Temperature & humidity sensors - TemperatureMeasurement and RelativeHumidityMeasurement.
• Occupancy & boolean sensors - OccupancySensing (motion/ presence) and BooleanState (contact, water leak, or a generic boolean, depending on the device).

Every supported entity works with Dashboard cards, History, and Automations exactly like any other integration. Color control and illuminance sensors aren't supported yet - illuminance in particular uses a log-encoded value Matter devices report, which needs real hardware to verify the decode against.