Skip to content

Commit acb553b

Browse files
EndreEGhermabe
EndreEG
authored and
hermabe
committed
Bluetooth: rssi_power_control: Add power control sample
Adjusts peripheral Tx power based on RSSI measurements Signed-off-by: Endre Ekstang Grønevik <[email protected]>
1 parent 0e0ccce commit acb553b

File tree

12 files changed

+774
-0
lines changed

12 files changed

+774
-0
lines changed

‎CODEOWNERS‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -452,6 +452,7 @@
452452
/samples/bluetooth/mesh/ @nrfconnect/ncs-paladin
453453
/samples/bluetooth/multiple_adv_sets/ @nrfconnect/ncs-si-muffin
454454
/samples/bluetooth/nrf_dm/ @nrfconnect/ncs-si-muffin
455+
/samples/bluetooth/rssi_power_control/ @nrfconnect/ncs-dragoon
455456
/samples/bluetooth/peripheral_ams_client/ @leewkb4567
456457
/samples/bluetooth/peripheral_ancs_client/ @leewkb4567
457458
/samples/bluetooth/peripheral_bms/ @nrfconnect/ncs-si-muffin
@@ -590,6 +591,7 @@
590591
/samples/bluetooth/multiple_adv_sets/*.rst @nrfconnect/ncs-si-muffin-doc
591592
/samples/bluetooth/nrf_dm/*.rst @nrfconnect/ncs-si-muffin-doc
592593
/samples/bluetooth/path_loss_monitoring/*.rst @nrfconnect/ncs-dragoon-doc
594+
/samples/bluetooth/rssi_power_control/*.rst @nrfconnect/ncs-dragoon-doc
593595
/samples/bluetooth/peripheral_ams_client/*.rst @nrfconnect/ncs-si-muffin-doc
594596
/samples/bluetooth/peripheral_ancs_client/*.rst @nrfconnect/ncs-si-muffin-doc
595597
/samples/bluetooth/peripheral_bms/*.rst @nrfconnect/ncs-si-muffin-doc

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -482,6 +482,8 @@ Bluetooth samples
482482
* :ref:`ble_subrating`
483483
* :ref:`ble_throughput`
484484

485+
* Added the :ref:`bluetooth_automated_power_control` sample.
486+
485487
* Updated the network core image applications for the following samples from the :zephyr:code-sample:`bluetooth_hci_ipc` sample to the :ref:`ipc_radio` application for multicore builds:
486488

487489
* :ref:`bluetooth_conn_time_synchronization`

‎samples/bluetooth/rssi_power_control/README.rst‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
.. _bluetooth_automated_power_control:
2+
3+
Bluetooth: Automated power control
4+
##################################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
The Automated power control sample demonstrates how to monitor the Bluetooth® Low Energy signal strength (RSSI) and dynamically adjust the transmit (TX) power of a connected Peripheral device.
11+
There are two versions of this sample: One for the central device (in the :file:`rssi_power_control/central` folder) and one for the peripheral device (in the :file:`rssi_power_control/peripheral` folder)
12+
13+
The sample for the central device collects RSSI data and sends power control commands to optimize the connection quality, which in turn optimizes the current consumption.
14+
15+
The sample for the peripheral device is simply advertising its existence, allowing the central device to establish a connection.
16+
17+
Requirements
18+
************
19+
20+
The sample supports the following development kits:
21+
22+
.. table-from-sample-yaml::
23+
24+
You must use two compatible development kits to run this sample, one running the version for the central device (:file:`rssi_power_control/central`) and one running the version for the peripheral device (:file:`rssi_power_control/peripheral`).
25+
26+
Overview
27+
********
28+
29+
This sample illustrates Bluetooth LE power control by having the central device read the RSSI of an active connection and use it to adjust the transmit power of the peripheral version.
30+
The central version directly invokes SoftDevice Controller (SDC) APIs to configure power control behavior based on RSSI measurements.
31+
This approach only works on single-core platforms where the Bluetooth Controller and application run on the same core.
32+
33+
There are two ways to monitor the connection parameters:
34+
35+
* Terminal output - Connects to the Central device's virtual serial port to view RSSI and TX power logs in real time.
36+
* Graphical plotting - Uses the provided script to visualize signal strength over time:
37+
38+
.. code-block:: console
39+
40+
python3 tools/plot_path_loss.py --comport COMPORT
41+
42+
.. note::
43+
Make sure no terminal is open on the same serial port when using the Python plotting script, as it requires exclusive access.
44+
Example of serial port - ``/dev/ttyACM1``.
45+
46+
This sample works only on single-core SoCs because it directly calls ``sdc_*`` functions (such as :c:func:`sdc_hci_cmd_vs_set_power_control_request_params`) that are only accessible on the core running the Bluetooth Controller.
47+
On dual-core platforms such as nRF5340 or nRF54H20 SoCs, the Bluetooth Controller runs on the network core, making these calls inaccessible from the application core and resulting in linker errors.
48+
49+
Workaround for dual-core SoCs
50+
=============================
51+
52+
To adapt this sample for dual-core SoCs:
53+
54+
1. Remove all ``sdc_*`` function calls from the application.
55+
#. Use Zephyr HCI commands to interface with the controller:
56+
57+
.. code-block:: c
58+
59+
struct net_buf *buf = bt_hci_cmd_create(...);
60+
bt_hci_cmd_send_sync(...);
61+
62+
Refer to the :zephyr:code-sample:`bluetooth_hci_pwr_ctrl` sample or Nordic DevZone for reference implementations.
63+
64+
User interface
65+
**************
66+
67+
The following is the user interface used by the two versions of this sample:
68+
69+
Central device:
70+
71+
* Virtual serial output displays live RSSI and TX power data.
72+
* Optional plotting provides a visual graph of signal variation over time.
73+
74+
Peripheral device:
75+
76+
* No direct user interface.
77+
* Automatically accepts connections and responds to TX power control commands.
78+
79+
Configuration
80+
*************
81+
82+
|config|
83+
84+
Additional configuration
85+
========================
86+
87+
Check and configure the following Kconfig options:
88+
89+
* :kconfig:option:`CONFIG_BT_CENTRAL` - Enables the Bluetooth LE Central role for the Central application.
90+
* :kconfig:option:`CONFIG_BT_PERIPHERAL` - Enables the Bluetooth LE Peripheral role for the Peripheral application.
91+
* :kconfig:option:`CONFIG_BT_DEVICE_NAME` - Sets the advertised name of the Peripheral (default: ``power_control_peripheral``).
92+
* :kconfig:option:`CONFIG_BT_SCAN` - Enables scanning for Bluetooth LE advertisements (Central only).
93+
* :kconfig:option:`CONFIG_BT_SCAN_FILTER_ENABLE` - Enables name-based filtering for Bluetooth scan results (Central only).
94+
* :kconfig:option:`CONFIG_BT_CTLR_CONN_RSSI` - Enables controller-side RSSI reporting for active connections.
95+
* :kconfig:option:`CONFIG_BT_TRANSMIT_POWER_CONTROL` - Enables support for Bluetooth LE transmit power control.
96+
* :kconfig:option:`CONFIG_BT_CTLR_TX_PWR_DYNAMIC_CONTROL` - Allows dynamic adjustment of transmit power based on RSSI feedback.
97+
* :kconfig:option:`CONFIG_BT_HCI_RAW` - Enables raw HCI interface for communication between the application and controller cores (used in IPC radio configurations).
98+
* :kconfig:option:`CONFIG_LOG` - Enables logging through Zephyr's logging subsystem (optional but useful for debugging).
99+
100+
Building and running
101+
********************
102+
103+
.. |sample path| replace:: :file:`samples/bluetooth/power_control_demo`
104+
105+
.. include:: /includes/build_and_run.txt
106+
107+
.. |sample_or_app| replace:: sample
108+
109+
.. |ipc_radio_dir| replace:: :file:`sysbuild/ipc_radio`
110+
111+
.. include:: /includes/ipc_radio_conf.txt
112+
113+
Testing
114+
=======
115+
116+
|test_sample|
117+
118+
1. Program one development kit with the power control firmware for the peripheral device.
119+
#. Program another development kit with the power control firmware for the central device.
120+
#. Open a terminal on the Central's virtual serial port or run the plotting script.
121+
#. Power on both devices.
122+
#. The Central will scan and connect to the Peripheral automatically.
123+
#. Observe RSSI and TX power data printed or plotted.
124+
#. Move the devices or add obstructions to see dynamic power adjustment.
125+
126+
Sample output
127+
=============
128+
129+
The following output is logged from the central device:
130+
131+
.. code-block:: console
132+
133+
[00:00:01.000,000] I: Starting BLE Central
134+
[00:00:01.500,000] I: Scanning for peripherals...
135+
[00:00:03.020,000] I: Found peripheral: FF:EE:DD:CC:BB:AA (random)
136+
[00:00:03.050,000] I: Connection to FF:EE:DD:CC:BB:AA (random)
137+
[00:00:03.800,000] I: Connected to FF:EE:DD:CC:BB:AA (random)
138+
[00:00:05.010,000] I: Successful initialization of power control
139+
[00:00:06.010,000] I: Tx: 0 dBm, RSSI: -33 dBm
140+
[00:00:07.010,000] I: Tx: -9 dBm, RSSI: -45 dBm
141+
142+
Dependencies
143+
************
144+
145+
This sample uses the following |NCS| libraries:
146+
147+
* :ref:`nrf_bt_scan_readme`
148+
149+
It also relies on the following Zephyr's Bluetooth and HCI layers:
150+
151+
* :ref:`zephyr:kernel_api`:
152+
153+
* :file:`include/zephyr/kernel.h`
154+
155+
* :ref:`zephyr:bluetooth_api`:
156+
157+
* :file:`include/zephyr/bluetooth/addr.h`
158+
* :file:`include/zephyr/bluetooth/bluetooth.h`
159+
* :file:`include/zephyr/bluetooth/conn.h`
160+
161+
* :ref:`zephyr:logging_api`:
162+
163+
* :file:`include/zephyr/logging/log.h`
164+
165+
If using the optional Python plotting script, the following dependencies are required:
166+
167+
* Python 3.6 or newer
168+
* The following Python modules:
169+
170+
.. code-block:: console
171+
172+
pip install pyserial matplotlib

‎samples/bluetooth/rssi_power_control/central/CMakeLists.txt‎

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

‎samples/bluetooth/rssi_power_control/central/prj.conf‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
#
2+
# Copyright (c) 2025 Nordic Semiconductor
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
CONFIG_NCS_SAMPLES_DEFAULTS=y
8+
CONFIG_BT=y
9+
CONFIG_BT_CENTRAL=y
10+
CONFIG_BT_SCAN=y
11+
CONFIG_BT_SCAN_FILTER_ENABLE=y
12+
CONFIG_BT_SCAN_NAME_CNT=1
13+
CONFIG_BT_CTLR_CONN_RSSI=y
14+
CONFIG_BT_TRANSMIT_POWER_CONTROL=y
15+
CONFIG_BT_CTLR_TX_PWR_DYNAMIC_CONTROL=y

‎samples/bluetooth/rssi_power_control/central/sample.yaml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
#
2+
# Copyright (c) 2025 Nordic Semiconductor
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
sample:
8+
description: Central device of a Bluetooth Low Energy automated power controller.
9+
A feedback system that adjusts the transmit power based on the current RSSI
10+
— increasing, decreasing, or maintaining it as needed.
11+
name: Bluetooth LE central with automated power control
12+
tests:
13+
sample.bluetooth.central_automated_power_control:
14+
sysbuild: true
15+
integration_platforms:
16+
- nrf52840dk/nrf52840
17+
- nrf54l15dk/nrf54l15/cpuapp
18+
platform_allow:
19+
- nrf52840dk/nrf52840
20+
- nrf54l15dk/nrf54l15/cpuapp
21+
harness: console
22+
harness_config:
23+
type: one_line
24+
regex:
25+
- "Scanning for peripherals..."
26+
tags:
27+
- bluetooth
28+
- ci_build
29+
- sysbuild

0 commit comments

Comments
 (0)