Python Matter WebSocket Server
项目描述
Python Matter Server
本项目基于官方Matter（原名CHIP）SDK，通过WebSocket实现Matter控制器服务器，并提供了服务器和客户端的实现。
本项目的目标是首先在Home Assistant中实现Matter支持，但其通用方法也使其适用于其他项目。
支持
有疑问吗？
您有多种方式获得答案
- Home Assistant 社区论坛。
- Home Assistant Discord聊天服务器。
- 加入/r/homeassistant Reddit 社区。
如果您在Home Assistant中使用Matter时遇到问题，请在Home Assistant Core 仓库中提交问题报告。
如果您确定您的问题与Matter服务器组件有关，也可以在此仓库中提交问题。
安装
我们强烈建议您使用Home Assistant OS和官方Matter服务器附加组件来使用Matter与Home Assistant。Matter集成会自动安装Python Matter Server附加组件。请参阅Home Assistant 文档。Home Assistant OS已经过测试和调整，可与Matter和Thread一起使用，这使得这种组合成为测试最充分且几乎无担忧的环境。
如果您仍然希望进行自行管理的容器安装，我们确实提供官方容器镜像。请注意，您可能在使用Matter设备（尤其是基于Thread的设备）时遇到通信问题。这主要是因为容器安装使用宿主网络，并依赖于您操作系统的网络管理。
与基于Wi-Fi/Ethernet的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-name-here",
"credentials": "wifi-password-here"
}
}
设置Thread数据集 通知控制器在入网新设备时需要使用的Thread凭证。
{
"message_id": "1",
"command": "set_thread_dataset",
"args": {
"dataset": "put-credentials-here"
}
}
代码配置佣金 配置新设备。对于基于WiFi或Thread的设备，需要在配置之前设置凭据，否则佣金配置将失败。支持QR码语法（MT:...）和字符串形式的手动配对码。控制器将使用蓝牙进行无线设备的佣金配置。如果运行Python Matter服务器控制器的机器缺少蓝牙支持，则佣金配置将仅适用于已连接到网络（通过电缆或另一个控制器）的设备。
{
"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
# Import the CHIP clusters
from chip.clusters import Objects as clusters
# Import the ability to turn objects into dictionaries, and vice-versa
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), # provide a percentage
transitionTime=0, # in seconds
)
注意使用基于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织物通信，并且当消费者（例如Home Assistant停止运行）时，Matter织物可以继续运行。
Python客户端库仅限
此存储库中还有一个Python客户端库（由Home Assistant使用），它消耗服务器发布的Websockets API。
客户端库依赖于包含所有（集群）模型的芯片/物联集群包，该包是操作系统/平台无关的。服务器库依赖于架构和操作系统特定的Matter核心SDK（仍称为CHIP）。我们为Linux（amd64和aarch64）构建并发布到PyPI的wheel，但对于其他平台（如Macos），您需要使用与集群包相同的SDK版本自行构建这些wheel。请参阅我们的构建脚本以获取说明： https://github.com/home-assistant-libs/chip-wheels/blob/main/.github/workflows/build.yaml
仅安装客户端部分： pip install python-matter-server
下载文件
下载您平台对应的文件。如果您不确定选择哪个，请了解有关安装包的更多信息。
源代码发行版
构建发行版
python_matter_server-6.6.0.tar.gz的散列值
| 算法 | 散列值 | |
|---|---|---|
| SHA256 | 5d9da5a33587b7d30ba647a8177381c46656da43cdc2c5d2a7ed59a65a95566f |
|
| MD5 | 77d26a3d7783bef9e54c7504089eda25 |
|
| BLAKE2b-256 | f667af8788857f52a664e412201482b987cc6c15076e0db7daa07944312d6db3 |
python_matter_server-6.6.0-py3-none-any.whl的散列值
| 算法 | 散列值 | |
|---|---|---|
| SHA256 | ce0e4db590200d8bd1cf2c0cedd3e06d485b2e0745f72ef81692a48eab044bef |
|
| MD5 | cc84346918b34941536deacf6d836e8a |
|
| BLAKE2b-256 | fe0e5a0444332431e2164cb26c0bbc35adea708c28fe53d082e82da6491ff4ee |
