Important: We're excited to introduce our new technical documentation platform docs.nordicsemi.com, currently in Beta version. We invite you to explore it and share your feedback. Read more on our DevZone blog.
This Matter bridge application demonstrates the usage of the Matter application layer to build a bridge device.
The bridge device allows the use of non-Matter devices in a Matter fabric by exposing them as Matter endpoints.
The devices on the non-Matter side of the Matter bridge are called bridged devices.
The Matter bridge 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.11ax (Wi-Fi 6) network.
You can use this application as a reference for creating your own application.
See Matter Bridge for more information about the Matter bridge specification and architecture.
A micro-USB cable to connect the development kit to the PC.
To commission the Matter bridge device and control it remotely through a Wi-Fi network, you also need a Matter controller device configured on PC or smartphone.
This requires additional hardware depending on your setup.
Note
Matter requires the GN tool.
If you are updating from the nRF Connect SDK version earlier than v1.5.0, see the GN installation instructions.
The application uses buttons to control the device state and a single LED to show the state of a device.
The Matter bridge has capability of representing non-Matter bridged devices as dynamic endpoints.
The application supports bridging the following Matter device types:
On/Off Light
Temperature Sensor
Humidity Sensor
All the listed Matter device types are enabled by default.
To disable one of them, set any of the following configuration options:
CONFIG_BRIDGE_ONOFF_LIGHT_BRIDGED_DEVICE to n to disable On/Off Light.
CONFIG_BRIDGE_TEMPERATURE_SENSOR_BRIDGED_DEVICE to n to disable Temperature Sensor.
CONFIG_BRIDGE_HUMIDITY_SENSOR_BRIDGED_DEVICE to n to disable Humidity Sensor.
The application supports over-the-air (OTA) device firmware upgrade (DFU) using either of the two following protocols:
Matter OTA update protocol.
Querying and downloading a new firmware image is done using the Matter operational network.
Simple Management Protocol (SMP) over Bluetooth LE.
The DFU is done using either a smartphone application or a PC command line tool.
Note that this protocol is not part of the Matter specification.
In both cases, MCUboot secure bootloader is used to apply the new firmware image.
Matter OTA update protocol is enabled by default.
To configure the application to support the DFU over both Matter and SMP, use the -DCONFIG_CHIP_DFU_OVER_BT_SMP=y build flag.
When building on the command line, run the following command:
west build -b build_target -- dfu_build_flag
Replace build_target with the build target name of the hardware platform you are using (see Requirements), and dfu_build_flag with the desired DFU build flag.
For example:
west build -b nrf7002dk_nrf5340_cpuapp -- -DCONFIG_CHIP_DFU_OVER_BT_SMP=y
For information about how to upgrade the device firmware using a PC or a smartphone, see the Updating the device firmware section.
The application supports two bridged device configurations that are mutually exclusive:
Simulated bridged device - This configuration simulates the functionality of bridged devices by generating pseudorandom measurement results and changing the light state in fixed-time intervals.
Bluetooth LE bridged device - This configuration allows to connect a real peripheral Bluetooth LE device to the Matter bridge and represent its functionalities using Matter Data Model.
The application supports the following Bluetooth LE services:
Nordic Semiconductor’s LED Button Service - represented by the Matter On/Off Light device type.
Zephyr’s Environmental Sensing Service - represented by the Matter Temperature Sensor and Humidity Sensor device types.
Depending on the bridged device you want to support in your application, enable it using the appropriate Kconfig option.
The Matter bridge supports adding and removing bridged devices dynamically at application runtime using Matter CLI commands from a dedicated Matter bridge shell module.
By default, the Matter accessory device has no IPv6 network configured.
To use the device within a Wi-Fi network, you must pair it with the Matter controller over Bluetooth® LE to get the configuration from the controller.
The Bluetooth LE advertising starts automatically upon device startup, but only for a predefined period of time (15 minutes by default).
If the Bluetooth LE advertising times out, you can re-enable it manually by pressing Button (SW2).
Additionally, the controller must get the Onboarding information from the Matter accessory device and provision the device into the network.
For details, see the Testing section.
The bridge application 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 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 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.
When the CONF_FILE variable contains a single file and this file follows the naming pattern prj_<buildtype>.conf, then the build type will be inferred to be <buildtype>.
The build type cannot be set explicitly.
The <buildtype> can be any string, but it is common to use release and debug.
The Partition Manager’s static configuration can also be made dependent on the build type.
When the build type has been inferred, the file pm_static_<buildtype>.yml will have precedence over pm_static.yml.
The child image Kconfig configuration can also be made dependent on the build type.
The child image Kconfig overlay file is named child_image/<child_image_name>.conf instead of prj.conf, but otherwise follows the same pattern as the parent Kconfig.
Alternatively, the child image Kconfig configuration file can be introduced as child_image/<child_image_name>/prj.conf and follow the same pattern as the parent Kconfig.
For example, child_image/mcuboot/prj_release.conf can be used to define release build type for mcuboot child image.
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:
debug – Debug version of the application.
You can use this version to enable additional features for verifying the application behavior, such as logs.
release – Release version of the application.
You can use this version to enable only the necessary application functionalities to optimize its performance.
Note
Selecting a build type is optional.
The debug build type is used by default if no build type is explicitly selected.
Shows the overall state of the device and its connectivity.
The following states are possible:
Short Flash On (50 ms on/950 ms off) - The device is in the unprovisioned (unpaired) state and is waiting for a commissioning application to connect.
Rapid Even Flashing (100 ms on/100 ms off) - The device is in the unprovisioned state and a commissioning application is connected over Bluetooth LE.
Solid On - The device is fully provisioned.
Button 1:
Depending on how long you press the button:
If pressed for less than three seconds, it initiates the SMP server (Simple Management Protocol).
After that, the Direct Firmware Update (DFU) over Bluetooth Low Energy can be started.
(See Updating the device firmware.)
If pressed for more than three seconds, it initiates the factory reset of the device.
Releasing the button within a 3-second window of the initiation cancels the factory reset procedure.
Button 2:
Enables Bluetooth LE advertising for the predefined period of time (15 minutes by default), and makes the device discoverable over Bluetooth LE.
SEGGER J-Link USB port:
Used for getting logs from the device or for communicating with it through the command-line interface.
<ble_device_index> is the Bluetooth LE device index on the list returned by the scan command.
The argument is mandatory and accepts only the values returned by the scan command.
[“node label”] is the node label for the bridged device.
The argument is optional and you can use it to better personalize the device in your application.
Example command:
uart:~$ matter_bridgeadd0"Kitchen Light"
The terminal output is similar to the following one:
I: Added device to dynamic endpoint 3 (index=0)I: Created 0x100 device type on the endpoint 3
Removing a bridged device from the Matter bridge
Use the following command:
matter_bridge remove <bridged_device_endpoint_id>
In this command, <bridged_device_endpoint_id> is the endpoint ID of the bridged device to be removed.
CONFIG_BRIDGED_DEVICE_SIMULATED - For the simulated bridged device.
CONFIG_BRIDGED_DEVICE_BT - For the Bluetooth LE bridged device.
Additionally, you can decide how many bridged devices the bridge application will support.
The decision will make an impact on the flash and RAM memory usage, and is verified in the compilation stage.
The application uses dynamic memory allocation and stores bridged device objects on the heap, so it may be necessary to increase the heap size using the CONFIG_CHIP_MALLOC_SYS_HEAP_SIZE Kconfig option.
Use the following configuration options to customize the number of supported bridged devices:
CONFIG_BRIDGE_MAX_BRIDGED_DEVICES_NUMBER - For changing the maximum number of non-Matter bridged devices supported by the bridge application
CONFIG_BRIDGE_MAX_DYNAMIC_ENDPOINTS_NUMBER - For changing the maximum number of Matter endpoints used for bridging devices by the bridge application.
This option does not have to be equal to CONFIG_BRIDGE_MAX_BRIDGED_DEVICES_NUMBER, as it is possible to use non-Matter devices that are represented using more than one Matter endpoint.
Configuring the number of Bluetooth LE bridged devices
You have to consider several factors to decide how many Bluetooth LE bridged devices to support.
Every Bluetooth LE bridged device uses a separate Bluetooth LE connection, so you need to consider the number of supported Bluetooth LE connections (selected using the CONFIG_BT_MAX_CONN Kconfig option) when you configure the number of devices.
Since the Matter stack uses one Bluetooth LE connection for commissioning, the maximum number of connections you can use for bridged devices is one less than is configured using the CONFIG_BT_MAX_CONN Kconfig option.
Increasing the number of Bluetooth LE connections affects the RAM usage on both the application and network cores.
The current maximum number of Bluetooth LE connections that can be selected using the default configuration is 10.
You can increase the number of Bluetooth LE connections if you decrease the size of the Bluetooth LE TX/RX buffers used by the Bluetooth controller, but this will decrease the communication throughput.
Build the target using the following command in the project directory to enable a configuration that increases the number of Bluetooth LE connections to 20 by decreasing the sizes of Bluetooth LE TX/RX buffers:
west build -b nrf7002dk_nrf5340_cpuapp -- -DCONFIG_BRIDGED_DEVICE_BT=y -DOVERLAY_CONFIG="overlay-bt_max_connections_app.conf" -Dhci_rpmsg_OVERLAY_CONFIG="absoule_path/overlay-bt_max_connections_net.conf"
Replace absolute_path with the absolute path to the Matter bridge application on your local disk.
To select the build type in the nRF Connect for VS Code extension:
When building an application as described in the nRF Connect for VS Code extension documentation, follow the steps for setting up the build configuration.
In the Add Build Configuration screen, select the desired .conf file from the Configuration drop-down menu.
Fill in other configuration options, if applicable, and click Build Configuration.
To select the build type when building the application from command line, specify the build type by adding the following parameter to the westbuild command:
-- -DCONF_FILE=prj_selected_build_type.conf
For example, you can replace the selected_build_type variable to build the release firmware for nrf7002dk_nrf5340_cpuapp by running the following command in the project directory:
The build_nrf7002dk_nrf5340_cpuapp 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/applications/matter_bridge/configuration/nrf7002dk_nrf5340_cpuapp/prj_shell.conf
After building the sample and programming it to your development kit, complete the following steps to test its basic features:
Connect the kit to the computer using a USB cable.
The kit is assigned a COM port (Windows) or ttyACM device (Linux), which is visible in the Device Manager.
Open a serial port connection to the kit using a terminal emulator that supports VT100/ANSI escape characters (for example, PuTTY).
See How to connect with PuTTY for the required settings.
Observe that the LED1 starts flashing (short flash on).
This means that the sample has automatically started the Bluetooth LE advertising.
Commission the device to the Matter network.
See Commissioning the device for more information.
During the commissioning process, write down the value for the bridge node ID.
This is going to be used in the next steps (<bridge_node_ID>).
Depending on the chosen bridged devices configuration, complete the steps in one of the following tabs:
Using the terminal emulator connected to the bridge, run the following Matter CLI command to add a new bridged device:
uart:~$ matter_bridge add <device_type>
The <device_type> is the value of the Matter device type that will be used to represent a new bridged device in the Matter Data Model.
See the description in Matter CLI commands for the list of supported values.
For example, if you want to add a new bridged device that will be exposed as an On/Off Light endpoint, use the following command:
uart:~$ matter_bridgeadd256
The terminal output is similar to the following one:
Write down the value for the bridged device dynamic endpoint ID.
This is going to be used in the next steps (<bridged_device_endpoint_ID>).
Use the CHIP Tool to read the value of an attribute from the bridged device endpoint.
For example, read the value of the on-off attribute from the onoff cluster using the following command:
The <bluetooth_device_index> is a Bluetooth LE device index that was scanned in the previous step.
For example, if you want to add a new Bluetooth LE bridged device with index 1, use the following command:
uart:~$ matter_bridgeadd1
The terminal output is similar to the following one:
For the Environmental Sensor, two endpoints are created: one implements the Temperature Sensor, and the other implements the Humidity Sensor.
Write down the value for the bridged device dynamic endpoint ID.
This is going to be used in the next steps (<bridged_device_endpoint_ID>).
Use the CHIP Tool to read the value of an attribute from the bridged device endpoint.
For example, read the value of the on-off attribute from the onoff cluster using the following command:
In case of the Environmental Sensor, the current temperature and humidity measurements forwarded by the Bluetooth LE Environmental Sensor can be read as follows:
Before starting the commissioning to Matter procedure, ensure that there is no other Bluetooth LE connection established with the device.
To commission the device, go to the Testing Matter in the nRF Connect SDK page and complete the steps for the Matter network environment and the Matter controller you want to use.
After choosing the configuration, the guide walks you through the following steps:
Build and install the Matter controller.
Commission the device.
Send Matter commands that cover scenarios described in the Testing section.
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 application, you can use one of the following onboarding information formats to provide the commissioner with the data payload that includes the device discriminator and the setup PIN code:
