1.. zephyr:code-sample:: ble_cs
2   :name: Channel Sounding
3   :relevant-api: bt_gap bluetooth
4
5   Use Channel Sounding functionality.
6
7Overview
8********
9
10These samples demonstrates how to use the Bluetooth Channel Sounding feature.
11
12The CS Test sample shows how to us the CS test command to override randomization of certain channel
13sounding parameters, experiment with different configurations, or evaluate the RF medium. It can
14be found under :zephyr_file:`samples/bluetooth/channel_sounding/cs_test`.
15
16The connected CS sample shows how to set up regular channel sounding procedures on a connection
17between two devices.
18It can be found under :zephyr_file:`samples/bluetooth/channel_sounding/connected_cs`
19
20A basic distance estimation algorithm is included in both.
21The Channel Sounding feature does not mandate a specific algorithm for computing distance estimates,
22but the mathematical representation described in [#phase_and_amplitude]_ and [#rtt_packets]_ is used
23as a starting point for these samples.
24
25Distance estimation using channel sounding requires data from two devices, and for that reason
26the channel sounding results in the sample are exchanged in a simple way using a GATT characteristic.
27This limits the amount of data that can be processed at once to about 512 bytes from each device,
28which is enough to estimate distance using a handful of RTT timings and PBR phase samples across
29about 35-40 channels, assuming a single antenna path.
30
31Both samples will perform channel sounding procedures repeatedly and print regular distance estimates to
32the console. They are designed assuming a single subevent per procedure.
33
34Diagrams illustrating the steps involved in setting up channel sounding procedures between two
35connected devices are available in [#cs_setup_phase]_ and [#cs_start]_.
36
37Requirements
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
43Building and Running
44********************
45
46These samples can be found under :zephyr_file:`samples/bluetooth/channel_sounding` in
47the Zephyr tree.
48
49See :zephyr:code-sample-category:`bluetooth` samples for details.
50
51These sample use two applications, so two devices need to be setup.
52Flash one device with the initiator application, and another device with the
53reflector application.
54
55The devices should perform distance estimations repeatedly every few seconds if they are close enough.
56
57Here is an example output from the connected CS sample:
58
59Reflector:
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
76Initiator:
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
94Here is an example output from the CS Test sample:
95
96Reflector:
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
111Initiator:
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
127References
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>`_
134