bluetoothctl-cs(1) Linux System Administration bluetoothctl-cs(1)

bluetoothctl-cs - Channel Sounding Submenu

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 CS Parameter Commands section below). Overrides are applied to the local parameter state immediately, so show reflects them right away; start always uses whatever values are currently set.

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. When the remote side starts or stops a procedure, the console prints Measurement started/Measurement stopped for that device — use show or watch the Active property to see the same transition. In this role the only parameters that are required or have any effect are role, 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.
> start [dev_addr] [duration_secs]
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)
> start
> start AA:BB:CC:DD:EE:FF
> start AA:BB:CC:DD:EE:FF 10
> start 0 10
> start AA:BB:CC:DD:EE:FF 300

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.

> stop [dev_addr]
org.bluez.ChannelSounding1(5) method StopMeasurement
[dev_addr]
Bluetooth address of the device to stop (optional when only one session is active; required otherwise)
> stop
> stop AA:BB:CC:DD:EE:FF
> stop 11:22:33:44:55:66

Controls the RAP Requester's received Ranging Data subscriptions independently of the local CS measurement lifecycle. Changing the mode disables the current RAS data CCCDs before enabling the requested mode.

> ranging-data-mode <dev_addr> <disabled/realtime/ondemand> [notify/indicate]
org.bluez.ChannelSounding1(5) method SetRangingDataMode
Disables all Ranging Data subscriptions.
Enables Real-time Ranging Data; transport defaults to notify.
Enables On-demand Data, Control Point, Ready, and Overwritten; transport defaults to notify. On-demand Data remains notification-based so segmented transfers are not limited by indication confirmation pacing.
Uses CCCD 0x0001 for the selected Ranging Data mode.
Uses CCCD 0x0002 for the selected Ranging Data mode.
> ranging-data-mode AA:BB:CC:DD:EE:FF disabled
> ranging-data-mode AA:BB:CC:DD:EE:FF realtime indicate
> ranging-data-mode AA:BB:CC:DD:EE:FF ondemand indicate

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.

Reference implementation only — not a real ranging algorithm. Registers bluetoothctl itself as a Channel Sounding ranging provider via RegisterRangingProvider(), then listens for ProcedureData signals on org.bluez.ChannelSounding1(5) and turns each one into a bounded, illustrative distance estimate (not an accurate measurement) exposed via org.bluez.RangingProvider1(5) — visible on the device's org.bluez.Ranging1(5) Distance property once bluetoothd reflects it.

The provider path defaults to /, the only path bluetoothctl exposes an ObjectManager at; a different path will register but bluetoothd will not discover any objects under it. The exported RangingProvider1 objects themselves are nested under /org/example/ranging rather than directly under /. See test/example-ranging-provider for a minimal standalone provider skeleton, which reports a fixed placeholder distance and does not parse ProcedureData at all.

Only one ranging provider may be registered per adapter at a time. If a real ranging daemon is already registered, this command fails with AlreadyExists; conversely, a real daemon cannot register while bluetoothctl's reference provider is active. Run unregister_provider (or stop the other provider) first.

> register_provider [path]
org.bluez.RangingProviderManager1(5) method RegisterRangingProvider
[path]
Provider root object path (optional; default /)
> register_provider

Unregisters the ranging provider previously registered with register_provider, removing its exposed RangingProvider objects.

> unregister_provider
org.bluez.RangingProviderManager1(5) method UnregisterRangingProvider
> unregister_provider

Each CS parameter is set with its own command, of the form cs.<param> <value>. Entering a param command with no value shows its current setting. Overrides apply to the local parameter state immediately, so show reflects them right away; start always uses whatever values are currently set. Array-valued parameters (channel_map, min_sub_event_len, max_sub_event_len) take colon-separated hex bytes with no 0x prefix.

> <param> [value]

Get/set the CS role.

> role [0x01|0x02|0x03]
[0x01|0x02|0x03]
0x01 Initiator, 0x02 Reflector, 0x03 Both (optional, shows current if omitted; default 0x03)
> role
> role 0x01
> role 0x02
> role 0x03

Get/set the CS sync antenna selection.

> sync_ant_sel [value]
[value]
CS sync antenna selection; 0xFE/0xFF reserved (optional, shows current if omitted; default 0xFF)
> sync_ant_sel
> sync_ant_sel 0x01

Get/set the maximum TX power.

> max_tx_power [dBm]
[dBm]
Max TX power in dBm, signed (optional, shows current if omitted; range −127 to +20; default 20)
> max_tx_power
> max_tx_power 10

Get/set the CS configuration identifier.

> config_id [value]
[value]
CS configuration identifier (optional, shows current if omitted; default 0)
> config_id
> config_id 1

Get/set where the CS configuration is written when cs.start sends it to the Controller.

> create_context [0|1]
[0|1]
0x00 write the configuration to the local Controller only; 0x01 also write it to the remote Controller using the CS Configuration procedure (optional, shows current if omitted; default 1)
> create_context
> create_context 0
> create_context 1

Get/set the CS main mode type.

> main_mode_type [1|2|3]
[1|2|3]
1 Mode 1 (RTT), 2 Mode 2 (PBR), 3 Both (optional, shows current if omitted; default 1)
> main_mode_type
> main_mode_type 2
> main_mode_type 3

Get/set the CS sub-mode type within the main mode.

> sub_mode_type [value]
[value]
Sub-mode within main mode; 0xFF = unused (optional, shows current if omitted; default 0xFF)
> sub_mode_type
> sub_mode_type 0x01

Get/set the minimum CS main mode steps per subevent.

