LE

General Description

API's used for LE L2CAP.

Functions
wiced_bool_t	wiced_bt_l2cap_cancel_ble_connect_req (wiced_bt_device_address_t rem_bda)
	Cancel a pending connection attempt to a LE device. More...
wiced_bool_t	wiced_bt_l2cap_update_ble_conn_params (wiced_bt_device_address_t rem_bdRa, wiced_bt_ble_pref_conn_params_t *p_conn_params)
	Update LE connection parameters. More...
wiced_bool_t	wiced_bt_l2cap_enable_update_ble_conn_params (wiced_bt_device_address_t rem_bda, wiced_bool_t enable)
	Application requests to disable or enable parameters update. More...
uint8_t	wiced_bt_l2cap_get_ble_conn_role (wiced_bt_device_address_t bd_addr)
	This function returns the connection role. More...
uint16_t	wiced_bt_l2cap_le_register (uint16_t le_psm, wiced_bt_l2cap_le_appl_information_t *p_cb_information)
	Other layers call this function to register L2CAP services for LE_PSM. More...
wiced_bool_t	wiced_bt_l2cap_le_deregister (uint16_t le_psm)
	Other layers call this function to deregister L2CAP services for LE_PSM. More...
uint16_t	wiced_bt_l2cap_le_connect_req (uint16_t le_psm, wiced_bt_device_address_t p_bd_addr, wiced_bt_ble_address_type_t bd_addr_type, wiced_bt_ble_conn_mode_t conn_mode, uint16_t rx_mtu, uint8_t req_security, uint8_t req_encr_key_size, tDRB *p_rx_drb)
	Initiate an L2CAP connection for LE_PSM. More...
wiced_bool_t	wiced_bt_l2cap_le_connect_rsp (wiced_bt_device_address_t p_bd_addr, uint8_t id, uint16_t lcid, uint16_t result, uint16_t rx_mtu, tDRB *p_rx_drb)
	Accept an incoming LE L2CAP connection. More...
wiced_bool_t	wiced_bt_l2cap_le_disconnect_req (uint16_t lcid)
	Higher layers call this function to disconnect a LE COC channel. More...
wiced_bool_t	wiced_bt_l2cap_le_disconnect_rsp (uint16_t lcid)
	Higher layers call this function to acknowledge the disconnection of a LE COC channel. More...
uint8_t	wiced_bt_l2cap_le_data_write (uint16_t cid, uint8_t *p_data, uint16_t buf_len)
	Send data over LE connection-oriented channel. More...
wiced_bool_t	wiced_bt_l2cap_le_set_user_congestion (uint16_t lcid, wiced_bool_t flow_off_peer)
	App can call this function to flow control data reception from the peer (flow controlled channels only, viz LE COC, ECRB channels) To stop sending credits/flow off the remote peer set flow_off_peer to WICED_TRUE To resume sending credits/flow on set flow_off_peer to WICED_FALSE. More...
uint16_t	wiced_bt_l2cap_le_get_peer_mtu (uint16_t lcid)
	Higher layers call this function to get peer MTU. More...
uint16_t	wiced_bt_l2cap_le_determ_secur_rsp (wiced_bt_device_address_t bd_addr, uint8_t req_secur, uint8_t req_encr_key_size)
	Higher layers call this function to check if the current device security settings are sufficient to continue with call establishment. More...

Function Documentation

wiced_bt_l2cap_cancel_ble_connect_req()

wiced_bool_t wiced_bt_l2cap_cancel_ble_connect_req

(

wiced_bt_device_address_t

rem_bda

)

Cancel a pending connection attempt to a LE device.

Parameters

[in]

rem_bda

: BD Address of remote

Returns

: TRUE if connection was cancelled

wiced_bt_l2cap_update_ble_conn_params()

wiced_bool_t wiced_bt_l2cap_update_ble_conn_params	(	wiced_bt_device_address_t	rem_bdRa,
		wiced_bt_ble_pref_conn_params_t *	p_conn_params
	)

Update LE connection parameters.

Parameters

[in]	rem_bdRa	: Remote BD Address
[in]	p_conn_params	: Preferred connection parameters

Returns

: TRUE if update started

wiced_bt_l2cap_enable_update_ble_conn_params()

wiced_bool_t wiced_bt_l2cap_enable_update_ble_conn_params	(	wiced_bt_device_address_t	rem_bda,
		wiced_bool_t	enable
	)

Application requests to disable or enable parameters update.

Note

By default parameter updates are allowed on connection complete This API is typically used to pause parameter updates.

Parameters

[in]	rem_bda	Remote Bd Address
[in]	enable	TRUE to enable,FALSE to disable. If enable = FALSE, and if parameters are already updated, this API resets them to what was requested during connection establishement If enable = TRUE, then any pending request sent through wiced_bt_l2cap_update_ble_conn_params is processed

Returns

: TRUE if update started

wiced_bt_l2cap_get_ble_conn_role()

uint8_t wiced_bt_l2cap_get_ble_conn_role

(

wiced_bt_device_address_t

bd_addr

)

This function returns the connection role.

Parameters

[in]

bd_addr

BD Address

Returns

link role.( 0 => HCI_ROLE_CENTRAL and 1 => HCI_ROLE_PERIPHERAL)

wiced_bt_l2cap_le_register()

uint16_t wiced_bt_l2cap_le_register	(	uint16_t	le_psm,
		wiced_bt_l2cap_le_appl_information_t *	p_cb_information
	)

Other layers call this function to register L2CAP services for LE_PSM.

Parameters

[in]	le_psm	: LE PSM value
[in]	p_cb_information	: L2CAP cb info

Returns

LE_PSM to use or zero if error. Typically the LE_PSM returned is the same as was passed in, but for an outgoing-only connection a "virtual" LE_PSM is returned and should be used in the calls to wiced_bt_l2cap_le_connect_req() and wiced_bt_l2cap_le_deregister().

wiced_bt_l2cap_le_deregister()

wiced_bool_t wiced_bt_l2cap_le_deregister

(

uint16_t

le_psm

)

Other layers call this function to deregister L2CAP services for LE_PSM.

Parameters

[in]

le_psm

LE PSM value

Returns

TRUE for success, FALSE for failure

wiced_bt_l2cap_le_connect_req()

uint16_t wiced_bt_l2cap_le_connect_req	(	uint16_t	le_psm,
		wiced_bt_device_address_t	p_bd_addr,
		wiced_bt_ble_address_type_t	bd_addr_type,
		wiced_bt_ble_conn_mode_t	conn_mode,
		uint16_t	rx_mtu,
		uint8_t	req_security,
		uint8_t	req_encr_key_size,
		tDRB *	p_rx_drb
	)

Initiate an L2CAP connection for LE_PSM.

This function is called by higher layers to initiate an L2CAP connection for LE_PSM. The connection is not established immediately; instead, the connection establishment process begins. The provided callback function will be invoked when the connection is established or if it fails.

Parameters

[in]	le_psm	LE Protocol/Service Multiplexer (PSM) value.
[in]	p_bd_addr	Pointer to the Bluetooth device address of the remote device.
[in]	bd_addr_type	Type of Bluetooth address. Must be either BLE_ADDR_PUBLIC or BLE_ADDR_RANDOM.
[in]	conn_mode	Connection mode. Must be either BLE_CONN_MODE_HIGH_DUTY or BLE_CONN_MODE_LOW_DUTY.
[in]	rx_mtu	Receive Maximum Transmission Unit (MTU) value, the size of the memory block pointed by p_rx_drb

Note

Each received packet can be up to rx_mtu bytes in length.

Parameters

[in]	req_security	Required security level for the connection.
[in]	req_encr_key_size	Required encryption key size.
[in]	p_rx_drb	Pointer to the Data Reception Buffer (DRB) to receive peer's data.

Note

It is the application's responsibility to ensure that the DRB of size >= (rx_mtu + DRB_OVERHEAD_SIZE) is properly allocated. See tDRB for details.

The DRB will be used to store incoming data from the peer device and can be released by the application upon receiving wiced_bt_l2cap_le_appl_information_t::le_release_drb_cb registered with the call to wiced_bt_l2cap_le_register.

The p_rx_drb can be released by the application upon receiving a callback with the wiced_bt_l2cap_le_appl_information_t::le_release_drb_cb of the p_cb_information member of wiced_bt_l2cap_le_register.

Returns

The Channel Identifier (CID) of the connection if successful, or 0 if the connection initiation failed.

Warning

Ensure that the p_rx_drb is properly allocated and sized to prevent buffer overflows.

See also

wiced_bt_l2cap_le_register

tDRB

wiced_bt_l2cap_le_connect_rsp()

wiced_bool_t wiced_bt_l2cap_le_connect_rsp	(	wiced_bt_device_address_t	p_bd_addr,
		uint8_t	id,
		uint16_t	lcid,
		uint16_t	result,
		uint16_t	rx_mtu,
		tDRB *	p_rx_drb
	)

Accept an incoming LE L2CAP connection.

This function is called by higher layers to accept an incoming LE L2CAP connection after receiving a connect indication callback.

Parameters

