This section defines the Low Energy (LE) GAP confirmation and indication macros, structures and API prototypes. More...

Overview

This section defines the Low Energy (LE) GAP confirmation and indication macros, structures and API prototypes.

It defines the generic LE procedures related to device discovery and LE link connectivity. Applications can be developed to configure the controller and control the Bluetooth devices operating in idle, advertising, scanning, initiating and connected modes.

Terms and Acronyms

Terms	Details
GAP	Generic Access Profile. This profile defines the generic procedures related to discovery of Bluetooth enabled devices and link management aspects of connecting to the Bluetooth enabled devices. It also defines procedures related to the use of different security levels.
HCI	Host Controller Interface. For more information, please refer to Wikipedia.
LE	Low Energy. For more information, please refer to Wikipedia.
Out-of-Band	An association mode, primarily designed for scenarios where an Out-of-Band mechanism is used to discover devices and to exchange or transfer cryptographic numbers used in the pairing process.
RSSI	Received Signal Strength Indication. For more information, please refer to Wikipedia.
ADV	Advertising. A device sends data in either non-connectable undirected or scannable undirected advertising events.
CSRK	Connection Signature Resolving Key. A 128-bit key used to sign data and verify signatures on the receiving device.
EDIV	Encrypted Diversifier. A 16-bit stored value used to identify the LTK distributed during LE legacy pairing.
GATT	Generic Attribute Profile. A service framework using the Attribute Protocol for discovering services, and for reading and writing characteristic values on a peer device.
IRK	Identity Resolving Key. A 128-bit key used to generate and resolve random addresses.
LTK	Long Term Key. A 128-bit key used to generate the contributory session key for an encrypted connection.
TK	Temporary Key. A 128-bit temporary key used in the pairing process to generate short term key.
RAND	Random Number. A 64-bit stored valued used to identify the LTK distributed during LE legacy pairing.
SMP	Security Manager (SM) Protocol defines the protocol and behavior to manage pairing, authentication and encryption between low energy devices.
I/O Capability	Input/Output Capability. It is used in pairing feature exchange process to determine which pairing method shall be used.
MITM	Man-in-the-middle Protection. For more information, please refer to Wikipedia.
LESC	Bluetooth LE Secure Connection. It is a new pairing procedures and algorithms defined in Bluetooth core specification version 4.2

How to use this module

