org.bluez.ChannelSounding1(5) Linux System Administration org.bluez.ChannelSounding1(5)

org.bluez.ChannelSounding1 - BlueZ D-Bus Channel Sounding API documentation

org.bluez
org.bluez.ChannelSounding1
[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
bluetoothctl(1), bluetoothctl-cs(1)

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). Clients that watch PropertiesChanged for Active (as bluetoothctl-cs(1) does) are notified of both the remote-initiated start and its eventual stop.

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, 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:

0):

Duration in seconds before the measurement is stopped automatically. A value of 0 disables the automatic timeout.

0x03):

CS role to use for the measurement.

Possible values:

0x01
Initiator
0x02
Reflector
0x03
Both (Initiator and Reflector)
0xFF):

CS sync antenna selection. Values 0xFE and 0xFF are reserved by the Bluetooth specification.

0x14):

Maximum TX power in dBm, treated as a signed value. Valid range is -127 to +20 dBm.

0x01):

Controls where the CS configuration is written. Set to 0x00 to write the configuration only to the local Controller. Set to 0x01 to write it to both the local and remote Controllers using the CS Configuration procedure.

CS configuration identifier.
Main CS mode used in the procedure.
Sub-mode within the main mode. Set to 0xFF when unused.
Minimum number of CS main mode steps per CS subevent.
Maximum number of CS main mode steps per CS subevent.
Number of times the main mode steps are repeated in a subevent.
Number of CS Mode 0 steps at the beginning of each subevent.
Round Trip Time measurement types for the configuration.
PHY used for CS sync packets.

Possible values:

0x01
LE 1M PHY
0x02
LE 2M PHY
10-byte channel map bitmap. Must be exactly 10 bytes.
Number of consecutive repetitions of the channel map.
Algorithm used for CS channel selection.
Shape used in the channel selection algorithm.
Channel jump size used in the channel selection algorithm.
Set to 1 to transmit a companion signal alongside the CS tone, 0 to disable.
Maximum duration of a single CS measurement procedure.
Minimum time between consecutive CS measurement procedures.
Maximum time between consecutive CS measurement procedures.
Maximum number of CS measurement procedures to run. A value of 0 means no limit.
Minimum CS subevent length as a 3-byte little-endian value. Must be exactly 3 bytes.
Maximum CS subevent length as a 3-byte little-endian value. Must be exactly 3 bytes.
Antenna configuration used for CS tone exchanges.
PHY used during CS procedures.

Possible values:

0x01
LE 1M PHY
0x02
LE 2M PHY
Difference between remote and local TX power during CS procedures. 0x80 indicates not applicable.
Preferred antenna to be used by the peer device.
SNR control setting for the initiator role. 0xFF indicates no preference.
SNR control setting for the reflector role. 0xFF indicates no preference.

Possible errors:

Examples:

[cs] > role 0x01
[cs] > main_mode_type 2
[cs] > start AA:BB:CC:DD:EE:FF
[cs] > start [dev_addr] [duration_secs]
[cs] > role 0x02
[cs] > start

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:

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:

Selects the RAP Requester's received Ranging Data subscription after remote RAS discovery has completed. This is independent of the local Channel Sounding measurement lifecycle. Changing mode first disables all current Ranging Data CCCD subscriptions, then enables the selected mode.

mode values:

0x00
Disabled. Stop receiving Ranging Data and disable all RAS data CCCDs.
0x01
Real-time. Enable the Real-time Ranging Data CCCD.
0x02
On-demand. Enable On-demand Data, Control Point, Ready, and Overwritten CCCDs.

transport selects the CCCD value for Real-time or On-demand mode. It is ignored for Disabled mode. Use 0x01 for notifications or 0x02 for indications. For On-demand mode, this applies to Control Point, Ready, and Overwritten; segmented On-demand Data always uses notifications.

Raises org.bluez.Error.Failed when remote RAS discovery and Features read have not completed, or the selected mode is unsupported by the peer.

Example:

[cs] > ranging-data-mode AA:BB:CC:DD:EE:FF disabled
[cs] > ranging-data-mode AA:BB:CC:DD:EE:FF realtime indicate
[cs] > ranging-data-mode AA:BB:CC:DD:EE:FF ondemand indicate

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.

data is an opaque binary blob rather than an introspectable D-Bus dict: every field is raw controller measurement data with no standalone meaning outside of the ranging algorithm that consumes it, so there is no debugging value in exposing it field-by-field at the D-Bus level. Consumers must decode it according to the fixed layout below.

All multi-byte integer fields are little-endian. Signed fields are noted explicitly; all others are unsigned.

ProcedureData blob:

u16  procedureCounter
u16  procedureSequence
s8   initiatorSelectedTxPower
s8   reflectorSelectedTxPower
u32  initiatorSubeventCount
<initiatorSubeventCount> x SubeventBlob
u8   initiatorProcedureAbortReason
u32  reflectorSubeventCount
<reflectorSubeventCount> x SubeventBlob
u8   reflectorProcedureAbortReason
ProcEnableConfigBlob
CsConfigParamBlob

SubeventBlob:

u16  startAclConnEvtCounter
u16  freqComp
s8   refPwrLvl
u8   numAntPaths
u8   subeventAbortReason
u64  timestampNanos
u32  numSteps
<numSteps> x StepBlob

StepBlob:

u8   stepMode                  # 0-3, selects the payload below
u8   stepChannel
<mode payload, shape per stepMode -- see Mode*Blob below>

ModeZeroBlob (5 bytes, present when stepMode is 0):

u8   packetQuality
u8   packetRssiDbm
u8   packetAntenna
u16  initiatorMeasuredFreqOffset

ModeOneBlob (16 bytes, present when stepMode is 1):

u8   packetQuality
u8   packetNadm
u8   packetRssiDbm
s16  toaTodInitiator
s16  todToaReflector
u8   packetAntenna
s16  packetPct1_i
s16  packetPct1_q
s16  packetPct2_i
s16  packetPct2_q

ModeTwoBlob (1 + 5*numPaths bytes, present when stepMode is 2):

u8   antennaPermutationIndex
<numPaths> x { s16 toneI, s16 toneQ }
<numPaths> x u8 toneQualityIndicator
# numPaths = min(numAntPaths + 1, 5), where numAntPaths comes from
# the enclosing SubeventBlob.

ModeThreeBlob (present when stepMode is 3):

ModeOneBlob
ModeTwoBlob

ProcEnableConfigBlob (16 bytes):

u8   toneAntennaConfigSelection
u32  subeventLenUs
u8   subeventsPerEvent
u16  subeventInterval
u16  eventInterval
u16  procedureInterval
u16  procedureCount
u16  maxProcedureLen

CsConfigParamBlob (30 bytes):

u8   modeType
u8   subModeType
u8   rttType
u8[10] channelMap
u8   minMainModeSteps
u8   maxMainModeSteps
u8   mainModeRepetition
u8   mode0Steps
u8   role
u8   csSyncPhyType
u8   channelSelectionType
u8   ch3cShapeType
u8   ch3cJump
u8   channelMapRepetition
u8   tIp1TimeUs
u8   tIp2TimeUs
u8   tFcsTimeUs
u8   tPmTimeUs
u8   tSwTimeUsSupportedByLocal
u8   tSwTimeUsSupportedByRemote
u16  bleConnInterval

The total blob length is fully determined by the counts embedded in the blob itself (initiatorSubeventCount, reflectorSubeventCount, each subevent's numSteps, and each mode-two step's numAntPaths) — there is no separate length table to consult.

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.

http://www.bluez.org

<linux-bluetooth@vger.kernel.org>

June 2026 BlueZ