MT2523 API Reference  LinkIt SDK v4
Bluetooth Low Energy

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

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_tbt_gap_le_get_local_config (void)
 This is a user-defined API that returns the local configuration. More...
 
bt_gap_le_local_key_tbt_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_tbt_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]handleis the handle of the connection to bond.
[in]pairing_configis 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]handleis the handle of the connection you want reply to.
[in]rspis 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]paramis 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]paramis 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_addrThe 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_handleis the connection handle.
[out]conn_infois 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]indA 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]handleis the handle of Bluetooth LE connection.
[in,out]connection_parameteris 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]handleis 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]enableis 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.

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]enableis a switch for the advertiser, cannot be NULL.
[in]paramis the advertising parameter.
[in]datais the advertising data.
[in]scan_rspis 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_addris 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]timeoutis 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]opis 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]deviceis 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]enableis a switch for the scanner, cannot be NULL.
[in]paramis 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]paramis 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]opis the method to operate the white list. Please refer to bt_gap_le_set_white_list_op_t.
[in]addressis 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]paramis 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]paramis 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.