Python Matter 服务器

本项目基于官方 Matter（原 CHIP）SDK实现了一个通过 WebSocket 的 Matter 控制器服务器，并提供了服务器和客户端实现。

该项目的主要目标是为 Home Assistant 提供 Matter 支持，但其通用方法也适用于其他项目。

支持

有问题？

您可以通过以下几种方式获得解答：

Home Assistant 社区论坛。
Home Assistant Discord 聊天服务器。
加入 Reddit 上的 /r/homeassistant 子版块。

如果您在 Home Assistant 中使用 Matter 时遇到问题，请在 Home Assistant Core 仓库中提交问题报告。

如果您确定问题与 Matter Server 组件有关，也可以在本仓库中提交问题。

安装

我们强烈建议使用 Home Assistant OS 和官方 Matter Server 插件来在 Home Assistant 中使用 Matter。Matter 集成会自动安装 Python Matter Server 插件。请参阅 Home Assistant 文档。Home Assistant OS 经过测试和优化，可与 Matter 和 Thread 一起使用，这使得这种组合成为最佳测试和基本无忧的环境。

如果您仍然更喜欢自管理的容器安装，我们确实提供官方容器镜像。请注意，您可能会遇到与 Matter 设备的通信问题，特别是基于 Thread 的设备。这主要是因为容器安装使用主机网络，并依赖于操作系统管理的网络。

与基于 Wi-Fi/以太网的 Matter 设备通信的要求

确保在主机网络上运行容器。主机网络接口需要与您用于配对的 Android/iPhone 设备在同一网络中。Matter 使用链路本地多播协议，这些协议在不同的 LAN 或 VLAN 之间无法工作。

主机网络接口需要启用 IPv6 支持。

通过 Thread 边界路由器与 Thread 设备通信的要求

为了通过不在 Matter 控制器服务器同一主机上运行的 Thread 边界路由器进行通信，需要正确配置 IPv6 路由。IPv6 路由主要通过 IPv6 邻居发现协议自动设置，特别是路由信息选项（RIO）。然而，是否处理 IPv6 邻居发现 RIO，以及是否正确处理，取决于您系统使用的网络管理软件。在处理这些路由信息选项时可能存在错误和注意事项。

通常，确保启用内核选项 CONFIG_IPV6_ROUTER_PREF，并禁用 IPv6 转发（sysctl 变量 net.ipv6.conf.all.forwarding）。如果启用了 IPv6 转发，Linux 内核不会执行可达性探测（RFC 4191），这可能导致较长时间（最多 30 分钟）才能检测到网络变化。

如果您使用 NetworkManager，请确保至少使用 NetworkManager 1.42。早期版本会丢失路由跟踪，过时的路由可能导致 Thread 设备无法访问。目前所有发布的 NetworkManager 版本都无法正确处理到同一网络的多个路由。这意味着如果您有多个 Thread 边界路由器，故障转移不会立即生效（参见 NetworkManager 问题 #1232）。

我们目前没有使用 systemd-networkd 的经验。它似乎有自己的 IPv6 邻居发现协议处理。

如果您不使用 NetworkManager 或 systemd-networkd，可以使用内核的 IPv6 邻居发现协议处理。

确保启用内核选项 CONFIG_IPV6_ROUTE_INFO，并设置以下 sysctl 变量：

sysctl -w net.ipv6.conf.wlan0.accept_ra=1
sysctl -w net.ipv6.conf.wlan0.accept_ra_rt_info_max_plen=64

如果您的系统启用了 IPv6 转发（不推荐，见上文），您需要将 accept_ra 变量设置为 2。另请参阅 Thread 边界路由器 - 双向 IPv6 连接和基于 DNS 的服务发现 codelab。

使用容器镜像运行 Matter 服务器

使用以下命令，您可以在 Docker 容器中运行 Matter 服务器。Matter 网络数据（结构信息）存储在当前目录下新创建的 data 目录中。调整命令以选择其他位置。

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

[!注意] 容器有一个默认的命令行设置（参见 Dockerfile）。如果您打算传递额外的参数，您也必须传递默认的命令行。

要使用蓝牙进行本地配对，请确保也传递 D-Bus 套接字：

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/home-assistant-libs/python-matter-server:stable --storage-path /data --paa-root-cert-dir /data/credentials --bluetooth-adapter 0

使用 Docker compose 运行

docker compose up -d
docker compose logs -f

注意：Matter 和此实现都处于早期阶段，可能缺少功能或需要改进。查看我们的开发说明了解如何参与开发和/或测试。

WebSocket 命令

此列表并不完整，完整概述请参见客户端实现。

设置 WiFi 凭证 告知控制器配对新设备时需要发送的 WiFi 凭证。

{
  "message_id": "1",
  "command": "set_wifi_credentials",
  "args": {
    "ssid": "wifi-名称-在此",
    "credentials": "wifi-密码-在此"
  }
}

设置 Thread 数据集 告知控制器配对新设备时需要使用的 Thread 凭证。

{
  "message_id": "1",
  "command": "set_thread_dataset",
  "args": {
    "dataset": "在此放置凭证"
  }
}

使用代码配对 配对新设备。对于基于 WiFi 或 Thread 的设备，需要预先设置凭证，否则配对将失败。支持 QR 码语法（MT:...）和手动配对代码字符串。控制器将使用蓝牙配对无线设备。如果运行 Python Matter Server 控制器的机器缺少蓝牙支持，配对将仅适用于已连接到网络的设备（通过电缆或其他控制器）。

{
  "message_id": "2",
  "command": "commission_with_code",
  "args": {
    "code": "MT:Y.ABCDEFG123456789"
  }
}

打开配对窗口 打开配对窗口，将此控制器上的设备配对到另一个控制器。返回用作区分器的代码。

{
  "message_id": "2",
  "command": "open_commissioning_window",
  "args": {
    "node_id": 1
  }
}

获取节点 获取已在控制器上配对的所有节点。

{
  "message_id": "2",
  "command": "get_nodes"
}

获取节点 获取单个节点的信息。

{
  "message_id": "2",
  "command": "get_node",
  "args": {
    "node_id": 1
  }
}

开始监听 当发出start_listening命令时，服务器将转储所有现有节点。从那一刻起，所有事件（包括节点属性变化）都将被转发。

{
  "message_id": "3",
  "command": "start_listening"
}

发送命令 因为我们使用Matter SDK的数据模型，这个过程会稍微复杂一些。以下是打开开关的示例：

import json

# 导入CHIP集群
from chip.clusters import Objects as clusters

# 导入将对象转换为字典以及反向转换的功能
from matter_server.common.helpers.util import dataclass_from_dict,dataclass_to_dict

command = clusters.OnOff.Commands.On()
payload = dataclass_to_dict(command)


message = {
    "message_id": "example",
    "command": "device_command",
    "args": {
        "endpoint_id": 1,
        "node_id": 1,
        "payload": payload,
        "cluster_id": command.cluster_id,
        "command_name": "On"
    }
}

print(json.dumps(message, indent=2))

{
  "message_id": "example",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "node_id": 1,
    "payload": {},
    "cluster_id": 6,
    "command_name": "On"
  }
}

你也可以为集群命令提供参数。例如，以下是如何改变亮度：

command = clusters.LevelControl.Commands.MoveToLevelWithOnOff(
  level=int(value), # 提供一个百分比
  transitionTime=0, # 以秒为单位
)

使用基于Thread的Matter设备时的注意事项

当通过非本地Thread边界路由器与Thread设备通信时，你的主机必须处理ICMPv6路由器广告。请参阅openthread.io双向IPv6连接代码实验室了解如何正确设置你的主机。请注意，NetworkManager有自己的ICMPv6路由器广告处理。需要使用最新版本的NetworkManager，但仍存在已知问题（参见NetworkManager问题#1232）。

Home Assistant操作系统10及更新版本可以正确处理ICMPv6路由器广告。

开发

想要帮助开发、测试和/或文档编写吗？太好了！随着这个项目和Matter的不断发展，以及越来越多的设备提供实际的Matter支持，将会有很多需要改进的地方。如果你想提供帮助，请在discord上与我们联系。

设置你的开发环境

要在Home Assistant中启用Matter支持，请参考Home Assistant文档。这些说明仅用于开发！

开发只能在（较新的）Linux或MacOS机器上进行。不支持其他操作系统。

下载/克隆仓库到你的本地机器。
设置开发环境：scripts/setup.sh

你可以查看scripts文件夹中的示例脚本，了解运行客户端和服务器的一般说明。

要仅运行服务器，你可以执行：python -m matter_server.server

服务器运行一个Matter控制器，并包含所有用于存储节点信息、面试和订阅的逻辑。为了与这个控制器交互，我们创建了一个小型的Websockets API，具有类似RPC的接口。该库包含一个客户端作为参考实现，该客户端反过来被Home Assistant使用。将服务器与客户端分离允许多个消费者可以与同一个Matter结构通信，并且Matter结构可以在消费者（例如Home Assistant）关闭时继续运行。

仅使用Python客户端库

本仓库还托管了一个Python客户端库（由Home Assistant使用），该库使用服务器发布的Websockets API。

客户端库依赖于chip/matter clusters包，该包包含所有（集群）模型，并且与操作系统/平台无关。服务器库依赖于Matter Core SDK（仍命名为CHIP），该SDK是特定于架构和操作系统的。我们为Linux（amd64和aarch64）构建（并发布）wheels到pypi，但对于其他平台（如MacOS），你需要自己使用与我们用于clusters包相同版本的SDK构建这些wheels。查看我们的构建脚本以获取指导：https://github.com/home-assistant-libs/chip-wheels/blob/main/.github/workflows/build.yaml

要仅安装客户端部分：pip install python-matter-server