使用 Matter-SDK 快速搭建 Matter 环境 (Linux)

Matter 作为一个统一的智能家居互联协议，凭借其高兼容性的特点，正逐渐打破各个智能家居之间的壁垒。乐鑫作为在 Matter 项目发布之初的早期成员，提供了一套开源、完整、易用的 Matter-SDK。

乐鑫的 Matter-SDK 是建立在开源 Matter-SDK 之上的，它提供了简化的 API、常用的外设、安全、制造和生产工具以及详尽的文档支持。该 SDK 包括丰富的生产参考资料，旨在简化 Matter 产品的开发过程，使用户能够在最短的时间内投入生产。

您可以通过点击以下链接，进一步了解 Matter：

ESP-Matter 编程指南
ESP-Matter 示例代码
Connectedhomeip Github 项目
乐鑫 Matter 系列文章

您可以观看下面的教程视频，也可以阅读本篇的图文教程。本文将详细介绍在 Linux 环境下，如何使用 Matter-SDK 完成 Matter 环境搭建。

【乐鑫教程】｜使用 Matter-SDK 快速搭建 Matter 环境 (Linux)

搭建步骤：

1. 系统及设备环境

操作系统：Ubuntu 22.04.3 LTS
主机配置：具有蓝牙适配器
网络：能流畅访问 Github 的网络环境
测试芯片：ESP32-C3-MINI-1
测试开发板：ESP32-C3-DevKitM-1 v1.0

注：Ubuntu 版本应为 20.04 和 22.04，并且为主机开发。若使用虚拟机，在用 CHIP Tool 工具进行配网调试时会出现查找蓝牙设备失败或者无法进行调试的情况。

2. 安装准备

2.1 Matter 安装准备

sudo apt-get install git gcc g++ pkg-config libssl-dev libdbus-1-dev \
libglib2.0-dev libavahi-client-dev ninja-build python3-venv python3-dev \
python3-pip unzip libgirepository1.0-dev libcairo2-dev libreadline-dev

安装过程具体请参考官方 Github 项目。

注：Windows 系统推荐使用 WSL 进行开发，详见官方 WSL 配置方法。

2.2 搭建 ESP-IDF 开发环境

Matter 的开发环境依赖于 ESP-IDF 开发环境，如果当前没有搭建 ESP-IDF 环境，请参考官方文档进行搭建，或者使用下面的指令进行快速搭建。

（1）安装 ESP-IDF 需要以下安装准备：

sudo apt-get install git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

（2）获取仓库，进行安装：

git clone --recursive https://github.com/espressif/esp-idf.git
cd esp-idf; git checkout v5.1.1; git submodule update --init --recursive;
./install.sh
cd ..

3. 获取并安装 Matter

使用以下指令获取仓库，进行安装：

cd esp-idf
source ./export.sh
cd ..

git clone --depth 1 https://github.com/espressif/esp-matter.git
cd esp-matter
git submodule update --init --depth 1
cd ./connectedhomeip/connectedhomeip
./scripts/checkout_submodules.py --platform esp32 linux --shallow
cd ../..
./install.sh
cd ..

4. 配置环境

当每一个新终端开启时，使用以下命令来配置 Matter 的开发环境：

cd esp-idf; source ./export.sh; cd ..
cd esp-matter; source ./export.sh; cd ..

您可以选择开启 Ccache 以提升编译速度：

export IDF_CCACHE_ENABLE=1

5. 编译 ESP-Matter 示例

进入 ESP-Matter Light 示例目录：

cd esp-matter/examples/light

开始编译示例，首先设置编译目标芯片平台（以 ESP32-C3 为例）：

idf.py set-target esp32c3

在正式进行烧录之前，推荐先擦除整片 Flash，烧录并监控：

idf.py erase_flash

idf.py flash monitor

至此，如果编译没有报错，程序成功烧录进 ESP32-C3，并在终端界面显示正常的状态，则代表 Matter 环境已被成功搭建。

6. 对 Matter 设备进行配网与基本控制

首先，使用在交互模式下的 CHIP Tool 进行配网。先为配网开启一个新的终端，配置 Matter 的开发环境，并运行：

cd esp-idf; source ./export.sh; cd ..
cd esp-matter; source ./export.sh; cd ..
export IDF_CCACHE_ENABLE=1
chip-tool interactive start

对设备进行配网具有多种途径，这里我们使用 BLE Wi-Fi 的方式进行配网，复制如下指令：

pairing ble-wifi 0x7283 <ssid> <passphrase> 20202021 3840

在上述指令中，0x7283 是随机选取的节点 ID，20202021 是配对码，3840 是鉴别码，粘贴命令到终端，确保电脑与所填 Wi-Fi 在同一网络环境内，在 SSID 填入 Wi-Fi 名称，passphrase 填入密码。填写完成后的示例如下：

pairing ble-wifi 0x7283 Espressif password 20202021 3840

开始运行，等待一段时间，当监控设备的终端中出现以下日志时，即代表配网成功：

I (347065) app_main: Commissioning complete 

I (347065) esp_matter_core: Commissioning Complete

在配网完成后，我们尝试使用一个命令来对 ESP32-C3 开发板上的 RGB 灯进行控制，复制以下开关翻转的命令到 CHIP Tool 终端中运行：

onoff toggle 0x7283 0x1

在监控设备的终端中我们可以看到 Received command 相关日志：

I (122717) esp_matter_command: Received command 0x00000002 for endpoint 0x0001's cluster 0x00000006 

I (122717) esp_matter_attribute: ********** R : Endpoint 0x0001's Cluster 0x00000006's Attribute 0x00000000 is 1 ********** 

I (122727) chip[ZCL]: Toggle ep1 on/off from state 1 to 0

即代表收到了指令的请求，同时，我们也可以看到开发板上的 RGB 灯关闭了，再次运行，RGB 灯被点亮。

7. 常见问题及其解决方法

（1）idf.py erase_flash 时出现：

/dev/ttyUSB0 failed to connect: Could not open /dev/ttyUSB0, the port doesn't exist
Serial port /dev/ttyS0
/dev/ttyS0 failed to connect: Could not open /dev/ttyS0, the port doesn't exist
No serial ports found. Connect a device, or use '-p PORT' option to set a specific port.

解决方法：需要确保该用户对 USB 口拥有正确的读写权限。

sudo adduser <username> dialout sudo chmod a+rw /dev/ttyACM0

（2）git clone 时出错或速度过慢：

dial tcp 108.160.167.174:443: connect: connection refused

解决方法：需要确保用户拥有一个能流畅访问 Github 的网络。

（3）编译 Light 示例时报错，显示：

ERROR: This script was called from a virtual environment, can not create a virtual environment again

解决方法：使用如下指令进行编译。

pip install -r $IDF_PATH/requirements.txt

（4）在配网过程中并未出现如下提示：

I (347065) app_main: Commissioning complete 

I (347065) esp_matter_core: Commissioning Complete

解决方法：尝试重复进行配网操作。

（5）运行 idf.py 相关指令时显示：

idf.py: command not found

原因：开启新终端时未配置 Matter 环境。

解决方法：使用如下指令配置 Matter 环境。

cd esp-idf; source ./export.sh; cd .. 

cd esp-matter; source ./export.sh; cd ..

（6）Matter 安装过程中出现：

/home/User/esp/esp-matter/connectedhomeip/connectedhomeip/.environment/activate.sh:190: command not found: pw Error during bootstrap--see messages above.

解决方法：

git clean -Xdf
rm -rf connectedhomeip/connectedhomeop/.environmemt
source ./scripts/bootstrap.sh

（7）Matter 安装过程中出现：

raise CalledProcessError(retcode, cmd) 

subprocess.CalledProcessError: Command '['/home/share/samba/app/esp-matter/connectedhomeip/connectedhomeip/.environment/pigweed-venv/bin/python', '-m', 'pip', 'install', '--log', '/home/share/samba/app/esp-matter/connectedhomeip/connectedhomeip/.environment/pigweed-venv/pip-requirements.log', '--requirement=/home/share/samba/app/esp-matter/connectedhomeip/connectedhomeip/scripts/setup/requirements.txt', '--constraint=/home/share/samba/app/esp-matter/connectedhomeip/connectedhomeip/scripts/setup/constraints.txt']' returned non-zero exit status 1.

原因：python 3.10 版本中 pip 安装器的 bug 对 Matter 在 python 环境设置过程中的 pip 安装步骤产生了影响。

解决办法：将 python 3.10 切换至更低的版本，例如 3.8，再对 ESP-IDF 和 ESP-Matter 进行安装。

以上就是通过 Matter-SDK 完成 ESP-Matter 的环境搭建及测试的全过程。如果您有任何问题，可以进入乐鑫官网查看相关技术文档获取帮助，欢迎在评论区留言讨论，或随时联系我们。