How I Added a Matter Device to Home Assistant - Step By Step 

 

If you run Home Assistant in a container, you can run a Docker image of the Matter server.

1.This Docker Matter Server  runs the controller software as a separate process and connects your Matter network (called Fabric in technical terms) and Home Assistant.

Start the Docker Matter Server  to make the WebSocket available to Home Assistant Core.

2.The Home Assistant Matter integration connects to this server via a WebSocket connection.

 

 

Guide:https://github.com/home-assistant-libs/python-matter-server

Table of Contents

If you don’t plan to use Thread, you won’t need a Thread Border Router.

Pre-Requisites

First, ensure your ha initialization includes the necessary Hardware: Home Assistant Connect ZBT-1,  built in bluetooth adapter, and rpi5.

Second, ensure your ha initialization includes the necessary Software: Home Assistant docker, matter server docker , and ha docker.

 

Make sure there is a Thread border router device present in your home network.

I have flashed my sonoff dongle-e with an openthread firmware (thread only).

 

Docker containers:

homeassistant container

openthread/otbr container
connect thread border router to the local network
Chạy Docker OTBR  |  OpenThread

python-matter-server container
matter controller server = matter add-on

https://community.home-assistant.io/t/using-matter-and-thread-in-a-dockerized-ha-instance/721088/7?u=msly

 

Speakers: HomePod (2nd generation), HomePod mini

TVs: Apple TV 4K (3rd generation) Wi-Fi + Ethernet, Apple TV 4K (2nd generation)

Make sure you run the container on the host network.

The host network interface needs IPv6 support enabled.

A Matter-enabled device.

 

You have Home Assistant Container  setup.

I solved it by doing the following:

run the otbr docker

run the homeassistant docker

enable the otbr integration

enable the thread integration (which should not see the network and allow you to make this preferred)

enable matter integration (which now allows you to add matter devices)

To use this:

install the matter server from docker

install the otbr integration integration to your homeassistant docker

install the matter integration to your homeassistant docker

A Matter-enabled device via ha app

 

Add Matter Integration

Add Matter Device 

Step 1.Running the Matter Server using container image

This project implements a Matter Controller Server over WebSockets using the official Matter (formerly CHIP) SDK.

 

1.your Matter Server is up and running.

you will have to start the Matter Server using Docker.

docker cli

mkdir datadocker

run ok

Matter Controller Server docker Init with bluetooth adapter. 

docker pull ghcr.io/home-assistant-libs/python-matter-server:8.0.0

202508
~~~

docker run -d \
  --name matter-server \
  --restart=unless-stopped \
  --security-opt apparmor=unconfined \
  -v /datadocker/matter-server:/data \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  ghcr.io/home-assistant-libs/python-matter-server:8.0.0 --storage-path /data --paa-root-cert-dir /data/credentials --bluetooth-adapter 0
~~~

https://github.com/home-assistant-libs/python-matter-server

or

Running using Docker compose

For this, create a docker compose file with the following content.

version: '3'  
services:  
  matter-server:  
    container_name: matter-server  
    image: ghcr.io/home-assistant-libs/python-matter-server:stable  
    restart: unless-stopped  
    security_opt:  
      - apparmor=unconfined  
    volumes:  
      - ./data:/data  
      - /run/dbus:/run/dbus:ro  
    network_mode: host

start the Matter Server docker container

docker compose up -d

 

 

docker inspect matter-server

docker logs  -f  matter-server

 

 

Web UI

http://192.168.2.125:5580/

 

 

 

 

step 2.Now we need to connect it to Home Assistant.

Add  Matter Integration

You can connect to the Matter Server WebSocket. Enter port 5580.

you will have to add the IP address of the machine you are currently running the Matter Server.

ws://<your matter server machine IP address>:5580/ws

 

ws://192.168.2.50:5580/ws

 

HA and python-matter-server talk to each other over websockets (ws) which can use IPv4 or IPv6.

 

 

step 3.Adding A Matter-enabled Device to Home Assistant

Now to add the Matter device, you will have to use the Home Assistant App for Android or IOS

MatterServerDockerRun-1.webp

 

matter-client-1.png

Once you have the app and you open it, go to the “Device & Services” settings page, click on “Add Integration” in the bottom right-hand corner and search for Matter.

 

Now click on “Add Matter Device”

 

https://www.matterxiaomi.com/boards/topic/19867/installing-matter-server-docker-image-on-a-raspberry-pi-3bmatter-over-wi-fi-via-docker-run

 

logs

