Matter
Matter 连接器让 ThingsPanel 能够发现、绑定、监控和控制局域网内的 Matter 灯具(开关灯和调光灯)。它属于「三方接入」类连接器:安装一次,建立接入点,再导入需要的设备。
1. 功能概览
- 发现:列出已与网关运行时配对的 Matter 节点,显示其中的开关灯或调光灯端点。
- 上报:Matter 属性上报转换为遥测(
power、brightness_pct),可达性转换为在线/离线。 - 控制:ThingsPanel 下发的
set_power、set_brightness命令会发送给设备。 - 范围:支持 On/Off 簇的灯具,可选 Level Control。不支持 Thread,不支持传感器、门锁、温控器等。
2. 工作原理
Matter 设备(你的局域网,IPv6 + mDNS)
▲
Matter 网关运行时 ← 由你自己运行,在 Agent 之外(需要访问局域网;保存 Matter "fabric" 数据)
▲ TCP :7001,共享令牌(请只放在私有网络)
Matter 连接器 ← 在插件管理里安装(由 Agent 运行)
▲
ThingsPanel 平台 + MQTT Broker
连接器刻意做得很小。所有需要访问局域网的事情(设备发现、配对、Matter fabric 凭据)都在网关运行时里,由你自己运行。Agent 只管理连接器。
3. 前提条件
- ThingsPanel 平台支持插件安装(受管运行时身份),并且签名插件目录里包含 Matter 连接器,由管理员提供。
- 一台与 Matter 设备处于**同一 IP 网络(及 IPv6/mDNS 组播域)**的 Linux 主机,已安装 Docker。Mac/Windows 的 Docker Desktop 里的容器无法加入局域网组播域,真实设备请使用 Linux。
- 为网关运行时准备一个持久化的 Docker 卷。它保存 Matter fabric(让 ThingsPanel 能控制你设备的密钥),请备份并且不要外泄。
- 设备需支持 Matter on-network(Wi-Fi/以太网)。不支持 Thread 设备。
4. 运行网关运行时
生成共享令牌(至少 32 个字符),在局域网主机上启动网关运行时:
openssl rand -hex 32 # 记下这个值,它就是连接器的令牌
docker run -d --name matter-gateway --restart unless-stopped \
--network host \
-v matter-gateway-data:/var/lib/thingspanel-matter \
--tmpfs /tmp:rw,nosuid,nodev,size=64m \
-e MATTER_CONTROLLER_TOKEN=<令牌> \
thingspanel-matter-gateway:<版本>
说明:
- 网关镜像由 Matter 连接器仓库构建(
connector/Dockerfile.gateway),镜像和版本请向管理员获取。 - 该端点监听
7001端口,使用明文 TCP。配对码会经过这个端口,所以请只放在私有网络,并且只允许连接器所在主机访问。 - 连接器必须能访问
<网关主机>:7001,该地址由管理员写在 Matter 目录条目里。
5. 安装连接器
此步骤由平台管理员完成。
- 打开应用管理 → 插件管理,切换到插件安装标签。
- 找到 Matter 卡片(名称和版本由你们的插件目录条目决定),点击安装。
- 填写第 4 步的网关令牌(
MATTER_CONTROLLER_TOKEN)。该值由 Agent 保存,之后只显示为「已设置」。

稍等片刻,卡片显示已启用。点击管理可以查看安装步骤和健康状态。

6. 让灯具与网关配对
配对在网关主机上进行,不在 ThingsPanel 里。先让灯具进入配对模式(或在厂商 App 里打开配对窗口),然后执行:
docker exec -it matter-gateway /connector matterctl commission --timeout-seconds 30
命令会提示输入配对码(PIN),输入时不回显;配对码只发送一次给本地控制器,不会写入日志或存储。查看结果:
docker exec matter-gateway /connector matterctl list
每个已配对的开关灯或调光灯端点都会列出节点号和端点号。要把节点从 Matter fabric 中移除(在 ThingsPanel 里解绑不会移除):
docker exec matter-gateway /connector matterctl remove --node-id <节点号> --confirm
7. 创建物模型和设备模板
ThingsPanel 下发的命令由物模型定义。每个租户做一次即可。
7.1 物模型
-
打开设备接入 → 物模型,点击新建物模型,填写名称(例如
Matter Dimmable Light)和版本,保存。
-
打开物模型定义标签,在遥测下新增两个字段:
名称 标识符 数据类型 Power powerBoolean Brightness brightness_pctNumber