Lazy loaded image
工具与配置
【MatterChipTool环境】在Ubuntu下搭建python-matter-server、Chip-tool、chip-lighting-app 并简单运用
字数 4634阅读时长≈ 12 分钟
2025-12-1
2026-9-15
子系统配置为：在Windows11环境下配置WSL Ubuntu24.04子系统， 也可以使用虚拟机例如VMware等

Python Matter 服务器配置

写在前面
注意今后每次开启服务器时都需要先进入虚拟环境

步骤 1：创建并激活虚拟环境

安装 Python 虚拟环境、pip 和（理论上）蓝牙支持：
验证一下蓝牙（多半是没有设备的，这是预期现象）：
创建并激活虚拟环境：
激活后，命令行前面会有前缀：

步骤 2：升级 pip

虚拟环境就位后，先升级 pip：
此时使用的是虚拟环境里的 pip，不会影响系统全局环境。

步骤 3：安装 python-matter-server

安装核心包：
安装成功后，可执行文件在虚拟环境的 bin 目录下，确认一下路径：

步骤 4：一次性补齐 Python 依赖

实际运行过程中，matter-server 会在导入阶段不断暴露出缺少的模块。最开始我是通过多次执行 matter-server --help，一个个看缺什么再装什么，依次踩到了：
  • cryptography
  • chip.exceptions（来自 home-assistant-chip-core）
  • zeroconf
  • atomicwrites
为了让后来的人少走弯路，可以直接一次性补齐这些依赖：
依赖全部装完后，可以先试：
如果能正常输出 Usage/Options 帮助，而不是 ModuleNotFoundError，说明 Python 层依赖已经齐了。

步骤 5：补充系统库依赖（libnl）

启动时，底层 CHIP 栈会加载一些系统动态库。如果缺失，会看到类似这样的错误：
这说明缺少 Netlink 相关的系统库。直接在 Ubuntu/WSL 中安装：
安装完成后，可以确认一下库文件是否存在：
到这里，底层系统库就准备好了。

步骤 6：解决 CHIP 在 /data 下写配置失败的问题

系统库装好后，再次启动 matter-server，会看到 CHIP 栈开始初始化失败：
核心问题是：CHIP 试图在 /data 目录下写入 chip_factory.ini，但默认的 WSL Ubuntu 并不存在 /data 这个目录，导致初始化失败。
一个简单粗暴、实测有效的解决方案：把 /data 软链接到我们自己的配置目录 ~/.matter_server。
先确保存储路径存在：
然后创建软链接：
检查一下链接是否正确：
这样，当 CHIP 再次尝试访问 /data/chip_factory.ini 时，实际就会落在 ~/.matter_server/chip_factory.ini，文件可以正常创建，栈也能顺利初始化。

步骤 7：正式启动 matter-server

准备好目录之后，就可以正式启动了：
参数说明：
  • -storage-path ~/.matter_server：用于保存配网信息、证书等持久化数据；
  • -port 5580：matter-server 暴露的 HTTP / WebSocket 端口；
  • -log-level DEBUG：开启详细日志，方便调试。
• 注意：新版本已经不支持旧文中的 -v 参数，使用 --log-level 代替。
如果一切正常，此时你会在终端看到类似下面的输出，并且不会再出现 traceback / core dumped：
此时 matter-server 会一直在前台跑着。
可以再开一个终端，激活虚拟环境后测试 HTTP 接口是否可用：
或者直接在Windows打开本地浏览器直接输入IP:5580来进入Python Matter服务器后台
  • 因为我们Linux子系统，所以Windows可以直接访问
  • IP为 ifconfig查看
正常应能看到如下界面
notion image

在子系统中起一个 Controller 和一个 Client 并互通

注：此处可重新创建一个虚拟环境

1 安装 / 编译 Matter 官方工具（chip-tool + 模拟设备）