The application calls functions bt_gap_le_set_advertising(), bt_gap_le_set_scan() and bt_gap_le_connect().
Then it receives a GAP confirmation or indication. The GAP confirmation or indication is used to notify the application that the process is complete or the indication is received. BT_GAP_LE_XXX_CNF confirms that the process completed successfully (the HCI received the related HCI command). BT_GAP_LE_XXX_IND confirms that a corresponding indicator is received.
The GAP confirmation and indication structures provide related information to the application. The application receives related data through the event parameters. In addition, a user-defined event callback is implemented to apply actions after receiving the confirmations or indications.
- Sample code:
  // Start advertising from the application, so other devices can scan for the advertisement.
  void user_application_start_advertising()
  {
  bt_app_advertising = true;
  bt_hci_cmd_le_set_advertising_parameters_t adv_para = {
  .advertising_interval_min = 0x0800,
  .advertising_interval_max = 0x0800,
  .advertising_type = BT_HCI_ADV_TYPE_CONNECTABLE_UNDIRECTED,
  .advertising_channel_map = 7,
  .advertising_filter_policy = 0
  };
  adv_enable.advertising_enable = BT_HCI_ENABLE;
  bt_gap_le_set_advertising(&adv_enable, &adv_para, NULL, NULL);
  }
  // Connect to a device from the application.
  void user_application_connect(bt_addr_type_t type, bt_bd_addr_ptr_t address)
  {
  bt_hci_cmd_le_create_connection_t connect_para = {
  .le_scan_interval = 0x0010,
  .le_scan_window = 0x0010,
  .initiator_filter_policy = BT_HCI_CONN_FILTER_ASSIGNED_ADDRESS,
  .peer_address = {
  .type = BT_ADDR_PUBLIC,
  },
  .own_address_type = BT_ADDR_PUBLIC,
  .conn_interval_min = 0x0006,
  .conn_interval_max = 0x0320,
  .conn_latency = 0x0000,
  .supervision_timeout = 0x07d0,
  .minimum_ce_length = 0x0000,
  .maximum_ce_length = 0x0190,
  };
  connect_para.peer_address.type = lt_addr_type;
  memcpy(connect_para.peer_address.addr, lt_addr, sizeof(lt_addr));
  bt_gap_le_connect(&connect_para);
  }
  // A user-defined static callback for the application to listen to the event.
  bt_status_t bt_app_event_callback(bt_msg_type_t msg, bt_status_t status, void *buff)
  {
  switch (msg)
  {
  case BT_GAP_LE_ADVERTISING_REPORT_IND:
  const bt_gap_le_advertising_report_ind_t *report = (bt_gap_le_advertising_report_ind_t *)p;
  BT_LOGI("APP", "BT_GAP_LE_ADVERTISING_REPORT_IND %s",
  (status == BT_STATUS_SUCCESS)? "Successful":"Failed");
  BT_LOGI("APP", "========================================");
  BT_LOGI("APP", "Address:\t%s", bt_debug_addr2str(&report->address));
  BT_LOGI("APP", "Event Type:\t%s", get_event_type(report->event_type));
  uint8_t count, ad_data_len, ad_data_type, ad_data_idx;
  count = 0;
  uint8_t buff[100] = {0};
  while (count < report->length_data) {
  ad_data_len = report->data[count];
  // Handle error for data length over 30 bytes.
  if (ad_data_len >= 0x1F) {
  BT_LOGI("APP", "Advertising Data Length Error");
  break;
  }
  ad_data_type = report->data[count+1];
  count+=2;
  if (ad_data_type == BT_GAP_LE_AD_TYPE_FLAG) {
  if (report->data[count] & BT_GAP_LE_AD_FLAG_LIMITED_DISCOVERABLE) {
  BT_LOGI("APP", "Advertising Flags:\tLE Limited Discoverable Mode");
  } else if (report->data[count] & BT_GAP_LE_AD_FLAG_GENERAL_DISCOVERABLE) {
  BT_LOGI("APP", "Advertising Flags:\tLE General Discoverable Mode");
  } else {
  BT_LOGI("APP", "Advertising Flags:\tUnknown: 0x%02x", report->data[count]);
  }
  count+=(ad_data_len-1);
  } else if (ad_data_type == BT_GAP_LE_AD_TYPE_NAME_COMPLETE) {
  for (ad_data_idx=0; ad_data_idx<(ad_data_len-1); ad_data_idx++, count++) {
  buff[ad_data_idx] = report->data[count];
  }
  BT_LOGI("APP", "Complete Name:\t%s", buff);
  } else {
  count+=(ad_data_len-1);
  }
  }
  printf("[I][APP] RAW DATA=0x");
  for (count = 0; count<report->length_data; count++) {
  printf("%02x", report->data[count]);
  }
  printf("\n");
  BT_LOGI("APP", "========================================");
  break;
  case BT_GAP_LE_CONNECT_IND:
  const bt_hci_subevt_le_connection_complete_t *connect_complete = ((bt_gap_le_connection_ind_t *)buff)->connection_complete;
  BT_LOGI("APP", "connection handle=0x%04x", connect_complete->connection_handle);
  BT_LOGI("APP", "role=%s", (connect_complete->role == BT_ROLE_MASTER)? "Master" : "Slave");
  BT_LOGI("APP", "peer address:%s (%s) ", bt_debug_bd_addr2str(connect_complete->peer_address),
  connect_complete->peer_address_type? "Random Device Address" : "Public Device Address");
  // The connection is established, you can now send data.
  break;
  case BT_GAP_LE_DISCONNECT_CNF:
  // Indicate the status of executing the bt_gap_le_disconnect() API.
  BT_LOGI("APP", "BT_GAP_LE_DISCONNECT_CNF %s",
  (status == BT_STATUS_SUCCESS)? "Successful":"Failed");
  break;
  case BT_GAP_LE_DISCONNECT_IND:
  bt_hci_evt_disconnect_complete_t *disconnect_complete;
  disconnect_complete = (bt_hci_evt_disconnect_complete_t*) buff;
  // Handle the disconnection event and release the disconnected link record.
  break;
  }
  return status;
  }

Functions
bt_status_t	bt_gap_le_set_random_address (bt_bd_addr_ptr_t random_addr)
	This function sets a random address. More...

bt_bd_addr_ptr_t	bt_gap_le_get_random_address (void)
	This function gets the random address. More...

bt_status_t	bt_gap_le_get_connection_information (bt_handle_t conn_handle, bt_gap_le_connection_information_t *conn_info)
	This function gets the connection information according to the connection handle. More...

bt_status_t	bt_gap_le_set_white_list (bt_gap_le_set_white_list_op_t op, const bt_addr_t *address)
	This function adds, removes or clears a device from the white list. More...

bt_status_t	bt_gap_le_set_resolving_list (bt_gap_le_set_resolving_list_op_t op, const void *device)
	This function adds, removes or clears a device from the resolving list. More...

bt_status_t	bt_gap_le_set_address_resolution_enable (bool enable)
	This function enables or disables the address resolution. More...

bt_status_t	bt_gap_le_set_resolvable_private_address_timeout (uint32_t timeout)
	This function sets the resolvable private address timeout value. More...

bt_status_t	bt_gap_le_set_advertising (const bt_hci_cmd_le_set_advertising_enable_t enable, const bt_hci_cmd_le_set_advertising_parameters_t param, const bt_hci_cmd_le_set_advertising_data_t data, const bt_hci_cmd_le_set_scan_response_data_t scan_rsp)
	This function sets the advertising. More...

bt_status_t	bt_gap_le_set_scan (const bt_hci_cmd_le_set_scan_enable_t enable, const bt_hci_cmd_le_set_scan_parameters_t param)
	This function sets the scan. More...

bt_status_t	bt_gap_le_connect (const bt_hci_cmd_le_create_connection_t *param)
	This function creates the link layer connection. More...

bt_status_t	bt_gap_le_cancel_connection (void)
	This function cancels the link layer connection. More...

bt_status_t	bt_gap_le_disconnect (const bt_hci_cmd_disconnect_t *param)
	This function disconnects the link layer connection. More...

bt_status_t	bt_gap_le_update_connection_parameter (const bt_hci_cmd_le_connection_update_t *param)
	This function updates the connection parameter. More...

bt_status_t	bt_gap_le_bond (uint32_t handle, bt_gap_le_smp_pairing_config_t const *const pairing_config)
	This function starts the pairing procedure. More...

bt_status_t	bt_gap_le_bonding_reply (uint32_t handle, bt_gap_le_bonding_reply_t const *const rsp)
	This function replies to the BT_GAP_LE_BONDING_REPLY_REQ_IND message. More...

bt_status_t	bt_gap_le_read_rssi (const bt_hci_cmd_read_rssi_t *handle)
	This function reads the RSSI value of the specific connection. More...

bt_status_t	bt_gap_le_update_data_length (const bt_hci_cmd_le_set_data_length_t *param)
	This function updates the data length used for a given connection. More...

bt_status_t	bt_gap_le_set_tx_power (const bt_hci_cmd_le_set_tx_power_t *param)
	This function sets the radio transmission power for a given connection. More...

bt_gap_le_local_config_req_ind_t *	bt_gap_le_get_local_config (void)
	This is a user-defined API that returns the local configuration. More...

bt_gap_le_local_key_t *	bt_gap_le_get_local_key (void)
	This is a user-defined API that returns the special and new local keys. More...

bt_gap_le_bonding_info_t *	bt_gap_le_get_bonding_info (const bt_addr_t remote_addr)
	This is a user-defined API that returns the bonding information. More...

bt_status_t	bt_gap_le_get_pairing_config (bt_gap_le_bonding_start_ind_t *ind)
	This is a user-defined API that gets the pairing configuration. More...

bool	bt_gap_le_is_connection_update_request_accepted (bt_handle_t handle, bt_gap_le_connection_update_param_t *connection_parameter)
	This is a user-defined API that returns whether to accept connection parameter update request. More...

Modules
	Define

	Struct

Function Documentation

