DOCSEARCHbyAlgolia
Submit Docs

python-matter-server

repository·main·Indexed 21 days ago

https://github.com/matter-js/python-matter-server

A certified Matter controller implementation that provides a WebSocket-based server and client, serving as the backbone for Matter integration in Home Assistant and other projects. It utilizes the official Matter (formerly CHIP) SDK. Note: This project has been rewritten and moved to matterjs-server; version 8.1.2 is the final release of python-matter-server.

Tokens
21.7K
Snippets
55
Records
78
Agent score
74%

What's inside python-matter-server

  1. Overview of Open Home Foundation Matter Server

    main
    The Open Home Foundation Matter Server is an officially certified software component used to create a Matter controller. It implements a Matter Controller Server over WebSockets, utilizing the official Matter (formerly CHIP) SDK as its base. It provides both a server and a client implementation and serves as the foundation for Matter support in Home Assistant, though it is designed to be used in other projects as well.

  2. Migrate to matterjs-server

    main

    IMPORTANT: Deprecation Notice

    The python-matter-server has been rewritten and moved to matterjs-server.

    Version 8.1.2 is the final version of python-matter-server, its libraries, and the docker-container. This repository will no longer receive updates or support. Users are strongly encouraged to migrate to the new server as soon as possible.

  3. Install only the Python client library

    main

    If you do not need to run the Matter Server itself but want to interact with an existing server via its Websockets API, you can install only the client library. The client library depends on the chip/matter clusters package, which is platform-independent.

    Note: The server library requires the Matter Core SDK (CHIP), which is OS and architecture-specific. While wheels are provided for Linux (amd64 and aarch64) on PyPI, macOS users may need to build their own wheels using the SDK version used by the clusters package.

    pip install python-matter-server

  4. Set up the Matter Server development environment

    main

    To develop with the Matter Server, you must use a recent Linux or MacOS machine. Windows is not supported.

    1. Clone the repository to your local machine.
    2. Run the setup script: scripts/setup.sh.
    3. Ensure a /data directory exists and has the necessary permissions for the user running the python-matter-server.
    # Clone the repo and run setup
./scripts/setup.sh

# Ensure data directory exists
mkdir /data

  5. Connect the Matter Dashboard to a WebSocket server

    main

    When running the Matter Dashboard, you must provide the WebSocket URL to connect to the Matter Server. The URL depends on your deployment method:

    • Local Python Matter Server: Use ws://localhost:5580.
    • Home Assistant Add-on: Use a URL like ws://homeassistant.local:5580.

    Configuring the Home Assistant Add-on for Network Access: If using the Home Assistant add-on, you must explicitly enable the WebSocket port for network access:

    1. Navigate to the Matter Server add-on info page.
    2. Go to the Configuration tab.
    3. Under the Network section, select "show disabled ports".
    4. Enter the desired port for the WebSocket server (e.g., 5580).
    5. Click Save and restart the add-on when prompted.

  6. Install and run the Matter Server

    main

    Depending on your use case, there are different ways to run the Matter Server:

    • Home Assistant Users: Use the official Matter Server add-on. Refer to the Home Assistant documentation for setup instructions.
    • Standalone Docker: You can run the Matter Server as a standalone container. See the Docker documentation for specific instructions.
    • Developers: To run the server or client in a local development environment, refer to the Development documentation.

  7. Configure networking for Matter Server

    main

    Matter relies on IPv6 link-local multicast protocols. To ensure successful communication, follow these networking guidelines:

    • Network Topology: Use a flat network or ensure the Matter Server, devices, border routers, and commissioning devices (phones) are all on the same (v)LAN. Matter multicast does not work across different LANs or VLANs.
    • Multicast Settings: Disable "Multicast optimizations" on professional networking gear (e.g., Unifi, Omada) as they can block Matter traffic.
    • mDNS: Do not enable mDNS forwarders on your network, as they can corrupt or hinder Matter packets.
    • IGMP/MLD Snooping: If your hardware supports it, experiment with IGMP/MLD snooping settings, as they can either help or hinder traffic.
    • IPv6: The host network interface must have IPv6 support enabled.

  8. Enable Bluetooth commissioning in Docker

    main

    To use local commissioning via Bluetooth, you must pass the host's D-Bus socket to the container and provide the necessary command-line arguments. If you override the default command, you must include the default arguments (like --storage-path) to ensure the server starts correctly.

    docker run -d \
  --name matter-server \
  --restart=unless-stopped \
  --security-opt apparmor=unconfined \
  -v $(pwd)/data:/data \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  ghcr.io/matter-js/python-matter-server:stable --storage-path /data --paa-root-cert-dir /data/credentials --bluetooth-adapter 0

  9. Run the Matter Server using a Docker container image

    main

    You can run the Matter Server using the official Docker container image. Note that the underlying host operating system must meet the requirements for Matter and Thread (see os_requirements.md). For Home Assistant users, using the official Matter Server add-on on Home Assistant OS is strongly recommended over a self-managed container to avoid communication issues with Thread devices.

    By default, network data (fabric information) is stored in a /data directory inside the container. You should map this to a persistent directory on your host.

    mkdir data
