Skip to content

Commit 4ef7306

Browse files
PizzaAllTheWayPizzaAllTheWay
committed
samples: bluetooth: add GAP 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 4ef7306

7 files changed

Lines changed: 601 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_gap_device_name_sample` sample.
347348

348349
* :ref:`ble_bms_sample` sample:
349350

‎samples/bluetooth/ble_gap_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_gap_device_name)
11+
12+
target_sources(app PRIVATE src/main.c)

‎samples/bluetooth/ble_gap_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_GAP_DEVICE_NAME
20+
module-str=BLE GAP Device Name Sample
21+
source "$(ZEPHYR_BASE)/subsys/logging/Kconfig.template.log_config"
22+
23+
source "Kconfig.zephyr"

‎samples/bluetooth/ble_gap_device_name/README.rst‎

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

‎samples/bluetooth/ble_gap_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_gap_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 Generic Access Profile Device Name Sample
3+
tests:
4+
sample.ble_gap_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)