search

t0bst4r / matterbridge-home-assistant

Apache License 2.0
31 stars 2 forks source link

readme

Matterbridge Home Assistant

This Matterbridge Home Assistant package provides bindings to connect HomeAssistant to Matterbridge.

"Buy Me A Coffee"

Installation

Manual Setup

Home Assistant Add-On

Follow the Home Assistant Add-On Repository to install Matterbridge with Home Assistant.

Custom Docker Deployment

There is a ready-to-use docker image built with this project.

Running it is as easy as starting any other Docker container. Just make sure to run the container with the host network, since that is required for matter clients to connect.

The docker image is configured using environment variables (see Configuration).

# Create a volume to persist the data written by matterbridge (optional)
docker volume create matterbridge-data

# Start the container
docker run -d \
  --network host \
  --volume matterbridge-data:/root/.matterbridge \
  --env HOME_ASSISTANT_URL="http://192.168.178.23:8123" \
  --env HOME_ASSISTANT_ACCESS_TOKEN="ey....yQ" \
  --env HOME_ASSISTANT_CLIENT_CONFIG='{ "includeDomains": ["light", "media_player"], "excludePatterns": ["media_player.*echo*"] }' \
  --name matterbridge
  ghcr.io/t0bst4r/matterbridge-home-assistant:latest

Or using docker-compose.yaml

services:
  matterbridge:
    image: ghcr.io/t0bst4r/matterbridge-home-assistant:latest
    restart: unless-stopped
    network_mode: host
    environment:
      HOME_ASSISTANT_URL: 'http://192.168.178.23:8123'
      HOME_ASSISTANT_ACCESS_TOKEN: 'ey....yQ'
      HOME_ASSISTANT_CLIENT_CONFIG: |
        {
          "includeDomains": ["light", "media_player"],
          "excludePatterns": ["media_player.*echo*"]
        }
    volumes:
      - data:/root/.matterbridge
volumes:
  data:

Configuration

This package can be configured using environment variables.

Using Environment Variables

Using a config file

This works for the Custom Docker Deployment only!

You can mount the following JSON file to your Docker container (wherever you like).

{
  "homeAssistantUrl": "http://192.168.178.23:8123",
  "homeAssistantAccessToken": "ey....yQ",
  "homeAssistantClientConfig": {
    "includeDomains": ["light", "media_player"],
    "excludePatterns": ["media_player.*echo*"]
  }
}

To tell the application to load your JSON file, just point the CONFIG_FILE environment variable to the path of this file:

docker run -d \
  --network host \
  --volume matterbridge-data:/root/.matterbridge \
  --volume $PWD/matterbridge-config:/config:ro \
  --env CONFIG_FILE="/config/matterbridge-config.json" \
  --name matterbridge
  ghcr.io/t0bst4r/matterbridge-home-assistant:latest

Whenever a property is missing in the provided JSON config, it will use the environment variables as fallback. So your config could look like this:

{
  "homeAssistantUrl": "http://192.168.178.23:8123",
  "homeAssistantClientConfig": {
    "includeDomains": ["light", "media_player"],
    "excludePatterns": ["media_player.*echo*"]
  }
}
docker run -d \
  --network host \
  --volume matterbridge-data:/root/.matterbridge \
  --volume $PWD/matterbridge-config:/config:ro \
  --env CONFIG_FILE="/config/matterbridge-config.json" \
  --env HOME_ASSISTANT_ACCESS_TOKEN="ey....yQ" \
  --name matterbridge
  ghcr.io/t0bst4r/matterbridge-home-assistant:latest

Client Config

The client config has to be a json string and can have the following properties:

interface HomeAssistantClientConfig {
  /**
   * The domains to include.
   * @example [ "light", "media_player" ]
   */
  includeDomains?: Array<string>;
  /**
   * Glob-Patterns to include entities.
   * @example [ "light.*", "media_player.*_tv_*" ]
   */
  includePatterns?: Array<string>;
  /**
   * The domains to exclude.
   * Exclusions are always winning against inclusions.
   * @example [ "media_player" ]
   */
  excludeDomains?: Array<string>;
  /**
   * Glob-Patterns to exclude entities.
   * Exclusions are always winning against inclusions.
   * @example [ "media_player.*echo*" ]
   */
  excludePatterns?: Array<string>;
}

Entities must match any of includePatterns or includeDomains and most not match any of excludeDomains and excludePatterns.

Example Configuration

HOME_ASSISTANT_URL=http://192.168.178.23:8123
HOME_ASSISTANT_ACCESS_TOKEN=ey....yQ
HOME_ASSISTANT_CLIENT_CONFIG={ "includeDomains": ["light", "media_player"], "excludePatterns": ["media_player.*echo*"] }

Commissioning / Pairing the device with your Matter controller

Start matterbridge and find the commissioning QR code in the logs. This code can be used to connect your Matter controller (like Alexa, Apple Home or Google Home) to the bridge.

Matterbridge commissioning code

Supported Entities

Contributors

t0bst4r bassrock