Feedback

Matter API

The Matter SDK is the reference implementation of the Matter protocol specification. It does not have a single, unified API documentation. Instead, you need to study the source code of existing Matter sample applications to learn how to interact with the library. To make this easier, Nordic Semiconductor provides a higher-level API that wraps the initialization of Matter components into more user-friendly code.

Note that the Matter SDK is written in C++, while the rest of the nRF Connect SDK uses C. C++ is a natural choice for complex protocol stacks, as it supports object-oriented programming features that are difficult to implement in C.

Use cases of the Matter application code

Initialization of application-specific components. For example, initialization of hardware modules and registration of proprietary Bluetooth^® LE services.
Initialization of the Matter stack.
Starting the application main event loop.
Interaction between the application and the Matter Data Model. This is based on the Zigbee Cluster Library (ZCL) callbacks.

Note

The Matter Data Model was designed based on the Zigbee solution, and some parts like for example the Zigbee Cluster Library (ZCL) were directly re-used in this protocol. For this reason, you might find the naming confusing at first sight.

Matter common utilities

The nRF Connect SDK provides nRF Connect Matter API and the utilities being a part of nRF Connect SDK Matter samples’ common components, located in the ncs/nrf/samples/matter/common directory.

The src directory contains optional modules that can be used across different samples and applications. The files in the app directory are particularly important – they are used by every Matter sample and application in the nRF Connect SDK and help you initialize and manage the Matter stack.

Note

Items marked in bold are especially important for getting started with Matter development. The remaining files may also be useful depending on your use case.

app – App helpers for initializing and integrating the Matter stack.
- …
- matter_event_handler.h – Declarations for the Matter event handling utilities.
- matter_event_handler.cpp – Implementations for the Matter event handling utilities.
- matter_init.h – Declarations for Matter stack initialization routines.
- matter_init.cpp – Helpers for initializing the Matter stack and platform services.
- task_executor.h – Declarations for the task executor utility.
- task_executor.cpp – Lightweight task/dispatch executor for deferred work.
binding – Binding client utilities for cluster-to-cluster interactions.
board – Board abstraction and LED widget helpers for samples.
bt_nus – Bluetooth NUS (Nordic UART Service) console support.
certification – Hooks and assets to support Matter certification workflows.
clusters – Shared cluster-specific helpers and headers.
dfu – Matter OTA and SMP-based Device Firmware Update helpers.
diagnostic – Diagnostic logs provider and crash/retention logging support.
event_trigger – Event Trigger feature helpers and default trigger definitions.
migration – Utilities to migrate data across schema or stack versions.
persistent_storage – Persistent storage abstraction with multiple backends.
pwm – PWM device abstraction used by LED and motor samples.
…
watchdog – Watchdog support enabling application health monitoring.

Initialization API

The initialization API allows developers to configure Matter stack core components, event handlers, and networking backends.

Note

The order in which stack components are initialized matters — incorrect ordering can cause initialization failures. The nRF Connect SDK Matter API provides wrapper functions that handle this for you in the correct order.

The nRF Connect Matter API contains the following functions that can be used to initialize Matter components:

Function name	Purpose
`CHIP_ERROR PrepareServer(const InitData)`	This function schedules the initialization of Matter components, including memory, server configuration and networking backend. It can initialize different modules depending on the selected configuration and it allows to customize the initialized content by the user.This function accepts an `InitData` argument that contains the implementation of all required Matter interfaces. If no argument is provided, this function uses the default-constructed `InitData` temporary object. After this function is used, the `StartServer()` function must be called to start the Matter thread,
`CHIP_ERROR StartServer()`	This is a blocking function that starts the Matter thread and waits until all Matter server components are initialized. It should be used after calling `PrepareServer()`.
`FactoryDataProviderBase* GetFactoryDataProvider()`	This function returns the generic pointer to the `FactoryDataProvider` object that was set during the initialization. It can be used when you need to access factory data at the Matter server initialization stage or as a part of the post initialization callback (`mPostServerInitClbk` in `InitData`).This function is only available if the `CONFIG_CHIP_FACTORY_DATA` Kconfig option is selected.
`PersistentStorageDelegate* GetPersistentStorageDelegate()`	This function returns the generic pointer to the `PersistentStorageDelegate` object that was either set externally by the user or internally by the default implementation.

