Edit

Matter API Reference#

Use this reference to find the application customization APIs available in a Silicon Labs Matter application. The available APIs depend on the application and its configuration.

Most of the following APIs are exposed through the generated AppTask interface. To customize those APIs, derive CustomerAppTask from the generated implementation and override the corresponding *Impl() hook. The Closure app also exposes ClosureManager APIs through a separate CustomerAppManager override chain. See Extending Base App Implementation for the implementation workflow.

Use autogen/AppTaskImpl.h in your project for the complete AppTask signatures. For Closure Manager APIs, use autogen/ClosureManagerImpl.h. The app-specific pages list each *Impl() override, its public API name, and the default behavior.

Extending Base App Implementation#

CustomerAppTask#

To customize AppTask behavior, override the relevant Silicon Labs implemented APIs in CustomerAppTask. The build system generates the base implementation and the complete set of overridable AppTask *Impl() APIs in autogen/AppTask.cpp and autogen/AppTaskImpl.h. Any *Impl() methods that you do not override use the Silicon Labs default implementation.

How to Override APIs#

CustomerAppTask extends the base AppTask by using the Curiously Recurring Template Pattern (CRTP). The base class declares one *Impl() method for each overridable API. Override only the *Impl() methods that you need. To override a *Impl() method:

  1. Find the *Impl() override in the app-specific reference. Copy that name, not the public API name.

  2. Declare the same method signature in CustomerAppTask.h under the private: section. Match the base *Impl() signature exactly.

  3. Implement the method in CustomerAppTask.cpp.

  4. Build the project.

If you implement the corresponding *Impl() method in CustomerAppTask, the application uses your implementation. Otherwise, it uses the Silicon Labs default implementation. All other methods automatically use their default implementations.

ClosureManager and CustomerAppManager#

The Closure app has a second CRTP override chain for its ClosureManager APIs. CustomerAppManager derives from ClosureManagerImpl<CustomerAppManager>. Declare and implement ClosureManager *Impl() overrides in CustomerAppManager, not in CustomerAppTask.

Use autogen/ClosureManagerImpl.h for the complete signatures. Methods that you do not override in CustomerAppManager use the Silicon Labs default ClosureManager implementation.

DataModelCallbacks and CustomerAppTask#

Code that previously resided in DataModelCallbacks.cpp before Matter Extension 2.9.2 now resides in AppTask.cpp. The Matter SDK's MatterPostAttributeChangeCallback is implemented in examples/platform/silabs/BaseApplication.cpp and forwards to AppTask::DMPostAttributeChangeCallback, which is defined in AppTask.cpp. You can customize this callback by overriding DMPostAttributeChangeCallbackImpl() in CustomerAppTask.

Forwarding into AppTask still goes through CRTP as described in How to Override APIs.

  • Methods that already exist in the AppTask — Customize them by overriding the matching *Impl() method in CustomerAppTask. Do not edit the AppTask.cpp for app-specific behavior.

  • New custom data model methods — Add them in CustomerAppTask directly. Do not add new application logic in autogenerated sources; those edits will not survive regeneration or project upgrades.

Sample Implementation#

The following example shows a minimal CustomerAppTask that overrides AppInitImpl() and ButtonEventHandlerImpl() from the lighting app implementation.

CustomerAppTask.h

#pragma once
#include "AppTaskImpl.h"

/**
 * Minimal AppTaskImpl-derived class. Override only the *Impl() methods you need;
 * add AppInitImpl(), GetAppTask(), and sAppTask as required by the CRTP base.
 */
class CustomerAppTask : public AppTaskImpl<CustomerAppTask>
{
public:
    static CustomerAppTask & GetAppTask() { return sAppTask; }

private:
    friend class AppTaskImpl<CustomerAppTask>;
    CHIP_ERROR AppInitImpl();
    void ButtonEventHandlerImpl(uint8_t button, uint8_t btnAction);
    static CustomerAppTask sAppTask;
};

CustomerAppTask.cpp

#include "CustomerAppTask.h"
#include "AppTask.h"
#include "AppConfig.h"
#include "AppEvent.h"
#include <platform/CHIPDeviceLayer.h>
#include <platform/silabs/platformAbstraction/SilabsPlatform.h>

using namespace ::chip::DeviceLayer::Silabs;

#define APP_FUNCTION_BUTTON 0
#define APP_LIGHT_SWITCH     1

CustomerAppTask CustomerAppTask::sAppTask;

AppTask & AppTask::GetAppTask()
{
    return CustomerAppTask::GetAppTask();
}

CHIP_ERROR CustomerAppTask::AppInitImpl()
{
    SILABS_LOG("CustomerAppTask: custom implementation (AppInitImpl)");
    CHIP_ERROR err = this->AppTask::AppInit();
    if (err == CHIP_NO_ERROR)
    {
        // Override the SDK default button handler registered in AppTask::AppInit().
        chip::DeviceLayer::Silabs::GetPlatform().SetButtonsCb(CustomerAppTask::ButtonEventHandler);
    }
    return err;
}

void CustomerAppTask::ButtonEventHandlerImpl(uint8_t button, uint8_t btnAction)
{
    SILABS_LOG("CustomerAppTask: custom implementation (ButtonEventHandlerImpl)");
    AppEvent button_event           = {};
    button_event.Type               = AppEvent::kEventType_Button;
    button_event.ButtonEvent.Action = btnAction;
    if (button == APP_LIGHT_SWITCH && btnAction == static_cast<uint8_t>(SilabsPlatform::ButtonAction::ButtonPressed))
    {
        button_event.Handler = LightActionEventHandler;
        AppTask::GetAppTask().PostEvent(&button_event);
    }
    else if (button == APP_FUNCTION_BUTTON)
    {
        button_event.Handler = BaseApplication::ButtonHandler;
        AppTask::GetAppTask().PostEvent(&button_event);
    }
}

Override API Reference#

The base API and implementation files are generated in the autogen/ directory. These files are regenerated whenever you upgrade the project to match the installed SDK version. Use them as a reference for overridable methods and app configuration. The app-specific pages in the following list describe each *Impl() override, its public API, and the default behavior.

File

Purpose

autogen/AppTaskImpl.h

Declarations of every overridable *Impl() method. Copy the signatures you need from here into CustomerAppTask.h.

autogen/AppTask.cpp

Silicon Labs provides the default AppTask implementation. Any *Impl() methods that you don't override use this implementation. Use it as a reference when customizing app behavior.

autogen/ClosureManagerImpl.h

Closure app only. Declarations of overridable ClosureManager *Impl() methods. Copy the signatures you need from here into CustomerAppManager.h.