Develop Matter new Device from scratch

[中文]

This section explains in detail the process of bk_matter creating a new Matter device type by creating a new On/Off Plug matter application based on bk_matter.

zap file configuration

The zap file is a configuration file of Matter. You can refer to the Matter protocol Device Library Specification to implement Configure the device type. For the use of zap tool, please refer to Matter Configuration Tool ZAP .

For an introduction to some basic concepts of Matter, please refer to Matter Introduction .

The zap tool will have multiple versions according to the development of matter, so the directory components/matter/connectedhomeip/zap contains two executable files:

• zap: Used for visual editing of zap files. This tool is needed when modifying the configuration zap file.

• zap-cli: Used to parse zap files and will be used during the compilation process.

The On/Off Plug device will include two endpoints.

Endpoint 0 device type is 0x0016 (Matter Root Node), which includes all basic clusters of Matter: basic information configuration (Basic Information cluster), wifi (Network Commissioning, WiFi Network Diagnostics), OTA (OTA Software Update Provider, OTA Software Update Requestor) etc. This part is basically the same for all types of devices. Therefore, it is more convenient to modify it directly on the basis of the examples/lighting-app/lighting-common/lighting-app.zap file. Only keep endpoint 0 and add new endpoints as needed.

The endpoint 1 device type is 0x010A (On/Off Plug-in Unit). For specific cluster configuration, you need to refer to the Device Library Specification document.

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

Save the file as on-off-plug.zap, which will be used in the next section.

Create gn project

1. First create a folder components/matter/connectedhomeip/examples/on-off-plug/beken to store the code and configuration of the new device.

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

2. Create some soft links and introduce some required dependencies.

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

3. Create file .gn, the configuration file of the gn project

# 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. Create the file args.gn with some default configuration for the project.

# 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 = false
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
chip_use_transitional_device_instance_info_provider = false
chip_use_transitional_commissionable_data_provider = false

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

Line 20 specifies the Matter compilation platform through chip_device_platform = "beken", and the source code under src/platform/beken will be used during compilation.

6. Create BUILD.gn to set the project source code, etc.

# 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" ]
}

Lines 40-49 mainly include the application layer code of this Matter device.

Lines 22-27 pass in the zap configuration file through the function chip_data_model . Therefore, you need to copy the zap file on-off-plug.zap created in the previous section to the modified directory. In addition, it needs to be executed in the directory components/matter/connectedhomeip .

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

This will generate the on-off-plug.matter file.

During the compilation process, the required cluster will be selected and added to the source code based on these two files, and some code will be generated. For the principle of this part, you can refer to the Matter document code_generation.

Implement code

1. Realize the basic operations of the plug device, mainly realizing the initialization of the Plug device and some other operations

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. Implement the callback of Matter. After the Matter protocol receives changes to the relevant properties of the control end, it will call the corresponding callback.

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. Start the Matter process, initialize and start the Matter CHIP process

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");

Build

Modify the configuration CONFIG_MATTER_EXAMPLE="on-off-plug" in the corresponding configuration file projects/matter/config/bk7258/config

You can compile the new matter application

make bk7258 PROJECT=matter