CTE Receiver#

CTE Receiver.




Modules
CTE type flags for limiting periodic advertising synchronization

sl_bt_evt_cte_receiver_dtm_iq_report
IQ sample report from DTM CTE packets.

sl_bt_evt_cte_receiver_connection_iq_report
IQ sample report from connection CTE packets.

sl_bt_evt_cte_receiver_connectionless_iq_report
IQ sample report from connectionless CTE packets.

sl_bt_evt_cte_receiver_silabs_iq_report
IQ samples report from Silicon Labs CTE packets.




Functions
sl_status_t	sl_bt_cte_receiver_set_dtm_parameters (uint8_t cte_length, uint8_t cte_type, uint8_t slot_durations, size_t switching_pattern_len, const uint8_t *switching_pattern)

sl_status_t	sl_bt_cte_receiver_clear_dtm_parameters ()

sl_status_t	sl_bt_cte_receiver_set_sync_cte_type (uint8_t sync_cte_type)

sl_status_t	sl_bt_cte_receiver_set_default_sync_receive_parameters (uint8_t mode, uint16_t skip, uint16_t timeout, uint8_t sync_cte_type, uint8_t reporting_mode)

sl_status_t	sl_bt_cte_receiver_set_sync_receive_parameters (uint8_t connection, uint8_t mode, uint16_t skip, uint16_t timeout, uint8_t sync_cte_type, uint8_t reporting_mode)

sl_status_t	sl_bt_cte_receiver_enable_connection_cte (uint8_t connection, uint16_t interval, uint8_t cte_length, uint8_t cte_type, uint8_t slot_durations, size_t switching_pattern_len, const uint8_t *switching_pattern)

sl_status_t	sl_bt_cte_receiver_disable_connection_cte (uint8_t connection)

sl_status_t	sl_bt_cte_receiver_enable_connectionless_cte (uint16_t sync, uint8_t slot_durations, uint8_t cte_count, size_t switching_pattern_len, const uint8_t *switching_pattern)

sl_status_t	sl_bt_cte_receiver_disable_connectionless_cte (uint16_t sync)

sl_status_t	sl_bt_cte_receiver_enable_silabs_cte (uint8_t slot_durations, uint8_t cte_count, size_t switching_pattern_len, const uint8_t *switching_pattern)

sl_status_t	sl_bt_cte_receiver_disable_silabs_cte ()

Detailed Description#

CTE Receiver.

Commands and events in this class manage Constant Tone Extension (CTE) receiving.

CTE feature is only supported by specific devices. Commands from this class will return SL_STATUS_NOT_SUPPORTED on devices that do not support CTE.

Function Documentation#

◆sl_bt_cte_receiver_set_dtm_parameters()#



sl_status_t sl_bt_cte_receiver_set_dtm_parameters	(	uint8_t	`cte_length,`
		uint8_t	`cte_type,`
		uint8_t	`slot_durations,`
		size_t	`switching_pattern_len,`
		const uint8_t *	`switching_pattern`
	)

Set CTE-related parameters of LE receiver test.

Parameters



[in]	`cte_length`	Expected CTE length in 8 us units* 0: No CTE

0x02 to 0x14: Expected CTE length

Default: 0 (no CTE) | | [in] | cte_type | Expected CTE type* 0: Expect AoA CTE

1: Expect AoD CTE with 1 us slots
2: Expect AoD CTE with 2 us slots

Default: 0 | | [in] | slot_durations | Slot durations* 1: Switching and sampling slots are 1 us each

2: Switching and sampling slots are 2 us each

Default: 1 | | [in] | switching_pattern_len | Length of data in switching_pattern | | [in] | switching_pattern | Antenna switching pattern. Antennas will be switched in this order with the antenna switch pins during CTE. If the CTE is longer than the switching pattern, the pattern starts over. This can be an empty array if CTE is unused. |

ReturnsSL_STATUS_OK if successful. Error code otherwise. Events

sl_bt_evt_cte_receiver_dtm_iq_report - Triggered when IQ samples have been received.

◆sl_bt_cte_receiver_clear_dtm_parameters()#



sl_status_t sl_bt_cte_receiver_clear_dtm_parameters	(		)

Clear CTE-related parameters that were previously set for LE receiver test. Default values will be restored for these parameters.

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_cte_receiver_set_sync_cte_type()#



sl_status_t sl_bt_cte_receiver_set_sync_cte_type	(	uint8_t	`sync_cte_type`	)

Set the sync CTE type to limit what types of periodic advertisers to sync to when scanning for periodic advertising synchronization. The set parameter takes effect immediately for all advertisers that have not already established synchronization.

Parameters



[in]	`sync_cte_type`	Sync CTE type flags. This value can be a bitmask of multiple flags from CTE type flags for limiting periodic advertising synchronization. Flags:* SL_BT_CTE_RECEIVER_DO_NOT_SYNC_TO_AOA (0x01, bit 0): Do not sync to packets with an AoA Constant Tone Extension

SL_BT_CTE_RECEIVER_DO_NOT_SYNC_TO_AOD_1_US (0x02, bit 1): Do not sync to packets with an AoD Constant Tone Extension with 1 us slots
SL_BT_CTE_RECEIVER_DO_NOT_SYNC_TO_AOD_2_US (0x04, bit 2): Do not sync to packets with an AoD Constant Tone Extension with 2 us slots
SL_BT_CTE_RECEIVER_SYNC_TO_CTE_ONLY (0x10, bit 4): Do not sync to packets without a Constant Tone Extension

Default: 0 |

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_cte_receiver_set_default_sync_receive_parameters()#



sl_status_t sl_bt_cte_receiver_set_default_sync_receive_parameters	(	uint8_t	`mode,`
		uint16_t	`skip,`
		uint16_t	`timeout,`
		uint8_t	`sync_cte_type,`
		uint8_t	`reporting_mode`
	)

Set the default parameters and the CTE type limitation for receiving Periodic Advertising Synchronization Transfers (PAST) over connections. The default parameters will be in effect for all subsequent connections and do not affect connections that have already opened. The parameters can be overridden for a specific connection using command sl_bt_cte_receiver_set_sync_receive_parameters after the connection is opened.

This command is relevant and available only when the application has included the bluetooth_feature_past_receiver component into the build. If the PAST receiver component is not included, this command returns the error SL_STATUS_NOT_AVAILABLE.

Parameters



[in]	`mode`	Enum sl_bt_past_receiver_mode_t. The mode to specify how the Bluetooth stack reacts when synchronization information is received. Values:* sl_bt_past_receiver_mode_ignore (0x0): No attempt is made to synchronize to a periodic advertising train for which the synchronization information was received. No event will be triggered towards the application.

sl_bt_past_receiver_mode_synchronize (0x1): Attempt to synchronize to a periodic advertising train for which the synchronization information was received. When the information is received, an event will be triggered to indicate success or failure and to provide the application with the periodic advertising synchronization handle.

Default: sl_bt_past_receiver_mode_ignore (No attempt is made to synchronize) | | [in] | skip | The maximum number of periodic advertising packets that can be skipped after a successful receive.* Range: 0x0000 to 0x01F3

Default value: 0 | | [in] | timeout | The maximum permitted time between successful receives. If this time is exceeded, synchronization is lost. Unit: 10 ms.* Range: 0x0A to 0x4000
Unit: 10 ms
Time range: 100 ms to 163.84 s
Default value: 1000 ms | | [in] | sync_cte_type | Sync CTE type flags to limit what types of periodic advertising trains to sync to when receiving sync transfers. This value can be a bitmask of multiple flags from CTE type flags for limiting periodic advertising synchronization. Flags:* SL_BT_CTE_RECEIVER_DO_NOT_SYNC_TO_AOA (0x01, bit 0): Do not sync to packets with an AoA Constant Tone Extension
SL_BT_CTE_RECEIVER_DO_NOT_SYNC_TO_AOD_1_US (0x02, bit 1): Do not sync to packets with an AoD Constant Tone Extension with 1 us slots
SL_BT_CTE_RECEIVER_DO_NOT_SYNC_TO_AOD_2_US (0x04, bit 2): Do not sync to packets with an AoD Constant Tone Extension with 2 us slots
SL_BT_CTE_RECEIVER_SYNC_TO_CTE_ONLY (0x10, bit 4): Do not sync to packets without a Constant Tone Extension

Default: 0 (do not limit synchronization by CTE type) | | [in] | reporting_mode | Enum sl_bt_sync_reporting_mode_t. Specifies the initial mode for reporting data received in the periodic advertising train after it has achieved synchronization. Values:* sl_bt_sync_report_none (0x0): Data received in periodic advertising trains is not reported to the application.

sl_bt_sync_report_all (0x1): Data received in periodic advertising trains is reported to the application.

Default: sl_bt_sync_report_all (Data received in periodic advertising trains is reported to the application) |

ReturnsSL_STATUS_OK if successful. Error code otherwise. Events

sl_bt_evt_sync_transfer_received - Triggered after synchronization transfer is received for a periodic advertising train.

◆sl_bt_cte_receiver_set_sync_receive_parameters()#



sl_status_t sl_bt_cte_receiver_set_sync_receive_parameters	(	uint8_t	`connection,`
		uint8_t	`mode,`
		uint16_t	`skip,`
		uint16_t	`timeout,`
		uint8_t	`sync_cte_type,`
		uint8_t	`reporting_mode`
	)

Set the parameters and the CTE type limitation for receiving Periodic Advertising Synchronization Transfers (PAST) over the specified connection. The parameters do not affect periodic advertising trains that the device has already synchronized to.

Parameters



[in]	`connection`	Connection handle
[in]	`mode`	Enum sl_bt_past_receiver_mode_t. The mode to specify how the Bluetooth stack reacts when synchronization information is received. Values:* sl_bt_past_receiver_mode_ignore (0x0): No attempt is made to synchronize to a periodic advertising train for which the synchronization information was received. No event will be triggered towards the application.

sl_bt_past_receiver_mode_synchronize (0x1): Attempt to synchronize to a periodic advertising train for which the synchronization information was received. When the information is received, an event will be triggered to indicate success or failure and to provide the application with the periodic advertising synchronization handle.

Default: sl_bt_past_receiver_mode_ignore (Do not attempt to synchronize) | | [in] | skip | The maximum number of periodic advertising packets that can be skipped after a successful receive.* Range: 0x0000 to 0x01F3

Default value: 0 | | [in] | timeout | The maximum permitted time between successful receives. If this time is exceeded, synchronization is lost. Unit: 10 ms.* Range: 0x0A to 0x4000
Unit: 10 ms
Time range: 100 ms to 163.84 s
Default value: 1000 ms | | [in] | sync_cte_type | Sync CTE type flags to limit what types of periodic advertising trains to sync to when receiving sync transfers. This value can be a bitmask of multiple flags from CTE type flags for limiting periodic advertising synchronization. Flags:* SL_BT_CTE_RECEIVER_DO_NOT_SYNC_TO_AOA (0x01, bit 0): Do not sync to packets with an AoA Constant Tone Extension
SL_BT_CTE_RECEIVER_DO_NOT_SYNC_TO_AOD_1_US (0x02, bit 1): Do not sync to packets with an AoD Constant Tone Extension with 1 us slots
SL_BT_CTE_RECEIVER_DO_NOT_SYNC_TO_AOD_2_US (0x04, bit 2): Do not sync to packets with an AoD Constant Tone Extension with 2 us slots
SL_BT_CTE_RECEIVER_SYNC_TO_CTE_ONLY (0x10, bit 4): Do not sync to packets without a Constant Tone Extension

sl_bt_sync_report_all (0x1): Data received in periodic advertising trains is reported to the application.

Default: sl_bt_sync_report_all (Data received in periodic advertising trains is reported to the application) |

ReturnsSL_STATUS_OK if successful. Error code otherwise. Events

sl_bt_evt_sync_transfer_received - Triggered after synchronization transfer is received for a periodic advertising train.

◆sl_bt_cte_receiver_enable_connection_cte()#



sl_status_t sl_bt_cte_receiver_enable_connection_cte	(	uint8_t	`connection,`
		uint16_t	`interval,`
		uint8_t	`cte_length,`
		uint8_t	`cte_type,`
		uint8_t	`slot_durations,`
		size_t	`switching_pattern_len,`
		const uint8_t *	`switching_pattern`
	)

Start IQ samplings on a connection. A CTE requests will be initiated periodically on the given connection and IQ sampling will be made on the received CTE responses.

Parameters



[in]	`connection`	Connection handle
[in]	`interval`	Measurement interval. CTE requests may be sent less often. For example, if a connection event is missed for any reason, the CTE request will be sent in the next connection event.* 0: No interval. The request is initiated only once.

Other values N: Initiate the request every N-th connection events | | [in] | cte_length | Minimum CTE length requested in 8 us units.* Range: 0x02 to 0x14
Time Range: 16 us to 160 us | | [in] | cte_type | Requested CTE type* 0: AoA CTE
1: AoD CTE with 1 us slots
2: AoD CTE with 2 us slots | | [in] | slot_durations | Slot durations* 1: Switching and sampling slots are 1 us each
2: Switching and sampling slots are 2 us each | | [in] | switching_pattern_len | Length of data in switching_pattern | | [in] | switching_pattern | Antenna switching pattern. Antennas will be switched in this order with the antenna switch pins during CTE. If the CTE is longer than the switching pattern, the pattern starts over. |

ReturnsSL_STATUS_OK if successful. Error code otherwise. Events

sl_bt_evt_cte_receiver_connection_iq_report - Triggered when IQ samples have been received.

◆sl_bt_cte_receiver_disable_connection_cte()#



sl_status_t sl_bt_cte_receiver_disable_connection_cte	(	uint8_t	`connection`	)

Stop the IQ sampling on a connection. CTEs will not be requested on the given connection.

Parameters



[in]	`connection`	Connection handle

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_cte_receiver_enable_connectionless_cte()#



sl_status_t sl_bt_cte_receiver_enable_connectionless_cte	(	uint16_t	`sync,`
		uint8_t	`slot_durations,`
		uint8_t	`cte_count,`
		size_t	`switching_pattern_len,`
		const uint8_t *	`switching_pattern`
	)

Start IQ sampling on a periodic advertising synchronization. IQ samples are taken on each CTE found in the periodic advertisements.

Parameters



[in]	`sync`	Periodic advertising synchronization handle
[in]	`slot_durations`	Slot durations* 1: Switching and sampling slots are 1 us each

2: Switching and sampling slots are 2 us each | | [in] | cte_count | - 0: Sample and report all available CTEs* Other values: Maximum number of sampled CTEs in each periodic advertising interval | | [in] | switching_pattern_len | Length of data in switching_pattern | | [in] | switching_pattern | Antenna switching pattern. Antennas will be switched in this order with the antenna switch pins during CTE. If the CTE is longer than the switching pattern, the pattern starts over. |

ReturnsSL_STATUS_OK if successful. Error code otherwise. Events

sl_bt_evt_cte_receiver_connectionless_iq_report - Triggered when IQ samples have been received.

◆sl_bt_cte_receiver_disable_connectionless_cte()#



sl_status_t sl_bt_cte_receiver_disable_connectionless_cte	(	uint16_t	`sync`	)

Stop IQ sampling on a periodic advertising synchronization.

Parameters



[in]	`sync`	Periodic advertising synchronization handle

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_cte_receiver_enable_silabs_cte()#



sl_status_t sl_bt_cte_receiver_enable_silabs_cte	(	uint8_t	`slot_durations,`
		uint8_t	`cte_count,`
		size_t	`switching_pattern_len,`
		const uint8_t *	`switching_pattern`
	)

Enable IQ sampling of Silicon Labs CTE found in extended advertisements.

Parameters



[in]	`slot_durations`	Slot durations* 1: Switching and sampling slots are 1 us each

2: Switching and sampling slots are 2 us each | | [in] | cte_count | - 0: Sample and report all available CTEs* Other values: Maximum number of sampled CTEs in each extended advertising interval | | [in] | switching_pattern_len | Length of data in switching_pattern | | [in] | switching_pattern | Antenna switching pattern. Antennas will be switched in this order with the antenna switch pins during CTE. If the CTE is longer than the switching pattern, the pattern starts over. |

ReturnsSL_STATUS_OK if successful. Error code otherwise. Events

sl_bt_evt_cte_receiver_silabs_iq_report - Triggered when IQ samples of Silicon Labs CTE have been received.

◆sl_bt_cte_receiver_disable_silabs_cte()#



sl_status_t sl_bt_cte_receiver_disable_silabs_cte	(		)

Disable IQ sampling of Silicon Labs CTE.

ReturnsSL_STATUS_OK if successful. Error code otherwise.