diff --git a/sld250-matter-references/custom-matter-device.md b/sld250-matter-references/custom-matter-device.md index e6cc8be..81b915e 100644 --- a/sld250-matter-references/custom-matter-device.md +++ b/sld250-matter-references/custom-matter-device.md @@ -9,128 +9,7 @@ using Matter. ## Extending Base App Implementation -### CustomerAppTask - -To customize app behavior, override any Silicon Labs implemented API in `CustomerAppTask`. This example provides `CustomerAppTask.h` and `CustomerAppTask.cpp` for that purpose. The build system generates the base implementation and the complete set of overridable `*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 method to override in the base API. For more information, see [Override API reference](#override-api-reference). -2. Declare the same method signature in `CustomerAppTask.h` under the `private:` section. Match the base `*Impl()` signature exactly. - > **NOTE:** - > `*Impl()` overrides are non-static instance methods, even when the corresponding public dispatcher (for example, `ButtonEventHandler`) is static. -3. Implement the method in `CustomerAppTask.cpp`. -4. Build the project. If you implement the corresponding `*Impl()` method in `CustomerAppTask`, your implementation is used. Otherwise, the Silicon Labs default implementation is used. You only need to implement the methods that you want to customize. All other methods automatically use the default implementation. - -### DataModelCallbacks and CustomerAppTask - -What used to live in `DataModelCallbacks.cpp` before Matter Extension 2.9.1 now lives in `AppTask.cpp`. The -Matter SDK's `MatterPostAttributeChangeCallback` is implemented in -`examples/platform/silabs/BaseApplication.cpp` and forwards to -`AppTask::DMPostAttributeChangeCallback` (defined in `AppTask.cpp`), which you -can customize via `DMPostAttributeChangeCallbackImpl()` in `CustomerAppTask`. - -Forwarding into `AppTask` still goes through CRTP as in -[How to Override APIs](#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 shows a minimal example `CustomerAppTask` that overrides `AppInitImpl()` and `ButtonEventHandlerImpl()` from -the lighting app implementation. - -**CustomerAppTask.h** - -```cpp -#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 -{ -public: - static CustomerAppTask & GetAppTask() { return sAppTask; } - -private: - friend class AppTaskImpl; - CHIP_ERROR AppInitImpl(); - void ButtonEventHandlerImpl(uint8_t button, uint8_t btnAction); - static CustomerAppTask sAppTask; -}; -``` - -**CustomerAppTask.cpp** - -```cpp -#include "CustomerAppTask.h" -#include "AppTask.h" -#include "AppConfig.h" -#include "AppEvent.h" -#include -#include - -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(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 are generated into the `autogen/` directory. These files are regenerated whenever you upgrade the project and match the installed SDK version. Use them as a reference for overridable methods and app configuration. - -| 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. | +To customize app behavior through the overridable APIs exposed by each app, see [Matter API Reference](/matter/{build-docspace-version}/matter-api-reference/). ## Using Matter with Clusters @@ -186,7 +65,7 @@ through this function. The command can then be dissected using conditional logic to call the proper application functions based on the most recent command received. -Attribute changes route through `CustomerAppTask` and `DMPostAttributeChangeCallbackImpl()`. For more information, see [Extending Base App Implementation](#extending-base-app-implementation). +Attribute changes route through `CustomerAppTask` and `DMPostAttributeChangeCallbackImpl()`. For more information, see [Matter API Reference](/matter/{build-docspace-version}/matter-api-reference/). ## Adding a Cluster to a ZAP Configuration @@ -257,5 +136,3 @@ In order to use a custom cluster in an application, follow these steps: ``` For an example, see [Sample ZAP file](https://github.com/SiliconLabsSoftware/matter_extension/blob/v2.9.1/slc/apps/performance_test_app/thread/performance-test-app.zap) - Install the **Custom ZAP generation** component under **Silicon Labs Matter -> Stack** in the project's Component Editor. - - diff --git a/sld295-matter-api-reference/air-quality-sensor-app.md b/sld295-matter-api-reference/air-quality-sensor-app.md new file mode 100644 index 0000000..547e39a --- /dev/null +++ b/sld295-matter-api-reference/air-quality-sensor-app.md @@ -0,0 +1,14 @@ +# Air Quality Sensor Application Override APIs + +To override any of the following hooks, declare the corresponding `*Impl()` method in `CustomerAppTask.h` and implement it in `CustomerAppTask.cpp`. Ensure that the method signature matches the declaration in `autogen/AppTaskImpl.h`. + +## AppTask + +| Override | Public API | Default behavior | +|---|---|---| +| `AppInitImpl` | `AppInit` | Registers the button callback, configures the LCD UI, and initializes the air quality sensor. | +| `InitAirQualitySensorImpl` | `InitAirQualitySensor` | Creates the periodic sensor timer, initializes the sensor hardware when available, and starts sampling. | +| `GetAirQualityValueImpl` | `GetAirQualityValue` | Reads the value from the onboard air quality sensor. If the sensor is unavailable, returns a simulated value. | +| `ButtonEventHandlerImpl` | `ButtonEventHandler` | Routes function-button events to the base application handler. | +| `SensorTimerEventHandlerImpl` | `SensorTimerEventHandler` | Reads the sensor value and schedules an update to the Air Quality attribute. | +| `DMPostAttributeChangeCallbackImpl` | `DMPostAttributeChangeCallback` | Logs changes to the Identify attribute. | diff --git a/sld295-matter-api-reference/attributes.md b/sld295-matter-api-reference/attributes.md deleted file mode 100644 index 8535535..0000000 --- a/sld295-matter-api-reference/attributes.md +++ /dev/null @@ -1,44 +0,0 @@ -# Attribute - -Attributes represent the current state of a device. For instance if the device is on or off, the current temperature, or the current level of a dimmer. Attributes are defined in the cluster specification. - -## Attribute Changes - -When a ZCL attribute is updated in the data model, the framework invokes the post-attribute-change path. The Silicon Labs Matter stack routes this as follows: `MatterPostAttributeChangeCallback` in `BaseApplication.cpp` → `AppTask::DMPostAttributeChangeCallback` in `autogen/AppTask.cpp` → your optional `DMPostAttributeChangeCallbackImpl()` override in `CustomerAppTask`. - -For more information, see [Extending Base App Implementation](/matter/{build-docspace-version}/matter-references/custom-matter-device/#extending-base-app-implementation). - -If this callback is implemented by the device, it is informed of the attribute change. The device may react to the attribute change. For example, in `DMPostAttributeChangeCallback` function the in `AppTask.cpp` file ([onoff-plug-app/src](https://github.com/SiliconLabsSoftware/matter_sdk/blob/main/examples/onoff-plug-app/silabs/src/AppTask.cpp)), if you want to add a custom handler code to control an RGB LED when on/off attribute in the `On-Off` Cluster changes, implement the following in `DMPostAttributeChangeCallbackImpl` in `src/CustomerAppTask.cpp`: - -```cpp -void DMPostAttributeChangeCallbackImpl(const chip::app::ConcreteAttributePath & attributePath, - uint8_t type, - uint16_t size, - uint8_t * value) -{ - ClusterId clusterId = attributePath.mClusterId; - AttributeId attributeId = attributePath.mAttributeId; - ChipLogProgress(Zcl, "Cluster callback: " ChipLogFormatMEI, ChipLogValueMEI(clusterId)); - - if (clusterId == OnOff::Id && attributeId == OnOff::Attributes::OnOff::Id) - { - if (*value) - { // turn on LED - sl_led_turn_on((sl_led_t *)&sl_simple_rgb_pwm_led_rgb_led0); - } - else - {// turn off LED - sl_led_turn_off((sl_led_t *)&sl_simple_rgb_pwm_led_rgb_led0); - } - /* ----------- */ - } - - //... -} -``` - -## Header File - -This file contains the high level namespaces and constant definitions for Attributes. In Simplicity Studio, this will be generated in the autogen/zap-generated/ folder of the matter project. - -- [Attribute](https://github.com/SiliconLabs/matter_extension/blob/main/third_party/matter_sdk/zzz_generated/app-common/app-common/zap-generated/ids/Attributes.h) diff --git a/sld295-matter-api-reference/base-platform-app.md b/sld295-matter-api-reference/base-platform-app.md new file mode 100644 index 0000000..85b3257 --- /dev/null +++ b/sld295-matter-api-reference/base-platform-app.md @@ -0,0 +1,15 @@ +# Base Platform Application Override APIs + +To override any of the following hooks, declare the corresponding `*Impl()` method in `CustomerAppTask.h` and implement it in `CustomerAppTask.cpp`. Ensure that the method signature matches the declaration in `autogen/AppTaskImpl.h`. + +## AppTask + +| Override | Public API | Default behavior | +|---|---|---| +| `AppInitImpl` | `AppInit` | Registers the button callback, initializes the LED, and shows the demo UI or QR code when enabled. | +| `ButtonEventHandlerImpl` | `ButtonEventHandler` | Routes user-action button events to `ApplicationEventHandler` and function-button events to the base application handler. | +| `ApplicationEventHandlerImpl` | `ApplicationEventHandler` | Toggles the LED when the user-action button is pressed. | +| `OnEnterActiveModeImpl` | `OnEnterActiveMode` | Updates the demo UI when the ICD server enters active mode. Available when `CHIP_CONFIG_ENABLE_ICD_SERVER` is enabled. | +| `OnEnterIdleModeImpl` | `OnEnterIdleMode` | Updates the demo UI when the ICD server enters idle mode. Available when `CHIP_CONFIG_ENABLE_ICD_SERVER` is enabled. | +| `OnTransitionToIdleImpl` | `OnTransitionToIdle` | Logs the transition while the ICD server moves to idle mode. Available when `CHIP_CONFIG_ENABLE_ICD_SERVER` is enabled. | +| `OnICDModeChangeImpl` | `OnICDModeChange` | Logs changes between Short Idle Time (SIT) and Long Idle Time (LIT) operating modes. Available when `CHIP_CONFIG_ENABLE_ICD_SERVER` is enabled. | diff --git a/sld295-matter-api-reference/closure-app.md b/sld295-matter-api-reference/closure-app.md new file mode 100644 index 0000000..00341c0 --- /dev/null +++ b/sld295-matter-api-reference/closure-app.md @@ -0,0 +1,38 @@ +# Closure Application Override APIs + +To override any of the following AppTask hooks, declare the corresponding `*Impl()` method in `CustomerAppTask.h` and implement it in `CustomerAppTask.cpp`. Ensure that the method signature matches the declaration in `autogen/AppTaskImpl.h`. + +## AppTask + +| Override | Public API | Default behavior | +|---|---|---| +| `AppInitImpl` | `AppInit` | Registers the button callback, initializes the display, and initializes Closure Manager. | +| `ButtonEventHandlerImpl` | `ButtonEventHandler` | Routes closure button presses to `ClosureButtonActionEventHandler` and function button events to the base application handler. | +| `ClosureButtonActionEventHandlerImpl` | `ClosureButtonActionEventHandler` | Stops motion if a closure action is in progress; otherwise, it starts a MoveTo toward the opposite position. | +| `DMPostAttributeChangeCallbackImpl` | `DMPostAttributeChangeCallback` | Logs Identify attribute changes. | +| `DMClosureControlClusterAttributeChangedCallbackImpl` | `DMClosureControlClusterAttributeChangedCallback` | Refreshes the UI when Closure Control `MainState` or `OverallCurrentState` changes. | +| `DMClosureDimensionClusterAttributeChangedCallbackImpl` | `DMClosureDimensionClusterAttributeChangedCallback` | Logs Closure Dimension attribute changes. | + +## ClosureManager + +These APIs use the Closure app's separate manager override chain. Declare and +implement the corresponding `*Impl()` methods in `CustomerAppManager`, which +derives from `ClosureManagerImpl`. Use +`autogen/ClosureManagerImpl.h` for exact signatures. Do not place these +overrides in `CustomerAppTask`. + +| Override | Public API | Default behavior | +|---|---|---| +| `InitImpl` | `Init` | Initializes the closure timer, closure endpoints, and panel endpoints. | +| `OnCalibrateCommandImpl` | `OnCalibrateCommand` | Validates and starts an asynchronous closure calibration. | +| `OnMoveToCommandImpl` | `OnMoveToCommand` | Validates a MoveTo command and sets overall panel targets. | +| `OnStopCommandImpl` | `OnStopCommand` | Stops the active closure operation and completes the stop action. | +| `OnSetTargetCommandImpl` | `OnSetTargetCommand` | Validates a SetTarget command and sets the selected panel target. | +| `OnStepCommandImpl` | `OnStepCommand` | Validates a Step command and sets the selected panel step target. | +| `HandleClosureActionCompleteImpl` | `HandleClosureActionComplete` | Finalizes a completed calibrate, stop, move, or unlatch action. | +| `HandleClosureMotionActionImpl` | `HandleClosureMotionAction` | Advances closure panels toward their target positions. | +| `HandleClosureUnlatchActionImpl` | `HandleClosureUnlatchAction` | Updates closure and panel states for an unlatch action. | +| `GetPanelNextPositionImpl` | `GetPanelNextPosition` | Calculates the next position between a panel's current and target positions. | +| `HandlePanelSetTargetActionImpl` | `HandlePanelSetTargetAction` | Advances one panel toward a SetTarget position. | +| `HandlePanelUnlatchActionImpl` | `HandlePanelUnlatchAction` | Updates one panel for an unlatch action. | +| `HandlePanelStepActionImpl` | `HandlePanelStepAction` | Applies a Step action to one panel. | diff --git a/sld295-matter-api-reference/cluster-implementation.md b/sld295-matter-api-reference/cluster-implementation.md deleted file mode 100644 index 3ef31f5..0000000 --- a/sld295-matter-api-reference/cluster-implementation.md +++ /dev/null @@ -1,7 +0,0 @@ -# Cluster Implementation on Matter Core - -This has the high level implementation of all the clusters present in Matter. - -## References - -[Cluster Implementation](https://github.com/SiliconLabs/matter_extension/tree/main/third_party/matter_sdk/src/app/clusters) diff --git a/sld295-matter-api-reference/cluster.md b/sld295-matter-api-reference/cluster.md deleted file mode 100644 index b7747aa..0000000 --- a/sld295-matter-api-reference/cluster.md +++ /dev/null @@ -1,16 +0,0 @@ -# Cluster - -Each Cluster is either a Client, Server, or both​. A Cluster is a collection of Attributes and Commands that are logically related. - -- Client: Stateless. Interacts with a server cluster by Reading, Writing, or Subscribing to an attribute​ -- Server: Holds the State of Data or Attribute - -Clusters contain: Attributes, Events, Commands​. - -For more details see: [Matter Data Model](../sld288-matter-fundamentals-data-model/index.md). - -## Header File - -The header file below contains namespaces and IDs of Clusters. In Simplicity Studio, this will be generated in the autogen/zap-generated/ folder of the matter project. - -- [Cluster](https://github.com/project-chip/connectedhomeip/blob/master/zzz_generated/app-common/app-common/zap-generated/ids/Clusters.h) \ No newline at end of file diff --git a/sld295-matter-api-reference/commands.md b/sld295-matter-api-reference/commands.md deleted file mode 100644 index 247c5b4..0000000 --- a/sld295-matter-api-reference/commands.md +++ /dev/null @@ -1,11 +0,0 @@ -# Commands - -Commmands are used to invoke a particular action. For instance an endpoint with the Doorlock client cluster can send an 'Invoke UnlockDoor' command to the Doorlock server to ask it to change the "LockState" attribute to unlocked. When validated and processed by the Doorlock server, this will then Unlock the door. - -## Header File - -This file contains the high level namespaces and constant definitions for Commands. In Simplicity Studio, this will be generated in the autogen/zap-generated/ folder of the matter project. - -- [Commands](https://github.com/SiliconLabs/matter_extension/blob/main/third_party/matter_sdk/zzz_generated/app-common/app-common/zap-generated/ids/Commands.h) - -The folder [```src/app```](https://github.com/SiliconLabs/matter_extension/tree/main/third_party/matter_sdk/src/app) contains several files related to the implementation of commands including interfaces, senders and handlers. diff --git a/sld295-matter-api-reference/datamodeltypes.md b/sld295-matter-api-reference/datamodeltypes.md deleted file mode 100644 index 43008cd..0000000 --- a/sld295-matter-api-reference/datamodeltypes.md +++ /dev/null @@ -1,15 +0,0 @@ -# Data Models - -The Data Model defines namespaces for endpoints, clusters, and attributes in the application. From a developer standpoint, this is handled by the ZAP tool. For Multi-Fabric devices, the data model is shared between the Fabrics. - -For a review of what the Matter Data Model is and how it is used, see the [Matter Data Model](../sld288-matter-fundamentals-data-model/index.md). - -## APIs - -The directory [```/src/app/util```](https://github.com/SiliconLabs/matter_extension/tree/main/third_party/matter_sdk/src/app/util) contains various utilities and some of the external API headers for interacting with the data model layer. In particular, the various data type definitions and the public APIs to the data model are declared in the headers here. - -## Header File - -This file contains definitions and constants for various data types and identifiers used in Matter. - -- [DataModelTypes](https://github.com/SiliconLabs/matter_extension/blob/main/third_party/matter_sdk/src/lib/core/DataModelTypes.h) diff --git a/sld295-matter-api-reference/event.md b/sld295-matter-api-reference/event.md deleted file mode 100644 index d2996b9..0000000 --- a/sld295-matter-api-reference/event.md +++ /dev/null @@ -1,13 +0,0 @@ -# Event - -Events are records of past state transitions such as a light device's on-off attribute changing from on to off. - -The autogenerated file [```include/AppEvent.h```](https://github.com/SiliconLabs/matter_extension/blob/main/third_party/matter_sdk/examples/template/silabs/include/AppEvent.h) contains the definition of the event object used by the application. It includes the event types, the structures for each event, and event handler. - -Custom event posting and handlers are overridden in the `CustomerAppTask` file, not in `autogen/AppTask.cpp`. - -## Header File - -This file contains the high level namespaces and constant definitions for Events. In Simplicity Studio, this will be generated in the autogen/zap-generated/ folder of the matter project. - -- [Event](https://github.com/SiliconLabs/matter_extension/blob/main/third_party/matter_sdk/zzz_generated/app-common/app-common/zap-generated/ids/Events.h) diff --git a/sld295-matter-api-reference/evse-app.md b/sld295-matter-api-reference/evse-app.md new file mode 100644 index 0000000..c1bb845 --- /dev/null +++ b/sld295-matter-api-reference/evse-app.md @@ -0,0 +1,12 @@ +# EVSE Application Override APIs + +To override any of the following hooks, declare the corresponding `*Impl()` method in `CustomerAppTask.h` and implement it in `CustomerAppTask.cpp`. Ensure that the method signature matches the declaration in `autogen/AppTaskImpl.h`. + +## AppTask + +| Override | Public API | Default behavior | +|---|---|---| +| `AppInitImpl` | `AppInit` | Registers the button callback, runs `ApplicationInit`, and registers EVSE test event triggers when enabled. | +| `ApplicationInitImpl` | `ApplicationInit` | Initializes the EVSE application and energy management LED. | +| `ButtonEventHandlerImpl` | `ButtonEventHandler` | Routes EVSE control button presses to `EnergyManagementActionEventHandler` and function button events to the base application handler. | +| `EnergyManagementActionEventHandlerImpl` | `EnergyManagementActionEventHandler` | Logs the control button event. By default, the handler does not start a charging action. | diff --git a/sld295-matter-api-reference/fan-control-app.md b/sld295-matter-api-reference/fan-control-app.md new file mode 100644 index 0000000..abae910 --- /dev/null +++ b/sld295-matter-api-reference/fan-control-app.md @@ -0,0 +1,18 @@ +# Fan Control Application Override APIs + +To override any of the following hooks, declare the corresponding `*Impl()` method in `CustomerAppTask.h` and implement it in `CustomerAppTask.cpp`. Ensure that the method signature matches the declaration in `autogen/AppTaskImpl.h`. + +## AppTask + +| Override | Public API | Default behavior | +|---|---|---| +| `AppInitImpl` | `AppInit` | Registers the button callback, initializes fan control, and updates the display. | +| `InitFanControlImpl` | `InitFanControl` | Installs Fan Control delegates, initializes the LED, and applies the initial attribute state. | +| `HandleStepImpl` | `HandleStep` | Handles a Fan Control Step command by updating speed or percentage settings. | +| `ButtonEventHandlerImpl` | `ButtonEventHandler` | Routes function button events to the base application handler. | +| `FanUiUpdateEventHandlerImpl` | `FanUiUpdateEventHandler` | Updates the fan LED and, when enabled, the display. | +| `HandleFanModeChangeImpl` | `HandleFanModeChange` | Synchronizes speed and percentage settings after a change to FanMode. | +| `DeriveFanModeFromPercentImpl` | `DeriveFanModeFromPercent` | Maps PercentSetting to Off, Low, Medium, or High fan mode. | +| `HandlePercentSettingChangeImpl` | `HandlePercentSettingChange` | Updates PercentCurrent after PercentSetting changes. | +| `HandleSpeedSettingChangeImpl` | `HandleSpeedSettingChange` | Updates SpeedCurrent after SpeedSetting changes. | +| `DMPostAttributeChangeCallbackImpl` | `DMPostAttributeChangeCallback` | Applies changes to the Fan Control PercentSetting, SpeedSetting, and FanMode attributes and logs Identify changes. | diff --git a/sld295-matter-api-reference/index.md b/sld295-matter-api-reference/index.md index a3d6fde..ee8017a 100644 --- a/sld295-matter-api-reference/index.md +++ b/sld295-matter-api-reference/index.md @@ -1,24 +1,188 @@ # Matter API Reference -This section covers the various Application Programming Interfaces (APIs) that a developer might use when developing a new Matter Application. +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. -- [**DataModel**](./datamodeltypes.md) -- [**Attributes**](./attributes.md) -- [**Clusters**](./cluster.md) -- [**Commands**](./commands.md) -- [**Events**](./event.md) -- [**Cluster Implementation**](./cluster-implementation.md) +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](#extending-base-app-implementation) +for the implementation workflow. -## Application APIs +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. -For information about customizing app behavior with `CustomerAppTask`, see [Extending Base App Implementation](/matter/{build-docspace-version}/matter-references/custom-matter-device/#extending-base-app-implementation). +## Extending Base App Implementation -### Initialization +### CustomerAppTask -Default initialization is included in `autogen/AppTask.cpp`. Override `AppInitImpl()` and other `*Impl()` hooks in `src/CustomerAppTask.cpp` to customize behavior. +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`. +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.1 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](#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** ```cpp -CHIP_ERROR AppTask::Init() +#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 +{ +public: + static CustomerAppTask & GetAppTask() { return sAppTask; } + +private: + friend class AppTaskImpl; + CHIP_ERROR AppInitImpl(); + void ButtonEventHandlerImpl(uint8_t button, uint8_t btnAction); + static CustomerAppTask sAppTask; +}; ``` -The `AppTask.cpp` file may also contain event handlers and helper code useful to the application. +**CustomerAppTask.cpp** + +```cpp +#include "CustomerAppTask.h" +#include "AppTask.h" +#include "AppConfig.h" +#include "AppEvent.h" +#include +#include + +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(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`. | + +- [Air Quality Sensor](./air-quality-sensor-app.md) +- [Base Platform](./base-platform-app.md) +- [Closure](./closure-app.md) +- [EVSE](./evse-app.md) +- [Fan Control](./fan-control-app.md) +- [Light Switch](./light-switch-app.md) +- [Lighting](./lighting-app.md) +- [Lock](./lock-app.md) +- [Multi-Sensor](./multi-sensor-app.md) +- [On/Off Plug](./onoff-plug-app.md) +- [Oven](./oven-app.md) +- [Rangehood](./rangehood-app.md) +- [Refrigerator](./refrigerator-app.md) +- [Thermostat](./thermostat-app.md) diff --git a/sld295-matter-api-reference/light-switch-app.md b/sld295-matter-api-reference/light-switch-app.md new file mode 100644 index 0000000..b94d76c --- /dev/null +++ b/sld295-matter-api-reference/light-switch-app.md @@ -0,0 +1,15 @@ +# Light Switch Application Override APIs + +To override any of the following hooks, declare the corresponding `*Impl()` method in `CustomerAppTask.h` and implement it in `CustomerAppTask.cpp`. Ensure that the method signature matches the declaration in `autogen/AppTaskImpl.h`. + +## AppTask + +| Override | Public API | Default behavior | +|---|---|---| +| `AppInitImpl` | `AppInit` | Registers the button callback, initializes the light switch endpoints, and creates the level control long press timer. | +| `InitLightSwitchImpl` | `InitLightSwitch` | Sets the light switch and generic switch endpoints and schedules Binding Manager initialization. | +| `ButtonEventHandlerImpl` | `ButtonEventHandler` | Converts hardware button activity into application button events. | +| `AppEventHandlerImpl` | `AppEventHandler` | Translates application button events into On/Off and Level Control binding actions. | +| `InitBindingHandlerImpl` | `InitBindingHandler` | Initializes the Binding Manager and registers its command and context release handlers. | +| `LightSwitchChangedHandlerImpl` | `LightSwitchChangedHandler` | Sends a pending On/Off or Level Control command through a matching bound peer or group. | +| `DMPostAttributeChangeCallbackImpl` | `DMPostAttributeChangeCallback` | Logs Identify attribute changes. | diff --git a/sld295-matter-api-reference/lighting-app.md b/sld295-matter-api-reference/lighting-app.md new file mode 100644 index 0000000..146db6e --- /dev/null +++ b/sld295-matter-api-reference/lighting-app.md @@ -0,0 +1,16 @@ +# Lighting Application Override APIs + +To override any of the following hooks, declare the corresponding `*Impl()` method in `CustomerAppTask.h` and implement it in `CustomerAppTask.cpp`. Ensure that the method signature matches the declaration in `autogen/AppTaskImpl.h`. + +## AppTask + +| Override | Public API | Default behavior | +|---|---|---| +| `AppInitImpl` | `AppInit` | Registers the button callback, initializes the light, LED, and display. | +| `InitLightImpl` | `InitLight` | Creates the off-effect timer and loads the OnOff attribute and, when enabled, the RGB color attributes from the cluster state. | +| `ButtonEventHandlerImpl` | `ButtonEventHandler` | Routes light action and function button events. | +| `OnTriggerOffWithEffectImpl` | `OnTriggerOffWithEffect` | Selects and starts the timer for an OffWithEffect command. | +| `LightActionEventHandlerImpl` | `LightActionEventHandler` | Toggles the light for a button event and synchronizes the OnOff attribute. | +| `LightTimerEventHandlerImpl` | `LightTimerEventHandler` | Posts the event that completes an off effect. | +| `LightControlEventHandlerImpl` | `LightControlEventHandler` | Applies level and color control events to the RGB LED. Available when `SL_MATTER_RGB_LED_ENABLED` is enabled. | +| `DMPostAttributeChangeCallbackImpl` | `DMPostAttributeChangeCallback` | Routes OnOff, Level Control, Color Control, and Identify attribute changes. | diff --git a/sld295-matter-api-reference/lock-app.md b/sld295-matter-api-reference/lock-app.md new file mode 100644 index 0000000..072ec99 --- /dev/null +++ b/sld295-matter-api-reference/lock-app.md @@ -0,0 +1,33 @@ +# Lock Application Override APIs + +To override any of the following hooks, declare the corresponding `*Impl()` method in `CustomerAppTask.h` and implement it in `CustomerAppTask.cpp`. Ensure that the method signature matches the declaration in `autogen/AppTaskImpl.h`. + +## AppTask + +| Override | Public API | Default behavior | +|---|---|---| +| `AppInitImpl` | `AppInit` | Registers the button callback, initializes the lock, and synchronizes the Door Lock cluster state. | +| `InitLockImpl` | `InitLock` | Initializes the lock state, credential storage, actuator timers, and the Door Lock server. | +| `ButtonEventHandlerImpl` | `ButtonEventHandler` | Routes lock-action and function-button events. | +| `LockButtonActionHandlerImpl` | `LockButtonActionHandler` | Converts a lock-button press into a lock or unlock action. | +| `UnlatchCallbackImpl` | `UnlatchCallback` | Schedules the transition from the unlatched state to the unlocked state when the unlatch timer expires. | +| `ActuatorMovementEventHandlerImpl` | `ActuatorMovementEventHandler` | Completes the actuator movement, updates the Door Lock state, and processes any pending request. | +| `LockActionEventHandlerImpl` | `LockActionEventHandler` | Starts the lock, unlock, or unlatch action carried by an application event. | +| `LockRequestEventHandlerImpl` | `LockRequestEventHandler` | Drains a staged Door Lock request and passes it to the application task. | +| `HandleLockRequestOnAppTaskImpl` | `HandleLockRequestOnAppTask` | Queues, completes, or starts a Door Lock request according to actuator state. | +| `UnlockAfterUnlatchImpl` | `UnlockAfterUnlatch` | Changes an unlatched lock to the unlocked state and stages an unlock request. | +| `DMPostAttributeChangeCallbackImpl` | `DMPostAttributeChangeCallback` | Responds to Door Lock `LockState` attribute changes. | +| `DMDoorLockOnDoorLockCommandImpl` | `DMDoorLockOnDoorLockCommand` | Validates a Lock command and stages a request for the locked state. | +| `DMDoorLockOnDoorUnlockCommandImpl` | `DMDoorLockOnDoorUnlockCommand` | Validates an Unlock command and stages an unlock or unlatch request, depending on Unbolt support. | +| `DMDoorLockOnDoorUnboltCommandImpl` | `DMDoorLockOnDoorUnboltCommand` | Validates an Unbolt command and stages a request for the unlocked state. | +| `DMDoorLockGetCredentialImpl` | `DMDoorLockGetCredential` | Retrieves credential data for the Door Lock server. | +| `DMDoorLockSetCredentialImpl` | `DMDoorLockSetCredential` | Persists credential data for the Door Lock server. | +| `DMDoorLockGetUserImpl` | `DMDoorLockGetUser` | Retrieves user data for the Door Lock server. | +| `DMDoorLockSetUserImpl` | `DMDoorLockSetUser` | Persists user data for the Door Lock server. | +| `DMDoorLockGetWeekDayScheduleImpl` | `DMDoorLockGetWeekDaySchedule` | Retrieves a user's weekday schedule. | +| `DMDoorLockSetWeekDayScheduleImpl` | `DMDoorLockSetWeekDaySchedule` | Persists a user's weekday schedule. | +| `DMDoorLockGetYearDayScheduleImpl` | `DMDoorLockGetYearDaySchedule` | Retrieves a user's year-day schedule. | +| `DMDoorLockSetYearDayScheduleImpl` | `DMDoorLockSetYearDaySchedule` | Persists a user's year-day schedule. | +| `DMDoorLockGetHolidayScheduleImpl` | `DMDoorLockGetHolidaySchedule` | Retrieves a holiday schedule. | +| `DMDoorLockSetHolidayScheduleImpl` | `DMDoorLockSetHolidaySchedule` | Persists a holiday schedule. | +| `DMDoorLockOnAutoRelockImpl` | `DMDoorLockOnAutoRelock` | Starts a lock action when automatic relocking occurs. | diff --git a/sld295-matter-api-reference/multi-sensor-app.md b/sld295-matter-api-reference/multi-sensor-app.md new file mode 100644 index 0000000..5ce5882 --- /dev/null +++ b/sld295-matter-api-reference/multi-sensor-app.md @@ -0,0 +1,18 @@ +# Multi Sensor Application Override APIs + +To override any of the following hooks, declare the corresponding `*Impl()` method in `CustomerAppTask.h` and implement it in `CustomerAppTask.cpp`. Ensure that the method signature matches the declaration in `autogen/AppTaskImpl.h`. + +## AppTask + +| Override | Public API | Default behavior | +|---|---|---| +| `AppInitImpl` | `AppInit` | Registers the button callback, initializes the occupancy LED and display, and starts the sensor manager. | +| `InitSensorManagerImpl` | `InitSensorManager` | Initializes the sensor clusters, registers the attribute listener, and schedules periodic sampling. | +| `GetTemperatureAndHumidityImpl` | `GetTemperatureAndHumidity` | Reads the Si70xx sensor if it is present; otherwise, provides simulated temperature and humidity values. | +| `ButtonEventHandlerImpl` | `ButtonEventHandler` | Routes events from the function and occupancy-toggle buttons. | +| `ProcessButtonEventImpl` | `ProcessButtonEvent` | Toggles the Occupancy attribute for an application button event. | +| `TriggerSensorActionImpl` | `TriggerSensorAction` | Samples temperature and humidity and updates their measured value attributes. | +| `OccupancyAttributeUpdateEventImpl` | `OccupancyAttributeUpdateEvent` | Updates the occupancy LED and display after the Occupancy attribute changes. | +| `SensorAttributeUpdateEventImpl` | `SensorAttributeUpdateEvent` | Updates the display after a temperature or humidity change. | +| `OnAttributeChangedImpl` | `OnAttributeChanged` | Converts Occupancy, Temperature Measurement, and Relative Humidity Measurement changes into application events. | +| `DMPostAttributeChangeCallbackImpl` | `DMPostAttributeChangeCallback` | Logs Identify attribute changes. | diff --git a/sld295-matter-api-reference/onoff-plug-app.md b/sld295-matter-api-reference/onoff-plug-app.md new file mode 100644 index 0000000..7fbe79a --- /dev/null +++ b/sld295-matter-api-reference/onoff-plug-app.md @@ -0,0 +1,13 @@ +# On/Off Plug Application Override APIs + +To override any of the following hooks, declare the corresponding `*Impl()` method in `CustomerAppTask.h` and implement it in `CustomerAppTask.cpp`. Ensure that the method signature matches the declaration in `autogen/AppTaskImpl.h`. + +## AppTask + +| Override | Public API | Default behavior | +|---|---|---| +| `AppInitImpl` | `AppInit` | Registers the button callback and initializes the plug, LED, and display. | +| `InitPlugImpl` | `InitPlug` | Reads the OnOff attribute into the plug On/Off state. | +| `ButtonEventHandlerImpl` | `ButtonEventHandler` | Routes plug-action and function-button events. | +| `OnOffActionEventHandlerImpl` | `OnOffActionEventHandler` | Toggles the plug and synchronizes its OnOff attribute for a button event. | +| `DMPostAttributeChangeCallbackImpl` | `DMPostAttributeChangeCallback` | Handles OnOff, Level Control, and Identify attribute changes. | diff --git a/sld295-matter-api-reference/oven-app.md b/sld295-matter-api-reference/oven-app.md new file mode 100644 index 0000000..84ee379 --- /dev/null +++ b/sld295-matter-api-reference/oven-app.md @@ -0,0 +1,23 @@ +# Oven Application Override APIs + +To override any of the following hooks, declare the corresponding `*Impl()` method in `CustomerAppTask.h` and implement it in `CustomerAppTask.cpp`. Ensure that the method signature matches the declaration in `autogen/AppTaskImpl.h`. + +## AppTask + +| Override | Public API | Default behavior | +|---|---|---| +| `AppInitImpl` | `AppInit` | Registers the button callback and initializes the oven, connectivity handler, cooktop LED, and display. | +| `ButtonEventHandlerImpl` | `ButtonEventHandler` | Routes oven-action and function-button events. | +| `OvenButtonHandlerImpl` | `OvenButtonHandler` | Converts an oven button press into a cooktop on/off action. | +| `OvenActionHandlerImpl` | `OvenActionHandler` | Applies an oven or cooktop action and updates the application UI. | +| `ConnectivityEventHandlerImpl` | `ConnectivityEventHandler` | Propagates the cooktop off state after DNS-SD initialization completes. | +| `InitBindingHandlerImpl` | `InitBindingHandler` | Initializes the Binding Manager and registers its command and context release handlers. | +| `CookTopBindingPropagateStateImpl` | `CookTopBindingPropagateState` | Notifies bound OnOff and Fan Control clusters of the cooktop state. | +| `BoundDeviceChangedHandlerImpl` | `BoundDeviceChangedHandler` | Writes the pending cooktop state to a matching bound OnOff or Fan Control peer. | +| `DMPostAttributeChangeCallbackImpl` | `DMPostAttributeChangeCallback` | Routes OnOff changes and observes Temperature Control and Identify changes. | +| `OnAttributeChangedImpl` | `OnAttributeChanged` | Converts an Oven Mode `CurrentMode` change into an application event. | +| `DMOvenModeClusterInitCallbackImpl` | `DMOvenModeClusterInitCallback` | Performs no application-specific action by default. | +| `DMOvenModeClusterShutdownCallbackImpl` | `DMOvenModeClusterShutdownCallback` | Performs no application-specific action by default. | +| `InitOvenImpl` | `InitOven` | Initializes the oven endpoints, delegates, binding, supported levels, and initial cluster state. | +| `OnOffAttributeChangeHandlerImpl` | `OnOffAttributeChangeHandler` | Synchronizes the cooktop and cooking-surface states after a change to the OnOff attribute. | +| `IsTransitionBlockedImpl` | `IsTransitionBlocked` | Returns true if the requested Oven Mode transition is in the blocked-transition list. | diff --git a/sld295-matter-api-reference/rangehood-app.md b/sld295-matter-api-reference/rangehood-app.md new file mode 100644 index 0000000..3c9d702 --- /dev/null +++ b/sld295-matter-api-reference/rangehood-app.md @@ -0,0 +1,14 @@ +# Rangehood Application Override APIs + +To override any of the following hooks, declare the corresponding `*Impl()` method in `CustomerAppTask.h` and implement it in `CustomerAppTask.cpp`. Ensure that the method signature matches the declaration in `autogen/AppTaskImpl.h`. + +## AppTask + +| Override | Public API | Default behavior | +|---|---|---| +| `AppInitImpl` | `AppInit` | Registers the button callback, initializes the rangehood, and updates the display. | +| `InitRangeHoodImpl` | `InitRangeHood` | Initializes the extractor hood endpoint and sets the light LED based on the cluster state. | +| `ButtonEventHandlerImpl` | `ButtonEventHandler` | Routes fan-control and function-button events. | +| `ActionTriggerHandlerImpl` | `ActionTriggerHandler` | Applies light on/off actions and refreshes the UI when the fan mode changes. | +| `FanControlButtonHandlerImpl` | `FanControlButtonHandler` | Toggles the fan mode in response to a button press. | +| `DMPostAttributeChangeCallbackImpl` | `DMPostAttributeChangeCallback` | Routes attribute changes from the Fan Control and On/Off clusters and monitors attribute changes from the Identify cluster. | diff --git a/sld295-matter-api-reference/refrigerator-app.md b/sld295-matter-api-reference/refrigerator-app.md new file mode 100644 index 0000000..068fa60 --- /dev/null +++ b/sld295-matter-api-reference/refrigerator-app.md @@ -0,0 +1,18 @@ +# Refrigerator Application Override APIs + +To override any of the following hooks, declare the corresponding `*Impl()` method in `CustomerAppTask.h` and implement it in `CustomerAppTask.cpp`. Ensure that the method signature matches its declaration in `autogen/AppTaskImpl.h`. The public `Init()` method maps to `CabinetModeInitImpl()` rather than `InitImpl()`. + +## AppTask + +| Override | Public API | Default behavior | +|---|---|---| +| `AppInitImpl` | `AppInit` | Registers the button callback and initializes the refrigerator. | +| `InitRefrigeratorImpl` | `InitRefrigerator` | Configures the refrigerator endpoint composition and semantic tags, and initializes the Temperature Control delegate. | +| `ButtonEventHandlerImpl` | `ButtonEventHandler` | Routes function-button events to the base application handler. | +| `DMPostAttributeChangeCallbackImpl` | `DMPostAttributeChangeCallback` | Handles attribute changes from the Refrigerator Alarm and Temperature Control clusters and monitors attribute changes from the Identify cluster. | +| `CabinetModeClusterInitImpl` | `CabinetModeClusterInit` | Constructs and initializes a `ModeBase::Instance` for the Cabinet Mode cluster on the refrigerator endpoint. | +| `CabinetModeInitImpl` | `Init` | Returns a success status. The Cabinet Mode delegate requires no additional initialization by default. | +| `HandleChangeToModeImpl` | `HandleChangeToMode` | Accepts the requested Cabinet Mode unless the request is for a direct transition between Normal and Rapid Freeze. | +| `GetModeLabelByIndexImpl` | `GetModeLabelByIndex` | Returns the supported Cabinet Mode label at the specified index. | +| `GetModeValueByIndexImpl` | `GetModeValueByIndex` | Returns the supported Cabinet Mode value at the specified index. | +| `GetModeTagsByIndexImpl` | `GetModeTagsByIndex` | Returns the semantic tags associated with the supported Cabinet Mode at the specified index. | diff --git a/sld295-matter-api-reference/thermostat-app.md b/sld295-matter-api-reference/thermostat-app.md new file mode 100644 index 0000000..b9e8f4d --- /dev/null +++ b/sld295-matter-api-reference/thermostat-app.md @@ -0,0 +1,17 @@ +# Thermostat Application Override APIs + +To override any of the following hooks, declare the corresponding `*Impl()` method in `CustomerAppTask.h` and implement it in `CustomerAppTask.cpp`. Ensure that the method signature matches the declaration in `autogen/AppTaskImpl.h`. + +## AppTask + +| Override | Public API | Default behavior | +|---|---|---| +| `AppInitImpl` | `AppInit` | Registers the button callback, sets the LCD UI, and initializes the thermostat. | +| `InitThermostatImpl` | `InitThermostat` | Initializes the sensor, UI, and periodic temperature sampling. | +| `InitSensorImpl` | `InitSensor` | Initializes the hardware temperature sensor if it is present. | +| `GetTemperatureImpl` | `GetTemperature` | Reads the Si70xx sensor if it is present; otherwise, provides a simulated temperature. | +| `ButtonEventHandlerImpl` | `ButtonEventHandler` | Routes function-button events to the base application handler. | +| `SensorTimerEventHandlerImpl` | `SensorTimerEventHandler` | Posts an application event to update the temperature when the sensor timer expires. | +| `TemperatureUpdateEventHandlerImpl` | `TemperatureUpdateEventHandler` | Samples the temperature and updates the Thermostat `LocalTemperature` attribute. | +| `DMPostAttributeChangeCallbackImpl` | `DMPostAttributeChangeCallback` | Handles attribute changes from the Thermostat cluster and monitors attribute changes from the Identify cluster. | +| `DMThermostatClusterInitImpl` | `DMThermostatClusterInit` | Installs the default Thermostat delegate on an endpoint. | diff --git a/sld57-matter-landing-page/index.md b/sld57-matter-landing-page/index.md index e1aa768..7133347 100644 --- a/sld57-matter-landing-page/index.md +++ b/sld57-matter-landing-page/index.md @@ -31,7 +31,7 @@ Want to get a Matter application up and running quickly? Here's a high-level ove 4. **[Optional] Customize Matter App Behavior and Logic** - Use Project Configurator and other Studio tools to customize your app logic: [Developing with Project Configurator](https://docs.silabs.com/ssv6ug/latest/ssv6-configure-project/) - - Customize app behavior in `CustomerAppTask` and `autogen/AppTask.cpp`. For more information, see [Extending Base App Implementation](/matter/{build-docspace-version}/matter-references/custom-matter-device/#extending-base-app-implementation). + - Customize app behavior in `CustomerAppTask` and `autogen/AppTask.cpp`. For more information, see [Matter API Reference](/matter/{build-docspace-version}/matter-api-reference/). - Follow documentation to develop a custom matter device with ZAP and corresponding callbacks: [Custom Matter Device Development](/matter/{build-docspace-version}/matter-references/custom-matter-device) 5. **Build and Flash** diff --git a/sld601-matter-application-development/matter-application-cluster-logic.md b/sld601-matter-application-development/matter-application-cluster-logic.md index 279c1c6..b843538 100644 --- a/sld601-matter-application-development/matter-application-cluster-logic.md +++ b/sld601-matter-application-development/matter-application-cluster-logic.md @@ -61,7 +61,7 @@ Additionally, a corresponding component is automatically added to your project. ## Step 4: Add Application Logic -For information about customizing app behavior, see [Extending Base App Implementation](/matter/{build-docspace-version}/matter-references/custom-matter-device/#extending-base-app-implementation). +For information about customizing app behavior, see [Matter API Reference](/matter/{build-docspace-version}/matter-api-reference/). Application logic centers on AppTask: @@ -140,4 +140,4 @@ Once the custom Door Lock node is successfully commissioned to the network, you mattertool onoff read on-off 1 ``` -Replace with the actual node ID assigned to your device during commissioning. \ No newline at end of file +Replace with the actual node ID assigned to your device during commissioning. diff --git a/sld601-matter-application-development/matter-event-timer-guide.md b/sld601-matter-application-development/matter-event-timer-guide.md index 02ca399..37ff358 100644 --- a/sld601-matter-application-development/matter-event-timer-guide.md +++ b/sld601-matter-application-development/matter-event-timer-guide.md @@ -5,7 +5,7 @@ The Matter event handler uses the FreeRTOS queue to transport a message from the producer to the consumer area. Events can be used to create asynchronous message processing or inter-task communication. -For information about customizing app behavior, see [Extending Base App Implementation](/matter/{build-docspace-version}/matter-references/custom-matter-device/#extending-base-app-implementation). +For information about customizing app behavior, see [Matter API Reference](/matter/{build-docspace-version}/matter-api-reference/). Steps to make an event work: diff --git a/sld601-matter-application-development/matter-scenes-quick-start-guide.md b/sld601-matter-application-development/matter-scenes-quick-start-guide.md index 5d719e9..a6883ce 100644 --- a/sld601-matter-application-development/matter-scenes-quick-start-guide.md +++ b/sld601-matter-application-development/matter-scenes-quick-start-guide.md @@ -166,7 +166,7 @@ public: ### Step 3 Implement Callbacks -For information about customizing app behavior, see [Extending Base App Implementation](/matter/{build-docspace-version}/matter-references/custom-matter-device/#extending-base-app-implementation). +For information about customizing app behavior, see [Matter API Reference](/matter/{build-docspace-version}/matter-api-reference/). Make the following additions to `src/CustomerAppTask.cpp`: