Power management

This section defines the confirmation types and APIs to switch the power on and off. More...

Overview

This section defines the confirmation types and APIs to switch the power on and off.

How to use this module

The application layer can power on the Bluetooth if it is powered off and a stack memory is assigned.

• Sample code:

  // Power on the Bluetooth from the application.
  void user_application_power_on_function()
  {
      // Initialize the public_addr and the random_addr according to the application requirements.
      bt_bd_addr_t public_addr = {0x11, 0x22, 0x33, 0x44, 0x55, 0x66};
      bt_bd_addr_t random_addr = {0xc0, 0x22, 0x33, 0x44, 0x55, 0xc6};
  
      bt_power_on(&public_addr, &random_addr);
  }
  
  // The application receives the power on confirmation event in the function #bt_app_event_callback() after calling #bt_power_on().
  bt_status_t bt_app_event_callback(bt_msg_type_t msg, bt_status_t status, void *buf)
  {
      switch (msg)
      {
          case BT_POWER_ON_CNF:
              // Add the implementation flow after the Bluetooth is powered on.
              break;
          case BT_GAP_LE_CONNECT_IND:
              // Connection is established.
              break;
          default:
              break;
      }
      return status;
  }

Functions
bt_status_t	bt_power_on (bt_bd_addr_ptr_t public_addr, bt_bd_addr_ptr_t random_addr)
	This function powers on the Bluetooth. More...
bt_status_t	bt_power_off (void)
	This function powers off the Bluetooth. More...
bt_status_t	bt_config_tx_power_level (const bt_config_tx_power_t *tx_power_info)
	This function configurates the radio transmission power level for bt and le connections. More...
bt_status_t	bt_app_event_callback (bt_msg_type_t msg, bt_status_t status, void *buf)
	This function is a static callback for the application to listen to the event. More...
void *	bt_alloc_rx_buffer_from_external (uint32_t buffer_size)
	This function is for memory allocation from Rx buffer by application. More...

Modules
	Define
	Define the power on or off events.
	Struct
	Define power on event parameter structure.

Function Documentation

void* bt_alloc_rx_buffer_from_external

(

uint32_t

buffer_size

)

This function is for memory allocation from Rx buffer by application.

Parameters

[in]

buffer_size

is the allocation size requested.

Returns

The point to Rx buffer allocated.

bt_status_t bt_app_event_callback	(	bt_msg_type_t	msg,
		bt_status_t	status,
		void *	buf
	)

This function is a static callback for the application to listen to the event.

Provide a user-defined callback.

Parameters

[in]	msg	is the callback message type.
[in]	status	is the status of the callback message.
[in]	buf	is the payload of the callback message.

Returns

The status of this operation returned from the callback.

bt_status_t bt_config_tx_power_level

(

const bt_config_tx_power_t *

tx_power_info

)

This function configurates the radio transmission power level for bt and le connections.

The transmission power settings is not mandatory. User can configurate the radio transmission power before power on Bluetooth, and the configuration will not be reset until chip reboot.

Parameters

[in]

tx_power_info

is a pointer to a structure that specifies the parameters for radio transmission power level.

Returns

BT_STATUS_SUCCESS, the operation success. BT_STATUS_FAIL, the operation fails. because the Bluetooth is power on or bt_init_tx_power_level is bigger than bt_max_tx_power_level.

bt_status_t bt_power_off

(

void

)

This function powers off the Bluetooth.

The SDK will not send disconnect requests to the existing connections during the power off operation. The application layer will receive BT_POWER_OFF_CNF after the Bluetooth is powered off.

Returns

BT_STATUS_SUCCESS, the power off request has been sent successfully. BT_STATUS_FAIL, the operation fails due to the same operation is ongoing. BT_STATUS_OUT_OF_MEMORY, the operation fails due to out of memory.

bt_status_t bt_power_on	(	bt_bd_addr_ptr_t	public_addr,
		bt_bd_addr_ptr_t	random_addr
	)

This function powers on the Bluetooth.

The application layer receives BT_POWER_ON_CNF with bt_power_on_cnf_t after the Bluetooth is powered on. Make sure the memory is initialized, the Bluetooth task is created and Bluetooth is powered on before calling any other Bluetooth APIs.

Parameters

[in]	public_addr	is a pointer to a given public address (6 bytes). If public_addr is NULL, the controller will generate a public address and provide it to the user using BT_POWER_ON_CNF with bt_power_on_cnf_t. If public_addr is not NULL, the address in the BT_POWER_ON_CNF is same as public_addr. The given public address should not be [00-00-00-00-00-00].
[in]	random_addr	is a pointer to a given random address(6 bytes).

Returns

BT_STATUS_SUCCESS, the power on request has been sent successfully. BT_STATUS_FAIL, the operation fails due to the same operation is ongoing. BT_STATUS_OUT_OF_MEMORY, the operation fails due to out of memory.