Skip to content

Commit fc8d942

Browse files
olivier-le-sagenashif
olivier-le-sage
authored and
nashif
committed
bluetooth: samples: Add samples showing basic channel sounding features
These samples demonstrate how to use the bluetooth 6.0 channel sounding APIs. A basic distance estimation algorithm is included. Signed-off-by: Olivier Lesage <[email protected]>
1 parent 4288962 commit fc8d942

File tree

21 files changed

+1794
-0
lines changed

21 files changed

+1794
-0
lines changed

‎samples/bluetooth/channel_sounding/README.rst‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
.. zephyr:code-sample:: ble_cs
2+
:name: Channel Sounding
3+
:relevant-api: bt_gap bluetooth
4+
5+
Use Channel Sounding functionality.
6+
7+
Overview
8+
********
9+
10+
These samples demonstrates how to use the Bluetooth Channel Sounding feature.
11+
12+
The CS Test sample shows how to us the CS test command to override randomization of certain channel
13+
sounding parameters, experiment with different configurations, or evaluate the RF medium. It can
14+
be found under :zephyr_file:`samples/bluetooth/channel_sounding/cs_test`.
15+
16+
The connected CS sample shows how to set up regular channel sounding procedures on a connection
17+
between two devices.
18+
It can be found under :zephyr_file:`samples/bluetooth/channel_sounding/connected_cs`
19+
20+
A basic distance estimation algorithm is included in both.
21+
The Channel Sounding feature does not mandate a specific algorithm for computing distance estimates,
22+
but the mathematical representation described in [#phase_and_amplitude]_ and [#rtt_packets]_ is used
23+
as a starting point for these samples.
24+
25+
Distance estimation using channel sounding requires data from two devices, and for that reason
26+
the channel sounding results in the sample are exchanged in a simple way using a GATT characteristic.
27+
This limits the amount of data that can be processed at once to about 512 bytes from each device,
28+
which is enough to estimate distance using a handful of RTT timings and PBR phase samples across
29+
about 35-40 channels, assuming a single antenna path.
30+
31+
Both samples will perform channel sounding procedures repeatedly and print regular distance estimates to
32+
the console. They are designed assuming a single subevent per procedure.
33+
34+
Diagrams illustrating the steps involved in setting up channel sounding procedures between two
35+
connected devices are available in [#cs_setup_phase]_ and [#cs_start]_.
36+
37+
Requirements
38+
************
39+
40+
* Two boards with Bluetooth LE and Channel Sounding support (such as an :ref:`nRF54L15 <nrf54l15dk_nrf54l15>`)
41+
* A controller that supports the Channel Sounding feature
42+
43+
Building and Running
44+
********************
45+
46+
These samples can be found under :zephyr_file:`samples/bluetooth/channel_sounding` in
47+
the Zephyr tree.
48+
49+
See :zephyr:code-sample-category:`bluetooth` samples for details.
50+
51+
These sample use two applications, so two devices need to be setup.
52+
Flash one device with the initiator application, and another device with the
53+
reflector application.
54+
55+
The devices should perform distance estimations repeatedly every few seconds if they are close enough.
56+
57+
Here is an example output from the connected CS sample:
58+
59+
Reflector:
60+
61+
.. code-block:: console
62+
63+
*** Using Zephyr OS v3.7.99-585fbd2e318c ***
64+
Starting Channel Sounding Demo
65+
Connected to EC:E7:DB:66:14:86 (random) (err 0x00)
66+
MTU exchange success (247)
67+
Discovery: attr 0x20006a2c
68+
UUID 87654321-4567-2389-1254-f67f9fedcba8
69+
Found expected UUID
70+
CS capability exchange completed.
71+
CS config creation complete. ID: 0
72+
CS security enabled.
73+
CS procedures enabled.
74+
75+
76+
Initiator:
77+
78+
.. code-block:: console
79+
80+
*** Using Zephyr OS v3.7.99-585fbd2e318c ***
81+
Starting Channel Sounding Demo
82+
Found device with name CS Sample, connecting...
83+
Connected to C7:78:79:CD:16:B9 (random) (err 0x00)
84+
MTU exchange success (247)
85+
CS capability exchange completed.
86+
CS config creation complete. ID: 0
87+
CS security enabled.
88+
CS procedures enabled.
89+
Estimated distance to reflector:
90+
- Round-Trip Timing method: 2.633891 meters (derived from 7 samples)
91+
- Phase-Based Ranging method: 0.511853 meters (derived from 38 samples)
92+
93+
94+
Here is an example output from the CS Test sample:
95+
96+
Reflector:
97+
98+
.. code-block:: console
99+
100+
*** Using Zephyr OS v3.7.99-585fbd2e318c ***
101+
Starting Channel Sounding Demo
102+
Connected to C7:78:79:CD:16:B9 (random) (err 0x00)
103+
MTU exchange success (247)
104+
Discovery: attr 0x20006544
105+
UUID 87654321-4567-2389-1254-f67f9fedcba8
106+
Found expected UUID
107+
Disconnected (reason 0x13)
108+
Re-running CS test...
109+
110+
111+
Initiator:
112+
113+
.. code-block:: console
114+
115+
*** Using Zephyr OS v3.7.99-585fbd2e318c ***
116+
Starting Channel Sounding Demo
117+
Found device with name CS Test Sample, connecting...
118+
Connected to EC:E7:DB:66:14:86 (random) (err 0x00)
119+
MTU exchange success (247)
120+
Estimated distance to reflector:
121+
- Round-Trip Timing method: 0.374741 meters (derived from 4 samples)
122+
- Phase-Based Ranging method: 0.588290 meters (derived from 35 samples)
123+
Disconnected (reason 0x16)
124+
Re-running CS test...
125+
126+
127+
References
128+
**********
129+
130+
.. [#phase_and_amplitude] `Bluetooth Core Specification v. 6.0: Vol. 1, Part A, 9.2 <https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-60/out/en/architecture,-change-history,-and-conventions/architecture.html#UUID-a8d03618-5fcf-3043-2198-559653272b1b>`_
131+
.. [#rtt_packets] `Bluetooth Core Specification v. 6.0: Vol. 1, Part A, 9.3 <https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-60/out/en/architecture,-change-history,-and-conventions/architecture.html#UUID-9d4969af-baa6-b7e4-03ca-70b340877adf>`_
132+
.. [#cs_setup_phase] `Bluetooth Core Specification v. 6.0: Vol. 6, Part D, 6.34 <https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-60/out/en/low-energy-controller/message-sequence-charts.html#UUID-73ba2c73-f3c8-3b1b-2bdb-b18174b88059>`_
133+
.. [#cs_start] `Bluetooth Core Specification v. 6.0: Vol. 6, Part D, 6.35 <https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-60/out/en/low-energy-controller/message-sequence-charts.html#UUID-c75cd2f9-0dd8-bd38-9afc-c7becfa7f073>`_

‎samples/bluetooth/channel_sounding/connected_cs/initiator/CMakeLists.txt‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# SPDX-License-Identifier: Apache-2.0
2+
3+
cmake_minimum_required(VERSION 3.20.0)
4+
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
5+
project(connected_cs_initiator)
6+
7+
target_sources(app PRIVATE ../../src/connected_cs_initiator.c ../../src/distance_estimation.c)
8+
9+
zephyr_library_include_directories(
10+
${CMAKE_CURRENT_LIST_DIR}/../../include
11+
)

‎samples/bluetooth/channel_sounding/connected_cs/initiator/prj.conf‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
CONFIG_BT=y
2+
CONFIG_BT_SMP=y
3+
CONFIG_BT_CENTRAL=y
4+
CONFIG_BT_GAP_AUTO_UPDATE_CONN_PARAMS=n
5+
CONFIG_BT_GATT_CLIENT=y
6+
CONFIG_BT_GATT_DYNAMIC_DB=y
7+
CONFIG_BT_ATT_PREPARE_COUNT=3
8+
CONFIG_BT_CHANNEL_SOUNDING=y
9+
10+
CONFIG_BT_BUF_ACL_RX_SIZE=251
11+
CONFIG_BT_BUF_ACL_TX_SIZE=251
12+
CONFIG_BT_L2CAP_TX_MTU=247
13+
14+
CONFIG_MAIN_STACK_SIZE=4096
15+
16+
CONFIG_CBPRINTF_FP_SUPPORT=y

‎samples/bluetooth/channel_sounding/connected_cs/initiator/sample.yaml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
sample:
2+
name: Bluetooth Channel Sounding - Initiator
3+
tests:
4+
sample.bluetooth.channel_sounding.connected_cs.initiator:
5+
harness: bluetooth
6+
platform_allow:
7+
- qemu_cortex_m3
8+
- qemu_x86
9+
tags: bluetooth
10+
integration_platforms:
11+
- qemu_cortex_m3

‎samples/bluetooth/channel_sounding/connected_cs/reflector/CMakeLists.txt‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# SPDX-License-Identifier: Apache-2.0
2+
3+
cmake_minimum_required(VERSION 3.20.0)
4+
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
5+
project(connected_cs_reflector)
6+
7+
target_sources(app PRIVATE ../../src/connected_cs_reflector.c ../../src/distance_estimation.c)
8+
9+
zephyr_library_include_directories(
10+
${CMAKE_CURRENT_LIST_DIR}/../../include
11+
)

‎samples/bluetooth/channel_sounding/connected_cs/reflector/prj.conf‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
CONFIG_BT=y
2+
CONFIG_BT_SMP=y
3+
CONFIG_BT_PERIPHERAL=y
4+
CONFIG_BT_GAP_AUTO_UPDATE_CONN_PARAMS=n
5+
CONFIG_BT_GATT_CLIENT=y
6+
CONFIG_BT_CHANNEL_SOUNDING=y
7+
8+
CONFIG_BT_BUF_ACL_RX_SIZE=251
9+
CONFIG_BT_BUF_ACL_TX_SIZE=251
10+
CONFIG_BT_L2CAP_TX_MTU=247
11+
12+
CONFIG_MAIN_STACK_SIZE=4096
13+
14+
CONFIG_CBPRINTF_FP_SUPPORT=y

‎samples/bluetooth/channel_sounding/connected_cs/reflector/sample.yaml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
sample:
2+
name: Bluetooth Channel Sounding - Reflector
3+
tests:
4+
sample.bluetooth.channel_sounding.connected_cs.reflector:
5+
harness: bluetooth
6+
platform_allow:
7+
- qemu_cortex_m3
8+
- qemu_x86
9+
tags: bluetooth
10+
integration_platforms:
11+
- qemu_cortex_m3

‎samples/bluetooth/channel_sounding/cs_test/initiator/CMakeLists.txt‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# SPDX-License-Identifier: Apache-2.0
2+
3+
cmake_minimum_required(VERSION 3.20.0)
4+
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
5+
project(cs_test_initiator)
6+
7+
target_sources(app PRIVATE ../../src/cs_test_initiator.c ../../src/distance_estimation.c)
8+
9+
zephyr_library_include_directories(
10+
${CMAKE_CURRENT_LIST_DIR}/../../include
11+
)

‎samples/bluetooth/channel_sounding/cs_test/initiator/prj.conf‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
CONFIG_BT=y
2+
CONFIG_BT_CENTRAL=y
3+
CONFIG_BT_GATT_CLIENT=y
4+
CONFIG_BT_GATT_DYNAMIC_DB=y
5+
CONFIG_BT_ATT_PREPARE_COUNT=3
6+
CONFIG_BT_CHANNEL_SOUNDING=y
7+
CONFIG_BT_CHANNEL_SOUNDING_TEST=y
8+
9+
CONFIG_BT_BUF_ACL_RX_SIZE=251
10+
CONFIG_BT_BUF_ACL_TX_SIZE=251
11+
CONFIG_BT_L2CAP_TX_MTU=247
12+
13+
CONFIG_MAIN_STACK_SIZE=4096
14+
15+
CONFIG_CBPRINTF_FP_SUPPORT=y

‎samples/bluetooth/channel_sounding/cs_test/initiator/sample.yaml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
sample:
2+
name: Bluetooth Channel Sounding Test - Initiator
3+
tests:
4+
sample.bluetooth.channel_sounding.cs_test.initiator:
5+
harness: bluetooth
6+
platform_allow:
7+
- qemu_cortex_m3
8+
- qemu_x86
9+
tags: bluetooth
10+
integration_platforms:
11+
- qemu_cortex_m3

0 commit comments

Comments
 (0)