Skip to content

Commit 09228a5

Browse files
Thomas-DepperugeGerritsen
Thomas-Deppe
authored and
rugeGerritsen
committed
Samples: Bluetooth: Add peripheral with multiple identities sample
Adding a peripheral sample where a single physical device can create and manage multiple advertisers, making it appear as multiple distinct devices. The peripheral will set up as many advertisers as defined by CONFIG_BT_EXT_ADV_MAX_ADV_SET. Each advertisers will each contain a unique identity and therefore random address. Once a disconnected event is received the associated advertiser will immediately start again. Signed-off-by: Thomas Deppe <[email protected]>
1 parent ea19874 commit 09228a5

File tree

11 files changed

+549
-0
lines changed

11 files changed

+549
-0
lines changed

‎CODEOWNERS

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -451,6 +451,7 @@
451451
/samples/bluetooth/peripheral_rscs/ @nrfconnect/ncs-si-muffin
452452
/samples/bluetooth/peripheral_status/ @nrfconnect/ncs-si-muffin
453453
/samples/bluetooth/peripheral_uart/ @nrfconnect/ncs-si-muffin
454+
/samples/bluetooth/peripheral_with_multiple_identities/ @nrfconnect/ncs-dragoon
454455
/samples/bluetooth/radio_coex_1wire/ @nrfconnect/ncs-dragoon
455456
/samples/bluetooth/radio_notification_cb/ @nrfconnect/ncs-dragoon
456457
/samples/bluetooth/rpc_host/ @nrfconnect/ncs-si-muffin

‎doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -299,6 +299,7 @@ Bluetooth samples
299299

300300
* The :ref:`channel_sounding_ras_reflector` sample demonstrating how to implement a Channel Sounding Reflector that exposes the Ranging Responder GATT Service.
301301
* The :ref:`channel_sounding_ras_initiator` sample demonstrating basic distance estimation with Channel Sounding by setting up a Channel Sounding Initiator that acts as a Ranging Requestor GATT Client.
302+
* The :ref:`bt_peripheral_with_multiple_identities` sample demonstrating how to use a single physical device to create and manage multiple advertisers, making it appear as multiple distinct devices by assigning each a unique identity.
302303
* Support for the ``nrf54l15dk/nrf54l05/cpuapp`` and ``nrf54l15dk/nrf54l10/cpuapp`` board targets in the following samples:
303304

304305
* :ref:`direct_test_mode`

‎samples/bluetooth/peripheral_with_multiple_identities/CMakeLists.txt

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
#
2+
# Copyright (c) 2024 Nordic Semiconductor ASA
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
cmake_minimum_required(VERSION 3.20.0)
7+
8+
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
9+
project(peripheral_with_multiple_identities)
10+
11+
target_sources(app PRIVATE src/main.c)

‎samples/bluetooth/peripheral_with_multiple_identities/Kconfig.sysbuild

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
#
2+
# Copyright (c) 2024 Nordic Semiconductor
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
source "${ZEPHYR_BASE}/share/sysbuild/Kconfig"
8+
9+
config NRF_DEFAULT_BLUETOOTH
10+
default y
11+
12+
config NRF_DEFAULT_IPC_RADIO
13+
default y