bt_status_t bt_gap_le_bond	(	uint32_t	handle,
		bt_gap_le_smp_pairing_config_t const *const	pairing_config
	)

This function starts the pairing procedure.

If the device acts as the master and needs (re-)bonding, it will start the SM. If the device acts as the master and was bonded before, it will start the encryption. If the device acts as the slave, it will send SM security request. The bt_gap_le_get_pairing_config() callback is invoked after the pairing procedure starts and the application receives the BT_GAP_LE_BONDING_COMPLETE_IND event after the pairing is complete. The BT_GAP_LE_BONDING_REPLY_REQ_IND event may be received to request the passkey or Out-of-Band data for pairing.

Parameters

[in]	handle	is the handle of the connection to bond.
[in]	pairing_config	is the pairing configuration to be used to bond with the remote device.

Returns: BT_STATUS_SUCCESS, the bonding procedure started successfully. BT_STATUS_FAIL, the SM session is busy. BT_STATUS_OUT_OF_MEMORY, out of memory.

bt_status_t bt_gap_le_bonding_reply	(	uint32_t	handle,
		bt_gap_le_bonding_reply_t const *const	rsp
	)

This function replies to the BT_GAP_LE_BONDING_REPLY_REQ_IND message.

Reply oob_data for Out-of-Band or passkey for Passkey Input pairing method.

Parameters

[in]	handle	is the handle of the connection you want reply to.
[in]	rsp	is the TK value (oob_data or passkey).

Returns: BT_STATUS_SUCCESS, the application replied with the Out-of-Band data or passkey successfully. BT_STATUS_OUT_OF_MEMORY, out of memory.

bt_status_t bt_gap_le_cancel_connection ( void )

This function cancels the link layer connection.

The operation is issued only after creating a connection and before receiving the BT_GAP_LE_CONNECT_IND event. The application receives the BT_GAP_LE_CONNECT_CANCEL_CNF event after the cancel connection command is complete.

Returns: BT_STATUS_SUCCESS, the operation completed successfully, otherwise it failed.

bt_status_t bt_gap_le_connect ( const bt_hci_cmd_le_create_connection_t * param )

This function creates the link layer connection.

The application receives the BT_GAP_LE_CONNECT_CNF event after the create connection command is complete. Then the application receives the BT_GAP_LE_CONNECT_IND event after the LE read remote used features complete event is received or the disconnection complete event is received.

Parameters

[in] param is the connection parameter.

Returns: BT_STATUS_SUCCESS, the operation completed successfully, otherwise it failed.

bt_status_t bt_gap_le_disconnect ( const bt_hci_cmd_disconnect_t * param )

This function disconnects the link layer connection.

The application receives the BT_GAP_LE_DISCONNECT_CNF event after the disconnect command is complete and the BT_GAP_LE_DISCONNECT_IND event after the disconnection complete event is received.

Parameters

[in] param is the parameter of disconnection request.

Returns: BT_STATUS_SUCCESS, the operation completed successfully, otherwise it failed.

bt_gap_le_bonding_info_t* bt_gap_le_get_bonding_info ( const bt_addr_t remote_addr )

This is a user-defined API that returns the bonding information.

Parameters

[in] remote_addr The address of a remote device to be bonded.

Returns: A pointer to the connection bonding information. The pointer should not be NULL and should point to a global variable.

bt_status_t bt_gap_le_get_connection_information	(	bt_handle_t	conn_handle,
		bt_gap_le_connection_information_t *	conn_info
	)

This function gets the connection information according to the connection handle.

Parameters

[in]	conn_handle	is the connection handle.
[out]	conn_info	is the connection information.

Returns: BT_STATUS_SUCCESS, the operation completed successfully, otherwise it failed.

bt_gap_le_local_config_req_ind_t* bt_gap_le_get_local_config ( void )

This is a user-defined API that returns the local configuration.

Returns: A pointer to the local configuration containing the default local key and secure connection mode flag. The pointer should not be NULL and should point to a global variable.

bt_gap_le_local_key_t* bt_gap_le_get_local_key ( void )

This is a user-defined API that returns the special and new local keys.

Because of the new local keys, the values of LTK, EDIV, Rand and CSRK should be regenerated each time before they are distributed.