介绍：
CHIP Tool （chip-tool） 是一个 Matter 控制器实现，允许将 Matter 设备入网并使用 Matter 消息与其通信，这些消息可能包含数据模型动作，如集群命令。 该工具还提供其他特定于 Matter 的实用程序，如解析设置有效负载或执行发现操作。
CHIP Tool 的官方 README：https://github.com/project-chip/connectedhomeip/blob/master/examples/chip-tool/README.md.
在 WSL 里操作：
常见问题解决：
  1. 如果在 git clone 卡住（因为网络问题），可以使用GitHub文件加速代理转换链接来加速克隆如（git clone https://hk.gh-proxy.org/https://github.com/project-chip/connectedhomeip.git）
  1. 如果在source scripts/bootstrap.sh卡住则可以让 git 克隆 pigweed 也走代理 URL
    1. 批量替换所有子模块 URL 为代理
        2. 然后检查一下几项确认修改成功：
        现在你应该能看到类似：
    2. 同步并重新拉取子模块
        • 先让 git 重新读取子模块配置：
        • 然后直接递归初始化 & 更新所有子模块（这一步可能稍微久一点）：
    3. 如果一切正常，它应该一路跑完没有 fatal: unable to access 'https://github.com/... 这种错误。并且会输出此界面
        4. notion image
  1. 如果在bootstrarp.sh 出现界面后，下载工具失败。因为编译前的初始化脚本 bootstrap.sh 需要访问 Google 服务器（CIPD）下载大量二进制工具，且通常不走普通的 VPN 通道（例如SOCKS5），必须手动配置 HTTP 代理，否则会报错 Network is unreachable。
    1. 安装并启动代理转换工具
        2. 我们需要一个工具将 VPN 的 SOCKS5 流量转换为终端可用的 HTTP 流量。 (保持当前终端不变，打开一个新的 WSL 窗口运行以下命令)
      注意：保持这个窗口开启，不要关闭。
      • 设置环境变量并初始化
      回到原来的 WSL 窗口（在 connectedhomeip 目录下），应用代理并开始初始化：
      • 下一步就可以激活环境了
          • 环境正常，激活环境时应输出
          notion image

控制模拟灯泡

我们目前已经完成了以下步骤：
  1. 在WSL Ubuntu中安装了python-matter-server并成功运行。
  1. 编译了chip-tool（Matter控制器）和chip-lighting-app（模拟灯泡设备）。
如果不确定是否存在，可以在 WSL 终端里检查一下：
到这里，我已经拥有三样东西：
  • 正在跑的 Python Matter Server（控制器 + 网关服务）
      • python-matter-server 本质上就是一个 Matter 控制器（准确说是“控制器 + 网关服务”），只是它不是像 chip-tool 那样用命令行直接发指令，而是：
      • 在后台维护一个 Matter 控制器栈（fabric、证书、配网信息等）
      • 对外提供 HTTP / WebSocket API 和 Web 前端页面
      • 由“客户端”（浏览器、自动化系统、Home Assistant 等）通过这些 API 去控制设备 通过自身暴露的 API（REST/WebSocket/其它 RPC）去控制设备
  • chip-tool（另一个控制器）
  • chip-lighting-app（模拟灯泡设备）
matter-server 和 chip-tool 是两个独立控制器，可以分别对设备进行配网和控制。 下面以 chip-tool + chip-lighting-app 为例，完成一套完整的配对和控制流程。

终端 1：运行模拟灯泡设备

在第一个终端中（root），启动模拟灯泡：
启动后，注意日志中的关键字段：
这表示设备处于「可配网」状态。
如果日志中出现 Fabric already commissioned，说明设备曾被配对过，需要先清理 /tmp/chip_* 再重启应用。

终端 2：启动控制器并完成配网

在第二个终端中（root），激活环境并用 chip-tool 作为控制器：
执行配网命令：
参数说明：
  • pairing onnetwork：通过本地网络自动发现并配对设备；
  • 第一个 1：自定义的 Node ID，后面控制设备都用这个 ID；
  • 20202021：配网 PIN 码，必须与灯泡日志中的 Setup Pin Code 一致；
  • -paa-trust-store-path：指向开发用的 PAA 根证书目录。
如果成功，chip-tool 日志中会看到：
此时，设备端也会刷出一大堆 PASE/CASE/commissioning 日志，说明双方握手成功。

实现控制器开关灯

在同一个 chip-tool 终端中，使用 OnOff 集群命令控制模拟灯泡：
参数解释：
  • 第一个 1：Node ID（配网时指定的那个 1，对应设备的逻辑地址）。
  • 第二个 1：Endpoint ID，lighting-app 默认使用 endpoint 1。
如果一切正常：
  • 控制器终端会显示命令发送成功；
  • 模拟设备终端会输出一大堆，其中有一句类似：
至此，在同一个 WSL 环境里，官方控制器 chip-tool 成功配网并控制了官方模拟灯泡 chip-lighting-app。

用 matter-server 控制灯

  • 我们需要知道：正在跑的 Python Matter Server（控制器 + 网关服务）
      • python-matter-server 本质上就是一个 Matter 控制器（准确说是“控制器 + 网关服务”），只是它不是像 chip-tool 那样用命令行直接发指令，而是：
    • 在后台维护一个 Matter 控制器栈（fabric、证书、配网信息等）
    • 对外提供 HTTP / WebSocket API 和 Web 前端页面
    • 通过自身暴露的 API（REST/WebSocket/其它 RPC）去控制设备由“客户端”（浏览器、自动化系统、Home Assistant 等）通过这些 API 去控制设备
用 matter-server 控制灯，一共分两步：
  1. 把灯（chip-lighting-app）配网到 matter-server 管理的 fabric 里
  1. 通过 matter-server 提供的 Web 页面或 HTTP API 发 On/Off 命令

