.\" Man page generated from reStructuredText .\" by the Docutils 0.23 manpage writer. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "org.bluez.ChannelSounding1" "5" "June 2026" "BlueZ" "Linux System Administration" .SH Name org.bluez.ChannelSounding1 \- BlueZ D-Bus Channel Sounding API documentation .SH Interface .INDENT 0.0 .TP .B Service org.bluez .TP .B Interface org.bluez.ChannelSounding1 .TP .B Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX .TP .B Used by \fBbluetoothctl(1)\fP, \fBbluetoothctl\-cs(1)\fP .UNINDENT .SS Methods .SS void StartMeasurement(dict params) .sp Starts a Channel Sounding distance measurement procedure on the connected device. All configuration is supplied in a single \fBa{sv}\fP dictionary. Any key that is omitted retains its current value in the daemon. .sp The device to measure is identified by the D\-Bus object path on which this method is called (\fB[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX\fP). Only one measurement per device object may be active at a time. Calling \fBStartMeasurement\fP while a session is already active returns \fBorg.bluez.Error.InProgress\fP\&. .sp When \fBrole\fP is Reflector (\fB0x02\fP), 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 \fBActive\fP property only transitions to \fBtrue\fP 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 \fBPropertiesChanged\fP for \fBActive\fP (as \fBbluetoothctl\-cs(1)\fP does) are notified of both the remote\-initiated start and its eventual stop. .sp For Initiator role (or Both), \fBduration_secs\fP 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 \fBrole\fP, \fBsync_ant_sel\fP and \fBmax_tx_power\fP are required or have any effect — the remaining keys are accepted but otherwise unused, since no local procedure is armed. .sp Supported dictionary keys: .INDENT 0.0 .TP .B uint32 duration_secs (Default 0): .sp Duration in seconds before the measurement is stopped automatically. A value of 0 disables the automatic timeout. .TP .B byte role (Default 0x03): .sp CS role to use for the measurement. .sp Possible values: .INDENT 7.0 .TP .B 0x01 Initiator .TP .B 0x02 Reflector .TP .B 0x03 Both (Initiator and Reflector) .UNINDENT .TP .B byte sync_ant_sel (Default 0xFF): .sp CS sync antenna selection. Values 0xFE and 0xFF are reserved by the Bluetooth specification. .TP .B byte max_tx_power (Default 0x14): .sp Maximum TX power in dBm, treated as a signed value. Valid range is \-127 to +20 dBm. .TP .B byte create_context (Default 0x01): .sp 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. .TP .B byte config_id CS configuration identifier. .TP .B byte main_mode_type Main CS mode used in the procedure. .TP .B byte sub_mode_type Sub\-mode within the main mode. Set to 0xFF when unused. .TP .B byte main_mode_min_steps Minimum number of CS main mode steps per CS subevent. .TP .B byte main_mode_max_steps Maximum number of CS main mode steps per CS subevent. .TP .B byte main_mode_repetition Number of times the main mode steps are repeated in a subevent. .TP .B byte mode0_steps Number of CS Mode 0 steps at the beginning of each subevent. .TP .B byte rtt_types Round Trip Time measurement types for the configuration. .TP .B byte sync_phy PHY used for CS sync packets. .sp Possible values: .INDENT 7.0 .TP .B 0x01 LE 1M PHY .TP .B 0x02 LE 2M PHY .UNINDENT .TP .B array{byte} channel_map 10\-byte channel map bitmap. Must be exactly 10 bytes. .TP .B byte channel_map_repetition Number of consecutive repetitions of the channel map. .TP .B byte channel_selection_type Algorithm used for CS channel selection. .TP .B byte channel_shape Shape used in the channel selection algorithm. .TP .B byte channel_jump Channel jump size used in the channel selection algorithm. .TP .B byte companion_signal_enable Set to 1 to transmit a companion signal alongside the CS tone, 0 to disable. .TP .B uint16 max_procedure_duration Maximum duration of a single CS measurement procedure. .TP .B uint16 min_period_between_procedures Minimum time between consecutive CS measurement procedures. .TP .B uint16 max_period_between_procedures Maximum time between consecutive CS measurement procedures. .TP .B uint16 max_procedure_count Maximum number of CS measurement procedures to run. A value of 0 means no limit. .TP .B array{byte} min_sub_event_len Minimum CS subevent length as a 3\-byte little\-endian value. Must be exactly 3 bytes. .TP .B array{byte} max_sub_event_len Maximum CS subevent length as a 3\-byte little\-endian value. Must be exactly 3 bytes. .TP .B byte tone_antenna_config_selection Antenna configuration used for CS tone exchanges. .TP .B byte phy PHY used during CS procedures. .sp Possible values: .INDENT 7.0 .TP .B 0x01 LE 1M PHY .TP .B 0x02 LE 2M PHY .UNINDENT .TP .B byte tx_power_delta Difference between remote and local TX power during CS procedures. 0x80 indicates not applicable. .TP .B byte preferred_peer_antenna Preferred antenna to be used by the peer device. .TP .B byte snr_control_initiator SNR control setting for the initiator role. 0xFF indicates no preference. .TP .B byte snr_control_reflector SNR control setting for the reflector role. 0xFF indicates no preference. .UNINDENT .sp Possible errors: .INDENT 0.0 .TP .B org.bluez.Error.InProgress .TP .B org.bluez.Error.InvalidArgs .TP .B org.freedesktop.DBus.Error.Failed .UNINDENT .sp Examples: .INDENT 0.0 .TP .B bluetoothctl set role then start .nf [cs] > role 0x01 [cs] > main_mode_type 2 [cs] > start AA:BB:CC:DD:EE:FF .fi .sp .TP .B bluetoothctl start with defaults .nf [cs] > start [dev_addr] [duration_secs] .fi .sp .TP .B bluetoothctl configure as Reflector (applies settings, does not start a measurement) .nf [cs] > role 0x02 [cs] > start .fi .sp .UNINDENT .SS void StopMeasurement(void) .sp 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. .sp Raises \fBorg.bluez.Error.NotConnected\fP if no measurement is active. .sp Possible errors: .INDENT 0.0 .TP .B org.bluez.Error.NotConnected .TP .B org.freedesktop.DBus.Error.Failed .UNINDENT .sp In \fBbluetoothctl(1)\fP, the device address argument may be omitted only when a single measurement is active; it is required when multiple measurements are active. .sp Examples: .INDENT 0.0 .TP .B bluetoothctl stop the only active measurement .nf [cs] > stop .fi .sp .TP .B bluetoothctl stop a specific device when multiple are active .nf [cs] > stop AA:BB:CC:DD:EE:FF .fi .sp .UNINDENT .SS void SetRangingDataMode(byte mode, byte transport) .sp Selects the RAP Requester\(aqs 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. .sp \fBmode\fP values: .INDENT 0.0 .TP .B 0x00 Disabled. Stop receiving Ranging Data and disable all RAS data CCCDs. .TP .B 0x01 Real\-time. Enable the Real\-time Ranging Data CCCD. .TP .B 0x02 On\-demand. Enable On\-demand Data, Control Point, Ready, and Overwritten CCCDs. .UNINDENT .sp \fBtransport\fP selects the CCCD value for Real\-time or On\-demand mode. It is ignored for Disabled mode. Use \fB0x01\fP for notifications or \fB0x02\fP for indications. For On\-demand mode, this applies to Control Point, Ready, and Overwritten; segmented On\-demand Data always uses notifications. .sp Raises \fBorg.bluez.Error.Failed\fP when remote RAS discovery and Features read have not completed, or the selected mode is unsupported by the peer. .sp Example: .INDENT 0.0 .TP .B bluetoothctl disable Real\-time Ranging Data .nf [cs] > ranging\-data\-mode AA:BB:CC:DD:EE:FF disabled .fi .sp .TP .B bluetoothctl enable Real\-time indications .nf [cs] > ranging\-data\-mode AA:BB:CC:DD:EE:FF realtime indicate .fi .sp .TP .B bluetoothctl enable On\-demand indications .nf [cs] > ranging\-data\-mode AA:BB:CC:DD:EE:FF ondemand indicate .fi .sp .UNINDENT .SS Signals .SS void ProcedureData(array{byte} data) .sp 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. .sp \fBdata\fP 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. .sp All multi\-byte integer fields are little\-endian. Signed fields are noted explicitly; all others are unsigned. .sp ProcedureData blob: .INDENT 0.0 .INDENT 3.5 .sp .EX u16 procedureCounter u16 procedureSequence s8 initiatorSelectedTxPower s8 reflectorSelectedTxPower u32 initiatorSubeventCount x SubeventBlob u8 initiatorProcedureAbortReason u32 reflectorSubeventCount x SubeventBlob u8 reflectorProcedureAbortReason ProcEnableConfigBlob CsConfigParamBlob .EE .UNINDENT .UNINDENT .sp SubeventBlob: .INDENT 0.0 .INDENT 3.5 .sp .EX u16 startAclConnEvtCounter u16 freqComp s8 refPwrLvl u8 numAntPaths u8 subeventAbortReason u64 timestampNanos u32 numSteps x StepBlob .EE .UNINDENT .UNINDENT .sp StepBlob: .INDENT 0.0 .INDENT 3.5 .sp .EX u8 stepMode # 0\-3, selects the payload below u8 stepChannel .EE .UNINDENT .UNINDENT .sp ModeZeroBlob (5 bytes, present when stepMode is 0): .INDENT 0.0 .INDENT 3.5 .sp .EX u8 packetQuality u8 packetRssiDbm u8 packetAntenna u16 initiatorMeasuredFreqOffset .EE .UNINDENT .UNINDENT .sp ModeOneBlob (16 bytes, present when stepMode is 1): .INDENT 0.0 .INDENT 3.5 .sp .EX u8 packetQuality u8 packetNadm u8 packetRssiDbm s16 toaTodInitiator s16 todToaReflector u8 packetAntenna s16 packetPct1_i s16 packetPct1_q s16 packetPct2_i s16 packetPct2_q .EE .UNINDENT .UNINDENT .sp ModeTwoBlob (1 + 5*numPaths bytes, present when stepMode is 2): .INDENT 0.0 .INDENT 3.5 .sp .EX u8 antennaPermutationIndex x { s16 toneI, s16 toneQ } x u8 toneQualityIndicator # numPaths = min(numAntPaths + 1, 5), where numAntPaths comes from # the enclosing SubeventBlob. .EE .UNINDENT .UNINDENT .sp ModeThreeBlob (present when stepMode is 3): .INDENT 0.0 .INDENT 3.5 .sp .EX ModeOneBlob ModeTwoBlob .EE .UNINDENT .UNINDENT .sp ProcEnableConfigBlob (16 bytes): .INDENT 0.0 .INDENT 3.5 .sp .EX u8 toneAntennaConfigSelection u32 subeventLenUs u8 subeventsPerEvent u16 subeventInterval u16 eventInterval u16 procedureInterval u16 procedureCount u16 maxProcedureLen .EE .UNINDENT .UNINDENT .sp CsConfigParamBlob (30 bytes): .INDENT 0.0 .INDENT 3.5 .sp .EX 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 .EE .UNINDENT .UNINDENT .sp The total blob length is fully determined by the counts embedded in the blob itself (\fBinitiatorSubeventCount\fP, \fBreflectorSubeventCount\fP, each subevent\(aqs \fBnumSteps\fP, and each mode\-two step\(aqs \fBnumAntPaths\fP) — there is no separate length table to consult. .SS Properties .SS boolean Active [readonly] .sp Indicates whether a CS distance measurement procedure is currently active on this device. .sp Set to \fBtrue\fP when a procedure starts — either because the local Initiator called \fBStartMeasurement\fP successfully, or because the remote Initiator enabled a CS procedure on the local Reflector. .sp Set to \fBfalse\fP when the procedure stops for any reason: the local application called \fBStopMeasurement\fP, the measurement duration timer expired, or the ACL connection was dropped. .sp This property emits \fBPropertiesChanged\fP on every transition so that clients can track measurement state without polling. .SH RESOURCES .sp \% .SH REPORTING BUGS .sp \% .\" End of generated man page.