Connection

[中文]

Connection is the basis for data transmission between BLE devices. The connection is established through the interaction between the central device (Central) and the peripheral device (Peripheral). Before reading this section, it is recommended to read the connection section to understand the related introduction of BLE connection.

GAP Layer

The GAP layer is the control layer of the BLE protocol stack, responsible for managing connections, disconnections, connection parameter management, etc. In NimBLE, its API interface is defined in the ble_gap.h file.

The main functions of the GAP layer include:

Main functions of the GAP layer

Function Description	Related API
Device discovery and broadcasting	Broadcast Control: ‘ble_gap_adv_start’, ‘ble_gap_adv_stop’, ‘ble_gap_adv_active’ Broadcast data settings: ‘ble_gap_adv_set_data’, ‘ble_gap_adv_rsp_set_data’ Scan Control: ‘ble_gap_disc’, ‘ble_gap_disc_cancel’, ‘ble_gap_disc_active’ Extended Broadcast: ‘ble_gap_ext_adv_*’ related functions Periodic Broadcasting: ‘ble_gap_periodic_adv_*’ related functions
Connection management	Establish connection: ‘ble_gap_connect’, ‘ble_gap_ext_connect’ Connection Parameter Update: ‘ble_gap_update_params’ Connection Termination: ‘ble_gap_terminate’ Connection status query: ‘ble_gap_conn_find’, ‘ble_gap_conn_active’ Multi-connection support: ‘ble_gap_multi_connect’
Security related	Pairing and Encryption: ‘ble_gap_security_initiate’, ‘ble_gap_pair_initiate’ Encryption Control: ‘ble_gap_encryption_initiate’ Unpair: ‘ble_gap_unpair’, ‘ble_gap_unpair_oldest_peer’ Privacy Mode: ‘ble_gap_set_priv_mode’
Physical layer parameter control	PHY Settings: ‘ble_gap_set_prefered_le_phy’, ‘ble_gap_read_le_phy’ Data Length Control: ‘ble_gap_set_data_len’ Subrate Control: ‘ble_gap_set_default_subrate’, ‘ble_gap_subrate_req’
Signal quality monitoring	RSSI Reading: ‘ble_gap_conn_rssi’ Path Loss Reporting: ‘ble_gap_set_path_loss_reporting_enable’ Transmit Power Report: ‘ble_gap_set_transmit_power_reporting_enable’
Event handling	Event callback registration: ‘ble_gap_set_event_cb’ Event Listener: ‘ble_gap_event_listener_register’ Supports multiple event types, such as connection, disconnection, encryption status change, etc.
Test function	DTM(Direct Test Mode): ‘ble_gap_dtm_tx_start’, ‘ble_gap_dtm_rx_start’ Enhanced DTM: ‘ble_gap_dtm_enh_tx_start’, ‘ble_gap_dtm_enh_rx_start’
Other functions	Whitelist Management: ‘ble_gap_wl_set’ Device Information Reading: ‘ble_gap_read_rem_ver_info’ Address Resolution: ‘ble_gap_rd_local_resolv_addr’

Obtain the list of paired devices

In NimBLE, you can obtain the list of paired devices by calling the ble_store_util_bonded_peers() function. This function will return all the information of the bonded devices, including the device address, keys, etc.

Set Channel Map

In NimBLE, the Channel Map can be set by calling the ble_hs_hci_set_chan_class() function. This function internally invokes the Set_Host_Chan_Class command, informing the controller which data channels are faulty and should be avoided in future connections. It should be noted that this setting only affects the channels available to the controller when establishing future connections or scanning/broadcasting, it does not trigger the sending of the LL_CHANNEL_MAP_REQ command, nor does it change the channel mapping of existing connections. The controller may use this information to avoid faulty channels when establishing future connections, but it will not trigger channel map updates for existing connections.

Reference examples:

Bluedroid:

• GATT Server example

• GATT Client example

NimBLE:

• BLE Central example

• BLE Peripheral example

Multiple connections

Multiple connections is a feature of BLE devices, where a master device can connect to multiple slave devices at the same time.

Reference examples:

Bluedroid:

• GATT Multi-connection Client example

• GATT Server/Client Coexistence example

NimBLE:

• BLE Multi-connection example

BLE Security

Concepts of pairing and bonding:

Pairing: Two devices agree to establish a connection with a certain level of security.

Bonding: At least one device sends security-related information (such as Long Term Key (LTK), Connection Signature Resolution Key (CSRK), or Identity Resolution Key (IRK)) to another device for future connections. After successful pairing, if bonding is supported, key distribution will be carried out; otherwise, bonding information will not be exchanged. Pairing may occur without necessarily requiring bonding. During the pairing process, devices will exchange attributes to determine whether the other party supports bonding. If neither party supports bonding, the security information of the other party will not be stored.

In NimBLE, the configuration related to pairing and bonding is defined by the ble_hs_cfg structure, and users can enable the corresponding configuration items as needed:

• sm_io_cap: Set IO capabilities, used for authentication methods during the pairing process

• sm_bonding: Whether to enable the bonding function

• sm_our_key_dist: The type of key distributed by this device

  • BLE_SM_PAIR_KEY_DIST_ENC: Encryption Key

  • BLE_SM_PAIR_KEY_DIST_ID: Identity Resolution Key (IRK)

• sm_their_key_dist: Type of key distributed by the peer device

  • BLE_SM_PAIR_KEY_DIST_ENC: Encryption Key

  • BLE_SM_PAIR_KEY_DIST_ID: Identity Resolution Key (IRK)

• sm_mitm: Whether to enable man-in-the-middle protection

• sm_sc: Whether to enable secure connections (LE Secure Connections)

Initiate pairing request actively:

In NimBLE, you can actively initiate a pairing request through the ble_gap_security_initiate() function.

Initiate pairing request from the mobile end:

You can also initiate a pairing request by calling the corresponding API on the mobile end. In addition, accessing encrypted services or properties will also automatically trigger pairing.