docker logs -f matter-server
2025-08-06 20:16:16.785 (MainThread) INFO [matter_server.server.stack] Initializing CHIP/Matter Logging...
2025-08-06 20:16:16.786 (MainThread) INFO [matter_server.server.stack] Initializing CHIP/Matter Controller Stack...
[1754511376.818026][1:1] CHIP:CTL: Setting attestation nonce to random value
[1754511376.818238][1:1] CHIP:CTL: Setting CSR nonce to random value
[1754511376.818942][1:1] CHIP:DL: ChipLinuxStorage::Init: Using KVS config file: /tmp/chip_kvs
[1754511376.829178][1:1] CHIP:DL: Wrote settings to /tmp/chip_kvs
[1754511376.829379][1:1] CHIP:DL: ChipLinuxStorage::Init: Using KVS config file: /data/chip_factory.ini
[1754511376.829478][1:1] CHIP:DL: ChipLinuxStorage::Init: Using KVS config file: /data/chip_config.ini
[1754511376.829548][1:1] CHIP:DL: ChipLinuxStorage::Init: Using KVS config file: /data/chip_counters.ini
[1754511376.832806][1:1] CHIP:DL: Wrote settings to /data/chip_counters.ini
[1754511376.832816][1:1] CHIP:DL: NVS set: chip-counters/reboot-count = 45 (0x2D)
[1754511376.833076][1:1] CHIP:DL: Got Ethernet interface: eth0
[1754511376.833187][1:1] CHIP:DL: Found the primary Ethernet interface:eth0
[1754511376.833288][1:1] CHIP:DL: Got WiFi interface: wlan0
[1754511376.833302][1:1] CHIP:DL: Failed to reset WiFi statistic counts
2025-08-06 20:16:16.833 (MainThread) INFO [chip.storage] Initializing persistent storage from file: /data/chip.json
2025-08-06 20:16:16.833 (MainThread) INFO [chip.storage] Loading configuration from /data/chip.json...
2025-08-06 20:16:16.913 (MainThread) INFO [chip.CertificateAuthority] Loading certificate authorities from storage...
2025-08-06 20:16:16.913 (MainThread) INFO [chip.CertificateAuthority] New CertificateAuthority at index 1
2025-08-06 20:16:16.913 (MainThread) INFO [chip.CertificateAuthority] Loading fabric admins from storage...
2025-08-06 20:16:16.914 (MainThread) INFO [chip.FabricAdmin] New FabricAdmin: FabricId: 0x0000000000000001, VendorId = 0xFFF1
2025-08-06 20:16:16.914 (MainThread) INFO [matter_server.server.stack] CHIP Controller Stack initialized.
2025-08-06 20:16:16.914 (MainThread) INFO [matter_server.server.server] Starting the Matter Server...
2025-08-06 20:16:16.917 (MainThread) INFO [matter_server.server.helpers.paa_certificates] Skip fetching certificates (already fetched within the last 24h).
2025-08-06 20:16:16.917 (MainThread) INFO [chip.FabricAdmin] Allocating new controller with CaIndex: 1, FabricId: 0x0000000000000001, NodeId: 0x000000000001B669, CatTags: []
2025-08-06 20:16:17.014 (MainThread) INFO [matter_server.server.vendor_info] Loading vendor info from storage.
2025-08-06 20:16:17.019 (MainThread) INFO [matter_server.server.vendor_info] Loaded 338 vendors from storage.
2025-08-06 20:16:17.019 (MainThread) INFO [matter_server.server.vendor_info] Fetching the latest vendor info from DCL.
2025-08-06 20:16:18.595 (MainThread) INFO [matter_server.server.vendor_info] Fetched 337 vendors from DCL.
2025-08-06 20:16:18.595 (MainThread) INFO [matter_server.server.vendor_info] Saving vendor info to storage.
2025-08-06 20:16:18.598 (MainThread) INFO [matter_server.server.device_controller] Loaded 0 nodes from stored configuration
2025-08-06 20:16:18.603 (MainThread) INFO [matter_server.server.server] Matter Server successfully initialized.

 

Note

1.Matter Over WiFi and Matter Over Thread are different. Only Matter Over Thread needs a Open Thread Border Router.

 

Useful links

 

offcial document:https://github.com/home-assistant-libs/python-matter-server/blob/main/docs/docker.md

https://smarthomecircle.com/add-matter-devices-to-home-assistant

https://community.home-assistant.io/t/installing-matter-server-docker-image-on-a-raspberry-pi/637152/5

https://www.matteralpha.com/how-to/how-to-use-home-assistant-to-add-matter-devices-without-phone

https://www.matterxiaomi.com/boards/topic/19867/installing-matter-server-docker-image-on-a-raspberry-pi-3bmatter-over-wi-fi-via-docker-run#27332

Comments


Comments are closed