Note
This sample is a copy of the matter :ref:`light_bulb sample from the Nordic Connect SDK 2.3.0https://github.com/nrfconnect/sdk-nrf/tree/v2.3.0/samples/matter/light_bulb` with Memfault integration added. Below is the original README.
This light bulb sample demonstrates the usage of the :ref:`Matter <ug_matter>` application layer to build a white dimmable light bulb device. This device works as a Matter accessory device, meaning it can be paired and controlled remotely over a Matter network built on top of a low-power, 802.15.4 Thread network or on top of a Wi-Fi network. Support for both Thread and Wi-Fi is mutually exclusive and depends on the hardware platform, so only one protocol can be supported for a specific light bulb device. You can use this sample as a reference for creating your own application.
Note
This sample is self-contained and can be tested on its own. However, it is required when testing the :ref:`Matter light switch <matter_light_switch_sample>` sample.
The sample supports the following development kits:
.. table-from-sample-yaml::
If you want to commission the light bulb device and :ref:`control it remotely <matter_light_bulb_network_mode>`, you also need a Matter controller device :ref:`configured on PC or mobile <ug_matter_configuring>`. This requires additional hardware depending on the setup you choose.
The development kits for this sample offer the following IPv6 network support for Matter:
- Matter over Thread is supported for
nrf52840dk_nrf52840,nrf5340dk_nrf5340_cpuapp, andnrf21540dk_nrf52840. - Matter over Wi-Fi is supported for
nrf5340dk_nrf5340_cpuappwith thenrf7002_ekshield attached or fornrf7002dk_nrf5340_cpuapp.
The sample uses buttons to test changing the light bulb and device states, and LEDs to show the state of these changes. You can test it in the following ways:
- Standalone, by using a single DK that runs the light bulb application.
- Remotely over the Thread or Wi-Fi, which requires more devices.
The remote control testing requires a Matter controller that you can configure either on a PC or a mobile device (for remote testing in a network). You can enable both methods after :ref:`building and running the sample <matter_light_bulb_sample_remote_control>`.
By default, the Matter accessory device has no IPv6 network configured. You must pair it with the Matter controller over Bluetooth® LE to get the configuration from the controller to use the device within a Thread or Wi-Fi network. The controller must get the Onboarding information from the Matter accessory device and provision the device into the network. For details, see the Commissioning the device section.
The sample uses different configuration files depending on the supported features. Configuration files are provided for different build types and they are located in the application root directory.
The :file:`prj.conf` file represents a debug build type.
Other build types are covered by dedicated files with the build type added as a suffix to the prj part, as per the following list.
For example, the release build type file name is :file:`prj_release.conf`.
If a board has other configuration files, for example associated with partition layout or child image configuration, these follow the same pattern.
Before you start testing the application, you can select one of the build types supported by the sample. This sample supports the following build types, depending on the selected board:
debug-- Debug version of the application - can be used to enable additional features for verifying the application behavior, such as logs or command-line shell.release-- Release version of the application - can be used to enable only the necessary application functionalities to optimize its performance.no_dfu-- Debug version of the application without Device Firmware Upgrade feature support - can be used for the nRF52840 DK, nRF5340 DK, nRF7002 DK, and nRF21540 DK.
Note
Selecting a build type is optional.
The debug build type is used by default if no build type is explicitly selected.
- LED 2:
Shows the state of the light bulb. The following states are possible:
- Solid On - The light bulb is on.
- Off - The light bulb is off.
Additionally, the LED starts blinking evenly (500 ms on/500 ms off) when the Identify command of the Identify cluster is received on the endpoint
1. The command's argument can be used to specify the duration of the effect.
- Button 2:
- On nRF52840 DK, nRF5340 DK, and nRF21540 DK: Changes the light bulb state to the opposite one.
- On nRF7002 DK:
- If pressed for less than three seconds, it changes the lock state to the opposite one.
- If pressed for more than three seconds, it starts the NFC tag emulation, enables Bluetooth LE advertising for the predefined period of time (15 minutes by default), and makes the device discoverable over Bluetooth LE.
- Button 4:
- On nRF52840 DK, nRF5340 DK, and nRF21540 DK: Starts the NFC tag emulation, enables Bluetooth LE advertising for the predefined period of time (15 minutes by default), and makes the device discoverable over Bluetooth LE. This button is used during the :ref:`commissioning procedure <matter_light_bulb_sample_remote_control_commissioning>`.
- On nRF7002 DK: Not available.
- NFC port with antenna attached:
- Optionally used for obtaining the Onboarding information from the Matter accessory device to start the :ref:`commissioning procedure <matter_light_bulb_sample_remote_control_commissioning>`.
See Configuration for information about building the sample with the DFU support.
Before you start testing the application, you can select one of the Matter light bulb build types, depending on your building method.
Selecting a build type in |VSC|
For example, you can replace the selected_build_type variable to build the release firmware for nrf52840dk_nrf52840 by running the following command in the project directory:
west build -b nrf52840dk_nrf52840 -d build_nrf52840dk_nrf52840 -- -DCONF_FILE=prj_release.conf
The build_nrf52840dk_nrf52840 parameter specifies the output directory for the build files.
Note
If the selected board does not support the selected build type, the build is interrupted.
For example, if the shell build type is not supported by the selected board, the following notification appears:
File not found: ./ncs/nrf/samples/matter/light_bulb/configuration/nrf52840dk_nrf52840/prj_shell.confAfter building the sample and programming it to your development kit, complete the following steps to test its basic features.
You can either test the sample's basic features or use the light switch sample to test the light bulb's :ref:`communication with another device <matter_light_bulb_sample_light_switch_tests>`.
After building the sample and programming it to your development kit, complete the following steps to test its basic features:
Observe that LED 2 is off.
Press Button 2 on the light bulb device. The LED 2 turns on and the following messages appear on the console:
I: Turn On Action has been initiated I: Turn On Action has been completed
Press Button 2 again. The LED 2 turns off and the following messages appear on the console:
I: Turn Off Action has been initiated I: Turn Off Action has been completed
Press Button 1 to initiate the factory reset of the device.
After building this sample and the :ref:`Matter light switch <matter_light_switch_sample>` sample and programming them to the development kits, complete the steps in the following sections to test communication between both devices.
Complete the following steps to bind both devices:
Remote control allows you to control the Matter light bulb device from an IPv6 network.
To commission the device, go to the :ref:`ug_matter_gs_testing` page and complete the steps for the Matter over Thread or Matter over Wi-Fi development environment and the Matter controller you want to use. After choosing the environment configuration, the guide walks you through the following steps:
- Configure the Thread Border Router (only for Matter over Thread communication).
- Build and install the Matter controller.
- Commission the device.
- Send Matter commands that cover scenarios described in the Testing section.
If you are new to Matter, the recommended approach is to use :ref:`CHIP Tool for Linux or macOS <ug_matter_configuring_controller>`.
Before starting the commissioning procedure, the device must be made discoverable over Bluetooth LE. The device becomes discoverable automatically upon the device startup, but only for a predefined period of time (15 minutes by default). If the Bluetooth LE advertising times out, use one of the following buttons to enable it again:
- On nRF52840 DK, nRF5340 DK and nRF21540 DK:
- Press Button 4.
- On nRF7002 DK:
- Press Button 2 for at least three seconds.
When you start the commissioning procedure, the controller must get the onboarding information from the Matter accessory device. The onboarding information representation depends on your commissioner setup.
For this sample, you can use one of the following :ref:`onboarding information formats <ug_matter_network_topologies_commissioning_onboarding_formats>` to provide the commissioner with the data payload that includes the device discriminator and the setup PIN code:
Light bulb sample onboarding information
QR Code QR Code Payload Manual pairing code Scan the following QR code with the app for your ecosystem:
MT:6FCJ142C00KA0648G00 34970112332
To upgrade the device firmware, complete the steps listed for the selected method in the :doc:`matter:nrfconnect_examples_software_update` tutorial in the Matter documentation.
This sample uses the Matter library that includes the |NCS| platform integration layer:
In addition, it uses the following |NCS| components:
The sample depends on the following Zephyr libraries: