Tx_power_settings

General Description

This section provides functions for reading and writing Transmit Power.

It lists APIs for setting advertisement Transmit power and for reading it and also for setting transmit power of active link.

Functions
wiced_result_t	wiced_bt_ble_set_adv_tx_power (int8_t power, wiced_bt_dev_vendor_specific_command_complete_cback_t *p_cb)
	Command to set LE Advertisement Transmit power. More...
wiced_result_t	wiced_bt_ble_read_adv_tx_power (wiced_bt_dev_cmpl_cback_t *p_cback)
	Read LE Advertisement transmit power. More...
wiced_result_t	wiced_bt_set_tx_power (wiced_bt_device_address_t bd_addr, int8_t power, wiced_bt_dev_vendor_specific_command_complete_cback_t *p_cb)
	Command to set the transmit power on given link. More...
wiced_result_t	wiced_bt_set_transmit_power_range (wiced_bt_device_address_t bd_addr, int8_t max_tx_power, int8_t min_tx_power, wiced_bt_dev_vendor_specific_command_complete_cback_t *p_cb)
	Command to set the range of transmit power on the link. More...
wiced_result_t	wiced_bt_dev_read_tx_power (wiced_bt_device_address_t remote_bda, wiced_bt_transport_t transport, wiced_bt_dev_cmpl_cback_t *p_cback)
	API to read the transmit power for the requested link associated with remote_bda This API sends HCI_Read_Transmit_Power_Level command to Controller. More...

Function Documentation

wiced_bt_ble_read_adv_tx_power()

wiced_result_t wiced_bt_ble_read_adv_tx_power

(

wiced_bt_dev_cmpl_cback_t *

p_cback

)

Read LE Advertisement transmit power.

This API sends HCI_LE_Read_Advertising_Channel_Tx_Power command to controller.

Note

This API can be used to get Tx power for Legacy advertisements.
It will return an error if the application is using Extended Advertisements.
See Bluetool Core spec 5.2, Vol 4, Part E, section 3.1.1 Legacy and Extended advertising

Parameters

[in]

p_cback

: Result callback (pointer to wiced_bt_tx_power_result_t will be passed to p_cback)

Returns

wiced_result_t
WICED_BT_PENDING : if command issued to controller.
WICED_BT_NO_RESOURCES : if couldn't allocate memory to issue command
WICED_BT_BUSY : if command is already in progress
WICED_BT_ILLEGAL_VALUE : if p_cback is NULL

wiced_bt_ble_set_adv_tx_power()

wiced_result_t wiced_bt_ble_set_adv_tx_power	(	int8_t	power,
		wiced_bt_dev_vendor_specific_command_complete_cback_t *	p_cb
	)

Command to set LE Advertisement Transmit power.

This API helps to set Tx power of Legacy advertisement .
This API should not be used for setting Tx power during Extended advertisement. Instead wiced_bt_ble_set_ext_adv_parameters_v2() should be used.

Parameters

[in]	power	: power value in db
[in]	p_cb	: Result callback (pointer to wiced_bt_set_adv_tx_power_result_t will be passed as wiced_bt_dev_vendor_specific_command_complete_params_t::p_param_buf)

Returns

wiced_result_t
WICED_BT_PENDING : if p_cb is not NULL
WICED_BT_SUCCESS : if p_cb is NULL

wiced_bt_dev_read_tx_power()

wiced_result_t wiced_bt_dev_read_tx_power	(	wiced_bt_device_address_t	remote_bda,
		wiced_bt_transport_t	transport,
		wiced_bt_dev_cmpl_cback_t *	p_cback
	)

API to read the transmit power for the requested link associated with remote_bda This API sends HCI_Read_Transmit_Power_Level command to Controller.

Parameters

[in]	remote_bda	: Bluetooth address of peer device
[in]	transport	: Transport type (valid types: BT_TRANSPORT_BR_EDR and BT_TRANSPORT_LE)
[in]	p_cback	: Result callback (wiced_bt_tx_power_result_t will be passed to the callback)

Returns

wiced_result_t
WICED_BT_PENDING : if command issued to controller.
WICED_BT_NO_RESOURCES : if couldn't allocate memory to issue command
WICED_BT_UNKNOWN_ADDR : if no active link with remote_bda specified
WICED_BT_BUSY : if command is already in progress

wiced_bt_set_transmit_power_range()

wiced_result_t wiced_bt_set_transmit_power_range	(	wiced_bt_device_address_t	bd_addr,
		int8_t	max_tx_power,
		int8_t	min_tx_power,
		wiced_bt_dev_vendor_specific_command_complete_cback_t *	p_cb
	)

Command to set the range of transmit power on the link.

This command will set minimum and maximum values of transmit power for the link associated with remote device identified by bd_addr

Parameters

[in]	bd_addr	: Bluetooth address of peer device
[in]	max_tx_power	: maximum power value in dBm
[in]	min_tx_power	: minimum power value in dBm
[in]	p_cb	: Result callback (wiced_bt_set_transmit_power_range_result_t will be passed to the callback)

Returns

wiced_result_t
WICED_BT_PENDING : if p_cb is not NULL
WICED_BT_UNKNOWN_ADDR : if no active link with specified bd_addr or if bd_addr is NULL
WICED_BT_SUCCESS : if p_cb is NULL

Note

This API is supported by generic target of CYW20829B0 and CYW89829B0 controllers only.
Valid power values for max_tx_power and min_tx_power are -28 dBm to 20 dBm
CYW20829B0 and CYW89829B0 controllers internally maintain a table of power values which are separated by 4. e.g. .., -8, -4, 0, 4, 8, ..
The given max_tx_power and min_tx_power values are then rounded up to the nearest ceiling value in the power table.
e.g. If -19dBm is passed as min_tx_power and -7dBm is passed as max_tx_power, controller will set power range as -16dBm to -4dBm.
Controller will inform the set power range through wiced_bt_set_transmit_power_range_result_t::p_param_buf of p_cb

wiced_bt_set_tx_power()

wiced_result_t wiced_bt_set_tx_power	(	wiced_bt_device_address_t	bd_addr,
		int8_t	power,
		wiced_bt_dev_vendor_specific_command_complete_cback_t *	p_cb
	)

Command to set the transmit power on given link.

This command will adjust the transmit power attenuation for the link associated with remote device identified by bd_addr

Parameters

[in]	bd_addr	: Bluetooth address of peer device To set Adv Tx power, keep bd_addr NULL
[in]	power	: Power value in dBm
[in]	p_cb	: Result callback (wiced_bt_set_adv_tx_power_result_t will be passed to the callback)

Returns

wiced_result_t
WICED_BT_PENDING : if p_cb is not NULL
WICED_BT_UNKNOWN_ADDR : if no active link with specified bd_addr
WICED_BT_ERROR : if bd_addr is NULL
WICED_BT_SUCCESS : if p_cb is NULL

Note

Valid power value for CYW20829B0 and CYW89829B0 controllers is -28 dBm to 20 dBm
CYW20829B0 and CYW89829B0 controllers internally maintain a table of power values which are separated by 4. e.g. .., -8, -4, 0, 4, 8, ..
The given power value is then rounded up to the nearest ceiling value in the power table.
e.g. If -7 is passed as power, controller will set power value to -4dBm.