Deep dive in Matter initialization data

The InitData structure passed to PrepareServer() is highly configurable and customizable.

Each Matter component in this structure is defined as a public pointer to a generic interface, initially assigned a default implementation. If you provide a custom implementation in your application, the compiler strips out the unused default.

The InitData structure contains the following:

/** @brief Matter initialization data.
 *
 * This structure contains all user specific implementations of Matter interfaces
 * and custom initialization callbacks that must be initialized in the Matter thread.
 */
struct InitData {
      /** @brief Matter stack events handler. */
      chip::DeviceLayer::PlatformManager::EventHandlerFunct mEventHandler{ DefaultEventHandler };
      /** @brief Pointer to the user provided NetworkCommissioning instance. */
#ifdef CONFIG_CHIP_WIFI
      chip::app::Clusters::NetworkCommissioning::Instance *mNetworkingInstance{ &sWiFiCommissioningInstance };
#else
      chip::app::Clusters::NetworkCommissioning::Instance *mNetworkingInstance{ nullptr };
#endif
      /** @brief Pointer to the user provided custom server initialization parameters. */
      chip::CommonCaseDeviceServerInitParams *mServerInitParams{ &sServerInitParamsDefault };
      /** @brief Pointer to the user provided custom device info provider implementation. */
      chip::DeviceLayer::DeviceInfoProviderImpl *mDeviceInfoProvider{ nullptr };
#ifdef CONFIG_CHIP_FACTORY_DATA
      /** @brief Pointer to the user provided FactoryDataProvider implementation. */
      chip::DeviceLayer::FactoryDataProviderBase *mFactoryDataProvider{ &sFactoryDataProviderDefault };
#endif
#ifdef CONFIG_CHIP_CRYPTO_PSA
      /** @brief Pointer to the user provided OperationalKeystore implementation. */
      chip::Crypto::OperationalKeystore *mOperationalKeyStore{ &sOperationalKeystoreDefault };
#endif
      /** @brief Custom code to execute in the Matter main event loop before the server initialization. */
      CustomInit mPreServerInitClbk{ nullptr };
      /** @brief Custom code to execute in the Matter main event loop after the server initialization. */
      CustomInit mPostServerInitClbk{ nullptr };

      /** @brief Default implementation static objects that will be stripped by the compiler when above
       * pointers are overwritten by the application. */
#ifdef CONFIG_CHIP_WIFI
      static chip::app::Clusters::NetworkCommissioning::Instance sWiFiCommissioningInstance;
#endif
      static chip::CommonCaseDeviceServerInitParams sServerInitParamsDefault;
#ifdef CONFIG_CHIP_FACTORY_DATA
      static chip::DeviceLayer::FactoryDataProvider<chip::DeviceLayer::InternalFlashFactoryData> sFactoryDataProviderDefault;
#endif
#ifdef CONFIG_CHIP_CRYPTO_PSA
      static chip::Crypto::PSAOperationalKeystore sOperationalKeystoreDefault;
#endif
};

For example, you could imagine that the default implementation is almost enough for you, but you need to perform some additional action after the Matter server is initialized. It can be easily done by extending the default InitData structure with your custom implementation of mPostServerInitClbk callback:

CHIP_ERROR MatterAppInit()
{
      /* Initialize Matter stack */
      ReturnErrorOnFailure(Nrf::Matter::PrepareServer(Nrf::Matter::InitData{ .mPostServerInitClbk = [] {
             LOG_INF("Matter server has been initialized.");
             /* Change some LED state */
             return CHIP_NO_ERROR;
      } }));

      /* Application specific initialization, for example, hardware initialization.

         ...
      */

      /* Start Matter thread that will run the scheduled initialization procedure. */
      return Nrf::Matter::StartServer();
}

Note

The PrepareServer() call may contain more fields of the InitData being initialized, or can be called without any explicit argument. If there is no explicit argument, the default initialization will be provided

