Skip to content

Commit 9081805

Browse files
PizzaAllTheWayPizzaAllTheWay
committed
samples: bluetooth: add Device Name sample
Add a new BLE sample demonstrating how a peer can read and write the GAP Device Name characteristic (UUID 0x2A00) over BLE. The sample: - Advertises with a configurable default device name. - Allows connected peers to write a new name with open permissions. - Updates the SoftDevice GAP name and advertising data immediately. - Persists the new name to flash (BM ZMS) so it survives reboots. - Loads the saved name from storage on boot, falling back to the Kconfig default if none exists. Includes sample documentation and changelog entry. Signed-off-by: Martynas Smilingis <martynas.smilingis@nordicsemi.no>
1 parent fc29f50 commit 9081805

7 files changed

Lines changed: 592 additions & 0 deletions

File tree

‎doc/nrf-bm/release_notes/release_notes_changelog.rst‎

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

345345
* The :ref:`ble_nus_central_sample` sample.
346346
* The :ref:`peripheral_nfc_pairing_sample` sample.
347+
* The :ref:`ble_device_name_sample` sample.
347348

348349
* :ref:`ble_bms_sample` sample:
349350

‎samples/bluetooth/ble_device_name/CMakeLists.txt‎

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

‎samples/bluetooth/ble_device_name/Kconfig‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
#
2+
# Copyright (c) 2025 Nordic Semiconductor ASA
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
menu "Bluetooth LE GAP Device Name sample"
8+
9+
config SAMPLE_BLE_DEVICE_NAME
10+
string "Device name"
11+
default "nRF_BM_GAP_DN"
12+
13+
config SAMPLE_BM_ZMS_SECTOR_SIZE
14+
int "Sector size"
15+
default 512
16+
17+
endmenu
18+
19+
module=SAMPLE_BLE_DEVICE_NAME
20+
module-str=BLE Device Name Sample
21+
source "$(ZEPHYR_BASE)/subsys/logging/Kconfig.template.log_config"
22+
23+
source "Kconfig.zephyr"