Returns: A pointer to the local key. The pointer cannot be NULL. It's recommended to use a global variable to store the local key.

bt_status_t bt_gap_le_get_pairing_config ( bt_gap_le_bonding_start_ind_t * ind )

This is a user-defined API that gets the pairing configuration.

Parameters

[in] ind A pointer to the bonding start indication structure. The pairing_config_req inside the structure should be a global variable.

Returns: BT_STATUS_SUCCESS, if the pairing configuration was set successfully. BT_STATUS_OUT_OF_MEMORY, out of memory.

bt_bd_addr_ptr_t bt_gap_le_get_random_address ( void )

This function gets the random address.

Returns: The random address.

bool bt_gap_le_is_connection_update_request_accepted	(	bt_handle_t	handle,
		bt_gap_le_connection_update_param_t *	connection_parameter
	)

This is a user-defined API that returns whether to accept connection parameter update request.

Parameters

[in]	handle	is the handle of Bluetooth LE connection.
[in,out]	connection_parameter	is the connection parameter of the request.

Returns: true, if the request is accepted, false otherwise.

bt_status_t bt_gap_le_read_rssi ( const bt_hci_cmd_read_rssi_t * handle )

This function reads the RSSI value of the specific connection.

The application receives the BT_GAP_LE_READ_RSSI_CNF event after the read RSSI command is complete.

Parameters

[in] handle is the connection handle.

Returns: BT_STATUS_SUCCESS, the operation completed successfully, otherwise it failed.

bt_status_t bt_gap_le_set_address_resolution_enable ( bool enable )

This function enables or disables the address resolution.

The application receives the BT_GAP_LE_SET_ADDRESS_RESOLUTION_ENABLE_CNF event after this command is complete.

Parameters

[in] enable is a flag to specify whether the address resolution in the controller should be disabled (0) or enabled (1).

Returns: BT_STATUS_SUCCESS, the operation completed successfully, otherwise it failed.

bt_status_t bt_gap_le_set_advertising	(	const bt_hci_cmd_le_set_advertising_enable_t *	enable,
		const bt_hci_cmd_le_set_advertising_parameters_t *	param,
		const bt_hci_cmd_le_set_advertising_data_t *	data,
		const bt_hci_cmd_le_set_scan_response_data_t *	scan_rsp
	)

This function sets the advertising.

Commands will be sent in the sequence of advertising parameter, advertising data, scan response data and advertising enable. The stack will not set advertising parameters if the advertising parameter is NULL. If BT_STATUS_OUT_OF_MEMORY is returned, application should send fewer commands at a time. The application receives the BT_GAP_LE_SET_ADVERTISING_CNF event after the enable command is complete.

Parameters

[in]	enable	is a switch for the advertiser, cannot be NULL.
[in]	param	is the advertising parameter.
[in]	data	is the advertising data.
[in]	scan_rsp	is the scan response data.

Returns: BT_STATUS_SUCCESS, the operation completed successfully, otherwise it failed.

bt_status_t bt_gap_le_set_random_address ( bt_bd_addr_ptr_t random_addr )

This function sets a random address.

The random address has to be configured before advertising, scanning or initiating. The application receives the BT_GAP_LE_SET_RANDOM_ADDRESS_CNF event after the set random address command is complete.

Parameters

[in] random_addr is a pointer to a given random address(6 bytes). It should not be NULL.

Returns: BT_STATUS_SUCCESS, the operation completed successfully, otherwise it failed.

bt_status_t bt_gap_le_set_resolvable_private_address_timeout ( uint32_t timeout )

This function sets the resolvable private address timeout value.

The application receives the BT_GAP_LE_SET_RESOLVABLE_PRIVATE_ADDRESS_TIMEOUT_CNF event after this command is complete.

Parameters

[in] timeout is the resolvable private address timeout value.

Returns: BT_STATUS_SUCCESS, the operation completed successfully, otherwise it failed.

bt_status_t bt_gap_le_set_resolving_list	(	bt_gap_le_set_resolving_list_op_t	op,
		const void *	device
	)

This function adds, removes or clears a device from the resolving list.

The application receives the BT_GAP_LE_SET_RESOLVING_LIST_CNF event after the adding, removing or clearing operation is complete.

Parameters

