This Matterbridge Home Assistant package provides bindings to connect HomeAssistant to Matterbridge.
- Follow those instructions to set up
matterbridge
. - Install the plugin
npm install -g matterbridge-home-assistant
- Make sure the plugin is configured properly using environment variables (see Configuration).
- Activate the plugin
matterbridge -add matterbridge-home-assistant
- Start matterbridge using
matterbridge -bridge
Follow the Home Assistant Add-On Repository to install Matterbridge with Home Assistant.
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:
This package can be configured using environment variables.
HOME_ASSISTANT_URL
- the home assistant url (e.g.http://192.168.178.23:8123
)HOME_ASSISTANT_ACCESS_TOKEN
- a long living access token created in Home AssistantHOME_ASSISTANT_CLIENT_CONFIG
- a json string containing the client config (see below)
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
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
.
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*"] }
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.
- Light entities (
light.
) including on-off, brightness and hue & saturation control - Switch entities (
switch.
) including on-off control - Input-Boolean entities (
input_boolean.
) including on-off control - Media Players (
media_player.
) are mapped to Switches and currently only support on-off control - Climate Devices (
climate.
) currently work in progress, not released yet. - Scenes (
scene.
) are mapped to Switches and currently only support on-off control - Scripts (
script.
) are mapped to Switches and currently only support on-off control - Automations (
automation.
) are mapped to Switches and currently only support on-off control