[in]	p_bd_addr	Pointer to the Bluetooth device address of the remote device.
[in]	id	Connection identifier received from the wiced_bt_l2cap_le_connect_indication_cback_t callback.
[in]	lcid	Local Channel Identifier (CID) for this connection.
[in]	result	L2CAP connection result code. See L2CAP_CONN_RESULT for possible values.
[in]	rx_mtu	Receive Maximum Transmission Unit (MTU) value. Must be appropriately sized based on available memory.

Note

Each received packet can be up to rx_mtu bytes in length, preferably set to wiced_bt_cfg_ble_t::ble_max_rx_pdu_size

Parameters

[in]

p_rx_drb

Pointer to the Data Reception Buffer (DRB) to receive peer's data. MUST be large enough to hold RX MTU data. See tDRB for details.

Note

The p_rx_drb can be released by the application upon receiving a callback with the wiced_bt_l2cap_le_appl_information_t::le_release_drb_cb of the p_cb_information member of wiced_bt_l2cap_le_register.

Returns

TRUE if the connection is successfully accepted, FALSE otherwise.

Warning

Ensure that the p_rx_drb is properly allocated and sized to prevent buffer overflows.

See also

wiced_bt_l2cap_le_connect_indication_cback_t

wiced_bt_l2cap_le_register

L2CAP_CONN_RESULT

tDRB

wiced_bt_l2cap_le_disconnect_req()

wiced_bool_t wiced_bt_l2cap_le_disconnect_req

(

uint16_t

lcid

)

Higher layers call this function to disconnect a LE COC channel.

Parameters

[in]

lcid

Local CID value

Returns

TRUE if disconnect sent, else FALSE

wiced_bt_l2cap_le_disconnect_rsp()

wiced_bool_t wiced_bt_l2cap_le_disconnect_rsp

(

uint16_t

lcid

)

Higher layers call this function to acknowledge the disconnection of a LE COC channel.

Parameters

[in]

lcid

Local CID value

Returns

void

wiced_bt_l2cap_le_data_write()

uint8_t wiced_bt_l2cap_le_data_write	(	uint16_t	cid,
		uint8_t *	p_data,
		uint16_t	buf_len
	)

Send data over LE connection-oriented channel.

Parameters

[in]	cid	: CID value
[in]	p_data	: Input buffer
[in]	buf_len	: p_data buffer size

Returns

L2CAP_DATAWRITE_SUCCESS, if data accepted, else FALSE L2CAP_DATAWRITE_CONGESTED, if data accepted and the channel is congested L2CAP_DATAWRITE_FAILED, if error

wiced_bt_l2cap_le_set_user_congestion()

wiced_bool_t wiced_bt_l2cap_le_set_user_congestion	(	uint16_t	lcid,
		wiced_bool_t	flow_off_peer
	)

App can call this function to flow control data reception from the peer (flow controlled channels only, viz LE COC, ECRB channels) To stop sending credits/flow off the remote peer set flow_off_peer to WICED_TRUE To resume sending credits/flow on set flow_off_peer to WICED_FALSE.

Note

: This API is typically invoked by applications that buffer incoming data for further processing/forwarding. On invoking the API further issuance of L2CAP credits is stopped, however, the remote will continue to send data till it runs out of credits. The maximum amount of data size expected to be received is 2 * Receive MTU which could be split over a max of (Receive MTU + 2(Sdu header size))/(Receive MPS) number of packets

Parameters

[in]	lcid	: Local CID value
[in]	flow_off_peer	: to flow off peer set to WICED_TRUE, to flow on peer set to WICED_FALSE

Returns

TRUE if command processed OK

wiced_bt_l2cap_le_get_peer_mtu()

uint16_t wiced_bt_l2cap_le_get_peer_mtu

(

uint16_t

lcid

)

Higher layers call this function to get peer MTU.

Parameters

[in]

lcid

: Local CID value

Returns

Peer MTU or 0.

wiced_bt_l2cap_le_determ_secur_rsp()

uint16_t wiced_bt_l2cap_le_determ_secur_rsp	(	wiced_bt_device_address_t	bd_addr,
		uint8_t	req_secur,
		uint8_t	req_encr_key_size
	)

Higher layers call this function to check if the current device security settings are sufficient to continue with call establishment.

It is called by call acceptor on reception of LE Credit Based Connection Request.

Parameters

[in]	bd_addr	: BD Address
[in]	req_secur	: Security required
[in]	req_encr_key_size	: Key size

Returns

L2CAP_CONN_OK/L2CAP_BLE_CONN_BAD_AUTHENT/ L2CAP_BLE_CONN_BAD_KEY_SIZE/L2CAP_BLE_CONN_BAD_ENCRYPT/ L2CAP_CONN_NO_RESOURCES.