步骤 0：准备好三个东西

  1. WSL 里运行 matter-server（已经有了） 确保它在跑，端口 5580：
    1. WSL 里运行模拟灯泡
        2. 另开一个 WSL 终端，启动灯泡：
        日志里要看到：
        如果看到 Fabric already commissioned，先清理：
    1. 确认你能从 Windows 访问 matter-server
    在 WSL 里查看 IP：
    比如看到 eth0 是 172.22.133.5，那么在 Windows 浏览器打开：
    能看到一个简单的 Web 页面就说明 server 正常。

    步骤 1：使用 matter-server 把灯添加到Fabric中

    如果之前灯泡绑定了控制器， 可以先rm -f /tmp/chip_*清理一下数据。
    启动灯泡后，看到的 Manual pairing code: [34970112332] ，34970112332就是添加的code
    然后就可以添加了。
    notion image

    解决 Unable to find PAA 设备证明失败问题

    在前面的步骤中（0. 准备环境 / 1. 让 matter-server 把灯“收进来”），环境都已经搭好，但在真正配网时，
    仍然可能卡在设备证明（Attestation）这一步，日志里出现类似报错：

    1. 问题的根本原因

    Matter 设备在配网时会提供一条证书链：
    设备证书（DAC） → 产品中级证书（PAI） → 产品根证书（PAA）。
    控制器需要在本地的 PAA 根证书信任库里找到与这条链匹配的 PAA，才能完成设备证明。如果本地没有对应 PAA，就会出现上述 “Unable to find PAA / CA certificate not found / PAA not found in DCL and/or local PAA trust store” 的错误。
    我这次碰到的问题有两个坑：
    1. 证书链是正确的，但根证书不在控制器使用的目录里。
    1. Python Matter Server 有多个“看起来很像”的路径和参数：
        • 源码中的默认目录是：~/.matter-server/paa-root-certs（中划线）
        • 我一开始放在了：~/.matter_server/paa_root_certs（下划线）
        • CLI 参数叫：-paa-root-cert-dir（单数），不是 -paa-root-certs-dir
    路径名和参数名的这点细微差别，导致我把正确的证书放到了错误的目录，控制器当然找不到对应的 PAA。

    2. 如何找到设备对应的 PAA

    首先要确认设备在用哪一个 PAA。
    方法是从 SDK 自带的测试证书里查：
    可以看到 PAA 的 SKID：
    日志中 PAI 的 AKID 也是这串值（去掉冒号就是一连串 40 字节十六进制字符串），说明设备用的根就是这个 Chip-Test-PAA-FFF1-Cert.pem。

    3. 把 PAA 证书转换成 DER 并命名正确

    Python Matter Server / CHIP 控制器的文件信任库约定：
    PAA 以 DER 格式存储，文件名就是 SKID（去掉冒号）。
    在同一目录下执行：
    简单检查一下文件：
    能看到明显的 X.509 结构头（30 82 ...）和 Matter Test PAA1 等字样，就说明这个 DER 文件是正常的。

    4. 放到 正确的 PAA 信任目录

    这个地方是整个问题的关键。
    根据 Python Matter Server 的实现：
    • 默认 PAA 目录常量是：DEFAULT_PAA_ROOT_CERTS_DIR = ~/.matter-server/paa-root-certs
    • CLI 对应参数是：-paa-root-cert-dir
    • 底层 CHIP 还可以通过环境变量 MATTER_PAA_ROOT_CERTS_DIR 来指定目录
    我一开始只注意到了 ~/.matter_server/paa_root_certs（下划线），而真正被服务器使用的是 ~/.matter-server/paa-root-certs（中划线）。
    正确操作是：
    然后用显式参数和环境变量一起启动 matter-server，避免路径歧义：
    这里同时做了三件事：
    1. 把证书放到了 Python Matter Server 代码中的默认目录（中划线）。
    1. 用 MATTER_PAA_ROOT_CERTS_DIR 告诉底层 CHIP 也去这个目录找 PAA。
    1. 用 CLI 参数 -paa-root-cert-dir 再次显式指定同一目录，保证 Matter Server 和 CHIP 对 PAA 路径的认知一致。
    这一步之后，再重新执行配网：
    • 日志里不再有 Unable to find PAA、CA certificate not found、PAA not found in DCL and/or local PAA trust store；
    • 设备证明（AttestationVerification）成功，后续网络配置和访问控制步骤可以继续执行，灯泡最终成功“收进来”。
    结果如图：
    notion image
    notion image
    notion image
    由于Server是通过自身暴露的 API（REST/WebSocket/其它 RPC）由“客户端”（浏览器、自动化系统、Home Assistant 等）通过这些 API 去控制设备
    所以。。。。。。。。。
    上一篇
    【ESP-Matter环境】_搭建ESP-Matter环境，并使用esp32_-_h2_模拟Matter_Node（light）
    下一篇
    【ESP-IDF环境】在Windows子系统WSL下搭建Ubuntu24.04的ESP32+vscode开发环境
    评论
    Loading...
    目录