LE Channel Sounding

General Description

This section contains LE Channel Sounding defines, structures and functions.

Note

Applications using channel sounding are expected to use extended mode ADV and Scan APIs and cannot invoke any of the Legacy mode APIs for advertisement and scanning

Data Structures
struct	wiced_ble_cs_capabilites_t
	Structure for channel sounding capabilities. More...
struct	wiced_ble_cs_default_settings_t
	Structure for setting channel sounding default settings. More...
struct	wiced_ble_cs_fae_table_data_t
	Structure for the FAE table. More...
struct	wiced_ble_cs_config_t
	Structure to set the CS config. More...
struct	wiced_ble_cs_procedure_params_t
	CS Procedure parameters. More...
struct	wiced_ble_cs_config_complete_t
	Structure to return the CS Configuration complete event. More...
struct	wiced_ble_cs_procedure_enable_complete_t
	Structure to return the CS Procedure enable complete event. More...
struct	wiced_ble_cs_subevent_result_to_app_t
	CS events to the application. More...
struct	wiced_ble_cs_subevent_continue_result_hdr_t
	CS Subevent continue result hdr. More...
struct	wiced_ble_cs_subevent_result_hdr_t
	CS Subevent result hdr. More...
union	wiced_ble_cs_event_data_t
	union of data for CS events More...

Macros
#define	WICED_BLE_CS_FAE_TABLE_SIZE   72
	Size of the CS FAE (Frequency Actuation Error) Table.
#define	WICED_BLE_CS_CHANNEL_MAP_SIZE   10
	Size of the CS Channel Map.

Typedefs
typedef uint8_t	wiced_ble_cs_fae_table_t[WICED_BLE_CS_FAE_TABLE_SIZE]
	CS FAE (Frequency Actuation Error) table.
typedef uint8_t	wiced_ble_cs_channel_map_t[WICED_BLE_CS_CHANNEL_MAP_SIZE]
	CS Channel map 10 octet value to set the CS channel map, This parameter contains 80 1-bit fields. More...
typedef uint8_t	wiced_ble_cs_events_t
	Channel sounding events (see wiced_ble_cs_events_e)
typedef void(*	wiced_ble_cs_events_cb_t) (wiced_ble_cs_events_t event, uint8_t status, wiced_ble_cs_event_data_t *p_data)
	Callback wiced_ble_cs_events_cb_t. More...

Enumerations
enum	wiced_ble_cs_events_e {   WICED_BLE_CS_READ_LOCAL_CAPABILITIES_COMPLETE,   WICED_BLE_CS_READ_REMOTE_CAPABILITIES_COMPLETE,   WICED_BLE_CS_WRITE_CACHED_CAPABILITIES_CMD_COMPLETE,   WICED_BLE_CS_WRITE_DEFAULT_SETTINGS_COMPLETE,   WICED_BLE_CS_READ_REMOTE_FAE_TABLE_COMPLETE,   WICED_BLE_CS_WRITE_CACHED_REMOTE_FAE_TABLE_COMPLETE,   WICED_BLE_CS_SET_SECURITY_ENABLE_COMPLETE,   WICED_BLE_CS_CONFIG_COMPLETE,   WICED_BLE_CS_SET_CHANNEL_CLASSIFICATION_COMPLETE,   WICED_BLE_CS_PROCEDURE_ENABLE_CMD_COMPLETE,   WICED_BLE_CS_PROCEDURE_ENABLE_COMPLETE_EVT,   WICED_BLE_CS_SUBEVENT_RESULT_EVT,   WICED_BLE_CS_SUBEVENT_RESULT_CONTINUE_EVT }
	CS Events enumeration. More...

Functions
wiced_result_t	wiced_ble_cs_register (wiced_ble_cs_events_cb_t pf_cs_cb)
	Register the callback for receiving CS events. More...
wiced_result_t	wiced_ble_cs_read_local_supported_capabilities (void)
	Read local supported CS capabilities The local capabilities read are returned in the registered callback, with event set to WICED_BLE_CS_READ_LOCAL_CAPABILITIES_COMPLETE. More...
wiced_result_t	wiced_ble_cs_read_remote_supported_capabilities (uint16_t acl_conn_handle)
	Read remote supported CS capabilities The remote capabilities read are returned in the registered callback, with event set to WICED_BLE_CS_READ_REMOTE_CAPABILITIES_COMPLETE. More...
wiced_result_t	wiced_ble_cs_write_cached_remote_capabilities (wiced_ble_cs_capabilites_t *p_cap)
	Write cached remote supported CS capabilities WICED_BLE_CS_WRITE_CACHED_CAPABILITIES_CMD_COMPLETE is generated on completion of this API. More...