> main_mode_min_steps [value]
[value]
Min CS main mode steps per subevent (optional, shows current if omitted; default 2)
> main_mode_min_steps
> main_mode_min_steps 4

Get/set the maximum CS main mode steps per subevent.

> main_mode_max_steps [value]
[value]
Max CS main mode steps per subevent (optional, shows current if omitted; default 3)
> main_mode_max_steps
> main_mode_max_steps 8

Get/set how many times main mode steps are repeated in a subevent.

> main_mode_repetition [value]
[value]
Repetition count (optional, shows current if omitted; default 1)
> main_mode_repetition
> main_mode_repetition 2

Get/set the number of CS Mode 0 steps at the beginning of each subevent.

> mode0_steps [value]
[value]
CS Mode 0 step count (optional, shows current if omitted; default 2)
> mode0_steps
> mode0_steps 3

Get/set the RTT measurement types bitmask.

> rtt_types [value]
[value]
RTT measurement types bitmask (optional, shows current if omitted; default 0)
> rtt_types
> rtt_types 0x01

Get/set the PHY used for CS sync.

> sync_phy [0x01|0x02]
[0x01|0x02]
0x01 LE 1M, 0x02 LE 2M (optional, shows current if omitted; default 0x01)
> sync_phy
> sync_phy 0x02

Get/set the 10-byte CS channel map bitmap.

> channel_map [b0:b1:...:b9]
[b0:b1:...:b9]
10 colon-separated hex bytes (optional, shows current if omitted; default FC:FF:7F:FC:FF:FF:FF:FF:FF:1F)
> channel_map
> channel_map FF:FF:FF:FF:FF:FF:FF:FF:FF:FF

Get/set the number of consecutive repetitions of the channel map.

> channel_map_repetition [value]
[value]
Repetition count (optional, shows current if omitted; default 1)
> channel_map_repetition
> channel_map_repetition 3

Get/set the CS channel selection algorithm.

> channel_selection_type [value]
[value]
Channel selection algorithm (optional, shows current if omitted; default 0)
> channel_selection_type
> channel_selection_type 1

Get/set the shape used in the channel selection algorithm.

> channel_shape [value]
[value]
Channel shape (optional, shows current if omitted; default 0)
> channel_shape
> channel_shape 1

Get/set the channel jump size.

> channel_jump [value]
[value]
Channel jump size (optional, shows current if omitted; default 2)
> channel_jump
> channel_jump 4

Get/set whether the companion signal is transmitted.

> companion_signal_enable [0|1]
[0|1]
1 to transmit companion signal, 0 to disable (optional, shows current if omitted; default 0)
> companion_signal_enable
> companion_signal_enable 1

Get/set the maximum duration of one CS measurement procedure.

> max_procedure_duration [value]
[value]
Maximum procedure duration (optional, shows current if omitted; default 1600)
> max_procedure_duration
> max_procedure_duration 800

Get/set the minimum time between consecutive procedures.

> min_period_between_procedures [value]
[value]
Minimum period (optional, shows current if omitted; default 30)
> min_period_between_procedures
> min_period_between_procedures 50

Get/set the maximum time between consecutive procedures.

> max_period_between_procedures [value]
[value]
Maximum period (optional, shows current if omitted; default 150)
> max_period_between_procedures
> max_period_between_procedures 200

Get/set the maximum number of procedures.

> max_procedure_count [value]
[value]
Max procedure count; 0 = no limit (optional, shows current if omitted; default 0)
> max_procedure_count
> max_procedure_count 100

Get/set the minimum CS subevent length.

> min_sub_event_len [b0:b1:b2]
[b0:b1:b2]
3-byte LE value, colon-separated hex (optional, shows current if omitted; default 00:20:00)
> min_sub_event_len
> min_sub_event_len 00:10:00

Get/set the maximum CS subevent length.

> max_sub_event_len [b0:b1:b2]
[b0:b1:b2]
3-byte LE value, colon-separated hex (optional, shows current if omitted; default 03:20:00)
> max_sub_event_len
> max_sub_event_len 04:20:00

Get/set the antenna configuration for CS tone exchanges.

> tone_antenna_config_selection [value]
[value]
Antenna config selection (optional, shows current if omitted; default 0x07)
> tone_antenna_config_selection
> tone_antenna_config_selection 0x01

Get/set the PHY used for CS procedures.

> phy [0x01|0x02]
[0x01|0x02]
0x01 LE 1M, 0x02 LE 2M (optional, shows current if omitted; default 0x01)
> phy
> phy 0x02

Get/set the remote vs local TX power delta.

> tx_power_delta [value]
[value]
TX power delta; 0x80 = not applicable (optional, shows current if omitted; default 0x80)
> tx_power_delta
> tx_power_delta 0x05

Get/set the preferred antenna for the peer device.

> preferred_peer_antenna [value]
[value]
Preferred peer antenna (optional, shows current if omitted; default 0x03)
> preferred_peer_antenna
> preferred_peer_antenna 0x01

Get/set the SNR control for the initiator.

> snr_control_initiator [value]
[value]
SNR control; 0xFF = no preference (optional, shows current if omitted; default 0xFF)
> snr_control_initiator
> snr_control_initiator 0x01

Get/set the SNR control for the reflector.

> snr_control_reflector [value]
[value]
SNR control; 0xFF = no preference (optional, shows current if omitted; default 0xFF)
> snr_control_reflector
> snr_control_reflector 0x01
> snr_control_initiator 0x01
> snr_control_reflector 0x01

http://www.bluez.org

<linux-bluetooth@vger.kernel.org>

Free use of this software is granted under the terms of the GNU Lesser General Public Licenses (LGPL).

June 2026 BlueZ