‎samples/bluetooth/peripheral_with_multiple_identities/README.rst

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
.. _bt_peripheral_with_multiple_identities:
2+
3+
Bluetooth: Peripheral with multiple identities
4+
##############################################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
The sample demonstrates how to use a single physical device to create and manage multiple advertisers, making it appear as multiple distinct devices by assigning each a unique identity.
11+
You can use this sample to test a central device that requires connections to multiple peripheral devices when you do not have several development kits available.
12+
13+
Requirements
14+
************
15+
16+
The sample supports the following development kits:
17+
18+
.. table-from-sample-yaml::
19+
20+
Overview
21+
********
22+
23+
Each Bluetooth® device is identified by its identity address.
24+
When a peripheral is advertising, it uses this identity address or generates an address from this address using an Identity Resolving Key (IRK).
25+
The sample application starts multiple connectable advertisers, each with their own identity, allowing a single device to advertise as multiple devices.
26+
27+
This sample has the following features:
28+
29+
* It uses a single physical device to emulate multiple Bluetooth advertisers.
30+
* Each advertiser is assigned a unique identity and a corresponding random static address, ensuring they can be distinctly identified.
31+
* Advertisers are restarted upon disconnection.
32+
33+
Number of advertisers
34+
=====================
35+
36+
The sample sets up and starts as many advertisers as specified by the :kconfig:option:`CONFIG_BT_EXT_ADV_MAX_ADV_SET` Kconfig option.
37+
If the values specified in the configurations are not equal, additional considerations are required to ensure proper setup and restarting of each advertiser.
38+
39+
Creating multiple identities
40+
============================
41+
42+
The :c:func:`create_id` function configures a new identity by passing an identity value within the range ``0`` to the value set in the :kconfig:option:`CONFIG_BT_ID_MAX` Kconfig option.
43+
44+
The identities are created using the :c:func:`bt_id_create` API, where both arguments are set to ``NULL``.
45+
This generates a new random static address and a random IRK for the identity.
46+
Alternatively, you can pass a specific address and IRK values can be passed to customize the identity's configuration.
47+
48+
Setting up and initializing advertisers
49+
=======================================
50+
51+
Each advertiser is set up as a *connectable legacy advertiser* with a long advertising interval.
52+
You can adjust these values to specific use cases using the :c:struct:`bt_le_adv_param` structure.
53+
Set the :c:member:`bt_le_adv_param.id` field to assign a given identity to an advertiser.
54+
55+
The extended advertising version of the API is used as it supports multiple advertising instances and sets.
56+
These instances are stored in an array where the advertiser's identity serves as the index, to simplify the retrieval and management.
57+
A unique name is generated for each advertiser combining :kconfig:option:`CONFIG_BT_DEVICE_NAME` with its identity.
58+
This is set by using the :c:func:`bt_le_ext_adv_set_data` function.
59+
60+
Starting an advertiser
61+
======================
62+
63+
A work item is initialized for each advertiser to ensure that tasks are executed independently, preventing race conditions and avoiding blocking within callback functions.
64+
Each advertiser's work item is submitted to the work queue, where it is started using the :c:func:`bt_le_ext_adv_start` function.
65+
By default, this function does not attempt to resume connectable advertising after a connection is established.
66+
67+
Connection callbacks
68+
====================
69+
70+
After the initial setup of each advertiser, the sample continues to execute asynchronously using callbacks to define its behavior.
71+
The sample uses the following two connection callbacks (see the :c:struct:`bt_conn_cb` structure):
72+
73+
* Connected callback - When a connection is established, the sample prints the central's address.
74+
* Disconnected callback - When a disconnection occurs, the central's address is printed along with the advertiser that was disconnected.
75+
The identity associated with the connection is retrieved by calling the :c:func:`bt_conn_get_info()` function to obtain :c:member:`bt_conn_info.id`.
76+
The work item (advertiser) associated with this identity is submitted to the work queue to restart the advertiser.
77+
The identity is used as the index to retrieve the associated advertiser from the array.
78+
79+
Extending the sample
80+
====================
81+
82+
You can also add the following features to this sample:
83+
84+
* Increase the number of advertisers - Modify the configuration options listed above to support more advertisers.
85+
* Customize individual advertisers - Extend the :c:struct:`advertiser_info` structure to customize advertising parameters, advertising data, and a name for each advertiser.
86+
* Custom advertising data - Customize the advertising data to include additional information, in addition to supporting scan responses.
87+
* Reuse identities for multiple advertisers - Once all identities have been initialized, the sample supports reuse for other advertisers.
88+
* Advanced features - Extend the sample to implement other Bluetooth features or use it in conjunction with other samples.
89+
90+
Configuration
91+
*************
92+
93+
|config|
94+
95+
Check and configure the following Kconfig options:
96+
97+
* :kconfig:option:`CONFIG_BT_ID_MAX` defines how many identities will be used.
98+
99+
* :kconfig:option:`CONFIG_BT_MAX_CONN` defines how many connections can be established.
100+
The sample expects this configuration to be set to the same value as :kconfig:option:`CONFIG_BT_ID_MAX`.
101+
102+
* :kconfig:option:`CONFIG_BT_EXT_ADV_MAX_ADV_SET` defines the maximum number of advertising sets available.
103+
The sample expects this configuration to be set to the same value as :kconfig:option:`CONFIG_BT_ID_MAX`.
104+
105+
* :kconfig:option:`CONFIG_BT_DEVICE_NAME` defines the base name given to each advertiser.
106+
107+
Building and running
108+
********************
109+
110+
.. |sample path| replace:: :file:`samples/bluetooth/peripheral_with_multiple_identities`
111+
112+
.. include:: /includes/build_and_run_ns.txt
113+
114+
Testing
115+
=======
116+
117+
|test_sample|
118+
119+
1. |connect_kit|
120+
#. |connect_terminal|
121+
#. Start the `nRF Connect for Mobile`_ application on your smartphone or tablet.
122+
123+
There should now be multiple devices advertising with the name ``Nordic Peripheral ID`` followed by the ID.
124+
#. Connect to the device and observe that the central's address is printed.
125+
#. Disconnect from any device and observe that the correct advertiser is disconnected.
126+
#. The disconnected advertiser is restarted.
127+
#. In the **SCANNER** tab, observe that there are still the configured number of advertisers.
128+
129+
Sample output
130+
=============
131+
132+
The result should look similar to the following output::
133+
134+
I: SoftDevice Controller build revision:
135+
I: d6 da c7 ae 08 db 72 6f |......ro
136+
I: 2a a3 26 49 2a 4d a8 b3 |*.&I*M..
137+
I: 98 0e 07 7f |....
138+
I: HW Platform: Nordic Semiconductor (0x0002)
139+
I: HW Variant: nRF52x (0x0002)
140+
I: Firmware: Standard Bluetooth controller (0x00) Version 58.49843 Build 3849690618
141+
I: Identity: FA:BB:79:57:D6:45 (random)
142+
I: HCI: version 6.0 (0x0e) revision 0x1055, manufacturer 0x0059
143+
I: LMP: version 6.0 (0x0e) subver 0x1055
144+
Bluetooth initialized
145+
Starting 20 advertisers
146+
Using current id: 0
147+
Created Nordic Peripheral ID: 0: 0x2000bce8
148+
Advertiser 0 successfully started
149+
New id: 1
150+
Using current id: 1
151+
Created Nordic Peripheral ID: 1: 0x2000bd00
152+
Advertiser 1 successfully started
153+
New id: 2
154+
Using current id: 2
155+
Created Nordic Peripheral ID: 2: 0x2000bd18
156+
Advertiser 2 successfully started
157+
New id: 3
158+
Using current id: 3
159+
Created Nordic Peripheral ID: 3: 0x2000bd30
160+
Advertiser 3 successfully started
161+
New id: 4
162+
Using current id: 4
163+
Created Nordic Peripheral ID: 4: 0x2000bd48
164+
Advertiser 4 successfully started
165+
New id: 5
166+
Using current id: 5
167+
Created Nordic Peripheral ID: 5: 0x2000bd60
168+
Advertiser 5 successfully started
169+
New id: 6
170+
Using current id: 6
171+
Created Nordic Peripheral ID: 6: 0x2000bd78
172+
Advertiser 6 successfully started
173+
New id: 7
174+
Using current id: 7
175+
Created Nordic Peripheral ID: 7: 0x2000bd90
176+
Advertiser 7 successfully started
177+
New id: 8
178+
Using current id: 8
179+
Created Nordic Peripheral ID: 8: 0x2000bda8
180+
Advertiser 8 successfully started
181+
New id: 9
182+
Using current id: 9
183+
Created Nordic Peripheral ID: 9: 0x2000bdc0
184+
Advertiser 9 successfully started
185+
New id: 10
186+
Using current id: 10
187+
Created Nordic Peripheral ID: 10: 0x2000bdd8
188+
Advertiser 10 successfully started
189+
New id: 11
190+
Using current id: 11
191+
Created Nordic Peripheral ID: 11: 0x2000bdf0
192+
Advertiser 11 successfully started
193+
New id: 12
194+
Using current id: 12
195+
Created Nordic Peripheral ID: 12: 0x2000be08
196+
Advertiser 12 successfully started
197+
New id: 13
198+
Using current id: 13
199+
Created Nordic Peripheral ID: 13: 0x2000be20
200+
Advertiser 13 successfully started
201+
New id: 14
202+
Using current id: 14
203+
Created Nordic Peripheral ID: 14: 0x2000be38
204+
Advertiser 14 successfully started
205+
New id: 15
206+
Using current id: 15
207+
Created Nordic Peripheral ID: 15: 0x2000be50
208+
Advertiser 15 successfully started
209+
New id: 16
210+
Using current id: 16
211+
Created Nordic Peripheral ID: 16: 0x2000be68
212+
Advertiser 16 successfully started
213+
New id: 17
214+
Using current id: 17
215+
Created Nordic Peripheral ID: 17: 0x2000be80
216+
Advertiser 17 successfully started
217+
New id: 18
218+
Using current id: 18
219+
Created Nordic Peripheral ID: 18: 0x2000be98
220+
Advertiser 18 successfully started
221+
New id: 19
222+
Using current id: 19
223+
Created Nordic Peripheral ID: 19: 0x2000beb0
224+
Advertiser 19 successfully started
225+
226+
Dependencies
227+
************
228+
229+
The sample uses the following Zephyr libraries:
230+
231+
* :file:`include/kernel.h`
232+
* :file:`include/sys/printk.h`
233+
234+
* :ref:`zephyr:bluetooth_api`:
235+
236+
* :file:`include/bluetooth/bluetooth.h`
237+
* :file:`include/bluetooth/conn.h`
238+
* :file:`include/bluetooth/hci.h`

