* [PATCH BlueZ v3 0/3] doc: Add Channel Sounding API and bluetoothctl documentation
@ 2026-07-09 12:51 Naga Bhavani Akella
2026-07-09 12:51 ` [PATCH BlueZ v3 1/3] doc/org.bluez.ChannelSounding1:Add Used by reference and Examples Naga Bhavani Akella
` (2 more replies)
0 siblings, 3 replies; 6+ messages in thread
From: Naga Bhavani Akella @ 2026-07-09 12:51 UTC (permalink / raw)
To: linux-bluetooth
Cc: luiz.dentz, quic_mohamull, quic_hbandi, quic_anubhavg,
Naga Bhavani Akella
Improve Channel Sounding documentation by adding cross-references
between the D-Bus APIs and bluetoothctl commands, along with practical
usage examples.
The D-Bus API documents gain :Used by: references to the bluetoothctl
cs submenu and examples for methods and signals, while the
bluetoothctl documentation is updated with :Uses: references,
argument descriptions, and usage examples.
Changes in v3:
- Addressed review comments.
- Dropped the rest of the previously submitted series pending redesign
Changes in v2:
- Addressed review comments.
- Dropped the rest of the previously submitted series pending redesign
Naga Bhavani Akella (3):
doc/org.bluez.ChannelSounding1:Add Used by reference and Examples
doc/org.bluez.ChannelSoundingRanging1:Add references and examples
doc/bluetoothctl-cs: Add :Uses: fields and document arguments
Makefile.am | 4 +
doc/bluetoothctl-cs.rst | 281 ++++++++++++
doc/org.bluez.ChannelSounding1.rst | 532 ++++++++++++++++++++++
doc/org.bluez.ChannelSoundingRanging1.rst | 66 +++
4 files changed, 883 insertions(+)
create mode 100644 doc/bluetoothctl-cs.rst
create mode 100644 doc/org.bluez.ChannelSounding1.rst
create mode 100644 doc/org.bluez.ChannelSoundingRanging1.rst
--
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH BlueZ v3 1/3] doc/org.bluez.ChannelSounding1:Add Used by reference and Examples
2026-07-09 12:51 [PATCH BlueZ v3 0/3] doc: Add Channel Sounding API and bluetoothctl documentation Naga Bhavani Akella
@ 2026-07-09 12:51 ` Naga Bhavani Akella
2026-07-09 14:49 ` doc: Add Channel Sounding API and bluetoothctl documentation bluez.test.bot
2026-07-09 12:51 ` [PATCH BlueZ v3 2/3] doc/org.bluez.ChannelSoundingRanging1:Add references and examples Naga Bhavani Akella
2026-07-09 12:51 ` [PATCH BlueZ v3 3/3] doc/bluetoothctl-cs: Add :Uses: fields and document arguments Naga Bhavani Akella
2 siblings, 1 reply; 6+ messages in thread
From: Naga Bhavani Akella @ 2026-07-09 12:51 UTC (permalink / raw)
To: linux-bluetooth
Cc: luiz.dentz, quic_mohamull, quic_hbandi, quic_anubhavg,
Naga Bhavani Akella
Add :Used by: field linking to bluetoothctl cs submenu and
Examples section showing corresponding bluetoothctl cs commands
for D-Bus methods
---
doc/org.bluez.ChannelSounding1.rst | 532 +++++++++++++++++++++++++++++
1 file changed, 532 insertions(+)
create mode 100644 doc/org.bluez.ChannelSounding1.rst
diff --git a/doc/org.bluez.ChannelSounding1.rst b/doc/org.bluez.ChannelSounding1.rst
new file mode 100644
index 000000000..a573a635f
--- /dev/null
+++ b/doc/org.bluez.ChannelSounding1.rst
@@ -0,0 +1,532 @@
+==========================
+org.bluez.ChannelSounding1
+==========================
+
+----------------------------------------------
+BlueZ D-Bus Channel Sounding API documentation
+----------------------------------------------
+
+:Version: BlueZ
+:Date: June 2026
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service: org.bluez
+:Interface: org.bluez.ChannelSounding1
+:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
+:Used by: **bluetoothctl(1)**, **bluetoothctl-cs(1)**
+
+Methods
+-------
+
+void StartMeasurement(dict params)
+``````````````````````````````````
+
+Starts a Channel Sounding distance measurement procedure on the connected
+device. All configuration is supplied in a single ``a{sv}`` dictionary.
+Any key that is omitted retains its current value in the daemon.
+
+The device to measure is identified by the D-Bus object path on which
+this method is called
+(``[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX``).
+Only one measurement per device object may be active at a time. Calling
+**StartMeasurement** while a session is already active returns
+``org.bluez.Error.InProgress``.
+
+When ``role`` is Reflector (``0x02``), this method does not start a CS
+distance measurement: a Reflector never initiates a procedure locally,
+so it cannot start one via this call. Instead, all given configuration
+is applied and stored so the controller is ready to respond once a
+remote Initiator begins a procedure, and the method returns success
+without arming a local measurement session. The ``Active`` property
+only transitions to ``true`` when a remote-initiated procedure
+actually starts, which may happen well after this method returns (or
+not at all, if the remote never initiates one).
+
+For Initiator role (or Both), ``duration_secs`` and the device object
+path are the parameters that matter to start a measurement; every
+other key below is optional configuration with a usable default. For
+Reflector role, only ``role``, ``cs_sync_ant_sel`` and ``max_tx_power``
+are required or have any effect — the remaining keys are accepted but
+otherwise unused, since no local procedure is armed.
+
+Supported dictionary keys:
+
+:uint32 duration_secs (Default: 0):
+
+ Duration in seconds before the measurement is stopped
+ automatically. A value of 0 disables the automatic timeout.
+
+:byte role (Default: 0x03):
+
+ CS role to use for the measurement.
+
+ Possible values:
+
+ :0x01: Initiator
+ :0x02: Reflector
+ :0x03: Both (Initiator and Reflector)
+
+:byte cs_sync_ant_sel (Default: 0xFF):
+
+ CS sync antenna selection. Values 0xFE and 0xFF are reserved
+ by the Bluetooth specification.
+
+:byte max_tx_power (Default: 0x14):
+
+ Maximum TX power in dBm, treated as a signed value. Valid
+ range is -127 to +20 dBm.
+
+:byte config_id:
+
+ CS configuration identifier.
+
+:byte main_mode_type:
+
+ Main CS mode used in the procedure.
+
+:byte sub_mode_type:
+
+ Sub-mode within the main mode. Set to 0xFF when unused.
+
+:byte main_mode_min_steps:
+
+ Minimum number of CS main mode steps per CS subevent.
+
+:byte main_mode_max_steps:
+
+ Maximum number of CS main mode steps per CS subevent.
+
+:byte main_mode_repetition:
+
+ Number of times the main mode steps are repeated in a
+ subevent.
+
+:byte mode0_steps:
+
+ Number of CS Mode 0 steps at the beginning of each subevent.
+
+:byte rtt_types:
+
+ Round Trip Time measurement types for the configuration.
+
+:byte cs_sync_phy:
+
+ PHY used for CS sync packets.
+
+ Possible values:
+
+ :0x01: LE 1M PHY
+ :0x02: LE 2M PHY
+
+:array{byte} channel_map:
+
+ 10-byte channel map bitmap. Must be exactly 10 bytes.
+
+:byte channel_map_repetition:
+
+ Number of consecutive repetitions of the channel map.
+
+:byte channel_selection_type:
+
+ Algorithm used for CS channel selection.
+
+:byte channel_shape:
+
+ Shape used in the channel selection algorithm.
+
+:byte channel_jump:
+
+ Channel jump size used in the channel selection algorithm.
+
+:byte companion_signal_enable:
+
+ Set to 1 to transmit a companion signal alongside the CS
+ tone, 0 to disable.
+
+:uint16 max_procedure_duration:
+
+ Maximum duration of a single CS measurement procedure.
+
+:uint16 min_period_between_procedures:
+
+ Minimum time between consecutive CS measurement procedures.
+
+:uint16 max_period_between_procedures:
+
+ Maximum time between consecutive CS measurement procedures.
+
+:uint16 max_procedure_count:
+
+ Maximum number of CS measurement procedures to run.
+ A value of 0 means no limit.
+
+:array{byte} min_sub_event_len:
+
+ Minimum CS subevent length as a 3-byte little-endian value.
+ Must be exactly 3 bytes.
+
+:array{byte} max_sub_event_len:
+
+ Maximum CS subevent length as a 3-byte little-endian value.
+ Must be exactly 3 bytes.
+
+:byte tone_antenna_config_selection:
+
+ Antenna configuration used for CS tone exchanges.
+
+:byte phy:
+
+ PHY used during CS procedures.
+
+ Possible values:
+
+ :0x01: LE 1M PHY
+ :0x02: LE 2M PHY
+
+:byte tx_power_delta:
+
+ Difference between remote and local TX power during CS
+ procedures. 0x80 indicates not applicable.
+
+:byte preferred_peer_antenna:
+
+ Preferred antenna to be used by the peer device.
+
+:byte snr_control_initiator:
+
+ SNR control setting for the initiator role.
+ 0xFF indicates no preference.
+
+:byte snr_control_reflector:
+
+ SNR control setting for the reflector role.
+ 0xFF indicates no preference.
+
+Possible errors:
+
+:org.bluez.Error.InProgress:
+:org.bluez.Error.InvalidArgs:
+:org.freedesktop.DBus.Error.Failed:
+
+Examples:
+
+:bluetoothctl set role then start:
+ | [cs] > role 0x01
+ | [cs] > main_mode_type 2
+ | [cs] > start AA:BB:CC:DD:EE:FF
+:bluetoothctl start with defaults:
+ | [cs] > start [dev_addr [duration_secs]]
+:bluetoothctl configure as Reflector (applies settings, does not start a measurement):
+ | [cs] > role 0x02
+ | [cs] > start
+
+void StopMeasurement(void)
+``````````````````````````
+
+Stops the active Channel Sounding distance measurement on this device.
+The device is identified by the D-Bus object path on which this method
+is called — no session identifier is required.
+
+Raises ``org.bluez.Error.NotConnected`` if no measurement is active.
+
+Possible errors:
+
+:org.bluez.Error.NotConnected:
+:org.freedesktop.DBus.Error.Failed:
+
+In **bluetoothctl(1)**, the device address argument may be omitted only
+when a single measurement is active; it is required when multiple
+measurements are active.
+
+Examples:
+
+:bluetoothctl stop the only active measurement:
+ | [cs] > stop
+:bluetoothctl stop a specific device when multiple are active:
+ | [cs] > stop AA:BB:CC:DD:EE:FF
+
+Signals
+-------
+
+void ProcedureData(dict data)
+``````````````````````````````
+
+Emitted when a Channel Sounding measurement procedure completes on this
+device, carrying the raw CS procedure results as reported by the
+controller. Consumers such as an external ranging estimation daemon
+subscribe to this signal to compute distance estimates.
+
+:dict data:
+
+ :int32 procedureCounter:
+
+ Procedure counter value from the controller.
+
+ :int32 procedureSequence:
+
+ Sequence number of this procedure.
+
+ :byte initiatorSelectedTxPower:
+
+ TX power selected by the Initiator, treated as a signed
+ value.
+
+ :byte reflectorSelectedTxPower:
+
+ TX power selected by the Reflector, treated as a signed
+ value.
+
+ :uint32 initiatorSubeventCount:
+
+ Number of subevent results reported by the Initiator.
+
+ :array{dict} initiatorSubeventResults:
+
+ Present only when ``initiatorSubeventCount`` is greater
+ than 0. One entry per Initiator subevent, each with the
+ fields described in `Subevent Result`_ below.
+
+ :byte initiatorProcedureAbortReason:
+
+ Reason the Initiator's procedure was aborted, 0 if not
+ aborted.
+
+ :uint32 reflectorSubeventCount:
+
+ Number of subevent results reported by the Reflector.
+
+ :array{dict} reflectorSubeventResults:
+
+ Present only when ``reflectorSubeventCount`` is greater
+ than 0. One entry per Reflector subevent, each with the
+ fields described in `Subevent Result`_ below.
+
+ :byte reflectorProcedureAbortReason:
+
+ Reason the Reflector's procedure was aborted, 0 if not
+ aborted.
+
+ :dict procedureEnableConfig:
+
+ :byte toneAntennaConfigSelection:
+
+ Antenna configuration used for CS tone exchanges.
+
+ :uint32 subeventLenUs:
+
+ Subevent length in microseconds.
+
+ :byte subeventsPerEvent:
+
+ Number of subevents per event.
+
+ :uint32 subeventInterval:
+
+ Interval between subevents.
+
+ :uint32 eventInterval:
+
+ Interval between events.
+
+ :uint32 procedureInterval:
+
+ Interval between procedures.
+
+ :uint32 procedureCount:
+
+ Number of procedures configured.
+
+ :uint32 maxProcedureLen:
+
+ Maximum procedure length.
+
+ :dict csConfigParam:
+
+ :byte modeType:
+
+ Main CS mode used in the procedure.
+
+ :byte subModeType:
+
+ Sub-mode within the main mode.
+
+ :byte rttType:
+
+ Round Trip Time measurement type.
+
+ :array{byte} channelMap:
+
+ 10-byte channel map bitmap.
+
+ :byte minMainModeSteps:
+ :byte maxMainModeSteps:
+ :byte mainModeRepetition:
+ :byte mode0Steps:
+
+ :byte role:
+
+ CS role in effect for the procedure (Initiator,
+ Reflector, or Both).
+
+ :byte csSyncPhyType:
+
+ PHY used for CS sync packets.
+
+ :byte channelSelectionType:
+ :byte ch3cShapeType:
+ :byte ch3cJump:
+ :byte channelMapRepetition:
+ :byte tIp1TimeUs:
+ :byte tIp2TimeUs:
+ :byte tFcsTimeUs:
+ :byte tPmTimeUs:
+ :byte tSwTimeUsSupportedByLocal:
+ :byte tSwTimeUsSupportedByRemote:
+
+ :uint32 bleConnInterval:
+
+ BLE connection interval in effect during the
+ procedure.
+
+Subevent Result
+~~~~~~~~~~~~~~~~
+
+Each element of ``initiatorSubeventResults`` and
+``reflectorSubeventResults`` is a dict with the following fields:
+
+:int32 startAclConnEvtCounter:
+
+ ACL connection event counter at the start of the subevent.
+
+:int32 freqComp:
+
+ Frequency compensation value.
+
+:byte refPwrLvl:
+
+ Reference power level, treated as a signed value.
+
+:byte numAntPaths:
+
+ Number of antenna paths used.
+
+:byte subeventAbortReason:
+
+ Reason the subevent was aborted, 0 if not aborted.
+
+:uint64 timestampNanos:
+
+ Timestamp of the subevent result, in nanoseconds.
+
+:uint32 numSteps:
+
+ Number of steps reported in this subevent.
+
+:array{dict} stepData:
+
+ One entry per step. Each entry has:
+
+ :byte stepMode:
+
+ CS step mode (0-3).
+
+ :byte stepChannel:
+
+ Channel used for the step.
+
+ :dict modeZeroData:
+
+ Present when ``stepMode`` is 0.
+
+ :byte packetQuality:
+ :byte packetRssiDbm:
+ :byte packetAntenna:
+
+ :int32 initiatorMeasuredFreqOffset:
+
+ Frequency offset measured by the Initiator.
+
+ :dict modeOneData:
+
+ Present when ``stepMode`` is 1.
+
+ :byte packetQuality:
+ :byte packetNadm:
+ :byte packetRssiDbm:
+
+ :int32 toaTodInitiator:
+
+ Time of Arrival / Time of Departure at the
+ Initiator.
+
+ :int32 todToaReflector:
+
+ Time of Departure / Time of Arrival at the
+ Reflector.
+
+ :byte packetAntenna:
+
+ :array{int32} packetPct1:
+
+ In-phase/quadrature sample pair, as
+ ``[i_sample, q_sample]``.
+
+ :array{int32} packetPct2:
+
+ In-phase/quadrature sample pair, as
+ ``[i_sample, q_sample]``.
+
+ :dict modeTwoData:
+
+ Present when ``stepMode`` is 2.
+
+ :byte antennaPermutationIndex:
+
+ :array{int32} tonePctIQSamples:
+
+ Interleaved in-phase/quadrature tone samples, as
+ ``[i_sample, q_sample, ...]`` — one pair per
+ antenna path.
+
+ :array{byte} toneQualityIndicators:
+
+ One quality indicator byte per antenna path.
+
+ :dict modeThreeData:
+
+ Present when ``stepMode`` is 3. Contains the combined
+ fields of both **modeOneData** and **modeTwoData**.
+
+Properties
+----------
+
+boolean Active [readonly]
+`````````````````````````
+
+Indicates whether a CS distance measurement procedure is currently
+active on this device.
+
+Set to ``true`` when a procedure starts — either because the local
+Initiator called **StartMeasurement** successfully, or because the
+remote Initiator enabled a CS procedure on the local Reflector.
+
+Set to ``false`` when the procedure stops for any reason: the local
+application called **StopMeasurement**, the measurement duration timer
+expired, or the ACL connection was dropped.
+
+This property emits ``PropertiesChanged`` on every transition so that
+clients can track measurement state without polling.
+
+RESOURCES
+=========
+
+http://www.bluez.org
+
+REPORTING BUGS
+==============
+
+linux-bluetooth@vger.kernel.org
--
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH BlueZ v3 2/3] doc/org.bluez.ChannelSoundingRanging1:Add references and examples
2026-07-09 12:51 [PATCH BlueZ v3 0/3] doc: Add Channel Sounding API and bluetoothctl documentation Naga Bhavani Akella
2026-07-09 12:51 ` [PATCH BlueZ v3 1/3] doc/org.bluez.ChannelSounding1:Add Used by reference and Examples Naga Bhavani Akella
@ 2026-07-09 12:51 ` Naga Bhavani Akella
2026-07-09 12:51 ` [PATCH BlueZ v3 3/3] doc/bluetoothctl-cs: Add :Uses: fields and document arguments Naga Bhavani Akella
2 siblings, 0 replies; 6+ messages in thread
From: Naga Bhavani Akella @ 2026-07-09 12:51 UTC (permalink / raw)
To: linux-bluetooth
Cc: luiz.dentz, quic_mohamull, quic_hbandi, quic_anubhavg,
Naga Bhavani Akella
Add :Used by: field linking to bluetoothctl cs submenu and
Examples section showing the corresponding bluetoothctl output
for the RangeEstimate signal
---
doc/org.bluez.ChannelSoundingRanging1.rst | 66 +++++++++++++++++++++++
1 file changed, 66 insertions(+)
create mode 100644 doc/org.bluez.ChannelSoundingRanging1.rst
diff --git a/doc/org.bluez.ChannelSoundingRanging1.rst b/doc/org.bluez.ChannelSoundingRanging1.rst
new file mode 100644
index 000000000..0151ac503
--- /dev/null
+++ b/doc/org.bluez.ChannelSoundingRanging1.rst
@@ -0,0 +1,66 @@
+==================================
+org.bluez.ChannelSoundingRanging1
+==================================
+
+------------------------------------------------------
+BlueZ D-Bus Channel Sounding Ranging API documentation
+------------------------------------------------------
+
+:Version: BlueZ
+:Date: July 2026
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service: org.bluez
+:Interface: org.bluez.ChannelSoundingRanging1
+:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
+:Used by: **bluetoothctl(1)**, **bluetoothctl-cs(1)**
+
+This interface reports distance estimates derived from Channel Sounding
+measurement data. It is emitted by an external ranging estimation daemon
+(**cs-range-daemon**) which subscribes to the ``ProcedureData`` signal on
+**org.bluez.ChannelSounding1** for every device object, feeds the parsed
+CS procedure data into a distance-estimation library, and re-publishes
+the resulting estimate as **RangeEstimate** on the same device object
+path. It carries no methods or properties of its own.
+
+Signals
+-------
+
+void RangeEstimate(double distance_m, byte confidence)
+````````````````````````````````````````````````````````
+
+Emitted whenever a new distance estimate has been computed for the
+device identified by the object path on which the signal is raised.
+
+:double distance_m:
+
+ Estimated distance to the remote device, in meters.
+
+:byte confidence:
+
+ Confidence level of the estimate, expressed as a percentage
+ (0-100).
+
+Clients that started a Channel Sounding measurement via
+**org.bluez.ChannelSounding1.StartMeasurement** and wish to receive
+range estimates should watch for this signal on the same device object
+path.
+
+Examples:
+
+:bluetoothctl distance output while a measurement is active:
+ | [CS] Distance: 1.234 m Confidence: 87%
+
+RESOURCES
+=========
+
+http://www.bluez.org
+
+REPORTING BUGS
+==============
+
+linux-bluetooth@vger.kernel.org
--
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH BlueZ v3 3/3] doc/bluetoothctl-cs: Add :Uses: fields and document arguments
2026-07-09 12:51 [PATCH BlueZ v3 0/3] doc: Add Channel Sounding API and bluetoothctl documentation Naga Bhavani Akella
2026-07-09 12:51 ` [PATCH BlueZ v3 1/3] doc/org.bluez.ChannelSounding1:Add Used by reference and Examples Naga Bhavani Akella
2026-07-09 12:51 ` [PATCH BlueZ v3 2/3] doc/org.bluez.ChannelSoundingRanging1:Add references and examples Naga Bhavani Akella
@ 2026-07-09 12:51 ` Naga Bhavani Akella
2 siblings, 0 replies; 6+ messages in thread
From: Naga Bhavani Akella @ 2026-07-09 12:51 UTC (permalink / raw)
To: linux-bluetooth
Cc: luiz.dentz, quic_mohamull, quic_hbandi, quic_anubhavg,
Naga Bhavani Akella
Add :Uses: fields to link commands to their corresponding D-Bus API
methods, and document command arguments with usage examples.
---
Makefile.am | 4 +
doc/bluetoothctl-cs.rst | 281 ++++++++++++++++++++++++++++++++++++++++
2 files changed, 285 insertions(+)
create mode 100644 doc/bluetoothctl-cs.rst
diff --git a/Makefile.am b/Makefile.am
index 76c4ab5d4..84d0ff1c0 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -405,6 +405,8 @@ man_MANS += doc/org.bluez.Telephony.5 doc/org.bluez.Call.5
man_MANS += doc/org.bluez.ThermometerManager.5 \
doc/org.bluez.Thermometer.5 \
doc/org.bluez.ThermometerWatcher.5
+man_MANS += doc/org.bluez.ChannelSounding1.5 \
+ doc/org.bluez.ChannelSoundingRanging1.5
endif
manual_pages += doc/bluetoothd.8
manual_pages += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7 \
@@ -445,6 +447,8 @@ manual_pages += doc/org.bluez.Telephony.5 doc/org.bluez.Call.5
manual_pages += doc/org.bluez.ThermometerManager.5 \
doc/org.bluez.Thermometer.5 \
doc/org.bluez.ThermometerWatcher.5
+manual_pages += doc/org.bluez.ChannelSounding1.5 \
+ doc/org.bluez.ChannelSoundingRanging1.5
EXTRA_DIST += src/genbuiltin src/bluetooth.conf \
src/main.conf profiles/network/network.conf \
diff --git a/doc/bluetoothctl-cs.rst b/doc/bluetoothctl-cs.rst
new file mode 100644
index 000000000..05a7c8170
--- /dev/null
+++ b/doc/bluetoothctl-cs.rst
@@ -0,0 +1,281 @@
+================
+bluetoothctl-cs
+================
+
+--------------------------
+Channel Sounding Submenu
+--------------------------
+
+:Version: BlueZ
+:Copyright: Free use of this software is granted under the terms of the GNU
+ Lesser General Public Licenses (LGPL).
+:Date: June 2026
+:Manual section: 1
+:Manual group: Linux System Administration
+
+SYNOPSIS
+========
+
+**bluetoothctl** [--options] [cs.commands]
+
+This submenu controls Bluetooth Channel Sounding (CS) distance measurement
+using the **org.bluez.ChannelSounding1(5)** D-Bus interface. It allows
+starting and stopping measurements and inspecting the current parameter
+state and active session identifier.
+
+Each CS parameter has its own **cs.<param>** set command (see the table
+below). Overrides are applied to the local parameter state immediately,
+so **show** reflects them right away; **start** always uses whatever
+values are currently set.
+
+
+Channel Sounding Commands
+=========================
+
+start
+-----
+
+Starts a distance measurement on the connected device using the
+currently set CS parameters (see the **cs.<param>** commands below).
+All configuration is sent to the daemon in a single **StartMeasurement**
+call. On success the device path is printed to the console. Multiple
+simultaneous sessions across different devices are supported; each is
+tracked independently.
+
+Calling **start** on a device that already has an active measurement
+returns an error without starting a second session on the same device.
+
+For Initiator role (or Both), the mandatory parameters are the
+positional ``dev_addr`` and ``duration_secs``; every ``cs.<param>``
+command below is optional configuration with a usable default.
+
+If ``role`` is set to Reflector (``0x02``, via **cs.role**), **start**
+does not begin measuring distance: a Reflector never initiates a CS
+procedure. It only pushes the current parameters to the daemon and
+arms the device to respond once the remote Initiator starts one; the
+call still succeeds. Use **show** or watch the ``Active`` property to
+see when a procedure is actually running. In this role the only
+parameters that are required or have any effect are ``role``,
+``cs_sync_ant_sel`` and ``max_tx_power``; every other **cs.<param>**
+command below is accepted but unused.
+
+Positional arguments are optional:
+
+- ``dev_addr`` — Bluetooth address of the target device; uses the only
+ available CS-capable device when omitted.
+- ``duration_secs`` — auto-stop timeout in seconds; ``0`` (default) means
+ no timeout.
+
+:Usage: **> start [dev_addr [duration_secs]]**
+:Uses: **org.bluez.ChannelSounding1(5)** method **StartMeasurement**
+:[dev_addr]: Bluetooth address of the target device (optional; uses the
+ only available CS-capable device when omitted)
+:[duration_secs]: Seconds before auto-stop (optional, default 0 = no timeout)
+
+:Example Start with all defaults, no timeout:
+ | **> start**
+:Example Start on a specific device:
+ | **> start AA:BB:CC:DD:EE:FF**
+:Example Start on a specific device with 10-second auto-stop:
+ | **> start AA:BB:CC:DD:EE:FF 10**
+:Example Start with 10-second auto-stop (single device, address omitted):
+ | **> start 0 10**
+:Example Start with 5-minute auto-stop:
+ | **> start AA:BB:CC:DD:EE:FF 300**
+
+Setting CS parameters
+----------------------
+
+Each CS parameter is set with its own command, of the form
+``cs.<param> <value>``. Setting ``cs.role`` prints a note reminding
+which parameters matter for the newly selected role. Array-valued
+parameters (``channel_map``, ``min_sub_event_len``, ``max_sub_event_len``)
+take colon-separated hex bytes with no ``0x`` prefix.
+
+:Usage: **> <param> <value>**
+
+.. list-table::
+ :header-rows: 1
+ :widths: 35 15 50
+
+ * - Command
+ - Default
+ - Description
+ * - ``role``
+ - ``0x03``
+ - ``0x01`` Initiator, ``0x02`` Reflector, ``0x03`` Both
+ * - ``cs_sync_ant_sel``
+ - ``0xFF``
+ - CS sync antenna selection (0xFE/0xFF reserved)
+ * - ``max_tx_power``
+ - ``20``
+ - Max TX power in dBm (signed, range −127 to +20)
+ * - ``config_id``
+ - ``0``
+ - CS configuration identifier
+ * - ``main_mode_type``
+ - ``1``
+ - ``1`` Mode 1 (RTT), ``2`` Mode 2 (PBR), ``3`` Both
+ * - ``sub_mode_type``
+ - ``0xFF``
+ - Sub-mode within main mode; ``0xFF`` = unused
+ * - ``main_mode_min_steps``
+ - ``2``
+ - Min CS main mode steps per subevent
+ * - ``main_mode_max_steps``
+ - ``3``
+ - Max CS main mode steps per subevent
+ * - ``main_mode_repetition``
+ - ``1``
+ - Times main mode steps are repeated in a subevent
+ * - ``mode0_steps``
+ - ``2``
+ - CS Mode 0 steps at the beginning of each subevent
+ * - ``rtt_types``
+ - ``0``
+ - RTT measurement types bitmask
+ * - ``cs_sync_phy``
+ - ``0x01``
+ - PHY for CS sync: ``0x01`` LE 1M, ``0x02`` LE 2M
+ * - ``channel_map``
+ - ``FC:FF:7F:FC:FF:FF:FF:FF:FF:1F``
+ - 10-byte channel map bitmap (colon-separated hex)
+ * - ``channel_map_repetition``
+ - ``1``
+ - Consecutive repetitions of the channel map
+ * - ``channel_selection_type``
+ - ``0``
+ - CS channel selection algorithm
+ * - ``channel_shape``
+ - ``0``
+ - Shape used in channel selection algorithm
+ * - ``channel_jump``
+ - ``2``
+ - Channel jump size
+ * - ``companion_signal_enable``
+ - ``0``
+ - ``1`` to transmit companion signal, ``0`` to disable
+ * - ``max_procedure_duration``
+ - ``1600``
+ - Maximum duration of one CS measurement procedure
+ * - ``min_period_between_procedures``
+ - ``30``
+ - Minimum time between consecutive procedures
+ * - ``max_period_between_procedures``
+ - ``150``
+ - Maximum time between consecutive procedures
+ * - ``max_procedure_count``
+ - ``0``
+ - Max number of procedures; ``0`` = no limit
+ * - ``min_sub_event_len``
+ - ``00:20:00``
+ - Min CS subevent length, 3-byte LE (colon-separated hex)
+ * - ``max_sub_event_len``
+ - ``03:20:00``
+ - Max CS subevent length, 3-byte LE (colon-separated hex)
+ * - ``tone_antenna_config_selection``
+ - ``0x07``
+ - Antenna config for CS tone exchanges
+ * - ``phy``
+ - ``0x01``
+ - PHY for CS procedures: ``0x01`` LE 1M, ``0x02`` LE 2M
+ * - ``tx_power_delta``
+ - ``0x80``
+ - Remote vs local TX power delta; ``0x80`` = not applicable
+ * - ``preferred_peer_antenna``
+ - ``0x03``
+ - Preferred antenna for the peer device
+ * - ``snr_control_initiator``
+ - ``0xFF``
+ - SNR control for initiator; ``0xFF`` = no preference
+ * - ``snr_control_reflector``
+ - ``0xFF``
+ - SNR control for reflector; ``0xFF`` = no preference
+
+:Example Set role to Initiator only:
+ | **> role 0x01**
+:Example Set role to Reflector only (does not measure):
+ | **> role 0x02**
+:Example Set role to both Initiator and Reflector:
+ | **> role 0x03**
+:Example Set main mode to Mode 2 (PBR):
+ | **> main_mode_type 2**
+:Example Set main mode to both RTT and PBR:
+ | **> main_mode_type 3**
+:Example Set CS procedure PHY to LE 2M:
+ | **> phy 0x02**
+:Example Set CS sync PHY to LE 2M:
+ | **> cs_sync_phy 0x02**
+:Example Reduce max TX power to 10 dBm:
+ | **> max_tx_power 10**
+:Example Enable the companion signal:
+ | **> companion_signal_enable 1**
+:Example Limit the procedure count to 100:
+ | **> max_procedure_count 100**
+:Example Prefer high SNR on both roles:
+ | **> snr_control_initiator 0x01**
+ | **> snr_control_reflector 0x01**
+:Example Set a custom channel map (all enabled):
+ | **> channel_map FF:FF:FF:FF:FF:FF:FF:FF:FF:FF**
+:Example Configure Initiator, Mode 2, LE 2M, then start with a 30-second timeout:
+ | **> role 0x01**
+ | **> main_mode_type 2**
+ | **> phy 0x02**
+ | **> cs_sync_phy 0x02**
+ | **> start AA:BB:CC:DD:EE:FF 30**
+:Example Configure both roles, Mode 1, custom step counts, then start:
+ | **> role 0x03**
+ | **> main_mode_type 1**
+ | **> main_mode_min_steps 4**
+ | **> main_mode_max_steps 8**
+ | **> start**
+:Example Configure as Reflector with a 60-second timeout, then start:
+ | **> role 0x02**
+ | **> start AA:BB:CC:DD:EE:FF 60**
+
+stop
+----
+
+Stops an active CS distance measurement. When only one measurement is
+running the device address may be omitted. When multiple measurements
+are active the address is required to identify which one to stop.
+
+:Usage: **> stop [dev_addr]**
+:Uses: **org.bluez.ChannelSounding1(5)** method **StopMeasurement**
+:[dev_addr]: Bluetooth address of the device to stop (optional when
+ only one session is active; required otherwise)
+:Example Stop the only active measurement:
+ | **> stop**
+:Example Stop a specific device when multiple are active:
+ | **> stop AA:BB:CC:DD:EE:FF**
+:Example Stop a second device:
+ | **> stop 11:22:33:44:55:66**
+
+show
+----
+
+Displays all active measurements (device path for each) and the full
+set of CS parameter values that will be used on the next **start** call.
+When no measurements are active, ``none`` is shown.
+
+The parameter output is divided into three sections:
+
+- **Default Settings** — role, CS sync antenna selection, max TX power.
+- **CS Config Params** — per-procedure configuration fields including
+ mode type, step counts, PHY, and channel map.
+- **CS Frequency Params** — procedure scheduling fields including
+ duration, period, subevent lengths, and SNR control.
+
+:Usage: **> show**
+:Example Show active session and all CS parameters:
+ | **> show**
+
+RESOURCES
+=========
+
+http://www.bluez.org
+
+REPORTING BUGS
+==============
+
+linux-bluetooth@vger.kernel.org
--
^ permalink raw reply related [flat|nested] 6+ messages in thread
* RE: doc: Add Channel Sounding API and bluetoothctl documentation
2026-07-09 12:51 ` [PATCH BlueZ v3 1/3] doc/org.bluez.ChannelSounding1:Add Used by reference and Examples Naga Bhavani Akella
@ 2026-07-09 14:49 ` bluez.test.bot
0 siblings, 0 replies; 6+ messages in thread
From: bluez.test.bot @ 2026-07-09 14:49 UTC (permalink / raw)
To: linux-bluetooth, naga.akella
[-- Attachment #1: Type: text/plain, Size: 988 bytes --]
This is automated email and please do not reply to this email!
Dear submitter,
Thank you for submitting the patches to the linux bluetooth mailing list.
This is a CI test results with your patch series:
PW Link:https://patchwork.kernel.org/project/bluetooth/list/?series=1124699
---Test result---
Test Summary:
CheckPatch PASS 1.51 seconds
GitLint PASS 0.79 seconds
BuildEll PASS 20.23 seconds
BluezMake PASS 502.67 seconds
MakeCheck PASS 18.92 seconds
MakeDistcheck PASS 152.17 seconds
CheckValgrind PASS 221.21 seconds
CheckSmatch PASS 291.30 seconds
bluezmakeextell PASS 94.22 seconds
IncrementalBuild PASS 515.72 seconds
ScanBuild PASS 862.24 seconds
https://github.com/bluez/bluez/pull/2284
---
Regards,
Linux Bluetooth
^ permalink raw reply [flat|nested] 6+ messages in thread
* RE: doc: Add Channel Sounding API and bluetoothctl documentation
2026-07-10 5:59 [PATCH BlueZ v4 1/3] doc/org.bluez.ChannelSounding1:Add Used by reference and Examples Naga Bhavani Akella
@ 2026-07-10 9:23 ` bluez.test.bot
0 siblings, 0 replies; 6+ messages in thread
From: bluez.test.bot @ 2026-07-10 9:23 UTC (permalink / raw)
To: linux-bluetooth, naga.akella
[-- Attachment #1: Type: text/plain, Size: 988 bytes --]
This is automated email and please do not reply to this email!
Dear submitter,
Thank you for submitting the patches to the linux bluetooth mailing list.
This is a CI test results with your patch series:
PW Link:https://patchwork.kernel.org/project/bluetooth/list/?series=1125144
---Test result---
Test Summary:
CheckPatch PASS 1.00 seconds
GitLint PASS 0.72 seconds
BuildEll PASS 20.59 seconds
BluezMake PASS 606.38 seconds
MakeCheck PASS 18.06 seconds
MakeDistcheck PASS 142.12 seconds
CheckValgrind PASS 209.13 seconds
CheckSmatch PASS 246.97 seconds
bluezmakeextell PASS 89.02 seconds
IncrementalBuild PASS 671.59 seconds
ScanBuild PASS 783.15 seconds
https://github.com/bluez/bluez/pull/2288
---
Regards,
Linux Bluetooth
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2026-07-10 9:23 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-07-09 12:51 [PATCH BlueZ v3 0/3] doc: Add Channel Sounding API and bluetoothctl documentation Naga Bhavani Akella
2026-07-09 12:51 ` [PATCH BlueZ v3 1/3] doc/org.bluez.ChannelSounding1:Add Used by reference and Examples Naga Bhavani Akella
2026-07-09 14:49 ` doc: Add Channel Sounding API and bluetoothctl documentation bluez.test.bot
2026-07-09 12:51 ` [PATCH BlueZ v3 2/3] doc/org.bluez.ChannelSoundingRanging1:Add references and examples Naga Bhavani Akella
2026-07-09 12:51 ` [PATCH BlueZ v3 3/3] doc/bluetoothctl-cs: Add :Uses: fields and document arguments Naga Bhavani Akella
-- strict thread matches above, loose matches on Subject: below --
2026-07-10 5:59 [PATCH BlueZ v4 1/3] doc/org.bluez.ChannelSounding1:Add Used by reference and Examples Naga Bhavani Akella
2026-07-10 9:23 ` doc: Add Channel Sounding API and bluetoothctl documentation bluez.test.bot
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox