Matter test event triggers
Matter test event triggers are a set of software commands designed to initiate specific test scenarios.
You can activate these commands using the Matter Controller, which serves as the interface for executing them.
To activate a command, you need to enter the pre-defined activation codes that correspond to the desired test event.
All test event triggers are based on the generaldiagnostics
Matter cluster, and utilize the test-event-trigger
command to function.
This mechanism can be used during the Matter certification process to simulate common and specific device scenarios, and during software verification events to validate the correct operation of Matter-compliant devices.
To learn how to use the test event triggers functionality during the Matter certification process, see the Using in Matter certification section.
You can utilize the test event triggers predefined in the Default test event triggers section to streamline your testing process. If the predefined options do not meet your requirements, you can also define your own event triggers. To learn how to create custom event triggers, refer to the Custom test event triggers section of the documentation.
Requirements
The CHIP Tool application is required to send test-event-trigger
commands to the general diagnostics cluster.
Ensure that it is installed before initiating Matter testing events.
Your device needs to include the general diagnostics cluster within its Matter data model database to perform Matter testing events. For guidance on configuring the general diagnostics cluster on your device, refer to the instructions provided on the Adding clusters to Matter application page.
Activation of test event codes requires the provisioning of an enable key. To ensure secure operation, the enable key must be specific for each device. You can find instructions on how to establish the enable key for your device in the Setting the enable key section.
Default test event triggers
You can use the pre-defined common test event triggers in your application.
To disable them, set the CONFIG_NCS_SAMPLE_MATTER_TEST_EVENT_TRIGGERS_REGISTER_DEFAULTS
Kconfig option to n
.
The following table lists the available triggers and their activation codes:
Name |
Requirements |
Description |
Activation code [range] |
Value description |
---|---|---|---|---|
Factory reset |
None |
Perform a factory reset of the device with a delay. |
|
The range of |
Reboot |
None |
Reboot the device. |
|
The range of |
Block the Matter thread |
|
Block the Matter thread for specific amount of time. You can use this event trigger to check the Matter Watchdog functionality. |
|
The range of |
Block the Main thread |
|
Block the Main thread for specific amount of time. You can use this event trigger to check the Matter Watchdog functionality. |
|
The range of |
Diagnostic Logs User Data |
Enabled |
Trigger writing a specific number of |
|
The range of |
Diagnostic Logs Network Data |
Enabled |
Trigger writing a specific amount of |
|
The range of |
Diagnostic Crash Logs |
Either the snippet diagnostic-logs attached ( |
Trigger a simple crash that relies on execution of the undefined instruction attempt. |
|
No additional value supported. |
OTA query |
|
Trigger an OTA firmware update. |
|
The range of |
Smoke CO alarm - Smoke critical alarm |
Only for Matter Smoke CO Alarm |
Trigger a smoke alarm with critical severity level |
|
No additional value supported. |
Smoke CO alarm - Smoke alarm clean |
Only for Matter Smoke CO Alarm |
Trigger an action that ceases smoke alarm |
|
No additional value supported. |
Smoke CO alarm - CO critical alarm |
Only for Matter Smoke CO Alarm |
Trigger a CO alarm with critical severity level |
|
No additional value supported. |
Smoke CO alarm - CO alarm clean |
Only for Matter Smoke CO Alarm |
Trigger an action that ceases CO alarm |
|
No additional value supported. |
Smoke CO alarm - battery low level alarm |
Only for Matter Smoke CO Alarm |
Trigger a battery low level alarm |
|
No additional value supported. |
Smoke CO alarm - battery low level alarm clean |
Only for Matter Smoke CO Alarm |
Trigger an action that ceases battery low level alarm |
|
No additional value supported. |
Smoke CO alarm - hardware fault alarm |
Only for Matter Smoke CO Alarm |
Trigger a hardware fault alarm |
|
No additional value supported. |
Smoke CO alarm - hardware fault alarm clean |
Only for Matter Smoke CO Alarm |
Trigger an action that ceases hardware fault alarm |
|
No additional value supported. |
Smoke CO alarm - end of service alarm |
Only for Matter Smoke CO Alarm |
Trigger a end of service alarm |
|
No additional value supported. |
Smoke CO alarm - end of service alarm clean |
Only for Matter Smoke CO Alarm |
Trigger an action that ceases end of service alarm |
|
No additional value supported. |
Door lock jammed |
|
Simulate the jammed lock state. |
|
This activation code does not contain any value. |
Setting the enable key
The enable key can be provided either by utilizing the factory data, or directly in the application code.
Using factory data
You cannot set the enable key to a specific value using factory data unless the CONFIG_CHIP_FACTORY_DATA
Kconfig option is set to y
.
If it is not set, the default value 00112233445566778899AABBCCDDEEFF
will be used.
For secure operation, you need to ensure that the enable key is unique for all of your devices.
To specify the enable key through the build system, enable the SB_CONFIG_MATTER_FACTORY_DATA_GENERATE
Kconfig option by setting it to y
.
Then, set the CONFIG_CHIP_DEVICE_ENABLE_KEY
Kconfig option to a 32-byte hexadecimal string value.
If SB_CONFIG_MATTER_FACTORY_DATA_GENERATE
is set to n
, you can follow the Configuring factory data for the nRF Connect examples guide in the Matter documentation to generate the factory data set with the specific enable key value.
If you do not use the nRF Connect SDK Matter common module, you need to read the enable key value manually from the factory data set and provide it to the TestEventTrigger
class.
For example:
/* Prepare the factory data provider */
static chip::DeviceLayer::FactoryDataProvider<chip::DeviceLayer::InternalFlashFactoryData> sFactoryDataProvider;
sFactoryDataProvider.Init();
/* Prepare the buffer for enable key data */
uint8_t enableKeyData[chip::TestEventTriggerDelegate::kEnableKeyLength] = {};
MutableByteSpan enableKey(enableKeyData);
/* Load the enable key value from the factory data */
sFactoryDataProvider.GetEnableKey(enableKey);
/* Call SetEnableKey method to load the read value to the TestEventTrigger class. */
Nrf::Matter::TestEventTrigger::Instance().SetEnableKey(enableKey);
Directly in the code
Use the SetEnableKey method of the TestEventTrigger
class to set up the enable key.
For example:
/* Prepare Buffer for Test Event Trigger data which contains your "enable key" */
uint8_t enableKeyData[chip::TestEventTriggerDelegate::kEnableKeyLength] = {
0x00, 0x11, 0x22, 0x33, 0x44, 0x55,
0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb,
0xcc, 0xdd, 0xee, 0xff
};
/* Call SetEnableKey method to load the prepared value to the TestEventTrigger class. */
Nrf::Matter::TestEventTrigger::Instance().SetEnableKey(ByteSpan {enableKeyData});
Using in Matter certification
When you provide the enable key using factory data, you can utilize the event trigger feature during the Matter certification process.
This is because, when done this way, you can turn off the event trigger functionality by disabling access to the generaldiagnostics
cluster without altering the code that has already been certified.
Once the certification process is complete, you must deactivate the test event trigger functionality by generating new factory data with a modified enable key value.
This is done by setting the CONFIG_CHIP_DEVICE_ENABLE_KEY
Kconfig option to a value consisting solely of zeros.
For instance, to generate factory data with disabled event trigger functionality, set the CONFIG_CHIP_DEVICE_ENABLE_KEY
Kconfig option to the value 0x00000000000000000000000000000000
.
After generating it, flash the factory_data.hex
file onto the device.
Custom test event triggers
You can define and register custom test event triggers to initiate specific actions on your device.
An activation code is 64 bits in length, and consist of two components: the event trigger ID and the event trigger value.
The event trigger ID is 64 bits long and uniquely identifies the trigger. It is supplied as the first 48 bits of the activation code.
The event trigger value is specific to a given trigger. It is supplied as the last 24 bits of the activation code.
This means that the activation code has the pattern 0xIIIIIIIIIIIIVVVV
, where I
represents the ID part and V
represents the value part.
For example the 0xFFFFFFFF00011234
activation code stands for a trigger ID equal to 0xFFFFFFFF00010000
and a specific value of 0x1234
.
Note
Activation codes in range from 0x0000000000000000
to 0xFFFFFFFF00000000
are reserved for Matter stack purposes and should not be defined as custom event triggers.
A new event trigger consists of two fields: Mask
, and Callback
.
The
Mask
field is 32 bits long and specifies a mask for the trigger’s value.The
Callback
field is a callback function that will be invoked when the device receives a corresponding activation code.
The maximum number of event triggers that can be registered is configurable.
To adjust this limit, set the CONFIG_NCS_SAMPLE_MATTER_TEST_EVENT_TRIGGERS_MAX
Kconfig option to the desired value.
To register a new test event trigger, follow these steps:
Create a function that will be executed when the device receives a valid enable key and activation code.
This function must return a
CHIP_ERROR
code and accept aNrf::Matter::TestEventTrigger::TriggerValue
as its argument. You can utilize the provided argument within this function as needed.Use
CHIP_ERROR
codes to communicate appropriate responses to the Matter Controller. For instance, you might returnCHIP_ERROR_INVALID_ARGUMENT
to indicate that the user has provided an incorrect value argument.Note
The callback method is not thread-safe. Ensure that all operations within it are executed in a thread-safe manner. To perform operations within the Matter stack context, use the
chip::DeviceLayer::SystemLayer().ScheduleLambda
method. For operations in the application context, use theNrf::PostTask
function.Here is an example of how to create a callback function:
CHIP_ERROR MyFunctionCallback(Nrf::Matter::TestEventTrigger::TriggerValue value) { /* Define the required behavior of the device here. */ return CHIP_NO_ERROR; }
Register the new event trigger.
Use the following example as a guide to register a new event:
/* Create a new event */ Nrf::Matter::TestEventTrigger::EventTrigger myEventTrigger; /* Assign all fields */ uint64_t myTriggerID = /* Set the trigger ID */ myEventTrigger.Mask = /* Fill the value mask filed */; myEventTrigger.Callback = MyFunctionCallback; /* Register the new event */ CHIP_ERROR err = Nrf::Matter::TestEventTrigger::Instance().RegisterTestEventTrigger(myTriggerID, myEventTrigger); /* Remember to check the CHIP_ERROR return code */
If the returning CHIP_ERROR code is equal to CHIP_ERROR_NO_MEMORY, you need to increase the
NCS_SAMPLE_MATTER_TEST_EVENT_TRIGGERS_MAX
Kconfig option to the higher value.Here’s an example to handle the
0xFFFFFFFF00011234
activation code, where 1234 is the event trigger value field:Nrf::Matter::TestEventTrigger::EventTrigger myEventTrigger; uint64_t myTriggerID = 0xFFFFFFFF0001; myEventTrigger.Mask = 0xFFFF; myEventTrigger.Callback = MyFunctionCallback; CHIP_ERROR err = Nrf::Matter::TestEventTrigger::Instance().RegisterTestEventTrigger(myTriggerID, myEventTrigger);
Register an existing test event trigger handler
The Matter SDK has some test event trigger handlers implemented. All of them inherit the TestEventTriggerHandler class, and are implemented in various places in the Matter SDK.
The events declared in existing test event triggers can have a different semantic than described in the Custom test event triggers section.
Use the following example as a guide to register an existing event trigger handler:
/* Create the Trigger Handler object */
static TestEventTriggerHandler existingTriggerHandler;
CHIP_ERROR err = Nrf::Matter::TestEventTrigger::Instance().RegisterTestEventTriggerHandler(&existingTriggerHandler);
/* Remember to check the CHIP_ERROR return code */
If the returning CHIP_ERROR
code is equal to CHIP_ERROR_NO_MEMORY
, you need to increase the CONFIG_NCS_SAMPLE_MATTER_TEST_EVENT_TRIGGERS_MAX_TRIGGERS_DELEGATES
Kconfig option to the higher value.
For example, you can register and use the OTATestEventTriggerHandler
handler and trigger pre-defined Matter OTA DFU behaviors using the following code:
/* Create the Trigger Handler object */
static chip::OTATestEventTriggerHandler otaTestEventTrigger;
ReturnErrorOnFailure(Nrf::Matter::TestEventTrigger::Instance().RegisterTestEventTriggerHandler(&otaTestEventTrigger));
Usage
The Matter test event triggers feature is enabled by default for all Matter samples.
To disable it, set the CONFIG_NCS_SAMPLE_MATTER_TEST_EVENT_TRIGGERS
Kconfig option to n
.
To trigger a specific event on the device, run the following command:
./chip-tool generaldiagnostics test-event-trigger hex:<enable key> <activation code> <node id> 0
Replace the enable key
value with your device’s enable key, and the activation code
and node id
values with the values for the event you want to trigger.
The following is an example of the Reboot activation code with a 5 ms delay for Matter Template device which has a node id
set to 1
, using the default enable key:
./chip-tool generaldiagnostics test-event-trigger hex:00112233445566778899AABBCCDDEEFF 0xFFFFFFFF10000005 1 0