Merge branch 'feature/walkthrough_for_ble_multi_adv_v5.1' into 'relea…

…se/v5.1'

doc (nimble): Added the tutorial for ble_multi_adv example. (v5.1)

See merge request espressif/esp-idf!26178

examples/bluetooth/nimble/ble_multi_adv/tutorial/Ble_Phy_Peripheral_Example_Walkthrough.md → examples/bluetooth/nimble/ble_multi_adv/tutorial/Ble_Multi_Adv_Example_Walkthrough.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-In this tutorial, the ble_multi_adv example code for the espressif chipsets with BLE5.0 support is reviewed.This example aims at understanding support for multiple advertisements. It uses extended advertising functionality of BLE.
+In this tutorial, the ble_multi_adv example code for the espressif chipsets with BLE5.0 support is reviewed. This example aims at understanding support for multiple advertisements. It uses the extended advertising functionality of BLE.
 
 ## Includes
 
@@ -101,7 +101,7 @@ ESP_ERROR_CHECK( ret );
 ```
 
 ## BT Controller and Stack Initialization
-The main function calls `nimble_port_init()` to initialize BT Controller and nimble stack. This function initializes the BT controller by first creating its configuration structure named `esp_bt_controller_config_t` with default settings generated by the `BT_CONTROLLER_INIT_CONFIG_DEFAULT()` macro. It implements the Host Controller Interface (HCI) on the controller side, the Link Layer (LL), and the Physical Layer (PHY). The BT Controller is invisible to the user applications and deals with the lower layers of the BLE stack. The controller configuration includes setting the BT controller stack size, priority, and HCI baud rate. With the settings created, the BT controller is initialized and enabled with the `esp_bt_controller_init()` and `esp_bt_controller_enable()` functions:
+The main function calls `nimble_port_init()` to initialize the BT Controller and nimble stack. This function initializes the BT controller by first creating its configuration structure named `esp_bt_controller_config_t` with default settings generated by the `BT_CONTROLLER_INIT_CONFIG_DEFAULT()` macro. It implements the Host Controller Interface (HCI) on the controller side, the Link Layer (LL), and the Physical Layer (PHY). The BT Controller is invisible to the user applications and deals with the lower layers of the BLE stack. The controller configuration includes setting the BT controller stack size, priority, and HCI baud rate. With the settings created, the BT controller is initialized and enabled with the `esp_bt_controller_init()` and `esp_bt_controller_enable()` functions:
 
 ```c
 esp_bt_controller_config_t config_opts = BT_CONTROLLER_INIT_CONFIG_DEFAULT();
@@ -163,11 +163,11 @@ The host is configured by setting up the callbacks on Stack-reset, Stack-sync, r
 
 The Security Manager is configured by setting up the following SM's flag and attributes of the host
 
-1. sm_bonding: It represents Security Manager Bond Flag.
+1. sm_bonding: It represents the Security Manager Bond Flag.
 2. sm_mitm : It represents the Security Manager MITM Flag which results in requiring Man-In-The-Middle protection while pairing if it is set.
-3. sm_sc: It represents Security Manager Secure Connections Flag.
-4. sm_our_key_dist: It represents Security Manager's local key distribution mask.
-5. sm_their_key_dist: It represents Security Manager remote key distribution mask.
+3. sm_sc: It represents the Security Manager Secure Connections Flag.
+4. sm_our_key_dist: It represents the Security Manager's local key distribution mask.
+5. sm_their_key_dist: It represents the Security Manager remote key distribution mask.
 
 ```c
  ble_hs_cfg.sm_bonding = 1;
@@ -187,7 +187,7 @@ The main function calls `ble_svc_gap_device_name_set()` to set the default devic
 rc = ble_svc_gap_device_name_set("nimble-multi-adv");
 ```
 
-main function calls  `ble_store_config_init()` to configure the host by setting up the storage callbacks which handle the read, write, and deletion of security material.
+main function calls  `ble_store_config_init()` to configure the host by setting up the storage callbacks that handle the read, write, and deletion of security material.
 
 ```c
 /* XXX Need to have a template for store */
@@ -200,7 +200,18 @@ The main function ends by creating a task where nimble will run using `nimble_po
 nimble_port_freertos_init(ble_multi_adv_host_task);
 ```
 
-`esp_nimble_enable()` create a task where the nimble host will run. It is not strictly necessary to have a separate task for the nimble host, but since something needs to handle the default queue, it is easier to create a separate task.
+`esp_nimble_enable()` creates a task where the nimble host will run. It is not strictly necessary to have a separate task for the nimble host, but since something needs to handle the default queue, it is easier to create a separate task.
+
+## Need for Multiadvertisment
+Bluetooth 5 introduces a number of useful new features, such as multiple advertising sets. This feature supports having more than one advertising set concurrently without having to stop and restart advertising.
+
+All parameters including the advertising interval, advertising data, discoverability, connectability, and number of advertisements to send before stopping can be configured independently for each advertising set.
+It provides the following benefits over legacy advertisement.
+1. Efficiency in Data Transmission:
+2. Customized Information Broadcasting:
+3. Faster Device Discovery:
+4. Reduced Power Consumption:
+5. Customized Advertising Strategies:
 
 ## MultiAdvertising
  The demo example starts 4 types of advertising:
@@ -241,5 +252,39 @@ For each instance:
     ESP_LOGI(tag, "Instance %d started", instance);
 ```
 
+## GAP Events in ble_multi_adv
+We have set the application callback as `ble_multi_adv_gap_event()` to handle the various events. The event list is as follows:
+
+Case 1: `BLE_GAP_EVENT_CONNECT`
+- This case handles a new connection or a failed connection attempt.
+- It logs information about the connection status.
+- If the connection is successful (status == 0), it prints connection details and performs a GATT (Generic Attribute Profile) procedure.
+
+Case 2: `BLE_GAP_EVENT_DISCONNECT`
+- This case handles a disconnection event and logs the reason for the disconnection.
+
+Case 3: `BLE_GAP_EVENT_CONN_UPDATE`
+- This case handles a connection update event, which occurs when the central device updates the connection parameters.
+
+Case 4: `BLE_GAP_EVENT_ADV_COMPLETE`
+- This case handles an advertising complete event.
+- It occurs when advertising for a particular instance has been completed.
+- After completion, it restarts advertising.
+
+Case 5: `BLE_GAP_EVENT_ENC_CHANGE`
+- This case handles an encryption change event.
+- This event occurs when encryption is enabled or disabled for a connection.
+
+Case 6: `BLE_GAP_EVENT_NOTIFY_TX`
+- This case handles a notification transmission event.
+
+Case 7: `BLE_GAP_EVENT_SUBSCRIBE`
+- This case handles a subscription event.
+- It occurs when a central device subscribes or unsubscribes to notifications or indications from a characteristic.
+
+Case 8: `BLE_GAP_EVENT_MTU`
+- This case handles an MTU (Maximum Transmission Unit) update event.
+- This event occurs when the MTU for a connection is updated.
+
 ## Conclusion
- This example demos multi advertising using the Extended adv feature present in BLE5.0. User can have multiple instances of advertising with different advertisement reports. Each instance would show up to be associated with separate BT address when scanned from a remote device.
+ This example demonstrates multi-advertising using the Extended adv feature present in BLE5.0. Users can have multiple instances of advertising with different advertisement reports. Each instance would show up to be associated with a separate BT address when scanned from a remote device.