‎samples/bluetooth/peripheral_with_multiple_identities/boards/nrf5340dk_nrf5340_cpuapp.conf

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
#
2+
# Copyright (c) 2024 Nordic Semiconductor
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
# Application core does not have BLE controller. Disable controller related options.
8+
CONFIG_BT_CTLR_ADV_EXT=n

‎samples/bluetooth/peripheral_with_multiple_identities/boards/nrf54h20dk_nrf54h20_cpuapp.conf

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
#
2+
# Copyright (c) 2024 Nordic Semiconductor
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
# Application core does not have BLE controller. Disable controller related options.
8+
CONFIG_BT_CTLR_ADV_EXT=n

‎samples/bluetooth/peripheral_with_multiple_identities/prj.conf

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#
2+
# Copyright (c) 2024 Nordic Semiconductor
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
CONFIG_NCS_SAMPLES_DEFAULTS=y
8+
CONFIG_BT_DEVICE_NAME="Nordic Peripheral ID"
9+
CONFIG_BT=y
10+
CONFIG_BT_PERIPHERAL=y
11+
CONFIG_BT_EXT_ADV=y
12+
13+
CONFIG_BT_EXT_ADV_MAX_ADV_SET=20
14+
CONFIG_BT_MAX_CONN=20
15+
CONFIG_BT_ID_MAX=20
16+
CONFIG_BT_BUF_ACL_RX_COUNT=21

‎samples/bluetooth/peripheral_with_multiple_identities/sample.yaml

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
sample:
2+
description: Peripheral with multiple identities sample
3+
name: Peripheral with multiple identities
4+
tests:
5+
sample.bluetooth.peripheral_with_multiple_identities:
6+
sysbuild: true
7+
build_only: true
8+
integration_platforms:
9+
- nrf52840dk/nrf52840
10+
- nrf5340dk/nrf5340/cpuapp
11+
- nrf54l15dk/nrf54l05/cpuapp
12+
- nrf54l15dk/nrf54l10/cpuapp
13+
- nrf54l15dk/nrf54l15/cpuapp
14+
- nrf54h20dk/nrf54h20/cpurad
15+
platform_allow:
16+
- nrf52840dk/nrf52840
17+
- nrf5340dk/nrf5340/cpuapp
18+
- nrf54l15dk/nrf54l05/cpuapp
19+
- nrf54l15dk/nrf54l10/cpuapp
20+
- nrf54l15dk/nrf54l15/cpuapp
21+
- nrf54h20dk/nrf54h20/cpurad
22+
tags: bluetooth ci_build sysbuild

0 commit comments

Comments
 (0)