Matter 设备配网

配网流程

发现 Matter 设备

支持以下两种发现设备的方式：

• 扫码或输入编码

  Matter 标准方式，支持 涂鸦 Matter 设备、三方 Matter 设备

• 自发现搜索

  涂鸦特色功能，目前 仅 支持 Tuya Matter 设备

方式一：扫码或输码

此方式是 Matter 的标准接入方式，您可将用户通过扫描 Matter 配网二维码 的内容或者用户输入的 Matter 配网码 传递至 SDK 接口中进行解析，再将解析返回的 SetupPayload 对象按照本文内 配网流程 进一步执行。

配对设备之前，需要对设备附带的二维码或者配网码进行校验，以判断是否是真实的 Matter 配网码。

接口说明

private IMatterActivator mMatterDevActivatorInstance;
...
  mMatterDevActivatorInstance = ThingHomeSdk.getMatterDevActivatorInstance();
if (null == mMatterDevActivatorInstance) return;
SetupPayload setupPayload = mMatterDevActivatorInstance.parseSetupCode("MT:xxxxxxxxx");
if (setupPayload != null) {
  Log.w("parseSetupCode",setupPayload.toString());
}else {
  Log.w("parseSetupCode","Matter Illegal network code");
}

参数说明

参数	说明
setupCodeString	外包装上设备二维码信息、Matter 设备分享码或数字配网码

数据模型

SetupPayload 模型字段含义说明

属性	类型	说明
version	int	配网协议版本
vendorId	int	厂商信息 ID
productId	int	产品 ID
setupPinCode	long	8 位随机数字
discriminator	Discriminator	配网设备标识符的数据模型

方式二：自发现搜索

自发现搜索会扫描周边支持自发现配网的 Matter 设备。

接口说明

private IMatterDiscoveryActivator mDiscoveryActivatorInstance;
...
  mDiscoveryActivatorInstance = ThingHomeSdk.getDiscoveryActivatorInstance();
if (null== mDiscoveryActivatorInstance)return;
mDiscoveryActivatorInstance.startDiscovery(new IDynamicDiscoveryListener() {
  @Override
  public void onFound(ThingMatterDiscovery discovery) {
    Log.i("startDiscovery","onFound: "+discovery.toString());
  }

  @Override
  public void onError(String errorCode, String errorMsg) {
    Log.e("startDiscovery","onError, errorCode: "+errorCode+" errorMsg: "+errorMsg);
  }
});
}

参数说明

参数	说明
discoveryListener	发现设备的监听

停止发现设备

接口说明

void stopDiscovery();

代码示例

mDiscoveryActivatorInstance.stopDiscovery();

连接 Matter 设备

Matter 设备配网需要首先解析 Matter 设备配网码，获取 SetupPayload 模型对象，然后连接 Matter 设备。连接完成后，调试设备上云激活。

Matter 设备连接后建立完成 PASE（Passcode-Authenticated Session Establishment）会话，将触发 PASE 会话成功回调。

接口说明

ConnectDeviceBuilder builder = new ConnectDeviceBuilder();
builder.setSetupPayload(setupPayload);
builder.setSpaceId(homeId);
builder.setTimeout(timeout);
builder.setConnectCallback(new IThingConnectDeviceCallback() {
  @Override
  public void onFound(boolean isThingMatter, MatterDeviceTypeEnum deviceType) {
    //isThingMatter 是否是涂鸦设备，true：涂鸦设备，false：非涂鸦设备

  }

  @Override
  public void onConnected(ConnectResult connectResult) {

  }

  @Override
  public void onError(String errorCode, String errorMsg) {

  }
});
mMatterDevActivatorInstance.connectDevice(builder);

参数说明

参数	说明	说明
setupPayload	SetupPayload	解析配网码获取的设备模型
homeId	long	当前家庭 ID，详情参考 家庭管理 章节
timeout	long	配网的超时时间设置，单位是毫秒
thingConnectDeviceCallback	IThingConnectDeviceCallback	回调

调用 connectDevice 接口成功后可以获取设备类型 MatterDeviceTypeEnum。

数据模型

ConnectResult 是连接设备获取的模型，模型字段含义说明如下：

属性	类型	说明
discoveryType	DiscoveryType	设备 PASE 会话通讯能力， DiscoveryType.BLE：通过蓝牙发现。 DiscoveryType.MDNS：通过 MDNS 发现
ipAddress	String	路由器为设备分配的 ID，通过低功耗蓝牙发现该值为空
port	int	路由器为设备分配的端口，通过低功耗蓝牙发现该值为空
thingProductId	String	云端分配的产品 ID，涂鸦双模 Wi-Fi 设备的该值为空
accessType	int	是否是涂鸦设备（检测云服务）： 0：涂鸦 Matter 设备 1：非涂鸦 Matter 设备
isThingMatter	boolean	是否是涂鸦设备（解析设备广播）： true：涂鸦 Matter 设备 false：非涂鸦 Matter 设备
nodeId	long	为设备分配的配网节点 ID
typeEnum	MatterDeviceTypeEnum	设备类型
gwId	String	Thread 设备关联到的具有 OTBR（OpenThread Border Router）网络的网关 ID

