From dd72330a20a5c0b74cc246b9a2e99a473e5e74f3 Mon Sep 17 00:00:00 2001 From: Michael Duggan Date: Tue, 23 Jun 2026 10:55:42 -0400 Subject: [PATCH] migrate to custom-matter-device --- .../custom-matter-device.md | 27 ++++++++++++++++++- sld295-matter-api-reference/attributes.md | 2 +- sld295-matter-api-reference/index.md | 25 +---------------- sld57-matter-landing-page/index.md | 2 +- .../matter-application-cluster-logic.md | 2 +- .../matter-event-timer-guide.md | 2 +- .../matter-scenes-quick-start-guide.md | 2 +- 7 files changed, 32 insertions(+), 30 deletions(-) diff --git a/sld250-matter-references/custom-matter-device.md b/sld250-matter-references/custom-matter-device.md index 175533c..1d94cce 100644 --- a/sld250-matter-references/custom-matter-device.md +++ b/sld250-matter-references/custom-matter-device.md @@ -7,6 +7,31 @@ Build a customizable lighting app using the Matter protocol. This guide covers the basics of building a customizable lighting application using Matter. +## Application Customization Models + +Matter Extension 2.9.0 migrates a subset of sample apps to the Curiously Recurring Template Pattern (CRTP) based architecture, which removes app manager and DataModelCallbacks files. All other sample apps keep the previous architecture until the patch release. + +Check your project in Project Explorer: + +| If you see… | Architecture | Where to add custom logic | +|---|---|---| +| `src/CustomerAppTask.cpp` and `autogen/AppTask.cpp` | **New** | Override `*Impl()` hooks in `CustomerAppTask`, do not edit `autogen/AppTask.cpp` | +| `src/DataModelCallbacks.cpp` and editable `src/AppTask.cpp` | **Legacy** | Callbacks in `DataModelCallbacks.cpp`, init and app logic in `src/AppTask.cpp` | + +**Sample apps on the new architecture in 2.9.0:** + +- Lighting +- Zigbee Matter Light +- On/Off Plug +- Thermostat +- Lock +- Light Switch +- Rangehood +- Platform Template +- Air Quality Sensor + +All other Silicon Labs Matter sample apps in this release use the legacy model. Related guides label steps as **New architecture** or **Legacy architecture** where they differ. + ## Using Matter with Clusters In Matter, commands can be issued by using a cluster. A cluster is a set of @@ -61,7 +86,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. -Depending on your sample application, edit the files. For more information, refer to [Application Customization Models](/matter/{build-docspace-version}/matter-api-reference/#application-customization-models). New architecture apps route attribute changes through `CustomerAppTask` and `DMPostAttributeChangeCallbackImpl()`. Legacy architecture apps implement `MatterPostAttributeChangeCallback()` directly in `src/DataModelCallbacks.cpp`. +Depending on your sample application, edit the files as described in [Application Customization Models](#application-customization-models). New architecture apps route attribute changes through `CustomerAppTask` and `DMPostAttributeChangeCallbackImpl()`. Legacy architecture apps implement `MatterPostAttributeChangeCallback()` directly in `src/DataModelCallbacks.cpp`. ## Adding a Cluster to a ZAP Configuration diff --git a/sld295-matter-api-reference/attributes.md b/sld295-matter-api-reference/attributes.md index 8fad91c..5483fb8 100644 --- a/sld295-matter-api-reference/attributes.md +++ b/sld295-matter-api-reference/attributes.md @@ -4,7 +4,7 @@ Attributes represent the current state of a device. For instance if the device i ## Attribute Changes -Depending on your sample app, instructions apply. For more information, refer to [Application customization models](./index.md#application-customization-models). +Depending on your sample app, instructions apply. For more information, refer to [Application customization models](/matter/{build-docspace-version}/matter-references/custom-matter-device/#application-customization-models). ### New Architecture diff --git a/sld295-matter-api-reference/index.md b/sld295-matter-api-reference/index.md index 5195cce..960faa9 100644 --- a/sld295-matter-api-reference/index.md +++ b/sld295-matter-api-reference/index.md @@ -11,30 +11,7 @@ This section covers the various Application Programming Interfaces (APIs) that a ## Application APIs -### Application Customization Models - -Matter Extension 2.9.0 migrates a subset of sample apps to the Curiously Recurring Template Pattern (CRTP) based architecture, which removes app manager and DataModelCallbacks files. All other sample apps keep the previous architecture until the patch release. - -Check your project in Project Explorer: - -| If you see… | Architecture | Where to add custom logic | -|---|---|---| -| `src/CustomerAppTask.cpp` and `autogen/AppTask.cpp` | **New** | Override `*Impl()` hooks in `CustomerAppTask`, do not edit `autogen/AppTask.cpp` | -| `src/DataModelCallbacks.cpp` and editable `src/AppTask.cpp` | **Legacy** | Callbacks in `DataModelCallbacks.cpp`, init and app logic in `src/AppTask.cpp` | - -**Sample apps on the new architecture in 2.9.0:** - -- Lighting -- Zigbee Matter Light -- On/Off Plug -- Thermostat -- Lock -- Light Switch -- Rangehood -- Platform Template -- Air Quality Sensor - -All other Silicon Labs Matter sample apps in this release use the legacy model. Pages below label steps as **New architecture** or **Legacy architecture** where they differ. +For guidance on new vs legacy sample app architecture and where to add custom logic, see [Application Customization Models](/matter/{build-docspace-version}/matter-references/custom-matter-device/#application-customization-models). ### Initialization diff --git a/sld57-matter-landing-page/index.md b/sld57-matter-landing-page/index.md index 96f1cc2..c499e0f 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 using the model your sample app provides — see [Application Customization Models](/matter/{build-docspace-version}/matter-api-reference/#application-customization-models). Refactored apps use `CustomerAppTask` and `autogen/AppTask.cpp`, all other apps use `DataModelCallbacks.cpp` and `src/AppTask.cpp`. + - Customize app behavior using the model your sample app provides — see [Application Customization Models](/matter/{build-docspace-version}/matter-references/custom-matter-device/#application-customization-models). Refactored apps use `CustomerAppTask` and `autogen/AppTask.cpp`, all other apps use `DataModelCallbacks.cpp` and `src/AppTask.cpp`. - 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 2669620..4417f7b 100644 --- a/sld601-matter-application-development/matter-application-cluster-logic.md +++ b/sld601-matter-application-development/matter-application-cluster-logic.md @@ -62,7 +62,7 @@ Additionally, a corresponding component is automatically added to your project. ## Step 4: Add Application Logic -This guide uses the Lock sample app, which is on the **new architecture** in 2.9.0. See [Application Customization Models](/matter/{build-docspace-version}/matter-api-reference/#application-customization-models) to confirm which model your project uses. +This guide uses the Lock sample app, which is on the **new architecture** in 2.9.0. See [Application Customization Models](/matter/{build-docspace-version}/matter-references/custom-matter-device/#application-customization-models) to confirm which model your project uses. ### New Architecture diff --git a/sld601-matter-application-development/matter-event-timer-guide.md b/sld601-matter-application-development/matter-event-timer-guide.md index 3131c0b..d1bf386 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. -Depending on your sample app, instructions apply. See [Application Customization Models](/matter/{build-docspace-version}/matter-api-reference/#application-customization-models). +Depending on your sample app, instructions apply. See [Application Customization Models](/matter/{build-docspace-version}/matter-references/custom-matter-device/#application-customization-models). 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 3ec814d..dcd6f58 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 -This guide uses the Lighting sample app, which is on the **new architecture** in 2.9.0. See [Application Customization Models](/matter/{build-docspace-version}/matter-api-reference/#application-customization-models) to confirm which model your project uses. +This guide uses the Lighting sample app, which is on the **new architecture** in 2.9.0. See [Application Customization Models](/matter/{build-docspace-version}/matter-references/custom-matter-device/#application-customization-models) to confirm which model your project uses. #### New Architecture