wiced_result_t	wiced_ble_cs_security_enable (uint16_t acl_conn_handle)
	Enable CS security for the connection WICED_BLE_CS_SET_SECURITY_ENABLE_COMPLETE event is generated on completion of CS security enable for the connection. More...
wiced_result_t	wiced_ble_cs_set_default_settings (wiced_ble_cs_default_settings_t *p_def)
	Write default CS settings for the connection WICED_BLE_CS_WRITE_DEFAULT_SETTINGS_COMPLETE is generated on completion of this API. More...
wiced_result_t	wiced_ble_cs_read_remote_fae_table (uint16_t acl_conn_handle)
	Read remote FAE table for the connection WICED_BLE_CS_READ_REMOTE_FAE_TABLE_COMPLETE event is generated on read complete. More...
wiced_result_t	wiced_ble_cs_write_cached_remote_fae_table (wiced_ble_cs_fae_table_data_t *p_tab)
	Write cached remote FAE table WICED_BLE_CS_WRITE_CACHED_REMOTE_FAE_TABLE_COMPLETE is generated on completion of this API. More...
wiced_result_t	wiced_ble_cs_create_config (wiced_ble_cs_config_t *p_cfg)
	Create/Update CS Config for config id WICED_BLE_CS_CONFIG_COMPLETE is generated on completion of this API. More...
wiced_result_t	wiced_ble_cs_remove_config (uint16_t acl_conn_handle, uint8_t config_id)
	Remove CS Config for config id WICED_BLE_CS_CONFIG_COMPLETE is generated on completion of this API. More...
wiced_result_t	wiced_ble_cs_set_channel_classification (wiced_ble_cs_channel_map_t channel_map)
	Set the CS channel classification WICED_BLE_CS_SET_CHANNEL_CLASSIFICATION_COMPLETE is generated on completion of this API. More...
wiced_result_t	wiced_ble_cs_set_procedure_params (wiced_ble_cs_procedure_params_t *p_param)
	Set the CS procedure parameters WICED_BLE_CS_PROCEDURE_ENABLE_CMD_COMPLETE is generated on completion of this API. More...
wiced_result_t	wiced_ble_cs_set_procedure_enable (uint16_t acl_conn_handle, uint8_t config_id, uint8_t enable)
	Enable/Disable CS procedure WICED_BLE_CS_PROCEDURE_ENABLE_COMPLETE_EVT is generated on completion of this API. More...
const char *	wiced_ble_cs_get_event_str (wiced_ble_cs_events_t evt)
	Utility function to return an ascii string for the event. More...
wiced_result_t	wiced_ble_cs_read_subevent_result_event_hdr_from_stream (wiced_ble_cs_subevent_result_hdr_t *p_hdr, uint8_t *p_data, int len)
	Utility function to read the subevent result. More...
wiced_result_t	wiced_ble_cs_read_subevent_cont_result_event_hdr_from_stream (wiced_ble_cs_subevent_continue_result_hdr_t *p_hdr, uint8_t *p_data, int len)
	Utility function to read the subevent continue result. More...

Typedef Documentation

wiced_ble_cs_channel_map_t

typedef uint8_t wiced_ble_cs_channel_map_t[WICED_BLE_CS_CHANNEL_MAP_SIZE]

CS Channel map 10 octet value to set the CS channel map, This parameter contains 80 1-bit fields.

The nth such field (in the range 0 to 78) contains the value for CS channel index n. Channel n is enabled for CS procedure = 1 Channel n is disabled for CS procedure = 0 Channels n = 0, 1, 23, 24, 25, 77, and 78 shall be ignored and shall be set to zero. At least 15 channels shall be enabled. The most significant bit (bit 79) is reserved for future use.

wiced_ble_cs_events_cb_t

typedef void(* wiced_ble_cs_events_cb_t) (wiced_ble_cs_events_t event, uint8_t status, wiced_ble_cs_event_data_t *p_data)

Callback wiced_ble_cs_events_cb_t.

Adv extension command status, command complete event and LE adv extension meta event callback

Parameters

event	: Event type (see wiced_ble_cs_events_t)
p_data	: Event data (see wiced_ble_cs_event_data_t)

Returns

Nothing

Enumeration Type Documentation

wiced_ble_cs_events_e

enum wiced_ble_cs_events_e

CS Events enumeration.