[in]	op	is the method to operate the resolving list. The op could be BT_GAP_LE_ADD_TO_RESOLVING_LIST, BT_GAP_LE_REMOVE_FROM_RESOLVING_LIST or BT_GAP_LE_CLEAR_RESOLVING_LIST. For BT_GAP_LE_ADD_TO_RESOLVING_LIST, the user should create a bt_hci_cmd_le_add_device_to_resolving_list_t and pass the address to the device parameter. For BT_GAP_LE_REMOVE_FROM_RESOLVING_LIST, the user should create a bt_hci_cmd_le_remove_device_from_resolving_list_t and pass the address to the device parameter. For BT_GAP_LE_CLEAR_RESOLVING_LIST, the user should set NULL as the device parameter.
[in]	device	is the device to be added or removed.

Returns: BT_STATUS_SUCCESS, the operation completed successfully, otherwise it failed.

bt_status_t bt_gap_le_set_scan	(	const bt_hci_cmd_le_set_scan_enable_t *	enable,
		const bt_hci_cmd_le_set_scan_parameters_t *	param
	)

This function sets the scan.

Commands will be sent in the sequence of scan parameter and scan enable. The stack will not set the scanning parameter if the scan parameter is NULL. The application receives the BT_GAP_LE_SET_SCAN_CNF event after the enable command is complete and BT_GAP_LE_ADVERTISING_REPORT_IND after the remote device sends the advertising packet.

Parameters

[in]	enable	is a switch for the scanner, cannot be NULL.
[in]	param	is a pointer to the scan parameters or NULL if the user needs to disable the scan.

Returns: BT_STATUS_SUCCESS, the operation completed successfully, otherwise it failed.

bt_status_t bt_gap_le_set_tx_power ( const bt_hci_cmd_le_set_tx_power_t * param )

This function sets the radio transmission power for a given connection.

The application receives the BT_GAP_LE_SET_TX_POWER_CNF event after the set TX power command is complete.

Parameters

[in] param is a pointer to a structure that specifies the parameters for TX power.

Returns: BT_STATUS_SUCCESS, the operation completed successfully, otherwise it failed.

bt_status_t bt_gap_le_set_white_list	(	bt_gap_le_set_white_list_op_t	op,
		const bt_addr_t *	address
	)

This function adds, removes or clears a device from the white list.

The application receives the BT_GAP_LE_SET_WHITE_LIST_CNF event after the adding, removing or clearing command is complete.

Parameters

[in]	op	is the method to operate the white list. Please refer to bt_gap_le_set_white_list_op_t.
[in]	address	is the address with a type to be set. It should not be NULL when using BT_GAP_LE_ADD_TO_WHITE_LIST or BT_GAP_LE_REMOVE_FROM_WHITE_LIST. And it should be NULL when using the BT_GAP_LE_CLEAR_WHITE_LIST operation.

Returns: BT_STATUS_SUCCESS, the operation completed successfully, otherwise it failed.

bt_status_t bt_gap_le_update_connection_parameter ( const bt_hci_cmd_le_connection_update_t * param )

This function updates the connection parameter.

The stack will send a request to the controller to update LE connection parameter if the stack is the master. The stack will send an updating request to the remote device if the stack is the slave. The application receives the BT_GAP_LE_CONNECTION_UPDATE_CNF event after the HCI LE connection update command is complete or the L2CAP connection parameter update response is received. Then the application receives the BT_GAP_LE_CONNECTION_UPDATE_IND event after the connection update complete event is received.

Parameters

[in] param is the connection update parameter.

Returns: BT_STATUS_SUCCESS, the operation completed successfully, otherwise it failed.

bt_status_t bt_gap_le_update_data_length ( const bt_hci_cmd_le_set_data_length_t * param )

This function updates the data length used for a given connection.

The application receives the BT_GAP_LE_UPDATE_DATA_LENGTH_CNF event after the 'set data length command' is complete.

Parameters

[in] param is a pointer to the parameters of set data length, including connection handle, TX octets and TX time.

Returns: BT_STATUS_SUCCESS, the operation completed successfully, otherwise it failed.

Overview

Terms and Acronyms

How to use this module

Functions

Modules

Function Documentation