For more details regarding nRF Connect Matter initialization API, refer to the Doxygen commentary in the ncs/nrf/samples/matter/common/src/app/matter_init.h header file.

Event handling API

The Matter SDK propagates public events from the stack to the application layer. The nRF Connect Matter event handler API lets you register and unregister custom functions to handle these events. It also includes a default handler used by nRF Connect SDK Matter samples and applications.

Note

The specific Matter events in the application are listed in the ncs/modules/lib/matter/src/include/platform/CHIPDeviceEvent.h header file.

The nRF Connect Matter API contains of the following functions that can be used to handle events:

Function name	Purpose
`RegisterEventHandler()`	This function is used to register the provided Matter event handler(`EventHandlerFunct`) in a thread-safe manner. It is safe to call this function in the application after the Matter server has already been initialized.
`UnregisterEventHandler()`	This function is used to unregister the provided Matter event handler(`EventHandlerFunct`) in a thread-safe manner. It is safe to call this function in the application after the Matter server has already been initialized.
`DefaultEventHandler()`	This is an nRF Connect Matter event handler function that is registered in the nRF Connect Matter Initialization API by default. You can unregister this handler with the `UnregisterEventHandler()` function in the application if needed.

For example, if you want to turn on LED when Matter commissioning is complete, you could implement the following event handler:

static void CustomMatterEventHandler(const ChipDeviceEvent *event, intptr_t /* unused */)
{
      switch (event->Type) {
      case DeviceEventType::kCommissioningComplete:
          /* Custom code, for example, control LED */
          break;
      }
}

And the registering it using the API described above:

/* Register custom Matter event handler. */
ReturnErrorOnFailure(Nrf::Matter::RegisterEventHandler(CustomMatterEventHandler, 0));

Note

You should register new events during the initialization stage (after calling PrepareServer() method, but before calling the StartServer() method).

The following flow chart displays the flow of functions described in this topic, starting from application entry.

For more details regarding nRF Connect Matter event handler API, refer to the Doxygen commentary in the ncs/nrf/samples/matter/common/src/app/matter_event_handler.h header file.

Nordic Developer Academy Terms of Service

1. Introduction

‍These terms and conditions (“Terms of Use”) apply to the use of the Nordic Developer Academy, provided by Nordic Semiconductor ASA, org. nr. 966 011 726, a public limited liability company registered in Norway (“Nordic Semiconductor”). ‍

Nordic Developer Academy allows the user to take technical courses related to Nordic Semiconductor products, software and services, and obtain a certificate certifying completion of these courses. By completing the registration process for the Nordic Developer Academy, you are agreeing to be bound by these Terms of Use.

These Terms of Use are applicable as long as you have a user account giving you access to Nordic Developer Academy.‍

‍2. Access to and use of Nordic Developer Academy

‍‍Upon acceptance of these Terms of Use you are granted a non-exclusive right of access to, and use of Nordic Developer Academy, as it is provided to you at any time. Nordic Semiconductor provides Nordic Developer Academy to you free of charge, subject to the provisions of these Terms of Use and the Nordic Developer Academy Privacy Policy.

To access select features of Nordic Developer Academy, you need to create a user account. You are solely responsible for the security associated with your user account, including always keeping your login details safe.

You will able to receive an electronic certificate from Nordic Developer Academy upon completion of courses. By issuing you such a certificate, Nordic Semiconductor certifies that you have completed the applicable course, but does not provide any further warrants or endorsements for any particular skills or professional qualifications.

Nordic Semiconductor will continuously develop Nordic Developer Academy with new features and functionality, but reserves the right to remove or alter any existing functions without notice.

‍3. Acceptable use

You undertake that you will use Nordic Developer Academy in accordance with applicable law and regulations, and in accordance with these Terms of Use.‍ You must not modify, adapt, or hack Nordic Developer Academy or modify another website so as to falsely imply that it is associated with Nordic Developer Academy, Nordic Semiconductor, or any other Nordic Semiconductor product, software or service.

You agree not to reproduce, duplicate, copy, sell, resell or in any other way exploit any portion of Nordic Developer Academy, use of Nordic Developer Academy, or access to Nordic Developer Academy without the express written permission by Nordic Semiconductor. You must not upload, post, host, or transmit unsolicited email, SMS, or \”spam\” messages.