获取配网 Token

获取 Token

开始配网之前，SDK 需要在联网状态下从云端获取配网 Token，Token 的有效期为 10 分钟。且配置成功后就会失效，再次配网需要重新获取。

ThingHomeSdk.getActivatorInstance().getActivatorToken(homeId,new IThingActivatorGetToken() {

  @Override
  public void onSuccess(String token) {

  }

  @Override
  public void onFailure(String s, String s1) {

  }
});

参数说明

参数	说明
homeId	家庭 ID，详情参考 家庭管理 章节

调试设备

接口说明

CommissioningParameters commissioningParameters = new CommissioningParameters.Builder()
  .connectDeviceResult(connectResult)
  .setupPayload(setupPayload)
  .spaceId(homeId)
  .token(token)
  .ssid(wifiSSId)
  .password(wifiPwd)
  .timeOut(timeout)
  .build();
mMatterDevActivatorInstance.commissionDevice(commissioningParameters, new MatterActivatorCallback() {
  @SuppressLint("MissingPermission")
  @Override
  public void onActivatorSuccess(DeviceBean result) {

  }

  @Override
  public void onError(String errorCode, String errorMessage) {

  }

  @Override
  public void onDeviceAttestationFailed(long deviceControllerPtr, long devicePtr, int errorCode){
    //未认证通过
  }
});

参数说明

参数	说明	说明
setupPayload	SetupPayload	解析配网码获取的设备模型
homeId	long	当前家庭 ID，详情参考 家庭管理 章节
timeout	long	配网的超时时间设置，单位是毫秒
connectResult	ConnectResult	connectDevice 接口获取的模型
token	String	从云端获取配网 Token
wifiSSId	String	设备工作 Wi-Fi 的名称，双模设备不可为空
wifiPwd	String	设备工作 Wi-Fi 的密码，双模设备不可为空
gwId	String	网关 ID，涂鸦 Thread 子设备配网可绑定到指定网关下

Thread 子设备 PASE 会话参数组装：

• 子设备依赖 Matter 网关提供的 OTBR 网络进行配网，因此在建立 CASE 会话前，需要指定网关 ID。
• 在 PASE 会话阶段，SDK 会扫描周围可用的 Thread 网络并根据信号强度选择最佳网关 ID，在 void onConnected(ConnectResult connectResult); 回调中，ConnectResult 会提供可用的 gwId，如该参数为空或您想要指定网关，也可以使用当前家庭下的网关 ID。

设备认证确认

设备认证回调

如果您配对的是一个未经过官方认证的设备，那么会触发认证回调。如果触发了该回调，在您选择继续或放弃前，配网流程将会暂停。

接口说明

void onDeviceAttestationFailed(long deviceControllerPtr, long devicePtr, int errorCode);

参数说明

参数	说明
deviceControllerPtr	DeviceController 对象的指针
device	配网链路中的设备对象地址指针
error	未通过认证的错误信息

示例代码

@Override
public void onDeviceAttestationFailed(long deviceControllerPtr, long devicePtr, int errorCode){
    //未认证通过
}

继续或停止配网

如您认为该设备证书可以被信任，可以调用该接口继续配网亦或终止配网。

接口说明

mMatterDevActivatorInstance.continueCommissioningDevice(deviceControllerPtr,devicePtr,ignoreAttestationFailure);

参数说明

参数	说明	说明
deviceControllerPtr	long	设备 Controller 指针
devicePtr	long	配网设备指针
ignoreAttestationFailure	boolean	是否忽略认证继续配网 true：继续 false：取消

取消或终止配网

接口说明

mMatterDevActivatorInstance.cancelActivator();

错误码

错误码	说明	备注
3000	分配 nodeId 失败	检查网络状态、检查是否为当前家庭管理员
3003	通过蓝牙连接设备失败	检查蓝牙和定位权限
3004	扫描 mDNS 广播超时	检查手机和设备是否在同一个局域网内
3005	commissionDevice 时失败	-
3007	连接设备建立 PASE 会话超时	检查设备是否在配网状态
3008	commissionDevice 超时	-
3011	与设备连接 PASE 会话失败	-
3017	非涂鸦 Matter 设备激活失败	-
3019	网关不存在或网关局域网不在线	检查当前手机是否和网关是否在同一局域网内
3013	通用错误码	-