‎samples/bluetooth/ble_device_name/README.rst‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
.. _ble_device_name_sample:
2+
3+
Bluetooth: Persistent Device Name
4+
#################################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
The Device Name sample demonstrates how to read and write the Bluetooth LE GAP Device Name characteristic using |BMlong|.
11+
A connected peer can change the device name over Bluetooth LE.
12+
The new name takes effect immediately, persists across disconnects, and survives power cycles.
13+
14+
Requirements
15+
************
16+
17+
The sample supports the following development kits:
18+
19+
.. tabs::
20+
21+
.. group-tab:: Simple board variants
22+
23+
The following board variants do **not** have DFU capabilities:
24+
25+
.. list-table::
26+
:header-rows: 1
27+
28+
* - Hardware platform
29+
- PCA
30+
- SoftDevice
31+
- Board target
32+
* - `nRF54L15 DK`_
33+
- PCA10156
34+
- S115
35+
- bm_nrf54l15dk/nrf54l15/cpuapp/s115_softdevice
36+
* - `nRF54L15 DK`_ (emulating nRF54L10)
37+
- PCA10156
38+
- S115
39+
- bm_nrf54l15dk/nrf54l10/cpuapp/s115_softdevice
40+
* - `nRF54L15 DK`_ (emulating nRF54L05)
41+
- PCA10156
42+
- S115
43+
- bm_nrf54l15dk/nrf54l05/cpuapp/s115_softdevice
44+
* - `nRF54LM20 DK`_
45+
- PCA10184
46+
- S115
47+
- bm_nrf54lm20dk/nrf54lm20a/cpuapp/s115_softdevice
48+
* - nRF54LS05 DK
49+
- PCA10214
50+
- S115
51+
- bm_nrf54ls05dk/nrf54ls05b/cpuapp/s115_softdevice
52+
* - `nRF54LV10 DK`_
53+
- PCA10188
54+
- S115
55+
- bm_nrf54lv10dk/nrf54lv10a/cpuapp/s115_softdevice
56+
* - `nRF54L15 DK`_
57+
- PCA10156
58+
- S145
59+
- bm_nrf54l15dk/nrf54l15/cpuapp/s145_softdevice
60+
* - `nRF54L15 DK`_ (emulating nRF54L10)
61+
- PCA10156
62+
- S145
63+
- bm_nrf54l15dk/nrf54l10/cpuapp/s145_softdevice
64+
* - `nRF54L15 DK`_ (emulating nRF54L05)
65+
- PCA10156
66+
- S145
67+
- bm_nrf54l15dk/nrf54l05/cpuapp/s145_softdevice
68+
* - `nRF54LM20 DK`_
69+
- PCA10184
70+
- S145
71+
- bm_nrf54lm20dk/nrf54lm20a/cpuapp/s145_softdevice
72+
* - nRF54LS05 DK
73+
- PCA10214
74+
- S145
75+
- bm_nrf54ls05dk/nrf54ls05b/cpuapp/s145_softdevice
76+
* - `nRF54LV10 DK`_
77+
- PCA10188
78+
- S145
79+
- bm_nrf54lv10dk/nrf54lv10a/cpuapp/s145_softdevice
80+
81+
.. group-tab:: MCUboot board variants
82+
83+
The following board variants have DFU capabilities:
84+
85+
.. list-table::
86+
:header-rows: 1
87+
88+
* - Hardware platform
89+
- PCA
90+
- SoftDevice
91+
- Board target
92+
* - `nRF54L15 DK`_
93+
- PCA10156
94+
- S115
95+
- bm_nrf54l15dk/nrf54l15/cpuapp/s115_softdevice/mcuboot
96+
* - `nRF54L15 DK`_ (emulating nRF54L10)
97+
- PCA10156
98+
- S115
99+
- bm_nrf54l15dk/nrf54l10/cpuapp/s115_softdevice/mcuboot
100+
* - `nRF54L15 DK`_ (emulating nRF54L05)
101+
- PCA10156
102+
- S115
103+
- bm_nrf54l15dk/nrf54l05/cpuapp/s115_softdevice/mcuboot
104+
* - `nRF54LM20 DK`_
105+
- PCA10184
106+
- S115
107+
- bm_nrf54lm20dk/nrf54lm20a/cpuapp/s115_softdevice/mcuboot
108+
* - nRF54LS05 DK
109+
- PCA10214
110+
- S115
111+
- bm_nrf54ls05dk/nrf54ls05b/cpuapp/s115_softdevice/mcuboot
112+
* - `nRF54LV10 DK`_
113+
- PCA10188
114+
- S115
115+
- bm_nrf54lv10dk/nrf54lv10a/cpuapp/s115_softdevice/mcuboot
116+
* - `nRF54L15 DK`_
117+
- PCA10156
118+
- S145
119+
- bm_nrf54l15dk/nrf54l15/cpuapp/s145_softdevice/mcuboot
120+
* - `nRF54L15 DK`_ (emulating nRF54L10)
121+
- PCA10156
122+
- S145
123+
- bm_nrf54l15dk/nrf54l10/cpuapp/s145_softdevice/mcuboot
124+
* - `nRF54L15 DK`_ (emulating nRF54L05)
125+
- PCA10156
126+
- S145
127+
- bm_nrf54l15dk/nrf54l05/cpuapp/s145_softdevice/mcuboot
128+
* - `nRF54LM20 DK`_
129+
- PCA10184
130+
- S145
131+
- bm_nrf54lm20dk/nrf54lm20a/cpuapp/s145_softdevice/mcuboot
132+
* - nRF54LS05 DK
133+
- PCA10214
134+
- S145
135+
- bm_nrf54ls05dk/nrf54ls05b/cpuapp/s145_softdevice/mcuboot
136+
* - `nRF54LV10 DK`_
137+
- PCA10188
138+
- S145
139+
- bm_nrf54lv10dk/nrf54lv10a/cpuapp/s145_softdevice/mcuboot
140+
141+
Overview
142+
********
143+
144+
The sample advertises with a configurable device name and allows any connected peer to write a new name to the GAP Device Name characteristic (UUID 0x2A00).
145+
When a new name is written:
146+
147+
* The SoftDevice GAP name is updated immediately.
148+
* The advertising data is refreshed so scanners see the new name after disconnect.
149+
* The name is saved to flash (BM ZMS) so it persists across reboots.
150+
151+
On boot, the sample loads the previously saved name from storage.
152+
If none exists, it falls back to the default configured via :kconfig:option:`CONFIG_SAMPLE_BLE_DEVICE_NAME`.
153+
154+
User interface
155+
**************
156+
157+
LED 0:
158+
Lit when the device is initialized.
159+
160+
LED 1:
161+
Lit when a device is connected.
162+
163+
Building and running
164+
********************
165+
166+
This sample can be found under :file:`samples/bluetooth/ble_device_name/` in the |BMshort| folder structure.
167+
168+
For details on how to create, configure, and program a sample, see :ref:`getting_started_with_the_samples`.
169+
170+
Testing
171+
=======
172+
173+
1. Compile and program the application.
174+
#. Connect the device to the computer.
175+
#. Connect to the kit with a terminal emulator (for example, the `Serial Terminal app`_).
176+
#. Reset the kit.
177+
#. Observe that ``Advertising as nRF_BM_GAP_DN`` is printed in the terminal.
178+
You can configure this default name using the :kconfig:option:`CONFIG_SAMPLE_BLE_DEVICE_NAME` Kconfig option.
179+
#. Open the nRF Connect for Mobile or Desktop app and connect to the device.
180+
#. In the GAP service, find the **Device Name** characteristic (UUID 0x2A00).
181+
#. Read the current name to verify it matches the advertised name.
182+
#. Write a new name (for example, ``MyDevice``).
183+
#. Observe that the terminal prints::
184+
185+
Device name updated (8 bytes)
186+
New name
187+
4d 79 44 65 76 69 63 65 |MyDevice
188+
189+
#. Observe that ``Device name persisted to storage`` is printed shortly after.
190+
#. Disconnect from the device.
191+
#. Refresh and scan again using the nRF Connect for Mobile or Desktop.
192+
#. Observe that the device now advertises with the new name ``MyDevice``.
193+
#. Reset the kit and observe that the saved name is loaded from storage and used for advertising.