Enumerator
WICED_BLE_CS_READ_LOCAL_CAPABILITIES_COMPLETE	CS Read local capabilities complete event. Event data in wiced_ble_cs_event_data_t.cs_capabilities
WICED_BLE_CS_READ_REMOTE_CAPABILITIES_COMPLETE	CS Read Remote capabilities complete event. Event data in wiced_ble_cs_event_data_t.cs_capabilities
WICED_BLE_CS_WRITE_CACHED_CAPABILITIES_CMD_COMPLETE	CS write cached capabilities cmd complete event, Event data in wiced_ble_cs_event_data_t.acl_conn_handle.
WICED_BLE_CS_WRITE_DEFAULT_SETTINGS_COMPLETE	CS write default settings complete event, Event data in wiced_ble_cs_event_data_t.acl_conn_handle.
WICED_BLE_CS_READ_REMOTE_FAE_TABLE_COMPLETE	CS read remote FAE table complete event, Event data in wiced_ble_cs_event_data_t.fae_table.
WICED_BLE_CS_WRITE_CACHED_REMOTE_FAE_TABLE_COMPLETE	CS write cached FAE table complete event, Event data in wiced_ble_cs_event_data_t.acl_conn_handle.
WICED_BLE_CS_SET_SECURITY_ENABLE_COMPLETE	CS security enable complete event, Event data in wiced_ble_cs_event_data_t.acl_conn_handle.
WICED_BLE_CS_CONFIG_COMPLETE	CS config complete event, Event data in wiced_ble_cs_event_data_t.config_cmplt.
WICED_BLE_CS_SET_CHANNEL_CLASSIFICATION_COMPLETE	CS set channel classification complete event, Event data : NULL.
WICED_BLE_CS_PROCEDURE_ENABLE_CMD_COMPLETE	CS Procedure enable command complete event, Event data in wiced_ble_cs_event_data_t.acl_conn_handle.
WICED_BLE_CS_PROCEDURE_ENABLE_COMPLETE_EVT	CS Procedure enable complete evt. Event Data: wiced_ble_cs_event_data_t.proc_enable
WICED_BLE_CS_SUBEVENT_RESULT_EVT	CS Subevent result event. Event Data: wiced_ble_cs_event_data_t.cs_subevent_data
WICED_BLE_CS_SUBEVENT_RESULT_CONTINUE_EVT	CS Subevent result continue event. Event Data: wiced_ble_cs_event_data_t.cs_subevent_data

Function Documentation

wiced_ble_cs_register()

wiced_result_t wiced_ble_cs_register

(

wiced_ble_cs_events_cb_t

pf_cs_cb

)

Register the callback for receiving CS events.

Parameters

pf_cs_cb

: Function ptr to receive CS events

Returns

wiced_result_t

wiced_ble_cs_read_local_supported_capabilities()

wiced_result_t wiced_ble_cs_read_local_supported_capabilities

(

void

)

Read local supported CS capabilities The local capabilities read are returned in the registered callback, with event set to WICED_BLE_CS_READ_LOCAL_CAPABILITIES_COMPLETE.

Returns

wiced_result_t

wiced_ble_cs_read_remote_supported_capabilities()

wiced_result_t wiced_ble_cs_read_remote_supported_capabilities

(

uint16_t

acl_conn_handle

)

Read remote supported CS capabilities The remote capabilities read are returned in the registered callback, with event set to WICED_BLE_CS_READ_REMOTE_CAPABILITIES_COMPLETE.

Parameters

acl_conn_handle

: ACL connection handle

Returns

wiced_result_t

wiced_ble_cs_write_cached_remote_capabilities()

wiced_result_t wiced_ble_cs_write_cached_remote_capabilities

(

wiced_ble_cs_capabilites_t *

p_cap

)

Write cached remote supported CS capabilities WICED_BLE_CS_WRITE_CACHED_CAPABILITIES_CMD_COMPLETE is generated on completion of this API.

Parameters

p_cap

: Cached remote capabilities, previously received from the remote device

Returns

wiced_result_t

wiced_ble_cs_security_enable()

wiced_result_t wiced_ble_cs_security_enable

(

uint16_t

acl_conn_handle

)

Enable CS security for the connection WICED_BLE_CS_SET_SECURITY_ENABLE_COMPLETE event is generated on completion of CS security enable for the connection.

Parameters

acl_conn_handle

: ACL connection handle

Returns

wiced_result_t

wiced_ble_cs_set_default_settings()

wiced_result_t wiced_ble_cs_set_default_settings

(

wiced_ble_cs_default_settings_t *

p_def

)

Write default CS settings for the connection WICED_BLE_CS_WRITE_DEFAULT_SETTINGS_COMPLETE is generated on completion of this API.