You are responsible for ensuring that the information you post and the content you share does not;

contain false, misleading or otherwise erroneous information
infringe someone else’s copyrights or other intellectual property rights
contain sensitive personal data or
contain information that might be received as offensive or insulting.
Such information may be removed without prior notice.

‍Nordic Semiconductor reserves the right to at any time determine whether a use of Nordic Developer Academy is in violation of its requirements for acceptable use.

Violation of the at any time applicable requirements for acceptable use may result in termination of your account. We will take reasonable steps to notify you and state the reason for termination in such cases.

‍4. Routines for planned maintenance

‍Certain types of maintenance may imply a stop or reduction in availability of Nordic Developer Academy. Nordic Semiconductor does not warrant any level of service availability but will provide its best effort to limit the impact of any planned maintenance on the availability of Nordic Developer Academy.

5. Intellectual property rights

‍Nordic Semiconductor retains all rights to all elements of Nordic Developer Academy. This includes, but is not limited to, the concept, design, trademarks, know-how, trade secrets, copyrights and all other intellectual property rights.

Nordic Semiconductor receives all rights to all content uploaded or created in Nordic Developer Academy. You do not receive any license or usage rights to Nordic Developer Academy beyond what is explicitly stated in this Agreement.

‍6. Liability and damages

‍Nothing within these Terms of Use is intended to limit your statutory data privacy rights as a data subject, as described in the Nordic Developer Academy Privacy Policy. ‍You acknowledge that errors might occur from time to time and waive any right to claim for compensation as a result of errors in Nordic Developer Academy. When an error occurs, you shall notify Nordic Semiconductor of the error and provide a description of the error situation.

You agree to indemnify Nordic Semiconductor for any loss, including indirect loss, arising out of or in connection with your use of Nordic Developer Academy or violations of these Terms of Use. ‍Nordic Semiconductor shall not be held liable for, and does not warrant that (i) Nordic Developer Academy will meet your specific requirements, (ii) Nordic Developer Academy will be uninterrupted, timely, secure, or error-free, (iii) the results that may be obtained from the use of Nordic Developer Academy will be accurate or reliable, (iv) the quality of any products, services, information, or other material purchased or obtained by you through Nordic Developer Academy will meet your expectations, or that (v) any errors in Nordic Developer Academy will be corrected.

You accept that this is a service provided to you without any payment and hence you accept that Nordic Semiconductor will not be held responsible, or liable, for any breaches of these Terms of Use or any loss connected to your use of Nordic Developer Academy. Unless otherwise follows from mandatory law, Nordic Semiconductor will not accept any such responsibility or liability.

‍7. Change of terms

‍Nordic Semiconductor may update and change the Terms of Use from time to time. Nordic Semiconductor will seek to notify you about significant changes before such changes come into force and give you a possibility to evaluate the effects of proposed changes. Continued use of Nordic Developer Academy after any such changes shall constitute your acceptance of such changes. You can review the current version of the Terms of Use at any time at https://academy.nordicsemi.com/terms-of-service/

‍8. Transfer of rights

‍Nordic Semiconductor is entitled to transfer its rights and obligation pursuant to these Terms of Use to a third party as part of a merger or acquisition process, or as a result of other organizational changes.

‍9. Third Party Services

‍‍To the extent Nordic Developer Academy facilitates access to services provided by a third party, you agree to comply with the terms governing such third party services. Nordic Semiconductor shall not be held liable for any errors, omissions, inaccuracies, etc. related to such third party services.

‍10. Dispute resolution

‍‍The Terms of Use and any other legally binding agreement between yourself and Nordic Semiconductor shall be subject to Norwegian law and Norwegian courts’ exclusive jurisdiction.

Matter Fundamentals

Matter API

Use cases of the Matter application code

Note

Matter common utilities

Note

Initialization API

Note

Deep dive in Matter initialization data

Note

Event handling API

Note

Note

Switch language?

Change summary

What's new in the latest version

Matter

MCUboot & Partition Manager