从零开发Matter 新的设备类型产品

[English]

这一小节通过在bk_matter基础上，新建一个 On/Off Plug 的Matter应用，用于详细说明bk_matter创建Matter新设备类型的过程。

zap文件配置

zap文件是Matter的一个配置文件，可以通过参照 matter协议 Device Library Specification 对要实现的设备类型进行配置，关于zap工具的使用可以参考 Matter 配置工具 ZAP 。

关于Matter的一些基本概念的介绍可以参考 Matter 简介 。

zap工具会根据Matter的开发有多个版本，因此在目录 components/matter/connectedhomeip/zap 中包含了两个可执行文件：

• zap: 用于对zap文件进行可视化的编辑。修改配置zap文件时需要用到这个工具。

• zap-cli: 用于解析zap文件，在编译过程中会用到。

On/Off Plug设备将会包括两个endpoint。

endpoint 0 设备类型为 0x0016(Matter Root Node)，包含了Matter所有基础的cluster，基础信息配置（Basic Information cluster）、wifi（Network Commissioning，WiFi Network Diagnostics）、OTA（OTA Software Update Provider，OTA Software Update Requestor）等，对于所有类型的设备，这部分基本都一样。因此比较方便的做法是，直接在 examples/lighting-app/lighting-common/lighting-app.zap 文件的基础上进行修改，只保留endpoint 0 即可，按需添加新的endpoint即可。

endpoint 1 设备类型为 0x010A(On/Off Plug-in Unit)，对于具体cluster的配置，需要参考 Device Library Specification 文档。

On/Off Plug-in Unit Cluster Requirements

ID	Cluster	Client/Server	Quality	Conformance
0x0003	Identify	Server		M
0x0004	Groups	Server		M
0x0005	Scenes	Server		P,M
0x0006	On/Off	Server		M
0x0008	Level Control	Server		O

将文件保存为 on-off-plug.zap ，在下一小节中将会用到。

创建gn项目

1. 首先创建一个文件夹 components/matter/connectedhomeip/examples/on-off-plug/beken ，用于存放新设备的代码和配置。

mkdir -p components/matter/connectedhomeip/examples/on-off-plug/beken

2. 创建一些软链接，引入需要的一些依赖。

cd components/matter/connectedhomeip/examples/on-off-plug/beken
mkdir third_party
ln -s ../../build_overrides build_overrides
ln -s ../../../.. connectedhomeip

3. 创建文件 .gn ，gn项目的配置文件

# Copyright (c) 2022 Project CHIP Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

import("//build_overrides/build.gni")
import("//build_overrides/chip.gni")

# The location of the build configuration file.
buildconfig = "${build_root}/config/BUILDCONFIG.gn"

# CHIP uses angle bracket includes.
check_system_includes = true

default_args = {
  target_cpu = "risc-v"
  target_os = "freertos"

  import("//args.gni")
}

4. 创建文件 args.gn 对项目进行一些默认配置。

# Copyright (c) 2022 Project CHIP Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# Options from standalone-chip.mk that differ from configure defaults. These
# options are used from examples/.

import("//build_overrides/chip.gni")

chip_device_platform = "beken"

chip_project_config_include = ""
chip_system_project_config_include = ""
chip_ble_project_config_include = ""

mbedtls_target = "${chip_root}/config/beken/mbedtls:mbedtls"
lwip_platform = "external"

chip_build_tests = false

chip_inet_config_enable_tcp_endpoint = true
chip_inet_config_enable_udp_endpoint = true

chip_config_network_layer_ble = true
chip_config_memory_management = "platform"
chip_enable_additional_data_advertising = false
chip_enable_rotating_device_id = true
chip_enable_ota_requestor = false
chip_inet_config_enable_ipv4 = true

chip_detail_logging = false
chip_automation_logging = false

custom_toolchain = "${chip_root}/config/beken/toolchain:beken"

其中第20行通过 chip_device_platform = "beken" 制定了Matter的编译平台，编译时将会使用 src/platform/beken 下的源码。

5. 创建 BUILD.gn 用于设置项目源码等。

# Copyright (c) 2020 Project CHIP Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

import("//build_overrides/build.gni")
import("//build_overrides/chip.gni")
import("${chip_root}/examples/common/pigweed/pigweed_rpcs.gni")
import("${chip_root}/src/app/chip_data_model.gni")
import("${chip_root}/examples/on-off-plug/beken/args.gni")

examples_plat_dir = "${chip_root}/examples/platform/beken"

chip_data_model("on-off-plug") {
  zap_file = "on-off-plug.zap"

  is_server = true
}

static_library("MatterApp") {
  public_deps = [
    ":on-off-plug",
    "${chip_root}/examples/providers:device_info_provider",
    "${chip_root}/src/platform/logging:default",
  ]

  include_dirs = [
    "${chip_root}/examples/on-off-plug/beken/main/include",
    "${examples_plat_dir}",
  ]

  if (chip_enable_ota_requestor) {
    sources = [
      "${examples_plat_dir}/common/BekenAppServer.cpp",
      "${examples_plat_dir}/common/CHIPDeviceManager.cpp",
      "${examples_plat_dir}/common/CommonDeviceCallbacks.cpp",
      "${examples_plat_dir}/ota/OTAHelper.cpp",
      "main/DeviceCallbacks.cpp",
      "main/DsoHack.cpp",
      "main/chipinterface.cpp",
      "main/Plug.cpp",
    ]
  } else {
    sources = [
      "${examples_plat_dir}/common/BekenAppServer.cpp",
      "${examples_plat_dir}/common/CHIPDeviceManager.cpp",
      "${examples_plat_dir}/common/CommonDeviceCallbacks.cpp",
      "main/DeviceCallbacks.cpp",
      "main/DsoHack.cpp",
      "main/chipinterface.cpp",
      "main/Plug.cpp",
    ]
  }

  output_name = "libMatterApp"
  output_dir = "${root_out_dir}/lib"
  complete_static_lib = true
}