Parameters

p_def

: Default settings to be applied for the connection

Returns

wiced_result_t

wiced_ble_cs_read_remote_fae_table()

wiced_result_t wiced_ble_cs_read_remote_fae_table

(

uint16_t

acl_conn_handle

)

Read remote FAE table for the connection WICED_BLE_CS_READ_REMOTE_FAE_TABLE_COMPLETE event is generated on read complete.

Parameters

acl_conn_handle

: ACL connection handle

Returns

wiced_result_t

wiced_ble_cs_write_cached_remote_fae_table()

wiced_result_t wiced_ble_cs_write_cached_remote_fae_table

(

wiced_ble_cs_fae_table_data_t *

p_tab

)

Write cached remote FAE table WICED_BLE_CS_WRITE_CACHED_REMOTE_FAE_TABLE_COMPLETE is generated on completion of this API.

Parameters

p_tab

: Cached FAE table, previously received from the remote device

Returns

wiced_result_t

wiced_ble_cs_create_config()

wiced_result_t wiced_ble_cs_create_config

(

wiced_ble_cs_config_t *

p_cfg

)

Create/Update CS Config for config id WICED_BLE_CS_CONFIG_COMPLETE is generated on completion of this API.

Parameters

p_cfg

: Cached FAE table, previously received from the remote device

Returns

wiced_result_t

wiced_ble_cs_remove_config()

wiced_result_t wiced_ble_cs_remove_config	(	uint16_t	acl_conn_handle,
		uint8_t	config_id
	)

Remove CS Config for config id WICED_BLE_CS_CONFIG_COMPLETE is generated on completion of this API.

Parameters

acl_conn_handle	: ACL connection handle
config_id	: CS config identifier

Returns

wiced_result_t

wiced_ble_cs_set_channel_classification()

wiced_result_t wiced_ble_cs_set_channel_classification

(

wiced_ble_cs_channel_map_t

channel_map

)

Set the CS channel classification WICED_BLE_CS_SET_CHANNEL_CLASSIFICATION_COMPLETE is generated on completion of this API.

Parameters

channel_map

: Channel map to be used

Returns

wiced_result_t

wiced_ble_cs_set_procedure_params()

wiced_result_t wiced_ble_cs_set_procedure_params

(

wiced_ble_cs_procedure_params_t *

p_param

)

Set the CS procedure parameters WICED_BLE_CS_PROCEDURE_ENABLE_CMD_COMPLETE is generated on completion of this API.

Note

This API can be invoked only if the host has created a configuration using the wiced_ble_cs_create_config API

Parameters

p_param

: Procedure paramters to be set

Returns

wiced_result_t

wiced_ble_cs_set_procedure_enable()

wiced_result_t wiced_ble_cs_set_procedure_enable	(	uint16_t	acl_conn_handle,
		uint8_t	config_id,
		uint8_t	enable
	)

Enable/Disable CS procedure WICED_BLE_CS_PROCEDURE_ENABLE_COMPLETE_EVT is generated on completion of this API.

Note

This API can be invoked only if the host has created a configuration using the wiced_ble_cs_create_config API

Parameters

acl_conn_handle	: ACL connection handle
config_id	CS config identifier
enable	Set 1 to enable the procedure, 0 to disable

Returns

wiced_result_t

wiced_ble_cs_get_event_str()

const char* wiced_ble_cs_get_event_str

(

wiced_ble_cs_events_t

evt

)

Utility function to return an ascii string for the event.

Parameters

evt	CS event received

Returns

event_string

wiced_ble_cs_read_subevent_result_event_hdr_from_stream()

wiced_result_t wiced_ble_cs_read_subevent_result_event_hdr_from_stream	(	wiced_ble_cs_subevent_result_hdr_t *	p_hdr,
		uint8_t *	p_data,
		int	len
	)

Utility function to read the subevent result.

Parameters

[out]	p_hdr	On return this contains the parsed data from the event
[in]	p_data	: Received subevent data
[in]	len	: length of the data pointed to by p_data

Returns

wiced_result_t

wiced_ble_cs_read_subevent_cont_result_event_hdr_from_stream()

wiced_result_t wiced_ble_cs_read_subevent_cont_result_event_hdr_from_stream	(	wiced_ble_cs_subevent_continue_result_hdr_t *	p_hdr,
		uint8_t *	p_data,
		int	len
	)

Utility function to read the subevent continue result.

Parameters

[out]	p_hdr	On return this contains the parsed data from the event
[in]	p_data	: Received subevent data
[in]	len	: length of the data pointed to by p_data

Returns

wiced_result_t