‎samples/bluetooth/ble_device_name/prj.conf‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Logging
2+
CONFIG_LOG=y
3+
CONFIG_LOG_BACKEND_BM_UARTE=y
4+
5+
# SoftDevice
6+
CONFIG_SOFTDEVICE=y
7+
8+
# RNG (required by SoftDevice)
9+
CONFIG_NRF_SECURITY=y
10+
CONFIG_MBEDTLS_PSA_CRYPTO_C=y
11+
CONFIG_PSA_WANT_GENERATE_RANDOM=y
12+
13+
# Advertising library
14+
CONFIG_BLE_ADV=y
15+
16+
# ZMS
17+
CONFIG_BM_ZMS=y

‎samples/bluetooth/ble_device_name/sample.yaml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
sample:
2+
name: Bluetooth LE Device Name Sample
3+
tests:
4+
sample.ble_device_name:
5+
build_only: true
6+
integration_platforms:
7+
- bm_nrf54lv10dk/nrf54lv10a/cpuapp/s115_softdevice
8+
platform_allow:
9+
- bm_nrf54l15dk/nrf54l05/cpuapp/s115_softdevice
10+
- bm_nrf54l15dk/nrf54l05/cpuapp/s115_softdevice/mcuboot
11+
- bm_nrf54l15dk/nrf54l05/cpuapp/s145_softdevice
12+
- bm_nrf54l15dk/nrf54l05/cpuapp/s145_softdevice/mcuboot
13+
- bm_nrf54l15dk/nrf54l10/cpuapp/s115_softdevice
14+
- bm_nrf54l15dk/nrf54l10/cpuapp/s115_softdevice/mcuboot
15+
- bm_nrf54l15dk/nrf54l10/cpuapp/s145_softdevice
16+
- bm_nrf54l15dk/nrf54l10/cpuapp/s145_softdevice/mcuboot
17+
- bm_nrf54l15dk/nrf54l15/cpuapp/s115_softdevice
18+
- bm_nrf54l15dk/nrf54l15/cpuapp/s115_softdevice/mcuboot
19+
- bm_nrf54l15dk/nrf54l15/cpuapp/s145_softdevice
20+
- bm_nrf54l15dk/nrf54l15/cpuapp/s145_softdevice/mcuboot
21+
- bm_nrf54lm20dk/nrf54lm20a/cpuapp/s115_softdevice
22+
- bm_nrf54lm20dk/nrf54lm20a/cpuapp/s115_softdevice/mcuboot
23+
- bm_nrf54lm20dk/nrf54lm20a/cpuapp/s145_softdevice
24+
- bm_nrf54lm20dk/nrf54lm20a/cpuapp/s145_softdevice/mcuboot
25+
- bm_nrf54ls05dk/nrf54ls05b/cpuapp/s115_softdevice
26+
- bm_nrf54ls05dk/nrf54ls05b/cpuapp/s115_softdevice/mcuboot
27+
- bm_nrf54ls05dk/nrf54ls05b/cpuapp/s145_softdevice
28+
- bm_nrf54ls05dk/nrf54ls05b/cpuapp/s145_softdevice/mcuboot
29+
- bm_nrf54lv10dk/nrf54lv10a/cpuapp/s115_softdevice
30+
- bm_nrf54lv10dk/nrf54lv10a/cpuapp/s115_softdevice/mcuboot
31+
- bm_nrf54lv10dk/nrf54lv10a/cpuapp/s145_softdevice
32+
- bm_nrf54lv10dk/nrf54lv10a/cpuapp/s145_softdevice/mcuboot
33+
tags: ci_build

0 commit comments

Comments
 (0)