group("default") {
  deps = [ ":MatterApp" ]
}

config("config") {
  include_dirs = [ "include" ]
}

第40-49行主要包括了此Matter device的应用层代码。

第22-27行通过函数 chip_data_model 传入了zap配置文件。 因此需要将上一小节中创建的zap文件 on-off-plug.zap ，复制到改改目录下。 另外，需要目录 components/matter/connectedhomeip 中执行

./scripts/tools/zap/generate.py examples/on-off-plug/beken/on-off-plug.zap

这将会生成 on-off-plug.matter 文件。

编译过程中将会根据这个两个文件选择需要的cluster加入源码，并生成一些代码。关于这部分的原理，可以参考Matter 的文档 code_generation 。

实现相关代码

1. 实现plug设备的基本操作，主要实现对插座设备的初始化开关等操作

Plug.cpp

#define KEY_GPIO        GPIO_24
#define CONTROL_GPIO    GPIO_26
#define LED_GPIO        GPIO_9

void Plug::Init()
{
    ChipLogDetail(DeviceLayer,"Plug Init");
    gpio_config_t cfg;
	gpio_int_type_t int_type = GPIO_INT_TYPE_MAX;

    bk_gpio_disable_input(CONTROL_GPIO);
    bk_gpio_enable_output(CONTROL_GPIO);

    bk_gpio_disable_input(LED_GPIO);
    bk_gpio_enable_output(LED_GPIO);

    cfg.io_mode =GPIO_INPUT_ENABLE;
	int_type = GPIO_INT_TYPE_FALLING_EDGE;
	cfg.pull_mode = GPIO_PULL_UP_EN;
	bk_gpio_set_config(KEY_GPIO, &cfg);
	bk_gpio_register_isr(KEY_GPIO ,key_callback);
    bk_gpio_enable_interrupt(KEY_GPIO);

    bk_gpio_set_output_high(CONTROL_GPIO);
    bk_gpio_set_output_high(LED_GPIO);
    isOn = false;
    mFlashingFreq = 0;
    initOver = false;
}

void Plug::StartUpInit()
{
    ChipLogDetail(DeviceLayer,"Plug StartUpInit");
    if (Server::GetInstance().GetFabricTable().FabricCount() == 0)
    {
        LedStartFlashing(false);
    }
    initOver = true;
}

void Plug::SetOnOff(bool on)
{
    ChipLogDetail(DeviceLayer,"Plug SetOnOff");
    if(!initOver || mFlashingFreq != 0 || on == isOn)
    {
        return;
    }

2. 实现Matter的回调，Matter协议接收到控制端相关属性的更改后，会调用对应的回调

DeviceCallbacks.cpp

void AppDeviceCallbacks::PostAttributeChangeCallback(EndpointId endpointId, ClusterId clusterId, AttributeId attributeId,
                                                     uint8_t type, uint16_t size, uint8_t * value)
{
    switch (clusterId)
    {
    case Clusters::OnOff::Id:
        OnOnOffPostAttributeChangeCallback(endpointId, attributeId, value);
        break;
    default:
        ChipLogProgress(Zcl, "Unknown cluster ID: " ChipLogFormatMEI, ChipLogValueMEI(clusterId));
        break;
    }
}
void AppDeviceCallbacks::OnOnOffPostAttributeChangeCallback(EndpointId endpointId, AttributeId attributeId, uint8_t * value)
{
    VerifyOrExit(attributeId == Clusters::OnOff::Attributes::OnOff::Id,
                 ChipLogError(DeviceLayer, "[%s] Unhandled Attribute ID: '0x%04lx", TAG, attributeId));
    VerifyOrExit(endpointId == 1 || endpointId == 2,
                 ChipLogError(DeviceLayer, "[%s] Unexpected EndPoint ID: `0x%02x'", TAG, endpointId));
    PlugMgr().SetOnOff(*value);

exit:
    return;
}

3. 启动Matter进程，初始化并启动Matter CHIP进程

chipinterface.cpp

static AppDeviceCallbacks EchoCallbacks;
static void InitServer(intptr_t context)
{
    chip::BekenAppServer::Init();
    gExampleDeviceInfoProvider.SetStorageDelegate(&Server::GetInstance().GetPersistentStorage());
    chip::DeviceLayer::SetDeviceInfoProvider(&gExampleDeviceInfoProvider);
#if CHIP_DEVICE_CONFIG_ENABLE_OTA_REQUESTOR    
    OTAHelpers::Instance().InitOTARequestor();
#endif    
    PlugMgr().StartUpInit();
}

{
    ChipLogProgress(DeviceLayer, "on-off-plug!");
    chip::Inet::UDPEndPointImplLwIP::SetQueueFilter((chip::Inet::EndpointQueueFilter *)&filter);

    CHIPDeviceManager & deviceMgr = CHIPDeviceManager::GetInstance();
    err                           = deviceMgr.Init(&EchoCallbacks); // start the CHIP task
    if (err != CHIP_NO_ERROR)
    {
        ChipLogError(DeviceLayer, "DeviceManagerInit() - ERROR!\r\n");
    }
    else
    {
        ChipLogProgress(DeviceLayer, "DeviceManagerInit() - OK\r\n");
        vTaskDelay(pdMS_TO_TICKS(50)); // Just server the application event handler
    ChipLogProgress(SoftwareUpdate, "Exited");

编译

修改对应的配置文件 projects/matter/config/bk7258/config 中的配置 CONFIG_MATTER_EXAMPLE="on-off-plug"

即可编译新建的Matter 应用

make bk7258 PROJECT=matter