docker run -d \
  --name matter-server \
  --restart=unless-stopped \
  --security-opt apparmor=unconfined \
  -v $(pwd)/data:/data \
  --network=host \
  ghcr.io/matter-js/python-matter-server:stable

  10. Run the Matter Server using Docker Compose

    main

    Use the following Docker Compose configuration to manage the Matter Server.

    Key Requirements:

    • network_mode: host: Required for mDNS to work correctly.
    • security_opt: ["apparmor:unconfined"]: Needed for Bluetooth via D-Bus.
    • volumes:
      • Map a host directory to /data/ for persistent storage. It is recommended to use an .env file to set the USERDIR environment variable.
      • Map /run/dbus:/run/dbus:ro to enable Bluetooth via D-Bus.

    Note on Command Overrides: If you use the command: key to pass custom arguments, you must also include the default command-line arguments used by the image.

    services:
  # python-matter-server
  matter-server:
    image: ghcr.io/matter-js/python-matter-server:stable
    container_name: matter-server
    restart: unless-stopped
    # Required for mDNS to work correctly
    network_mode: host
    security_opt:
      # Needed for Bluetooth via dbus
      - apparmor:unconfined
    volumes:
      # Create an .env file that sets the USERDIR environment variable.
      - ${USERDIR:-$HOME}/docker/matter-server/data:/data/
      # Required for Bluetooth via D-Bus
      - /run/dbus:/run/dbus:ro
    # If you adjust command line, make sure to pass the default CMD arguments too:
    #command: --storage-path /data --paa-root-cert-dir /data/credentials --bluetooth-adapter 0

  11. Supported operating systems for Matter Server

    main

    The Matter Server requires 64-bit architectures. The following operating systems are supported:

    • MacOS: Version 14 or higher (arm-based CPU) is recommended for development. It works out of the box when used with a Python venv.
    • Linux: A very recent distribution and kernel are required. The host must be able to process ICMPv6 Router Advertisements.
      • Home Assistant OS: Version 10 and newer is fully supported as the Matter Server is provided as an add-on with all necessary fixes included.
    • Unsupported: Non-64-bit architectures, other operating systems, and WSL (Windows Subsystem for Linux) are not supported.

  12. Set up the Matter Dashboard for development

    main

    To develop the Matter Dashboard, you must first ensure that the Python Matter Server dependencies are installed on your system. Then, run the setup script to install the dashboard's dependencies.

    After setup, you can start the development server. The dashboard will be accessible at http://localhost:5010. Upon opening the dashboard, you will be prompted to provide your WebSocket server URL.

    # Install dependencies (requires python matter server dependencies to be present)
script/setup

# Run the development server
script/develop