Telink Matter Developer Guide
Overview
Applicable Chip
Some specific Telink chips support Matter. In this document, TLSR9528A is taken as an example to introduce how to use Matter with this chip.
Emergence of Matter
-
Challenges
The issue of "fragmentation" in IoT products not only troubles consumers and developers but also hinders the further development of smart home hardware products. Currently, the tech giants leading the development of IoT products each have their own independent smart home ecosystems, such as Amazon Alexa, Apple HomeKit, and Google Home.
-
For Consumers
When selecting smart products, consumers need to consider not only the product's functions, features, and price but also whether it is compatible with their existing home ecosystem. This creates difficulties in their selection process and inconvenience in usage.
-
For Businesses
Third-party developers must consider which ecosystem their product needs to support to meet the needs of their target users. If developers are not content with limiting their product to a single ecosystem and want to meet the diverse needs of different consumers and expand their market share, they may need to modify existing devices to support more ecosystems or develop new devices that support multiple smart ecosystems. Both options can present significant challenges. On one hand, they have to spend more time and effort on software adaptation for different smart ecosystems; on the other hand, they may even need to modify the underlying hardware or design to meet the requirements of certain ecosystems.
Therefore, all parties hope to form a commonly accepted and followed "standard" to solve the above "fragmentation" issue, facilitating the development of smart home brands and manufacturers, and making it easier for consumers to choose. To meet this common need, many IoT ecosystem builders, including Amazon, Apple, and Google, joined forces with the Zigbee Alliance in December 2019 to announce the formation of the Connected Home over IP (CHIP) project working group, dedicated to creating a new smart home protocol based on an open-source ecosystem. In May 2021, as the Zigbee Alliance was renamed the Connectivity Standards Alliance, the project working group negotiated and formulated the draft of this local area network application layer standard protocol and renamed CHIP to Matter.
Matter Overview
Matter devices will operate at a unified application layer and rely solely on the TCP/IP and UDP protocols formed by the IPv6 standard in the transport layer, thus being compatible with different physical media and data link standards. Since the IP network is a mesh structure, Matter will also present a mesh topology (composed of sub-networks of different communication technologies).
In the first version of the Matter protocol, scheduled for official release this fall, it will initially support device-to-device communication over Ethernet, Wi-Fi, and Thread networks; and use Bluetooth Low Energy (BLE) technology as the channel for Matter devices to join the network, simplifying the configuration steps of Matter devices. The Thread protocol is based on IEEE 802.15.4 technology, and devices in its network cannot directly communicate with Wi-Fi or Ethernet devices. Therefore, a Thread border router needs to be added to the Matter topology to enable Matter devices in the Thread network to interconnect with devices in other networks. For example, a Matter device that only supports the Thread network can communicate with a device that only supports the Wi-Fi network (such as an iPhone) through a Border Router (such as HomePod Mini).
In the Matter network, there will be a unified data model and interaction model. The Matter protocol treats the network as a shared resource, without exclusive network ownership and access rights, allowing multiple different protocol networks to coexist in the same IP network group. In the past, two smart devices needed to be in the same physical network to communicate with each other, but the Matter protocol will build multiple virtual networks, allowing smart devices in different physical networks to communicate with each other. A virtual network here is a collection of Matter devices, called a Fabric. In practice, a Fabric often corresponds to a network formed by a smart ecosystem.
A physical device is called a Node (equivalent to an Accessory in HomeKit), and a Node can be added to one or more Fabrics. Under the Node, logical functional units called Endpoints represent different functional modules, such as Endpoint 1 and Endpoint 2 representing different functional modules of an air conditioner; Endpoint 0 is a reserved root endpoint used to describe device characteristics. Endpoints use several Clusters (inherited from the Zigbee Cluster Library, ZCL) to represent specific functions, such as switches, wind power, temperature measurement, and temperature control. The interaction between Matter devices is completed through communication between an Endpoint of one device and an Endpoint of another device.
In addition, the network constructed by the Matter protocol has the following features:
-
Multi-Admin, supporting the ability to add Matter devices to different ecosystems simultaneously, managed by administrators in different Fabrics, achieving broad compatibility.
-
Sharing Matter vendor and device information through the Distributed Compliance Ledger (DCL). Each ecosystem can query the information needed during Matter network configuration, OTA, etc., from the DCL.
-
Allowing users to control local devices without connecting to the cloud.
-
Existing non-Matter smart devices also have the opportunity to be added to the Matter Fabric through Matter Bridge devices. The Matter Bridge device communicates with non-Matter devices, virtualizing non-Matter devices into corresponding Endpoints, just like a Node with multiple different functional Endpoints, allowing Matter devices in the Matter network to communicate with non-Matter devices.
Matter Features
The Matter protocol mainly targets the smart home market, supporting the following types of devices:
-
Lighting devices such as lights and switches
-
Air handling devices such as heating and cooling
-
Security devices such as detectors and alarms
-
Access control devices such as door locks
-
Audio-visual entertainment devices such as speakers and TVs
-
Lighting and ventilation devices such as windows and curtains
-
Network relay devices such as hotspots and bridges
With the development and evolution of the Matter protocol, more smart devices will be supported in the future.
The Future of Matter
The high attention Matter has received is not just because of its advanced concepts and standards but also due to the commitments of three smart home giants. At the inception of the Matter project, Amazon, Apple, and Google promised that devices using this protocol would be compatible with their ecosystems. After the launch of the Matter protocol, IoT product developers will be able to develop once and support multiple ecosystem access protocols (such as Amazon Alexa, Apple HomeKit, and Google Home), greatly simplifying developers' work and enabling smart devices to seamlessly connect to any Matter-compatible smart ecosystem. Consumers will also find it easier to choose products without worrying about compatibility with their existing ecosystem.
Telink Matter Overview
Telink Semiconductor actively participates in the development of Matter device functions, testing and certification of Matter devices, and the interpretation of Matter standards in Chinese. As a provider of low-power, high-performance wireless connectivity SoC chip solutions, we have launched a Matter Over Thread solution based on the TLSR9 series chips, which can be used to develop Matter Thread end devices.
Telink Matter Currently Supported Applications
Currently, Telink Matter supports the following examples:
(1) connectedhomeip/example/lighting-app/telink
lighting-app bulb application
(2) connectedhomeip/example/light-switch-app/telink
light-switch-app switch application
Repositories and Branches Used
The latest Docker Image is still being updated, which includes the Zephyr environment needed to compile Matter applications. If you want to learn more, you can check:
https://hub.docker.com/r/connectedhomeip/chip-build-telink
The custom branch telink_matter of Matter has been merged into the official master branch, so you can use the following repository:
https://github.com/project-chip/connectedhomeip
Purpose of This Document
This document provides a complete guide to the Telink Matter solution, including environment setup, Matter device firmware building and flashing, border router setup (including RCP building and flashing), chip-tool building and usage, helping users understand Telink Matter-related matters and better experience the functions of Telink Matter applications.
Requirements
Required Hardware and Tools
1) TLSR9528A as a Matter device
2) TLSR9528A as RCP
3) Raspberry Pi 4 as part of the border router, 4GB RAM version recommended
4) SD card for Raspberry Pi 4, at least 16GB
5) Host PC with Ubuntu v20.04 LTS, used as a build machine and host for the Matter device
6) Telink Programmer for programming the Matter device and RCP firmware
7) Wi-Fi Router acting as a Wi-Fi access point
Introduction to the TLSR9528 Evaluation Board
B92 Board info
| Board/SoC | Build target | Zephyr Board Info |
|---|---|---|
| B92 TLRS9528A | tlsr9528a, tlsr9528a_retention |
TLRS9528A |
Button Functions
The four mechanical buttons on the TLSR9528 evaluation board are laid out and function as follows:
| Button Number | Corresponding PIN | Function | Description |
|---|---|---|---|
| SW2 | PD2 | Factory Reset | Press button 1 three times to clear the current Thread network configuration and return to an unconfigured state |
| SW3 | PD6 | Trigger BLE Broadcast | Enter pairing mode, the device starts BLE broadcasting and becomes discoverable |
| SW4 | PD7 | Light Control | For bulbs, manually control the light switch. For switches, control the connected bulb's switch |
| SW5 | PF6 | Form Thread Network | The device joins the Thread network with default configuration, for testing purposes only |
LED Status
White LED indicates the current network status of the device:
| Status | Description |
|---|---|
| Short white flashes | Device not configured to a Thread network, Thread not enabled |
| Frequent white flashes | Device configured, Thread enabled, device attempting to join Thread network |
| Long white flashes | Device configured and joined Thread network as a child |
Red and Green LEDs indicate the light status:
-
On
Brightness 0 - 255 (maximum value)
-
Off
Connecting UART Module for Serial Output
The UART module helps us obtain serial debugging information from the Matter device. We can connect the pins as follows:
| UART Module | TLSR9528 Evaluation Board |
|---|---|
| TXD | PB3(pin 1 of J3) |
| RXD | PB2(pin 22 of J3) |
| GND | GND(e.g.pin 3 of J15 or pin 23 of J5) |
Baud rate: 115200 Bits/second,
Data bits: 8,
Parity: None,
Stop bits: 1.
Power Supply Methods
(1) Using USB Power
- Insert the jumper marked in the red box in the picture.
(2) Using Built-in PINs for VBAT
Without a USB cable, the TLSR9528 evaluation board can be powered using built-in PINs.
- Connect the VBAT pin of J5 to a 3.3V power supply.
- Ground the GND pin of J5.
Environment Setup
Install Zephyr Project Environment
Before proceeding with the following steps, perform an APT update and upgrade:
sudo apt update
sudo apt upgrade
(1) Install dependencies
wget https://apt.kitware.com/kitware-archive.sh
sudo bash kitware-archive.sh
sudo apt install --no-install-recommends git cmake ninja-build gperf \
ccache dfu-util device-tree-compiler \
python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \
make gcc gcc-multilib g++-multilib libsdl2-dev
Zephyr currently requires the following minimum versions of the main dependencies: CMake (3.20.0), Python3 (3.6), Devicetree compiler (1.4.6).
cmake --version
python3 --version
dtc --version
Before proceeding to the next step, please verify the installed versions on your system. If necessary, switch the APT mirror to a stable and up-to-date one, or manually update these dependencies.
(2) Install west
pip3 install west
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc
Ensure that ~/.local/bin is in the $PATH environment variable.
(3) Get Zephyr source code
west init ~/zephyrproject
cd ~/zephyrproject
west update
west blobs fetch hal_telink
west zephyr-export
Running west init and west update to get the Zephyr source code in mainland China may take extra time, and some projects may not update from external servers. Please look for alternative methods to download the latest source code.
(4) Install additional Python dependencies required by Zephyr
pip3 install --break-system-packages -r ~/telink_projects/zephyrproject/zephyr/scripts/requirements.txt
(5) Install toolchain
Download the Zephyr toolchain (about 1~2GB) to a local directory, which may take extra time in mainland China.
Execute the following command to download Zephyr SDK v0.16.1:
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.1/zephyr-sdk-0.16.1_linux-x86_64_minimal.tar.gz
Verify the downloaded toolchain archive.
wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.1/sha256.sum | shasum --check --ignore-missing
Add execution permissions.
chmod +x zephyr-sdk-0.16.1_linux-x86_64_minimal.tar.gz
Extract the archive to the specified path.
tar xvf zephyr-sdk-0.16.1_linux-x86_64_minimal.tar.xz
For latest master branch use Zephyr SDK v0.16.1:
Full SDK:
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.1/zephyr-sdk-0.16.1_linux-x86_64.tar.xz
wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.1/sha256.sum | shasum --check --ignore-missing
tar xvf zephyr-sdk-0.16.1_linux-x86_64.tar.xz
cd zephyr-sdk-0.16.1
./setup.sh -t riscv64-zephyr-elf -h -c
You can download and install the Zephyr SDK in the following recommended paths:
$HOME/zephyr-sdk[-x.y.z]
$HOME/.local/zephyr-sdk[-x.y.z]
$HOME/.local/opt/zephyr-sdk[-x.y.z]
$HOME/bin/zephyr-sdk[-x.y.z]
/opt/zephyr-sdk[-x.y.z]
/usr/zephyr-sdk[-x.y.z]
/usr/local/zephyr-sdk[-x.y.z]
[-x.y.z] is the version of the SDK you downloaded, for example, -0.16.1.
Note: After installation, the SDK folder cannot be moved.
Install only the riscv64 toolchain.
cd ~/zephyr-sdk-0.16.1
./setup.sh -t riscv64-zephyr-elf -h -c
(6) Verify installation completion
Before proceeding to install the Matter project environment, build the Hello World example to verify the Zephyr project environment installation.
cd ~/zephyrproject/zephyr
west build -p auto -b tlsr9528a zephyr/samples/hello_world -d build_helloWorld
Use the west build command in the Zephyr root directory folder to build the hello_world example. After the build is complete, you can find a file named zephyr.bin in the build_helloWorld/zephyr folder.
(7) Add Zephyr environment script to Shell
Note: Please append the Zephyr environment configuration script to ~/.bashrc, otherwise you may encounter
west builderrors in subsequent builds.
echo "source ~/zephyrproject/zephyr/zephyr-env.sh" >> ~/.bashrc
Then execute the following command to update the shell environment immediately:
source ~/.bashrc
(8) Add Telink Zephyr remote repository and pull the specified commit source code.
cd ~/zephyrproject/zephyr
git remote add telink https://github.com/telink-semi/zephyr
git fetch telink develop
git checkout develop
cd ..
west update
west blobs fetch hal_telink
(9) (Optional) If you want to switch to another branch or commit after completing all the above steps, just execute the following commands:
git fetch telink
git checkout <your_target_branch_or_commitid>
cd ..
west update
west blobs fetch hal_telink
Matter project setup
This section introduces the steps to get the specified commit on the Matter master branch, matching the Zephyr code pulled in the previous section.
(1) Install dependencies:
sudo apt-get install git gcc g++ pkg-config libssl-dev libdbus-1-dev \
libglib2.0-dev libavahi-client-dev ninja-build python3-venv python3-dev \
python3-pip unzip libgirepository1.0-dev libcairo2-dev libreadline-dev
(2) Clone the Matter project:
Clone the Matter project to a local directory, such as /home/${YOUR_USERNAME}/workspace/matter.
git clone https://github.com/project-chip/connectedhomeip
Where ${YOUR_USERNAME} is your username folder
(3) Switch to the specified commit on the master branch and update submodules.
cd ./connectedhomeip
git checkout master
git submodule update --init --recursive
(4) Run the bootstrap script
Execute bootstrap to prepare the Matter environment. The first run usually takes a long time.
source scripts/bootstrap.sh
Note: Every time you switch commits or change the environment, you may need to rerun the bootstrap script.
This step will generate a hidden folder called .environment in the Matter root directory connectedhomeip. In mainland China, it may take extra time or encounter failures.
Tip: If there are any issues with the Matter build environment, you can try:
1) Remove the environment (in the Matter project root directory):
rm -rf .environment
2) Redo the bootstrap script:
source scripts/bootstrap.sh
(5) (Optional) If you need to switch to another branch or commit, execute the following commands
git fetch origin
git checkout <your_target_branch_or_commitid>
git submodule update --init --recursive
rm -rf .environment
source scripts/bootstrap.sh
You can find more information here: https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/BUILDING.md
Docker Setup
To simplify Zephyr environment setup in sections Zephyr project setup and Telink Flashing tool setup, you can use an existing Docker image with a ready-to-use environment.
Run the Docker container (this will take a while to complete the first time):
docker run -it --rm -v $PWD:/host -w /host ghcr.io/project-chip/chip-build-telink:$(wget -q -O - https://raw.githubusercontent.com/project-chip/connectedhomeip/master/.github/workflows/examples-telink.yaml 2> /dev/null | grep chip-build-telink | awk -F: '{print $NF}')
Telink Flashing Tool Setup
(1) Download Toolchain:
Download and unzip the Telink flasher into your local directory, e.g. ~, to allow you to flash Zephyr into a Telink board.
Windows (GUI version):
wget https://wiki.telink-semi.cn/tools_and_sdk/Tools/BDT/BDT.zip
unzip BDT.zip
Linux (GUI and CLI versions):
wget https://wiki.telink-semi.cn/tools_and_sdk/others/Telink-BDT-Linux-X64-V1.6.4.zip
tar -xvf Telink_Libusb_BDT-Linux-X64-1.6.0.tar
Please note that the download may take several minutes because the zipped file is around hundreds of megabytes. The download may take extra time outside mainland China.
(2) Change udev Rules to use flasher without sudo:
Connect your BDT hardware to USB and check its IDs.
lsusb
...
Bus 001 Device 014: ID 248a:8266 Maxxter Telink Debugger v4.0
...
Update your udev rules: Create edit your udev file.
sudo nano /etc/udev/rules.d/51-usb-device.rules
Add the next line with your USB IDs.
SUBSYSTEM=="usb", ATTRS{idVendor}=="248a", ATTRS{idProduct}=="8266", MODE="0666"
Save file and restart udev subsystem
sudo udevadm control --reload-rules && sudo udevadm trigger
(3) Add BDT path to ~/.bashrc.
Edit
nano ~/.bashrc
Add the next variable according to your BDT path (where you extracted it)
export TELINK_BDT_BASE_DIR="/opt/telink_bdt/"
Compile
Perform the following operations in the Matter root directory. If using a Docker image, perform the operations in /root/chip:
(1) Start the Matter environment:
source scripts/activate.sh
(2) Go to the example directory:
cd examples/*app*/telink
app: lighting-app or light-switch-app
(3) If there is an existing build, delete the directory generated by the previous build:
rm -rf build/
(4) Build the example:
west build -b tlsr9528a
Additionally, in the build command, you need to specify -DFLASH_SIZE according to the flash size of the development board you are using. For example, if you are using a B92 development board with 2MB flash, the build command is:
west build -b tlsr9528a -- -DFLASH_SIZE=2m
You can find the target build file named zephyr.bin in the build/zephyr directory.
Note: Make sure your PC has the
gnbuild tool installed and configured, otherwise you may encounter build errors. Also, remember to executezephyr-env.shin the Zephyr project path, otherwise, you may encounter errors indicating thatwest builddoes not exist.
Compile chip-tool
(1) Start the Matter environment:
source scripts/activate.sh
(2) Go to the example directory:
cd examples/chip-tool
(3) If there is an existing build, delete the directory generated by the previous build:
rm -rf out/
(4) Build chip-tool
gn gen out
ninja -C out
The built file can be found in {MATTER_CHIP_TOOL_EXAMPLE_FOLDER}/out/chip-tool.
For more information about chip-tool, you can click the following link to view: https://github.com/project-chip/connectedhomeip/blob/master/examples/chip-tool/README.md
Firmware Burning
This burning instruction applies to both Windows and Ubuntu platforms. To burn a B92 EVB, you need at least the following hardware:
(1) A B92 EVB evaluation board;
(2) A Burning Evk burner;
(3) Two Mini-USB cables;
If you need to burn multiple B92 EVB evaluation boards simultaneously, please prepare multiple sets of the above hardware. Additionally, you may need a USB Hub with enough interfaces.
BDT and LinuxBDT Download
BDT is a burning and debugging tool that can be obtained from the following link:
Windows 10: http://wiki.telink-semi.cn/tools_and_sdk/Tools/BDT/BDT.zip
Ubuntu 20.04: http://wiki.telink-semi.cn/tools_and_sdk/Tools/BDT/LinuxBDT.tar.bz2
BDT Connection Method
Please follow the diagram below for hardware connection. The diagram shows the status after completing the hardware connection:
Note: Be sure to use the default jumper configuration.
Using BDT on Windows Platform
(1) Connect the burner to the computer's USB port using a USB cable.
(2) Download the BDT burning software, extract it to a local folder, and double-click the executable file "Telink BDT.exe". If everything is normal, you can see the following window display, and the device information of the connected burner can be seen in the system title bar (see the red box in the figure).
(3) Click the "SWS" button in the toolbar. If you see the information in the figure below, it means that all hardware connections are correct.
(4) Set the size of the Flash erase area. Click the "Setting" button in the toolbar. In the pop-up "Setting" window, you can see that the default size of the Flash erase area is 512kB.
Set the size of the Flash erase area to "2040", as shown below:
Note: For the TLSR
Matter Firmware
Bootloader Configuration
The bootloader build is enabled automatically when the CONFIG_CHIP_OTA_REQUESTOR=y is set.
The bootloader configuration file is located at the following path:
connectedhomeip/config/telink/app/bootloader.conf
This file contains the following options:
- CONFIG_BOOT_BOOTSTRAP - set to y in case if restoring the slot0 partition is expected from slot1 partition in case if slot0 is not bootable or damaged
- CONFIG_BOOT_SWAP_USING_MOVE - set to y in case if SWAP_MOVE logic need to be used
- CONFIG_BOOT_SWAP_USING_SCRATCH - set to y in case if SWAP_MOVE using scratch logic need to be used. Enabling this option expecting the availability of scratch partition in DTS
- CONFIG_BOOT_VALIDATE_SLOT0 - set to y in case if the whole slot0 image need to be validated. With this option disabled the only image magic is validated
Other MCUBoot configuration options are also allowed in this file. For finest tune please refer to official MCUBoot doc.
Flash Layout
Implemented as an overlay over standard zephyr .dts layout, which is located in the Matter repository 2MB flash overlay:
...
&flash {
reg = <0x20000000 0x200000>;
/delete-node/ partitions;
partitions {
compatible = "fixed-partitions";
#address-cells = <1>;
#size-cells = <1>;
boot_partition: partition@0 {
label = "mcuboot";
reg = <0x00000000 0x13000>;
};
slot0_partition: partition@13000 {
label = "image-0";
reg = <0x13000 0xec000>;
};
factory_partition: partition@ff000 {
label = "factory-data";
reg = <0xff000 0x1000>;
};
dac_keypair_partition: partition@100000 {
label = "dac-keypair";
reg = <0x100000 0x1000>; //store dac and key pair.
};
descriptor_partition: partition@101000 {
label = "sboot-descriptor";
reg = <0x101000 0x2000>;
};
storage_partition: partition@103000 {
label = "storage";
reg = <0x103000 0xf000>;
};
slot1_partition: partition@112000 {
label = "image-1";
reg = <0x112000 0xec000>;
};
vendor_partition: partition@1fe000 {
label = "vendor-data";
reg = <0x1fe000 0x2000>;
};
};
};
...
Note: The information in the table is for reference only. For the most accurate memory usage, please download the latest Matter code for confirmation.
Device Configuration
Basic Device Configuration
Basic device configuration is already set via application configuration file. The basic configuration can be extended via the same configuration file by adding new configurations to the file.
Application configuration file location (relative path):
examples/app/telink/prj.conf
MTD configuration
# OpenThread configs
CONFIG_OPENTHREAD_MTD=y
CONFIG_OPENTHREAD_FTD=n
FTD configuration example:
# OpenThread configs
CONFIG_OPENTHREAD_MTD=n
CONFIG_OPENTHREAD_FTD=y
BLE Address Configuration
BLE specification contains 4 types of BLE MAC addresses. Matter configuration uses only 2 of them:
- Public
- Random static (with and without flash saving)
The public address is a default address used in Matter. The public address value must be set by device vendor.
The BLE address reads out from the vendor memory area and applies to BLE device during initializing of the BLE driver.
The address type may be changed by the project configuration:
Public address configuration:
CONFIG_B9X_BLE_CTRL_MAC_TYPE_PUBLIC=y
CONFIG_B9X_BLE_PUBLIC_MAC_ADDR="00:11:22:38:c1:a4"
CONFIG_B9X_BLE_CTRL_MAC_TYPE_PUBLIC option sets the BLE address type to Public and enables the address readout from flash.
CONFIG_B9X_BLE_PUBLIC_MAC_ADDR option sets the public BLE address from string, if the address was not set in flash.
CONFIG_B9X_BLE_PUBLIC_MAC_ADDR option should be used for development purposes only.
Random static address configuration:
CONFIG_B9X_BLE_CTRL_MAC_TYPE_RANDOM_STATIC=y
CONFIG_B9X_BLE_CTRL_MAC_FLASH=y
CONFIG_B9X_BLE_CTRL_MAC_TYPE_RANDOM_STATIC option sets BLE address type to Random Static and enables Random address
generation at every device boot.
CONFIG_B9X_BLE_CTRL_MAC_FLASH option allows to store the Static Random address to flash to be used on the next device boot.
Using this option the Random Static address will be generated on the first boot and stored to flash. The next boots will read out and apply the stored Random Static address.
The BLE address location my be vary depends on flash size. The memory map for different flash sizes is shown below:
| Flash Size | Memory Address |
|---|---|
| 1 MB | 0xfd000 |
| 2 MB | 0x1fd000 |
| 4 MB | 0x3fd000 |
The BLE address flash encoding:
Public address:
0-2 bytes are public address bytes.\ 3-5 bytes are vendor bytes provided by BLE consortium.
Random static address:
0-4 bytes are random static bytes.\ 5 byte is a random static byte + 0xC0 mask.\ 6-7 are dummy bytes.\ 8 byte should be 0 for Random static address type.
Example:
Public address: 00:11:22:38:c1:a4 - 00:11:22 public address bytes, 38:c1:a4 - Telink vendor bytes provided by BLE consortium.\
Random static address: 00:11:22:33:44:55:aa
00 - 00:11:22:33:44:55 randomly generated bytes, aa:bb - dummy bytes, 00 - Random static address type.
Network Device Configuration
Device-to-device communication without a border router is available in case when one or several devices are configured as FTD (Full Thread Device), for example, a Light Bulb.
The default configuration for non-sleepy device - is a router. Each router can accept 32 child connections by default.
The amount of child connections is set by the following configuration:
CONFIG_OPENTHREAD_MAX_CHILDREN=1
In case of high network load per router device, this configuration may be set to 1 to reduce the amount of children connected to the parent device.
It is highly recommended to increase the CPU clock to 96MHz if the router mode is planned to use. This can be done by adding the following configuration to the board overlay file:
...
&cpu0 {
clock-frequency = <96000000>;
};
...
The default configuration of non-sleepy device can be manually changed from router to end device, which will disable the router mode.
Disabling the router mode will reduce the network and CPU load on the device and increase the network stability (avoid packet loss and retransmissions).
This configuration switches the FTD Router device to MTD End device:
CONFIG_CHIP_THREAD_DEVICE_ROLE_END_DEVICE=y
If the FTD End device mode is expected, then the FTD mode can be enabled manually:
CONFIG_OPENTHREAD_FTD=y
Build and Flash
In the Matter root folder or /root/chip/ if using Docker image:
(1) Activate Matter environment:
source ./scripts/activate.sh -p all,telink
(2) Activate Zephyr environment (needed for west build using Docker without script build with env):
export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
export ZEPHYR_BASE="$TELINK_ZEPHYR_BASE"
export ZEPHYR_SDK_INSTALL_DIR="$TELINK_ZEPHYR_SDK_DIR"
source $ZEPHYR_BASE/zephyr-env.sh
(3) Go to directory with the example:
cd examples/${app}/telink
${app}: air-quality-sensor-app, all-clusters-app, all-clusters-minimal-app, bridge-app, contact-sensor-app, lighting-app, light-switch-app, lock-app, ota-requestor-app, pump-app, pump-controller-app, resource-monitoring-app, shell, smoke-co-alarm-app, temperature-measurement-app, thermostat, window-app
(4) Remove the previous build if exists:
rm -rf build/
(5) Build the example (replace _
west build -b <build_target>
Also use key -DFLASH_SIZE, if your board has memory size different from 2MB, for example, -DFLASH_SIZE=1m or -DFLASH_SIZE=4m:
$ west build -b <build_target> -- -DFLASH_SIZE=4m
You can find the target built file called zephyr.bin under the build/zephyr directory.
(6) Flash the example (for the Ubuntu platform):
west flash --erase
(7) In case of build errors or crashes you might use the Zephyr version which was CI tested against Chip Project master:
Go to https://github.com/project-chip/connectedhomeip/blob/master/integrations/docker/images/stage-2/chip-build-telink/Dockerfile and look for ZEPHYR_REVISION = ${commit_ID}.
Then use this information to setup Zephyr:
cd ~/zephyrproject/zephyr/
git checkout ${commit_ID}
cd ..
west update
west blobs fetch hal_telink
Logging and Shell CLI
To get output from the device, connect UART to the following pins:
| Name | Pin |
|---|---|
| RX | PB3 (pin 15 of J3) |
| TX | PB2 (pin 18 of J3) |
| GND | GND (pin 23 of J5) |
Baud rate: 115200 bits/s
How to Configure Logging in Matter
Logging is enabled by default. To disable logging in your application, set this config:
In Matter config/telink/app/zephyr.conf, set CONFIG_SERIAL=n:
# Logging (set CONFIG_SERIAL to 'y' to enable logging and 'n' to disable logging)
CONFIG_SERIAL=n
Set Logging Level
To configure the logging level, set the value of the CONFIG_LOG_MAX_LEVEL parameter in Matter config/telink/app/zephyr.conf:
# Set the actual log level
# - 0 OFF, logging is turned off
# - 1 ERROR, maximal level set to LOG_LEVEL_ERR
# - 2 WARNING, maximal level set to LOG_LEVEL_WRN
# - 3 INFO, maximal level set to LOG_LEVEL_INFO
# - 4 DEBUG, maximal level set to LOG_LEVEL_DBG
CONFIG_LOG_MAX_LEVEL=3
The logging level by default is INFO (information).
How to Enable Zephyr Shell in Matter
It's possible to interact with the device via UART with Unix-like shell commands.
To include Shell in your application, set these two configs:
- In Matter config/telink/app/zephyr.conf, set
CONFIG_SHELL=y:
# Shell settings
CONFIG_SHELL=y
- Set
CONFIG_CHIP_LIB_SHELL=yin examples/lighting-app/telink/prj.conf
# CHIP shell
CONFIG_CHIP_LIB_SHELL=y
Now, after the board starts, you may print help and press Enter in the UART terminal to see a list of available CLI commands.
List of Matter commands
Every invoked command must be preceded by the matter prefix.
See the following subsections for the description of each Matter-specific command.
Command - device
Handles a group of commands that are used to manage the device. You must use this command together with one of the additional subcommands listed below.
Subcommand - factoryreset
Performs device factory reset, which is a hardware reset preceded by erasing all Matter settings stored in non-volatile memory.
uart:~$ matter device factoryreset
Performing factory reset ...
Command - onboardingcodes
Handles a group of commands that are used to view information about device onboarding codes. The onboardingcodes command takes one required parameter for the rendezvous type, and an optional parameter for printing a specific type of onboarding code.
The full format of the command is:
onboardingcodes none|softap|ble|onnetwork [qrcode|qrcodeurl|manualpairingcode]
To print all the onboarding codes:
uart:~$ matter onboardingcodes none
QRCode: MT:W0GU2OTB00KA0648G00
QRCodeUrl: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AW0GU2OTB00KA0648G00
ManualPairingCode: 34970112332
To print a specific type of onboarding code:
(1) Subcommand - qrcode
Prints the device onboarding QR code payload. Takes no arguments.
uart:~$ matter onboardingcodes none qrcode
MT:W0GU2OTB00KA0648G00
(2) Subcommand - qrcodeurl
Prints the URL to view the device onboarding QR code in a web browser. Takes no arguments.
uart:~$ matter onboardingcodes none qrcodeurl
https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AW0GU2OTB00KA0648G00
(3) Subcommand - manualpairingcode
Prints the pairing code for the manual onboarding of a device. Takes no arguments.
uart:~$ matter onboardingcodes none manualpairingcode
34970112332
Command - config
Handles a group of commands used to view device configuration information. You can use this command without any subcommand to print all available configuration data or to add a specific subcommand.
VendorId: 65521 (0xFFF1)
ProductId: 32768 (0x8000)
HardwareVersion: 1 (0x1)
FabricId:
PinCode: 020202021
Discriminator: f00
DeviceId:
The config command can also take the subcommands listed below.
(1) Subcommand - pincode
Prints the PIN code for device setup. Takes no arguments.
uart:~$ matter config pincode
020202021
(2) Subcommand - discriminator
Prints the device setup discriminator. Takes no arguments.
uart:~$ matter config discriminator
f00
(3) Subcommand - vendorid
Prints the vendor ID of the device. Takes no arguments.
uart:~$ matter config vendorid
65521 (0xFFFF1)
(4) Subcommand - productid
Prints the product ID of the device. Takes no arguments.
uart:~$ matter config productid
32768 (0x8000)
(5) Subcommand - hardwarever
Prints the hardware version of the device. Takes no arguments.
uart:~$ matter config hardwarever
0 (0x0)
Command - ble
Handles a group of commands used to control the device Bluetooth LE transport state. You must use this command together with one of the additional subcommands listed below.
(1) Subcommand - help
Prints help information about ble commands group.
uart:~$ matter ble help
help Usage: ble <subcommand>
adv Enable or disable advertisement. Usage: ble adv <start|stop|state>
(2) Subcommand - adv start
Enables Bluetooth LE advertising.
uart:~$ matter ble adv start
Starting BLE advertising
(3) Subcommand - adv stop
Disables Bluetooth LE advertising.
uart:~$ matter ble adv stop
Stopping BLE advertising
(4) Subcommand - adv status
Prints information about the current Bluetooth LE advertising status.
uart:~$ matter ble adv state
BLE advertising is disabled
Command - dns
Handles a group of commands used to trigger performing DNS queries. You should use this command together with one of the additional subcommands listed below.
(1) Subcommand - browse
Browses for DNS services of _matterc_udp type and prints the received response. Takes no argument.
uart:~$ matter dns browse
Browsing ...
DNS browse succeeded:
Hostname: 0E824F0CA6DE309C
Vendor ID: 9050
Product ID: 20043
Long discriminator: 3840
Device type: 0
Device name:
Commissioning mode: 0
IP addresses:
fd08:b65e:db8e:f9c7:2cc2:2043:1366:3b31
(2) Subcommand - resolve
Resolves the specified Matter node service given by the \
uart:~$ matter dns resolve <fabric-id> <node-id>
Resolving ...
DNS resolve for 000000014A77CBB3-0000000000BC5C01 succeeded:
IP address: fd08:b65e:db8e:f9c7:8052:1a8e:4dd4:e1f3
Port: 5540
(3) List of Telink CLI commands
Command -telink
Handles a group of Telink commands that are used to manage the device. You should use this command together with one of the additional subcommands listed below.
(1) Subcommand -reboot
Performs board reboot that is hardware reboot calling sys_reboot().
uart:~$ telink reboot
Performing reboot ...
(2) Light-switch-app CLI commands
Light-switch control commands should be available via Shell interface if the CONFIG_CHIP_LIB_SHELL=y is set in examples/light-switch-app/telink/prj.conf
Also CONFIG_SHELL=y should be set in config/telink/app/zephyr.conf to use Shell in Matter
matter switch help
To list all the available light-switch commands, call:
uart:~$ matter switch help
help Usage: switch <subcommand>
onoff Usage: switch onoff <subcommand>
groups Usage: switch groups <subcommand>
binding Usage: switch binding <subcommand>
UI
Buttons
The following buttons are available on TLSR9528A board in matrix configuration:
| Name | Function | Description |
|---|---|---|
| Button 1 | Factory reset | Perform factory reset to forget the currently commissioned Thread network and return to a decommissioned state (to activate, push the button 3 times) |
| Button 2 | Lighting control | Manually triggers the lighting state (only for lightning-app) |
| LightSwitch control | Triggers the light switch state (only for light-switch-app) | |
| Lock state control | Manually triggers the bolt lock state (only for lock-app) | |
| ContactSensor control | Triggers the contact sensor state (only for contact-sensor-app) | |
| Pump control | Manually triggers the pump state (only for pump-app, pump-controller-app) | |
| Window Open/Toggle move type | Single press manually triggers the Window Covering Open command, double toggles Lift-Tilt move type (only for window-app) | |
| Button 3 | Start BLE (optional) | Initiate BLE stack and start BLE advertisement |
| Button 4 | Thread start / Window Close | Commission thread with static credentials and enables the Thread on the device / manually triggers the Window Covering Close command (only for window-app) |
Note:
- When power saving modes(s) are enabled by default only two first buttons are enabled. In that case short TL_Key1 (J20 pin 15) to ground (J50 pin 15-23)
- Some apps will turn on BLE advertising automatically when powered on. Dependency in the app's
prj.conffrom:
# Enable CHIP pairing automatically on application start.
CONFIG_CHIP_ENABLE_PAIRING_AUTOSTART=y
Attention to be paid when you have more than one board flashed at the same time.
Factory reset using power on sequence
If device has no HW Button 1 - Factory reset there is a possibility to perform this action using a power-on sequence.
1) Switch off the device 2) Switch on the device and within 5 seconds after switching it on, switch it off. Repeat this step 5 times, and it triggers a factory reset.
In the lighting application, the main light (not the indication LED) indicates starting the factory reset procedure by 3-times blinking with an interval of 1 second.
By default, this feature is disabled. To enable it, add the following to prj.conf:
CONFIG_CHIP_ENABLE_POWER_ON_FACTORY_RESET=y
LEDs
(1) Indicate the current state of the Thread network
The White LED indicates current state of Thread network. It is able to be in the following states:
| State | Description |
|---|---|
| Blinks with short pulses | The device is not commissioned to Thread, Thread is disabled |
| Blinks with frequent pulses | The device is commissioned, Thread enabled. Device is trying to JOIN thread network |
| Blinks with wide pulses | The device commissioned and joined to the Thread network as a CHILD |
(2) Indicate the identify of the device
The Blue LED is used to identify the device. The LED starts blinking when the Identify command of the Identify cluster is received. The command's argument can be used to specify the the effect. It can be in the following effects:
| Effect | Description |
|---|---|
| Blinks (200 ms on/200 ms off) | Blink (EMBER_ZCL_IDENTIFY_EFFECT_IDENTIFIER_BLINK) |
| Breathe (during 1000 ms) | Breathe (EMBER_ZCL_IDENTIFY_EFFECT_IDENTIFIER_BREATHE) |
| Blinks (50 ms on/950 ms off) | Okay (EMBER_ZCL_IDENTIFY_EFFECT_IDENTIFIER_OKAY) |
| Blinks (1000 ms on/1000 ms off) | Channel Change (EMBER_ZCL_IDENTIFY_EFFECT_IDENTIFIER_CHANNEL_CHANGE) |
| Blinks (950 ms on/50 ms off) | Finish (EMBER_ZCL_IDENTIFY_EFFECT_IDENTIFIER_FINISH_EFFECT) |
| LED off | Stop (EMBER_ZCL_IDENTIFY_EFFECT_IDENTIFIER_STOP_EFFECT) |
(3) Indicate the current state of lightbulb
By default, Red and Green LEDs are used to show the current state of lightbulb (only for lightning-app). Blue LED is by default already occupied with Indication functionality.
(4) Indicate the current state of Contact Sensor, Lock, Pump (Controller) App, Window Cover
The Red LED shows current state of Contact Sensor, Bolt Lock and Pump. Short blinks in the Lock app indicate a transition state from Locked to Unlocked and vice versa. For both Pump apps, the white LED shows the on-off-state of the pump.
Red and Green LEDs indicate the current Window Cover Lift position (PWM in range of 0-254). To indicate the Tilt state in the same way, connect an external LED to the board pin PE0.
Bridge Solution
A Bridge serves to allow the use of non-Matter IoT devices (e.g. devices on a Zigbee or Z-Wave net work, or any other non-Matter connectivity technology) in a Matter Fabric, with the goal of enabling consumers to continue using these non-Matter devices alongside their Matter devices. The Telink Bridge Example demonstrates a simple lighting bridge and the use of dynamic endpoints.
The Bridge device performs the translation between Matter and other protocols allowing Matter nodes to communicate with Bridged Devices. A Bridge may also contain native Matter functionality, for example, it may itself be a Temperature sensor having both Thread and Zigbee connections.
As stated in Matter Specification, this is illustrated in the figure below: the non-Matter devices are exposed as Bridged Devices to Nodes on the Fabric. The Matter Nodes can communicate with both the (native) Matter devices and the Bridged Devices, thanks to the Bridge, which performs the translation between Matter and the other protocol.
Border Router
Overview
This chapter describes the creation of a Border Router for managing Matter devices using the B92 version as an example. The process includes the physical connection of the B92 to the network and integration with Apple, Google, Amazon, and Samsung platforms.
Hardware Required for Matter
- TLSR9528A as the Matter light device
- Suitable Border Router (e.g., Apple HomePod Mini, Google Nest Hub Gen2, Amazon Echo, Samsung SmartThings Station) for integration into the Matter network
- Wireless router providing Internet access for the Border Router
- Appropriate phone (iPhone or Google Pixel6) as the commissioner to control network access and device switching
Software Required for Matter
- Phone operating system with the latest security updates
- Appropriate firmware version for the Border Router and phone
- Telink Matter lighting-app firmware
Border Router Configuration
The OTBR (OpenThread Border Router) requires the following two components:
- Raspberry Pi 4: It is recommended to use the 4GB RAM version of the Raspberry Pi 4. The pre-configured image for Raspberry Pi can be found in the following link on WeiPan:
The default username for the image is pi, and the password is raspberry.
-
Radio Co-Processor: The RCP handles Thread communication and is implemented using a TLSR9528A evaluation board. The RCP firmware is also available at the above WeiPan address:
-
b92-zephyr-rcp-usb-cdc.bin– For B92 dongle, USB connection
Google Matter Topology
Google Matter Connection Steps
(1) Power on the wireless router and configure the WiFi network parameters.
Note: The wireless router needs to be configured with a VPN at this time to access www.google.com normally
(2) Turn on the Bluetooth on the Google phone, connect both the Google phone and Google Nest Hub Gen2 to the same WiFi network, and add the Google Nest Hub Gen2 in the Google Home App.
Google Nest Hub Gen2 configuration tutorial https://support.google.com/googlenest/answer/7029485?hl=en&co=GENIE.Platform%3DAndroid&oco=0
(3) Connect the B92 EVK development board to the power supply, connect the serial port of the development board to the computer via a USB-TTL tool, and then power on the development board.
The PB2-TXD and PB3-RXD of the development board, serial port configuration information 115200, 8N1, open MobaXterm on the computer to view the device output log.
(4) When the red light on the development board flashes briefly, find the QR code URL of the device from MobaXterm (see the red box in the figure).
(5) Copy the URL to the browser to get the QR code.
(6) Open the Google Home App, and click the "+" sign in the upper left corner of the main interface.
(7) Select Set up device.
(8) Select New device.
(9) Choose a home to join.
(10) Select Matter-enabled device type.
(11) Scan the QR code on the browser.
(12) Wait for the device to complete commissioning with Google Nest Hub Gen2.
(13) Set the device name.
(14) Successfully add the Matter device to Google Nest Hub Gen2, 2rd floor light is the newly added B92 EVK development board.
(15) Enter the control interface to control the light's on/off and brightness.
Apple Matter Demo
Overview of Apple Matter Demo
This chapter describes adding the B92 EVK development board as a Matter light device to the Apple HomePod Mini. Users can control the light on the development board via the Home App on an iPhone, including turning the light on/off and adjusting the brightness.
Hardware Required for Apple Matter
- TLSR9528A as the Matter light device
- Apple HomePod Mini as the Border Router of the Matter network
- Wireless router providing a WiFi access point for Apple HomePod Mini to verify data
- iPhone as the Commissioner platform for controlling the light's network access and switching
Software Required for Apple Matter
- iPhone operating system iOS 16.1.2
- Apple HomePod Mini firmware version 16.2
- Telink Matter lighting-app firmware
Apple Matter Topology
Apple Matter Connection Steps
(1) Power on the wireless router and configure the WiFi network parameters.
(2) Turn on the Bluetooth on the iPhone, connect the iPhone to the configured WiFi network, and power on the Apple HomePod Mini. When the white light on the top touchpad starts rotating, bring the iPhone close to the Apple HomePod Mini. When the floating window appears, click setup.
(3) Place the Apple HomePod Mini in the viewfinder.
(4) Wait for the Apple HomePod Mini setup to complete.
(5) Follow the prompts on the phone to successfully add the Apple HomePod Mini to the Home App.
(6) Connect the B92 EVK development board to the power supply, connect the serial port of the development board to the computer, and then power on the development board.
The PB2-TXD and PB3-RXD of the development board, serial port configuration information 115200, 8N1, open MobaXterm on the computer to view the device output log.
(7) When the red light on the development board flashes briefly, find the QR code URL of the device from MobaXterm (see the red box in the figure).
(8) Copy the URL to the browser to get the QR code.
(9) Open the Apple Home App, click the "+" sign in the upper right corner of the main interface, and select Add or Scan Accessory.
(10) Scan the QR code on the browser.
(11) Click "Add to 'Apple Home'".
(12) When the pop-up window appears, click Add Anyway.
(13) Set the device name.
(14) Successfully add the B92 EVK to the Apple HomePod Mini, light-1 is the newly added Matter light device.
(15) Enter the control interface to control the light's on/off and brightness.
Amazon Matter Demo
Overview of Amazon Matter Demo
This chapter describes adding the B92 EVK development board as a Matter device to the Amazon Echo. Users can control the light on the development board via the Amazon Alexa App on a Google phone, including turning the light on/off and adjusting the brightness.
Hardware Required for Amazon Matter
- TLSR9528A as the Matter light device
- Amazon Echo as the Border Router of the Matter network
- Wireless router providing a WiFi access point for Amazon Echo to verify data
- Google Pixel6 phone as the Commissioner platform for controlling the light's network access and switching
Software Required for Amazon Matter
- Google phone system Android 13 with the latest security patch
- Amazon Echo firmware version 0011040824196
- Amazon Alexa App version 2024.20
- Telink Matter lighting-app firmware
Amazon Matter Topology
Amazon Matter Connection Steps
(1) Power on the wireless router and configure the WiFi network parameters.
(2) Turn on the Google phone, and add the Amazon Echo in the Amazon Alexa App.
(3) Connect the B92 EVK development board to the power supply, connect the serial port of the development board to the computer, and then power on the development board.
The PB2-TXD and PB3-RXD of the development board, serial port configuration information 115200, 8N1, open MobaXterm on the computer to view the device output log.
(4) When the white light on the development board flashes briefly, find the QR code URL of the device from MobaXterm (see the red box in the figure).
(5) Copy the URL to the browser to get the QR code.
(6) Open the Amazon Alexa App, and click the "+" sign in the upper left corner of the main interface.
(7) Select Add Device.
(8) Select Matter Device.
(9) Select YES, there is a Matter logo.
(10) Ensure the device is in broadcast state, then select YES, the device is powered on.
(11) Select Scan QR Code.
(12) Scan the QR code on the browser.
(13) Select YES, the device is Matter compatible.
(14) Wait for the device to complete commissioning with Amazon Echo.
(15) Set the device name and room, both can be skipped.
(16) Successfully add the Matter device to Amazon Echo, first light is the newly added B92 EVK development board.
(17) Enter the control interface to control the light's on/off and brightness.
Samsung Matter Demo
Overview of Samsung Matter Demo
This chapter describes adding the B92 EVK development board as a Matter device to the SmartThings Station. Users can control the light on the development board through the SmartThings App on a Google phone, including turning the light on/off and adjusting the brightness.
Hardware Required for Samsung Matter
- TLSR9528A as the Matter light device
- SmartThings Station as the Border Router of the Matter network
- Wireless router providing a WiFi access point for SmartThings Station to verify data
- Google Pixel6 phone as the Commissioner platform for controlling the light's network access and switching
Software Required for Samsung Matter
- Google phone system Android 13 with the latest security patch
- SmartThings Station Hub firmware version 000.053.00019
- SmartThings App version 1.8.18.21
- Telink Matter lighting-app firmware
Samsung Matter Topology
Samsung Matter Connection Steps
(1) Open the SmartThings App, select the "+" in the upper right corner, and choose Add device.
(2) Select Partner devices, and click Add.
(3) Select Matter.
(4) Scan the QR code and select Continue.
(5) Wait for the connection to complete, and set the device name and room.
(6) The device can now be controlled by the SmartThings App.
chip-tool
Build
WARNING: Ensure that the chip tool is built on the same commit as the Matter firmware to prevent compatibility issues.
(1) Activate the environment under the Matter project root directory:
source ./scripts/activate.sh -p all,telink
(2) Update submodules:
./scripts/checkout_submodules.py --allow-changing-global-git-config --shallow --platform linux
(3) Go to the example folder:
cd examples/chip-tool
(4) Remove the previous build if necessary:
rm -rf out/
(5) Build:
gn gen out
ninja -C out
(6) The "chip-tool" binary can be located here:
${MATTER_CHIP_TOOL_EXAMPLE_FOLDER}/out/chip-tool
For more information, visit: https://github.com/project-chip/connectedhomeip/blob/master/examples/chip-tool/README.md
Usage
Commissioning
(1) BLE-Thread commissioning
1) Commission the device with the latest active dataset. See the Get active dataset section under the Border router heading:
./chip-tool pairing ble-thread ${NODE_ID} hex:${DATASET} ${PIN_CODE} ${DISCRIMINATOR}
NODE_ID can be any non-zero value that has not been used before. It acts as a handler for other "chip-tool" operations referring to a specific Matter device.
DATASETs are regenerated by the Thread border router when new Thread networks are formed. They might slightly differ in the middle of the hex string so DO NOT use the dataset from the following command directly. If you forget it, refer back to the Get active dataset section and replace DATASET with the current dataset.
Example:
$ ./chip-tool pairing ble-thread 1234
hex:0e080000000000010000000300000f35060004001fffe002081111111122222222070
8fd61f77bd3df233e051000112233445566778899aabbccddeeff030e4f70656e54687265
616444656d6f010212340410445f2b5ca6f2a93a55ce570a70efeecb0c0402a0fff8
20202021 3840
Commission might take some time. If it's successful, you should see the following message:
Device commissioning completed with success
(2) Clean Initialization of State
In case of failures, the device configuration can be cleared with the following command:
sudo rm -rf /tmp/chip_*
It's highly recommended to use a BLE 5.0 HCI controller on the host machine running "chip-tool". To check HCI version:
hciconfig -a
Thread on Network Commissioning
You can commission an example Matter device without BLE connectivity, relying only on Thread.
(1) Ensure that the OTBR (Open Thread Border Router) is up and running and network has been formed: Refer to the Border Router section of this guide for more details.
(2) Join the Matter Demo device using Button_3 (Joining Thread with hardcoded credentials):
(3) Confirm that the red LED blinks with short pauses:
Beside the LED indication, you can verify the device has joined using OTBR Web GUI (Topology).
(4) Use "chip-tool" for "onnetwork" commissioning:
./chip-tool pairing onnetwork ${NODE_ID) ${PIN_CODE}
Example:
./chip-tool pairing onnetwork 1001 20202021
PIN_CODE can be obtained from Demo Device logs. See the Matter Firmware section of this guide for more details.
Example logs:
I: 536 [DL]Device Configuration:
I: 542 [DL] Serial Number: 11223344556677889900
I: 547 [DL] Vendor Id: 65521 (0xFFF1)
I: 550 [DL] Product Id: 32772 (0x8004)
I: 554 [DL] Product Name: not-specified
I: 560 [DL] Hardware Version: 0
I: 566 [DL] Setup Pin Code (0 for UNKNOWN/ERROR): 20202021
I: 573 [DL] Setup Discriminator (0xFFFF for UNKNOWN/ERROR): 3840 (0xF00)
I: 583 [DL] Manufacturing Date: (not set)
I: 660 [DL] Device Type: 65535 (0xFFFF)
PIN_CODE == 20202021 in this case.
(1) Troubleshooting:
1) Ensure OTBR local interface accessibility via IPV6:
Obtain the IPv6:LocalAddress (OTBR Web GUI->Status) and ping it.
Example:
$ ping6 fd11:22:0:0:7b6a:4020:5b68:b403
PING fd11:22:0:0:7b6a:4020:5b68:b403(fd11:22::7b6a:4020:5b68:b403) 56 data bytes
64 bytes from fd11:22::7b6a:4020:5b68:b403: icmp_seq=1 ttl=64 time=0.540 ms
64 bytes from fd11:22::7b6a:4020:5b68:b403: icmp_seq=2 ttl=64 time=0.601 ms
64 bytes from fd11:22::7b6a:4020:5b68:b403: icmp_seq=3 ttl=64 time=0.587 ms
If the ping fails, proceed to step 4.
2) Ping Matter Device from OTBR.
To retrieve the IP address of the Matter example device, rebuild and reflash the firmware with the Zephyr console enabled (refer to the Matter Firmware section for more details).
In the Zephyr console:
uart:~$ ot ipaddr
fd11:22:0:0:1092:f710:43ba:bdb4
fdec:6dcd:f157:35fd:0:ff:fe00:9819
fdec:6dcd:f157:35fd:b409:ae04:2a3:fd74
fe80:0:0:0:1cef:9af0:c6a2:ab51
Done
Select the address that corresponds with the OTBR IPv6:LocalAddress, e.g.,
fd11:22:0:0:1092:f710:43ba:bdb4
Ping it from the OTBR console:
pi@raspberrypi:~ $ ping6 fd11:22:0:0:1092:f710:43ba:bdb4
PING fd11:22:0:0:1092:f710:43ba:bdb4(fd11:22::1092:f710:43ba:bdb4) 56 data bytes
64 bytes from fd11:22::1092:f710:43ba:bdb4: icmp_seq=1 ttl=64 time=24.5 ms
64 bytes from fd11:22::1092:f710:43ba:bdb4: icmp_seq=2 ttl=64 time=23.2 ms
64 bytes from fd11:22::1092:f710:43ba:bdb4: icmp_seq=3 ttl=64 time=22.2 ms
If the ping fails, verify your OTBR installation and the formation of the Thread Network. Examine /var/log/messages for potential errors.
3) Ping Matter Device from host PC.
Using the Matter Demo Device address obtained in Step 2, ping the address from the host PC (the machine running chip-tool).
If the ping from the host PC is successful, the on-network pairing for the chip-tool should also work. Clear the cached data:
sudo rm -rf /tmp/chip_*
./chip-tool pairing onnetwork ${NODE_ID) ${PIN_CODE}
If the ping fails, unplugging and replugging the Ethernet connector from the OTBR might help.
4) Examine routing on the host PC (PC running chip-tool):
$ sudo ip -6 route
::1 dev lo proto kernel metric 256 pref medium
2001:db7::/64 dev enp3s0 proto ra metric 100 pref medium
fd11:22::/64 via fe80::ba27:ebff:fe66:30f4 dev enp3s0 proto ra metric 100 pref medium
fe80::/64 dev tun0 proto kernel metric 256 pref medium
fe80::/64 dev enp3s0 proto kernel metric 1024 pref medium
default dev lo proto ra metric 1024 pref medium
You should observe a route towards the IPv6:LocalAddress subnet of the OTBR.
For instance:
fd11:22::/64 via fe80::ba27:ebff:fe66:30f4 dev enp3s0 proto ra metric 100 pref medium
This address should match the "link" address of the eth0 interface of OTBR, which can be retrieved using the 'ifconfig' command on OTBR ssh terminal):
$ ifconfig
eth0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500
inet 192.168.15.128 netmask 255.255.255.0 broadcast 192.168.15.255
inet6 fe80::ba27:ebff:fe66:30f4 prefixlen 64 scopeid 0x20<link>
inet6 2001:db7::ba27:ebff:fe66:30f4 prefixlen 64 scopeid 0x0<global>
ether b8:27:eb:66:30:f4 txqueuelen 1000 (Ethernet)
RX packets 297312 bytes 35495992 (33.8 MiB)
RX errors 0 dropped 0 overruns 0 frame 0
TX packets 14017 bytes 7107662 (6.7 MiB)
TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
If a route entry is missing, ensure that the _meshcop._udp service published by the OTBR is available on your PC using:
avahi-browse -r -t _meshcop._udp
This should return an entry coresponding to OTBR:
+ enp3s0 IPv6 OpenThread BorderRouter #8F53 _meshcop._udp local
+ enp3s0 IPv4 OpenThread BorderRouter #8F53 _meshcop._udp local
= enp3s0 IPv6 OpenThread BorderRouter #8F53 _meshcop._udp local
hostname = [raspberrypi-2.local]
address = [192.168.15.128]
port = [49153]
txt = ["omr=@\253\017\000\"\000\000\000\000" "dn=DefaultDomain" "bb=\240\191" "sq=\005" "pt=j\021\023\015" "at=\000\000\000\000\000\001\000\000" "sb=\000\000\001\177" "xa=n\190\155[\218\029\143S" "tv=1.3.0" "xp=\017\017\017\017\"\"\"\"" "nn=OpenThreadDemo" "mn=BorderRouter" "vn=OpenThread" "rv=1"]
= enp3s0 IPv4 OpenThread BorderRouter #8F53 _meshcop._udp local
hostname = [raspberrypi-2.local]
address = [192.168.15.128]
port = [49153]
txt = ["omr=@\253\017\000\"\000\000\000\000" "dn=DefaultDomain" "bb=\240\191" "sq=\005" "pt=j\021\023\015" "at=\000\000\000\000\000\001\000\000" "sb=\000\000\001\177" "xa=n\190\155[\218\029\143S" "tv=1.3.0" "xp=\017\017\017\017\"\"\"\"" "nn=OpenThreadDemo" "mn=BorderRouter" "vn=OpenThread" "rv=1"]
Visit https://openthread.io/guides/border-router/mdns-discovery#avahi_utilities for more details.
Lightbulb Control
(1) Switch on the light:
./chip-tool onoff on ${NODE_ID} 1
| Argument | Description |
|---|---|
| onoff | Cluster name |
| on | Command to the cluster |
| ${NODE_ID} | Unique node ID of the device. Should be greater than 0 |
| 1 | ID of the endpoint |
(2) Switch off the light:
./chip-tool onoff off ${NODE_ID} 1
| Argument | Description |
|---|---|
| onoff | Cluster name |
| off | Command to the cluster |
| ${NODE_ID} | Unique node ID of the device. Should be greater than 0 |
| 1 | ID of the endpoint |
(3) Read the light state:
./chip-tool onoff read on-off ${NODE_ID} 1
| Argument | Description |
|---|---|
| onoff | Cluster name |
| read | Command to the cluster |
| ${NODE_ID} | Unique node ID of device. Should be greater than 0 |
| 1 | ID of the endpoint |
(4) Change brightness of the light:
./chip-tool levelcontrol move-to-level 32 0 0 0 ${NODE_ID} 1
| Argument | Description |
|---|---|
| levelcontrol | Cluster name |
| move-to-level | Command to the cluster |
| 32 | Brightness value |
| 0 | Transition time |
| 0 | Option mask |
| 0 | Option override |
| ${NODE_ID} | Unique node ID of device. Should be greater than 0 |
| 1 | ID of the endpoint |
(5) Read brightness level:
./chip-tool levelcontrol read current-level ${NODE_ID} 1
| Argument | Description |
|---|---|
| levelcontrol | Cluster name |
| read | Command to the cluster |
| current-level | Attribute to read |
| ${NODE_ID} | Unique node ID of device. Should be greater than 0 |
| 1 | ID of the endpoint |
(6) Change the color of light (only for RGB LED mode, see Indicate current state of lightbulb for more details):
./chip-tool colorcontrol move-to-hue-and-saturation 120 250 0 0 0 ${NODE_ID} 1
| Argument | Description |
|---|---|
| colorcontrol | Cluster name |
| move-to-hue-and-saturation | Command to the cluster |
| 120 | Hue value |
| 250 | Saturation value |
| 0 | Transition time |
| 0 | Option mask |
| 0 | Option override |
| ${NODE_ID} | Unique node ID of device. Should be greater than 0 |
| 1 | ID of the endpoint |
Binding Cluster and Endpoints
Binding is the process that links clusters and endpoints on different devices, which enables them to communicate with each other.
To successfully perform binding, a controller is required. This controller should be able to write the binding table on the light switch device and write appropriate ACL to the light bulb endpoint in the Lighting Example application.
One such controller that can be used is the CHIP Tool.
The ACL should comprise information about all clusters that the light switch application may call.
More details on interacting with ZCL clusters can be found in the user guide of CHIP Tool.
You can perform the binding process to a single remote endpoint (unicast binding) or to multiple remote endpoints (group multicast).
Note: If you're using a light switch without brightness dimmer, only the first binding command with cluster number 6 needs to be applied.
(1) Unicast Binding to a Remote Endpoint using the CHIP Tool
In this scenario, we are considering a network with a light switch device having nodeId = <light-switch-node-id> and a light bulb device with nodeId = <lighting-node-id>. Both devices should be commissioned to the same Matter network.
Steps for Unicast Binding:
1) Add ACL to the development kit that is programmed with the Lighting Application Example by running the following command:
./chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": [<light-switch-node-id>], "targets": [{"cluster": 6, "endpoint": 1, "deviceType": null}, {"cluster": 8, "endpoint": 1, "deviceType": null}]}]' <lighting-node-id> 0
In this command:
[...]is JSON format message for attr-value so<light-switch-node-id>must be a real number when the command is executed.<lighting-node-id>can be a shell variable as ${NODE_ID} used for commissioning before.{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}is an ACL for the communication with the CHIP Tool.{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [<light-switch-node-id>], "targets": [{"cluster": 6, "endpoint": 1, "deviceType": null}, {"cluster": 8, "endpoint": 1, "deviceType": null}]}is an ACL for binding (cluster no. 6 is the On/Off cluster, and the cluster no. 8 is the Level Control cluster).
This command adds permissions to the lighting application device that allows it to receive commands from the light switch device.
2) Add a binding table to the Light Switch binding cluster:
./chip-tool binding write binding '[{"fabricIndex": 1, "node": <lighting-node-id>, "endpoint": 1, "cluster": 6}]' <light-switch-node-id> 1
In this command:
[...]is JSON format message for attr-value so<lighting-node-id>must be real numbers when the command is executed.<light-switch-node-id>can be a shell variable such as ${SWITCH_NODE_ID} used by chip-tool to do commissioning with Lighting Switch App.{"fabricIndex": 1, "node": <lighting-node-id>, "endpoint": 1, "cluster": 6}is a binding for the On/Off cluster.
(2) Group Multicast Binding to the Group of Remote Endpoints using the CHIP Tool
With group multicast binding, a single light switch can control multiple lighting devices simultaneously.
The group multicast binding targets all development kits that are programmed with the Lighting Application Example and added to the same multicast group.
After binding, the light switch sends multicast commands which all devices in the group will execute.
In this scenario, the commands are provided for a light switch device with the nodeId = <light-switch-node-id> and light bulb devices each with nodeId = <lighting-node-id>, all in the same Matter network.
Steps for Group Multicast Binding:
1) Add the light switch device to the multicast group by running the following command:
./chip-tool tests TestGroupDemoConfig --nodeId <light-switch-node-id>
<light-switch-node-id>can be a shell variable such as ${SWITCH_NODE_ID} used by chip-tool to do commissioning with Lighting Switch App.
2) Add all light bulbs to the same multicast group by applying command below for each of the light bulbs, using the appropriate <lighting-node-id> (the user-defined ID of the node being commissioned except <light-switch-node-id> due to use this <light-switch-node-id> for light-switch) for each of them:
./chip-tool tests TestGroupDemoConfig --nodeId <lighting-node-id>
<lighting-node-id>can be shell variables as ${NODE_ID}s used for commissioning before.
3) Add Binding commands for group multicast:
./chip-tool binding write binding '[{"fabricIndex": 1, "group": 257}]' <light-switch-node-id> 1
<light-switch-node-id>can be a shell variable such as ${SWITCH_NODE_ID} used for commissioning before.
Testing the communication
To test the communication between the light switch device and the bound devices, refer to the light switch buttons.
OTA with Linux OTA Provider
The OTA feature is enabled by default only for the "ota-requestor-app" example. If you wish to enable the OTA feature for another Telink example:
- set
CONFIG_CHIP_OTA_REQUESTOR=yin the respective "prj.conf" configuration file.
Upon building the application with the OTA feature enabled, utilize the following binary files:
- merged.bin: This is the primary binary for flashing the PCB (Use 2MB PCB).
- matter.ota: This is the binary for OTA Provider.
All binaries will have the same SW version. To test OTA, the "matter.ota" should have a higher SW version than the base SW.
Set CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=2 in corresponding "prj.conf" configuration file.
-
For Matter v1.0-branch branch, the default swap mode that run with the scratch partition is (
BOOT_SWAP_USING_SCRATCH). -
For Matter master branch, the default swap mode that can run without a scratch partition is (
BOOT_SWAP_USING_MOVE).
If you want to switch back to BOOT_SWAP_USING_SCRATCH for the master branch:
(1) Modify the CONFIG_BOOT_SWAP_USING_MOVE=n and CONFIG_BOOT_SWAP_USING_SCRATCH=y config in the bootloader.conf file.
(2) Add scratch_partition into tlsr9258a_2m_flash.overlay. More details can be found in the Flash Layout section and in the partition layout examples provided below.
The following are possible scratch partition layouts. Depending on your needs, you can choose the layout that fits best. Note: the larger scratch partition results in faster swapping, but it also reduces the partition sizes for code (slot0 and slot1).
32kB:
...
&flash {
reg = <0x20000000 0x200000>;
/delete-node/ partitions;
partitions {
compatible = "fixed-partitions";
#address-cells = <1>;
#size-cells = <1>;
boot_partition: partition@0 {
label = "mcuboot";
reg = <0x00000000 0x13000>;
};
slot0_partition: partition@13000 {
label = "image-0";
reg = <0x13000 0xef000>;
};
scratch_partition: partition@1ef000 {
label = "image-scratch";
reg = <0x1ef000 0x8000>;
};
factory_partition: partition@1f7000 {
label = "factory-data";
reg = <0x1f7000 0x1000>;
};
storage_partition: partition@1f8000 {
label = "storage";
reg = <0x1f8000 0xc000>;
};
slot1_partition: partition@1fe000 {
label = "image-1";
reg = <0x1fe000 0xef000>;
};
vendor_partition: partition@2ed000 {
label = "vendor-data";
reg = <0x2ed000 0x2000>;
};
};
};
...
(3) Verify and correct the offset (seek) if partitions have been modified or moved. Refer to the CMakeLists.txt and generate_factory_data.cmake.
(4) Optionally, to slightly decrease the swapping time, firmware verification for "slot0" can be disabled by setting the CONFIG_BOOT_VALIDATE_SLOT0=n for "build_mcuboot" in the "connectedhomeip/config/telink/app/bootloader.conf" file. However, this is not recommended.
For more MCUBoot options please refer to the Bootloader section in chapter 4 of this manual.
OTA Usage:
(1) Build the Linux OTA Provider:
./scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/ota-provider-app chip_config_network_layer_ble=false
(2) Run the Linux OTA Provider with OTA image:
./chip-ota-provider-app -f matter.ota
Here:
- matter.ota is the firmware to be updated.
Please keep this terminal window till the end of test. For "chip-tool" open a separate terminal window.
(3) In a new terminal, provision the Linux OTA Provider using "chip-tool":
./chip-tool pairing onnetwork ${OTA_PROVIDER_NODE_ID} 20202021
Here:
- ${OTA_PROVIDER_NODE_ID} is the node id of Linux OTA Provider. It is similar to NODE_ID for lighting-app. It should be a unique, non-zero value.
(4) Commission device (SeeCommissioning):
./chip-tool pairing ble-thread ${DEVICE_NODE_ID} hex:${DATASET} ${PIN_CODE} ${DISCRIMINATOR}
(5) Configure the Matter device with the default OTA Provider:
./chip-tool otasoftwareupdaterequestor write default-otaproviders '[{"fabricIndex": 1, "providerNodeID": ${OTA_PROVIDER_NODE_ID}, "endpoint": 0}]' ${DEVICE_NODE_ID} 0
(6) Configure the OTA Provider's access control list (ACL) that grants _Operate_ privileges to all nodes in the fabric. This is necessary to enable the nodes to send cluster commands to the OTA Provider:
./chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": null}]' ${OTA_PROVIDER_NODE_ID} 0
(7) Initiate the DFU procedure in one of the following methods:
- If you've built the device firmware with
-DCONFIG_CHIP_LIB_SHELL=yoption, which enables Matter shell commands, run the following command on the device shell:
matter ota query
- Alternatively, use chip-tool to send the "Announce OTA Provider" command to the device. The numeric arguments in sequence are: Provider Node ID, Provider Vendor ID, Announcement Reason, Provider Endpoint ID, Requestor Node ID and Requestor Endpoint ID.
./chip-tool otasoftwareupdaterequestor announce-otaprovider ${OTA_PROVIDER_NODE_ID} 0 0 0 ${DEVICE_NODE_ID} 0
After the device recognizes the OTA Provider node, it will automatically check the OTA Provider for a new firmware image.
Once the firmware image download is complete, the device will restart automatically to apply the update.
chip-device-ctrl.py
Build
(1) Activate environment under the Matter project root directory:
source ./scripts/activate.sh -p all,telink
(2) Build:
scripts/build_python.sh -m platform
Usage
Run
(1) Activate the Python environment:
source out/python_env/bin/activate
(2) Launch:
sudo out/python_env/bin/chip-device-ctrl
Commissioning
(1) Set the active dataset (Note: They are different once a new Thread network is generated. Please ensure to replace the dataset in the following command with the latest one. See Get active dataset paragraph in the Border router section):
chip-device-ctrl > set-pairing-thread-credential 0e08000000000001000000
0300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47
f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c
0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8
(2) Connect via BLE:
chip-device-ctrl > connect -ble 3840 20202021 ${NODE_ID}
(3) Wait until commissioning is complete. If everything is okay you shall see the following message.
Commissioning complete
Lightbulb control
Toggle the light:
chip-device-ctrl > zcl OnOff Toggle ${NODE_ID} 1 0
Configuring factory data for the Telink examples
Factory data is a set of device parameters written to the non-volatile memory during the manufacturing process. This guide describes the process of creating and programming factory data using Matter and the Telink platform from Telink Semiconductor.
The factory data parameter set includes different types of information, such as device certificates, cryptographic keys, device identifiers, and hardware. All these parameters are vendor-specific and must be inserted into a device's persistent storage during the manufacturing process. The factory data parameters are read at the boot time of a device. Then, they can be used in the Matter stack and user application (for example, during commissioning).
All of the factory data parameters are protected against modifications by the software, and the firmware data parameter set must be kept unchanged during the lifetime of the device. When implementing your firmware, you must ensure that the factory data parameters are not rewritten or overwritten during the Device Firmware Update or factory resets, except in some vendor-defined cases.
For the Telink platform, the factory data is stored by default in a separate partition of the internal flash memory.
- Overview
- Enabling factory data support
- Generating factory data
- Building an example with factory data
- Programming factory data
- Using own factory data implementation
Overview
You can implement the factory data set described in the factory data component table in various ways, as long as the final HEX/BIN file contains all mandatory components defined in the table. In this guide, the generating factory data and the building an example with factory data sections describe one of the implementations of the factory data set created by the Telink platform's maintainers. At the end of the process, you get a HEX file that contains the factory data partition in the CBOR format.
The factory data accessor is a component that reads and decodes factory data parameters from the device's persistent storage and creates an interface to provide all of them to the Matter stack and to the user application.
The default implementation of the factory data accessor assumes that the factory data stored in the device's flash memory is provided in the CBOR format. However, it is possible to generate the factory data set without using the Telink scripts and implement another parser and a factory data accessor. This is possible if the newly provided implementation is consistent with the Factory Data Provider.
For more information about preparing a factory data accessor, see the section about using own factory data implementation.
Note: Encryption and security of the factory data partition is not provided yet for this feature.
Factory data component table
The following table lists the parameters of a factory data set:
| Key name | Full name | Length | Format | Conformance | Description |
|---|---|---|---|---|---|
count |
number of factory binaries | 4 B | uint32 | optional | The number of manufacturing partition binaries to generate. Default is 1. |
output |
output directory | N/A | ASCII string | optional | Output path where generated data will be stored. |
spake2-path |
spake2 path | N/A | ASCII string | mandatory | Provide Spake2+ tool path |
chip-tool-path |
chip tool path | N/A | ASCII string | mandatory | Provide chip-tool path |
chip-cert-path |
chip cert path | N/A | ASCII string | mandatory | Provide chip-cert path |
overwrite |
overwrite | N/A | bool | optional | If output directory exists, this argument allows generating new factory data and overwriting it. |
in-tree |
in Matter tree | N/A | bool | optional | Use it only when building factory data from Matter source code. |
passcode |
SPAKE passcode | 4 B | uint32 | optional | A pairing passcode is a 27-bit unsigned integer that serves as a proof of possession during the commissioning. Its value must be restricted to the values from 0x0000001 to 0x5F5E0FE (00000001 to 99999998 in decimal), excluding the following invalid passcode values: 00000000, 11111111, 22222222, 33333333, 44444444, 55555555, 66666666, 77777777, 88888888, 99999999, 12345678, 87654321. |
spake2-it |
SPAKE2+ iteration counter | 4 B | uint32 | mandatory | A SPAKE2+ iteration counter is the amount of PBKDF2 (a key derivation function) interactions in a cryptographic process used during SPAKE2+ Verifier generation. |
discriminator |
Discriminator | 2 B | uint16 | mandatory | A 12-bit value matching the field of the same name in the setup code. The discriminator is used during the discovery process. |
commissioning-flow |
commissioning flow | 4 B | uint32 | optional | Device commissioning flow, 0:Standard, 1:User-Intent, 2:Custom. Default is 0. choices=[0, 1, 2] |
discovery-mode |
discovery mode | 4 B | uint32 | optional | Commissionable device discovery networking technology. 0:WiFi-SoftAP, 1:BLE, 2:On-network. Default is BLE. choices=[0, 1, 2] |
vendor-id |
vendor ID | 2 B | uint16 | mandatory | A CSA-assigned ID for the organization responsible for producing the device. |
vendor-name |
vendor name | <1, 32> B | ASCII string | mandatory | A human-readable vendor name that provides a simple string containing identification of device's vendor for the application and Matter stack purposes. |
product-id |
product ID | 2 B | uint16 | mandatory | A unique ID assigned by the device vendor to identify the product. It defaults to a CSA-assigned ID that designates a non-production or test product. |
product-name |
product name | <1, 32> B | ASCII string | mandatory | A human-readable product name that provides a simple string containing identification of the product for the application and the Matter stack purposes. |
hw-ver |
hardware version | 2 B | uint16 | mandatory | A hardware version number that specifies the version number of the hardware of the device. The value meaning and the versioning scheme is defined by the vendor. |
hw-ver-str |
hardware version string | <1, 64> B | uint16 | mandatory | A hardware version string parameter that specifies the version of the hardware of the device as a more user-friendly value than that presented by the hardware version integer value. The value meaning and the versioning scheme is defined by the vendor. |
mfg-date |
manufacturing date | <8, 10> B | ISO 8601 | mandatory | A manufacturing date specifies the date that the device was manufactured. The date format used is ISO 8601, for example YYYY-MM-DD. |
serial-num |
serial number | <1, 32> B | ASCII string | mandatory | A serial number parameter defines a unique number of the manufactured device. The maximum length of the serial number is 32 characters. |
enable-rotating-device-id |
enable rotating device id | N/A | bool | optional | Enable Rotating device id in the generated binaries. |
rd-id-uid |
rotating device ID unique ID | <16, 32> B | byte string | mandatory | The unique ID for the rotating device ID, which consists of a randomly-generated 128-bit (or longer) octet string. This parameter should be protected against reading or writing over-the-air after initial introduction into the device, and stay fixed during the lifetime of the device. |
cert |
certificate path | N/A | ASCII string | optional | The input certificate file in PEM format. |
key |
certificate key path | N/A | ASCII string | optional | The input key file in PEM format. |
cert-dclrn |
certificate declaration path | N/A | ASCII string | mandatory | The certificate declaration file in DER format. |
dac-cert |
DAC certificate path | N/A | ASCII string | optional | The input DAC certificate file in PEM format. |
dac-key |
DAC certificate key path | N/A | ASCII string | optional | The input DAC private key file in PEM format. |
lifetime |
certificate lifetime | 4 B | uint32 | optional | Lifetime of the generated certificate. Default is 4294967295 if not specified, indicating that certificate does not have a well-defined expiration date. |
valid-from |
certificate start date | <8, 19> B | ISO 8601 | optional | The start date for the certificate validity period in format YYYY-MM-DD [ HH:MM:SS ]. Default is the current date. |
paa |
PAA | N/A | bool | optional | Use input certificate cert as PAA certificate. |
pai |
PAI | N/A | bool | optional | Use input certificate cert as PAI certificate. |
offset |
factory partition offset | 4 B | uint32 | mandatory | Partition offset - an address in devices NVM memory, where factory data will be stored. |
size |
factory partition size | 2 B | uint16 | mandatory | The maximum partition size. |
Factory data format
The factory data set must be saved into a HEX/BIN file that can be written to the flash memory of the Matter device.
In the Telink example, the factory data set is represented in the CBOR format and is stored in a HEX/BIN file. The file is then programmed to a device.
All parameters of the factory data set are either mandatory or optional:
- Mandatory parameters must always be provided, as they are required, for example, to perform commissioning to the Matter network.
- Optional parameters can be used for development and testing purposes. For example, the
userdata parameter consists of all data that is needed by a specific manufacturer and that is not included in the mandatory parameters.
In the factory data set, the following formats are used:
- uint16 and uint32 - These are the numeric formats representing, respectively, two-bytes length unsigned integers and four-bytes length unsigned integers. This value is stored in a HEX file in the big-endian order.
- Byte string - This parameter represents the sequence of integers between
0and255(inclusive), without any encoding. - ASCII string is a string representation in ASCII encoding without null-terminating.
- ISO 8601 format is a date format that represents a date provided in the
YYYY-MM-DDorYYYYMMDDformat. - All certificates stored in factory data are provided in the X.509 format.
Enabling factory data support
By default, factory data support is disabled in all Telink examples, and the Telink devices use predefined parameters from the Matter core, which you should not change. To start using factory data stored in the flash memory and the Factory Data Provider from the Telink platform, build an example with the following option:
west build -- -DCONFIG_CHIP_FACTORY_DATA=y
Generating factory data
This section describes how to generate a factory data partition image.
Dependencies
Please make sure you have the following tools before using the generator tool:
Build Matter tools
(1) Using the following commands to generate chip-tool, spake2p and chip-cert at path/to/connectedhomeip/build/out/host:
cd path/to/connectedhomeip
source ./scripts/activate.sh -p all,telink
gn gen build/out/host
ninja -C build/out/host
cd path/to/connectedhomeip/scripts/tools/telink/
python3 -m pip install -r requirements.txt
(2) Add the tools path to $PATH:
export PATH="$PATH:path/to/connectedhomeip/build/out/host"
Preparing factory data partition on a device
The factory data partition is an area in the device’s persistent storage where a factory data set is stored.
This area is configured in the DTS file. connectedhomeip/tree/master/src/platform/telink/tlsr9518adk80d_2m_flash.overlay within which all partitions are declared.
To prepare an example that supports factory data, add a partition called factory-data to the tlsr9518adk80d.dts/tlsr9518adk80d.overlay file. The partition size should be a multiple of one flash page (for B91 SoCs, a single page size equals 4 kB).
See Flash Layout for an example of a factory data partition in the tlsr9518adk80d.dts/tlsr9518adk80d.overlay file.
The factory-data partition size has been set to one flash page (4 kB).
Script usage
To use this script, complete the following steps:
(1) Navigate to the connectedhomeip root directory.
(2) Run the script with -h option to see all possible options:
python scripts/tools/telink/mfg_tool.py -h
(3) Prepare a list of arguments:
a. Fill up all mandatory arguments:
--serial-num, --vendor-id, --product-id, --vendor-name, --product-name, --mfg-date, --hw-ver, --hw-ver-str, --enable-rotating-device-id, --spake2-path, --chip-tool-path, --chip-cert-path, --offset, --size
b. Add output file path:
--output <output_dir>
c. Add path to Certificate Declaration (mandatory):
-cd <path to Certificate Declaration in der format>
d. Specify which certificate will be used:
- User:
--dac-cert <path to DAC certificate in pem format>
--dac-key <path to DAC key in pem format>
--cert <path to PAI certificate in pem format>
--key <path to PAI key in pem format>
--pai
- Generate DAC and PAI:
--cert <path to PAA certificate in pem format>
--key <path to PAA key in pem format>
--paa
e. Add the new unique ID for rotating device ID using one of the following options:
- Provide an existing ID:
--rdid--uid <rotating device ID unique ID>
- Generate a new ID and provide it:
--enable-rotating-device-id
f. (optional) Specify your own passcode:
--passcode <passcode>
g. (optional) Specify your own discriminator:
--discriminator <discriminator>
h. (optional) Add the request to overwrite existing output files:
--overwrite
i. Specify partition offset and size:
--offset <partition_address_in_memory>
--size <partition_size>
In this command:
-
Important note:
For Matter v1.0-branch branch use:
--offset 0xf4000 --size 0x1000
For Matter v1.1-branch branch use:
--offset 0x104000 --size 0x1000
For latest Matter master branch use:
--offset 0x107000 --size 0x1000
(4) Run the script using the prepared list of arguments:
python3 mfg_tool.py <arguments>
For example, a final invocation of the Python script can look similar to the following one:
$ python3 scripts/tools/telink/mfg_tool.py \
--vendor-id 0xFFF2 --product-id 0x8001 \
--serial-num AABBCCDDEEFF11223344556677889900 \
--vendor-name "Telink Semiconductor" \
--product-name "not-specified" \
--mfg-date 2022-12-12 \
--hw-ver 1 \
--hw-ver-str "prerelase" \
--enable-rotating-device-id \
--pai \
--key ./credentials/test/attestation/Chip-Test-PAI-FFF2-8001-Key.pem \
--cert ./test/attestation/Chip-Test-PAI-FFF2-8001-Cert.pem \
-cd ./credentials/test/certification-declaration/Chip-Test-CD-FFF2-8001.der \
--spake2-path ./build/out/host/spake2p \
--chip-tool-path ./build/out/host/chip-tool \
--chip-cert-path ./build/out/host/chip-cert
--out ./factory_data
As the result of the above example files listed below will be created:
factory_data
├── device_sn.csv
└── fff2_8001
└── aabbccddeeff11223344556677889900
├── factory_data.bin
├── factory_data.hex
├── internal
│ ├── DAC_cert.der
│ ├── DAC_cert.pem
│ ├── DAC_key.pem
│ ├── DAC_private_key.bin
│ ├── DAC_public_key.bin
│ └── pai_cert.der
├── onb_codes.csv
├── pin_disc.csv
├── qrcode.png
└── summary.json
(5) (optional example) Generate 5 factory partitions [Optional argument : --count]
This will generate 5 unique Factory Data Partition images, for 5 devices we can consider "production batch". For each partition unique data like key, certificate, serial number etc. will be generated.
$ python3 mfg_tool.py --count 5 -v 0xFFF2 -p 0x8001 \
--serial-num AABBCCDDEEFF11223344556677889900 \
--vendor-name "Telink Semiconductor" \
--product-name "not-specified" \
--mfg-date 2022-02-02 \
--hw-ver 1 \
--hw-ver-str "prerelase" \
--enable-rotating-device-id \
--pai \
--key /path/to/connectedhomeip/credentials/test/attestation/Chip-Test-PAI-FFF2-8001-Key.pem \
--cert /path/to/connectedhomeip/credentials/test/attestation/Chip-Test-PAI-FFF2-8001-Cert. pem \
-cd /path/to/connectedhomeip/credentials/test/certification-declaration/ Chip-Test-CD-FFF2-8001.der \
--spake2-path /path/to/spake2p \
--chip-tool-path /path/to/chip-tool \
--chip-cert-path /path/to/chip-cert
As the result of the above example files listed below will be created:
out
├── device_sn.csv
└── fff2_8001
├── aabbccddeeff11223344556677889900
│ ├── factory_data.bin
│ ├── factory_data.hex
│ ├── internal
│ │ ├── DAC_cert.der
│ │ ├── DAC_cert.pem
│ │ ├── DAC_key.pem
│ │ ├── DAC_private_key.bin
│ │ ├── DAC_public_key.bin
│ │ └── pai_cert.der
│ ├── onb_codes.csv
│ ├── pin_disc.csv
│ ├── qrcode.png
│ └── summary.json
├── aabbccddeeff11223344556677889901
│ ├── factory_data.bin
│ ├── factory_data.hex
│ ├── internal
│ │ ├── DAC_cert.der
│ │ ├── DAC_cert.pem
│ │ ├── DAC_key.pem
│ │ ├── DAC_private_key.bin
│ │ ├── DAC_public_key.bin
│ │ └── pai_cert.der
│ ├── onb_codes.csv
│ ├── pin_disc.csv
│ ├── qrcode.png
│ └── summary.json
├── aabbccddeeff11223344556677889902
│ ├── factory_data.bin
│ ├── factory_data.hex
│ ├── internal
│ │ ├── DAC_cert.der
│ │ ├── DAC_cert.pem
│ │ ├── DAC_key.pem
│ │ ├── DAC_private_key.bin
│ │ ├── DAC_public_key.bin
│ │ └── pai_cert.der
│ ├── onb_codes.csv
│ ├── pin_disc.csv
│ ├── qrcode.png
│ └── summary.json
└── aabbccddeeff11223344556677889903
├── factory_data.bin
├── factory_data.hex
├── internal
│ ├── DAC_cert.der
│ ├── DAC_cert.pem
│ ├── DAC_key.pem
│ ├── DAC_private_key.bin
│ ├── DAC_public_key.bin
│ └── pai_cert.der
├── onb_codes.csv
├── pin_disc.csv
├── qrcode.png
└── summary.json
Note: By default, overwriting the existing output directory is disabled. This means that you cannot create a new directory with the same name in the exact location as an existing file. To allow overwriting, add the
--overwriteoption to the argument list of the Python script.
Building an example with factory data
You can manually generate the factory data set using the instructions described in the Generating factory data section. Another way is to use the Telink platform build system that creates factory data content automatically using Kconfig options and includes the content in the final firmware binary.
To enable generating the factory data set automatically, go to the example's directory and build the example with the following option:
west build -- -DCONFIG_CHIP_FACTORY_DATA=y -DCONFIG_CHIP_FACTORY_DATA_BUILD=y
Alternatively, you can also add CONFIG_CHIP_FACTORY_DATA_BUILD=y Kconfig setting to the example's prj.conf file.
Each factory data parameter has a default value. These are described in the Kconfig file. Setting a new value for the factory data parameter can be done either by providing it as a build argument list or by using interactive Kconfig interfaces.
Providing factory data parameters as a build argument list
This way for providing factory data can be used with a third-party build script, as it uses only one command. All parameters can be edited manually by providing them as an additional option for the west command:
west build -- -DCONFIG_CHIP_FACTORY_DATA=y --DCONFIG_CHIP_FACTORY_DATA_BUILD=y --DCONFIG_CHIP_DEVICE_DISCRIMINATOR=0xF11
Alternatively, you can add the relevant Kconfig option lines to the example's prj.conf file.
Programming factory data
The HEX/BIN file containing factory data can be programmed into the device's flash memory using BDT Tool and the Telink burning key.
Another way to program the factory data to a device is to use the Telink platform build system described in Building an example with factory data, and build an example with the additional option -DCONFIG_CHIP_FACTORY_DATA_MERGE_WITH_FIRMWARE=y:
$ west build -- \
-DCONFIG_CHIP_FACTORY_DATA=y \
-DCONFIG_CHIP_FACTORY_DATA_BUILD=y \
-DCONFIG_CHIP_FACTORY_DATA_MERGE_WITH_FIRMWARE=y
For better understanding various possibilities, see the table below:
| Mode (described in the table below) | (1) | (2) | (3) | (4) |
|---|---|---|---|---|
| CONFIG_CHIP_FACTORY_DATA | n | y | y | y |
| CONFIG_CHIP_FACTORY_DATA_BUILD | don't care | don't care | y | n |
| CONFIG_CHIP_FACTORY_DATA_MERGE_WITH_FIRMWARE | don't care | n | y | y |
| Mode | Description |
|---|---|
| (1) | hardcoded values will be taken |
| (2) | Factory data partition image won't be merged into final binary. Partition image has to be flashed in the other way or a runtime error will be reported on startup, since factory data accessor expects the partition to be in place |
| (3) | Factory data partition image will be created by the build system and merged into the main binary. Recommended for development purposes. |
| (4) | Build system expects externally generated factory data partition image (e.g., generated by the script described in "Script Usage" chapter) at the path used in connectedhomeip/config/telink/chip-module/CMakeLists.txt (e.g., ${PROJECT_BINARY_DIR}/factory/factory_data.bin ) |
You can also build an example with auto-generation of new CD, DAC and PAI certificates. The newly generated certificates will be added to factory data set automatically. To generate new certificates, disable using default certificates by building an example with the additional option -DCHIP_FACTORY_DATA_USE_DEFAULT_CERTS=n:
$ west build -- \
-DCONFIG_CHIP_FACTORY_DATA=y \
-DCONFIG_CHIP_FACTORY_DATA_BUILD=y \
-DCONFIG_CHIP_FACTORY_DATA_MERGE_WITH_FIRMWARE=y \
-DCONFIG_CHIP_FACTORY_DATA_USE_DEFAULT_CERTS=n
Note: To generate new certificates using the Telink platform build system, you need the
chip-certexecutable in your system variable PATH. To learn how to getchip-cert, go to the note at the end of Creating a factory data partition with the second script section, and then add the newly built executable to the system variable PATH. The Cmake build system will find this executable automatically.
After that, use the following command from the example's directory to write firmware and newly generated factory data at the same time:
west flash
Using own factory data implementation
The factory data generation process described above is only an example valid for the Telink platform. You can create a HEX file containing all Factory data component table in any format and then implement a parser to read out all parameters and pass them to a provider. Each manufacturer can implement a factory data set on its own by implementing a parser and a factory data accessor inside the Matter stack. Use the Telink Provider and FactoryDataParser as examples.
You can read the factory data set from the device's flash memory in different ways, depending on the purpose and the format. In the Telink example, the factory data is stored in the CBOR format. The device uses the Factory Data Parser to read out raw data, decode it, and store it in the FactoryData structure. The Factor Data Provider implementation uses this parser to get all needed factory data parameters and provide them to the Matter core.
In the Telink example, the FactoryDataProvider is a template class that inherits from DeviceAttestationCredentialsProvider, CommissionableDataProvider, and DeviceInstanceInfoProvider classes. Your custom implementation must also inherit from these classes and implement their functions to get all factory data parameters from the device's flash memory. These classes are virtual and need to be overridden by the derived class. To override the inherited classes, complete the following steps:
(1) Override the following methods:
// ===== Members functions that implement the DeviceAttestationCredentialsProvider
CHIP_ERROR GetCertificationDeclaration(MutableByteSpan & outBuffer) override;
CHIP_ERROR GetFirmwareInformation(MutableByteSpan & out_firmware_info_buffer) override;
CHIP_ERROR GetDeviceAttestationCert(MutableByteSpan & outBuffer) override;
CHIP_ERROR GetProductAttestationIntermediateCert(MutableByteSpan & outBuffer) override;
CHIP_ERROR SignWithDeviceAttestationKey(const ByteSpan & messageToSign, MutableByteSpan & outSignBuffer) override;
// ===== Members functions that implement the CommissionableDataProvider
CHIP_ERROR GetSetupDiscriminator(uint16_t & setupDiscriminator) override;
CHIP_ERROR SetSetupDiscriminator(uint16_t setupDiscriminator) override;
CHIP_ERROR GetSpake2pIterationCount(uint32_t & iterationCount) override;
CHIP_ERROR GetSpake2pSalt(MutableByteSpan & saltBuf) override;
CHIP_ERROR GetSpake2pVerifier(MutableByteSpan & verifierBuf, size_t & verifierLen) override;
CHIP_ERROR GetSetupPasscode(uint32_t & setupPasscode) override;
CHIP_ERROR SetSetupPasscode(uint32_t setupPasscode) override;
// ===== Members functions that implement the DeviceInstanceInfoProvider
CHIP_ERROR GetVendorName(char * buf, size_t bufSize) override;
CHIP_ERROR GetVendorId(uint16_t & vendorId) override;
CHIP_ERROR GetProductName(char * buf, size_t bufSize) override;
CHIP_ERROR GetProductId(uint16_t & productId) override;
CHIP_ERROR GetSerialNumber(char * buf, size_t bufSize) override;
CHIP_ERROR GetManufacturingDate(uint16_t & year, uint8_t & month, uint8_t & day) override;
CHIP_ERROR GetHardwareVersion(uint16_t & hardwareVersion) override;
CHIP_ERROR GetHardwareVersionString(char * buf, size_t bufSize) override;
CHIP_ERROR GetRotatingDeviceIdUniqueId(MutableByteSpan & uniqueIdSpan) override;
(2) Move the newly created parser and provider files to your project directory.
(3) Add the files to the CMakeList.txt file.
(4) Disable building both the default and the Telink implementations of factory data providers to start using your own implementation of factory data parser and provider. This can be done in one of the following ways:
- Add
CONFIG_CHIP_FACTORY_DATA_CUSTOM_BACKEND=yKconfig setting toprj.conffile. - Or build an example with following option:
west build -- -DCONFIG_CHIP_FACTORY_DATA_CUSTOM_BACKEND=y
Power Management for Telink examples
Low power device configuration
Low power configuration options:
- CONFIG_PM - y or n - should be y to enable the basic Low Power mode
- CONFIG_CHIP_ENABLE_SLEEPY_END_DEVICE_SUPPORT = y or n - should be y to enable the support for Thread Sleepy End Device, depends on CONFIG_OPENTHREAD_MTD=y
Optional tuning:
- CONFIG_CHIP_ENABLE_PM_DURING_BLE - y or n - should be y to enable the basic Low Power mode during BLE operation, by default the option is equal to CONFIG_PM
- CONFIG_TELINK_BUTTON_MANAGER_IRQ_MODE - y or n - should be y to enable buttons processing in an IRQ mode instead of polling mode, by default the option is equal to CONFIG_PM. The option n activates the button polling loop with 10ms polling period.
- CONFIG_TELINK_ENABLE_APPLICATION_STATUS_LED - y or n - should be n to disable Status LED, by default the option is opposite to CONFIG_PM
- CONFIG_CHIP_ICD_SLOW_POLL_INTERVAL = 0..65535 - default: 1000 - used to tune Thread Sleepy End Device slow mode poll interval
- CONFIG_CHIP_ICD_FAST_POLLING_INTERVAL = 0..65535 - default: 200 - used to tune Thread Sleepy End Device fast mode poll interval
- CONFIG_CHIP_ICD_IDLE_MODE_INTERVAL = 0..65535 - default: 120 - used to tune Thread Sleepy End Device idle mode poll interval
- CONFIG_CHIP_ICD_ACTIVE_MODE_INTERVAL = 0..65535 - default: 300 - used to tune Thread Sleepy End Device active mode interval
- CONFIG_CHIP_ICD_ACTIVE_MODE_THRESHOLD = 0..65535 - default: 300 - used to tune Thread Sleepy End Device active mode threshold
The configuration option CONFIG_TELINK_BUTTON_MANAGER_IRQ_MODE requires reconnection of the buttons by the following schematic and requires the external buttons usage in case of using the TLSR9218ADK80d or TLSR9528A EVK.
TLSR9528A EVK pin configuration:
| Name | Pin |
|---|---|
| BUTTON_1 | PD1 (pin 10 of J5) |
| BUTTON_2 | PD7 (pin 12 of J5) |
| BUTTON_3 | PD6 (pin 14 of J5) |
| BUTTON_4 | PF6 (pin 29 of J5) |
The second side buttons pins need to be connected together and connected to the GND. In case of using TLSR9218ADK80d or TLSR9528A EVK any GND pin on the back side of the board can be selected.
This kind of connection pulls the GPIO up internally and the button event comes by FALLING EDGE on GPIO.
Custom RF power values
Setting max RF power configuration example:
# Custom RF power values
CONFIG_B9X_BLE_CTRL_RF_POWER=9
CONFIG_OPENTHREAD_DEFAULT_TX_POWER=9
Note:
- CONFIG_OPENTHREAD_DEFAULT_TX_POWER and CONFIG_B9X_BLE_CTRL_RF_POWER is a value in dBm, valid range: -30 .. 9, default: 3.
- CONFIG_CHIP_OPENTHREAD_TX_POWER used in the previous version. Deprecated and removed from the latest SDK.
- CONFIG_B9X_BLE_CTRL_RF_POWER was a bool parameter used in the previous SDK version. The parameter type has been changed to integer in the latest SDK version.
Additional peripheral configuration
Each hardware module in the MCU consumes additional power, which is sometimes unwanted. The GPIO, UART, SPI, etc. consumes quite a lot of power, so keeping these peripherals enabled is not a good idea if they are not used. Also, dynamic peripheral configuration can be used in case of external IRQ to keep the peripheral off during sleep.
Here is a table with power consumption of some peripheral in a suspend mode:
| Peripheral | Power Consumption |
|---|---|
| UART | 180uA |
| SPI | 335uA |
| I2C | 630uA |
| GPIO | 130uA + pu/pd |
Power measurements data
By default both of TLSR9 MCUs support deep sleep mode with RAM retention. TLSR9218ADK80d has 64KB of retention RAM, TLSR9528a has 96Kb of retention RAM. The default app used for measurements is Light Switch App, consumes 89KB of retention RAM. So the measurement results below contain only the data for TLSR9528a as it has 96KB of retention RAM.
Telink TLSR9218ADK80D
(1) Power consumption table
The data collected in this table is provided for reference. The standard Matter advertising period, SED interval is used. The data collected by the user can be different because of measurements inaccuracy, project configuration, power supply.
All the data provided in this table was collected with fixed RF power of +2.8dB. The LightSwitch sample was used.
| Mode | Mode Period | Power Consumption |
|---|---|---|
| BLE Advertisement | 60 ms | 655uA |
| BLE Advertisement | 150 ms | 295uA |
| BLE Advertisement optional | 1000 ms | 91uA |
| BLE Connection Interval | 45 ms | 785uA |
| BLE Connection Request | 25 ms | 11.3mA |
| BLE Commissioning | 8260 ms | 3.1mA |
| Thread SED (ICD Slow Polling) | 1000 ms | 150.9uA |
| Thread SED (ICD Fast Polling) | 200 ms | 535.9uA |
| Thread SED (ICD Slow Polling) | 10000 ms | 56.0uA |
| Thread SED (ICD Fast Polling) | 2000 ms | 149.7uA |
| Thread Activity (TRX 96 bytes) | 8.6 ms | 12.58mA |
| MCU Suspend | All idle time | 45.6uA |
(2) Calculated lifetime
The basic Matter scenario is waiting for commissioning in BLE mode for only 15 min after power-on. During this period, a 150ms advertisement interval is used. After the 15-min commissioning window closes, the application enters suspend mode indefinitely until an IRQ event or reset occurs.
After successful commissioning, BLE shuts down and the Thread network becomes active. In this scenario, a 1000ms polling interval is used. The battery lifetime can be predicted for both scenarios. However, The user-specific scenarios can't be predicted, because they vary based on user preferences and habits.
| Mode | Mode Period | Current cost | Battery Lifetime (100mAh) |
|---|---|---|---|
| Commissioning mode | |||
| BLE Advertisement | 150 ms | 74 uAh | |
| MCU Suspend | All idle time | 99926uAh | 91 day |
| Thread operation mode | |||
| Thread SED (ICD Slow Polling) | 1000 ms | 151 uAh | 27 days |
| Thread SED (ICD Slow Polling) | 10000 ms | 56 uAh | 74 days |
Telink TLSR9528A
(1) Power consumption table
The data collected in this table is provided for reference. The standard Matter advertising period, SED interval is used. The data collected by the user can be different because of measurements inaccuracy, project configuration, power supply. All the data provided in this table was collected with fixed RF power of +2.8db. The LightSwitch sample was used.
The BLE consumption data below is common for Suspend and Deep Sleep modes:
| Mode | Mode Period | Power Consumption |
|---|---|---|
| BLE Advertisement | 60 ms | 718uA |
| BLE Advertisement | 150 ms | 342.6uA |
| BLE Advertisement optional | 1000 ms | 158uA |
| BLE Connection Interval | 45 ms | 623.7uA |
| BLE Connection Request | 1.95 s | 9.6mA |
| BLE Commissioning | 23510 ms | 2.27mA |
Thread suspend mode:
| Mode | Mode Period | Power Consumption |
|---|---|---|
| Thread SED (ICD Slow Polling) | 1000 ms | 247uA |
| Thread SED (ICD Fast Polling) | 200 ms | 715.7uA |
| Thread SED (ICD Slow Polling) | 10000 ms | 148.6uA |
| Thread SED (ICD Fast Polling) | 2000 ms | 956.8uA |
| Thread Activity (TRX 96 bytes) | 10.2 ms | 11.8mA |
| MCU Suspend | All idle time | 136.9uA |
Thread deep sleep mode:
| Mode | Mode Period | Power Consumption |
|---|---|---|
| Thread SED (ICD Slow Polling) | 1000 ms | 194uA |
| Thread SED (ICD Fast Polling) | 200 ms | 997.5uA |
| Thread SED (ICD Slow Polling) | 10000 ms | 23uA |
| Thread SED (ICD Fast Polling) | 2000 ms | 95.5uA |
| Thread Activity (TRX 96 bytes) | 17.8 ms | 10.24mA |
| MCU Suspend | All idle time | 4.6uA |
(2) Calculated lifetime
The basic Matter scenario is waiting for commissioning in BLE mode for only 15 min after power-on. During this period, a 150ms advertisement interval is used. After the 15-min commissioning window closes, the application enters suspend mode indefinitely until an IRQ event or reset occurs.
After successful commissioning, BLE shuts down and the Thread network becomes active. In this scenario, a 1000ms polling interval is used. The battery lifetime can be predicted for both scenarios. However, The user-specific scenarios can't be predicted, because they vary based on user preferences and habits.
| Mode | Mode Period | Current cost | Battery Lifetime (100mAh) |
|---|---|---|---|
| Commissioning mode | |||
| BLE Advertisement | 150 ms | 88 uAh | |
| MCU Suspend | All idle time | 99926uAh | 91 day |
| Thread operation mode (Suspend) | |||
| Thread SED (ICD Slow Polling) | 1000 ms | 247 uAh | 16 days |
| Thread SED (ICD Slow Polling) | 10000 ms | 149 uAh | 27 days |
| Thread operation mode (Deep Sleep) | |||
| Thread SED (ICD Slow Polling) | 1000 ms | 194 uAh | 21 days |
| Thread SED (ICD Slow Polling) | 10000 ms | 95 uAh | 43 days |
Power measurements graph
Telink TLSR9218ADK80D
Telink TLSR9528A
(1) BLE Mode
(2) Thread mode (MCU Suspend)
(3) Thread mode (MCU Deep Sleep)
Will be provided later.
Using NFC Tags with Telink Examples
NFC Configuration
Enable NFC Functionality:
- Set
CONFIG_CHIP_NFC_COMMISSIONINGto y (yes) or n (no). For enabling NFC functionality, it should be set to y.
Optional Tuning:
-
NFC Board Replacement: If alternative NFC boards with compatible drivers are available, they can be used.
-
Configuration Adjustments: Modify the following in
KConfig(located atconnectedhomeip/config/telink/chip-module/): -
For a different NFC board's connection type, change the setting in
CHIP_NFC_COMMISSIONINGto imply I2C. -
For a different NFC board model, adjust
CHIP_NFC_COMMISSIONINGto imply ST25DVXXKC, based on the Zephyr drivers.
Note:
The current branch of the Zephyr project does not support NFC devices. Utilize the specific Zephyr branch at this GitHub link for NFC functionality.
NFC Board Hardware Connection
Currently, the Zephyr drivers support only the ST25DVXXKC NFC device. To connect it to the Telink EVK board, use the following pin configuration:
TLSR9528A EVK Pin Configuration:
| Name | Pin |
|---|---|
| SCL | PC0 (pin 11 of J3) |
| SDA | PC1 (pin 13 of J3) |
| GND | GND (pin 7 of J15) |
| +3.3V | TL_VBAT (pin 3 of J15, without removing jumper) |
Note:
For I2C devices, ensure the presence of pull-up resistors. If absent, add external 5kΩ resistors on the SCL and SDA lines.
NFC Usage
Simply tap your smartphone on the NFC tag and select an app (e.g., Google Home) to begin the commissioning process.
Adding a New NFC Board
(1) Choose an NFC board with I2C, SPI, or another interface supported by Telink EVK boards.
(2) Incorporate the new NFC driver into the Zephyr project: (zephyr/drivers/nfc/, zephyr/include/drivers/nfc/).
(3) Add the NFC device to Telink DTS (boards/riscv/tlsr9518adk80d/tlsr9528a-common.dtsi).
(4) Change the NFC device in the Matter project's KConfig (connectedhomeip/config/telink/chip-module/):
-
For your new NFC board's connection type, adjust the setting in
CHIP_NFC_COMMISSIONINGto imply I2C. -
For your new NFC board's model, set
CHIP_NFC_COMMISSIONINGto imply ST25DVXXKC, following the Zephyr drivers.