Merge branch 'docs/migrate_esp32_bluetooth_networking_to_api_guide' into 'master'

docs: Migrate ESP32 Bluetooth Networking PDF content to BluFi API Guide

Closes DOC-7825

See merge request espressif/esp-idf!38043

docs/en/api-guides/ble/blufi.rst

@@ -1,7 +1,7 @@
 BluFi
-^^^^^^
+=======
 
-:link_to_translation:`en:[English]`
+:link_to_translation:`zh_CN:[中文]`
 
 Overview
 ----------
@@ -12,6 +12,218 @@ Fragmenting, data encryption, and checksum verification in the BluFi layer are t
 
 You can customize symmetric encryption, asymmetric encryption, and checksum support customization. Here we use the DH algorithm for key negotiation, 128-AES algorithm for data encryption, and CRC16 algorithm for checksum verification.
 
+
+Getting Started
+-----------------
+
+This section provides a step-by-step guide to configuring Wi-Fi on an {IDF_TARGET_NAME} device using the EspBlufi app.
+
+
+Prerequisites
+^^^^^^^^^^^^^^^
+
+Hardware:
+
+* An {IDF_TARGET_NAME} module
+* A computer, connected to the module for power supply and serial logging
+* A mobile phone running Android or iOS
+
+
+Software:
+
+* BluFi example: :example:`bluetooth/blufi` (to be flashed into {IDF_TARGET_NAME})
+* Mobile App: EspBlufi
+
+    - Android: `EspBlufi For Android <https://github.com/EspressifApp/EspBlufiForAndroid>`_
+    - iOS: `EspBlufi For iOS <https://github.com/EspressifApp/EspBlufiForiOS>`_
+
+For detailed instructions on flashing BluFi example, please refer to ESP-IDF :doc:`../../get-started/index` documentation.
+
+
+Configuring Wi-Fi via the EspBlufi App
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Setting {IDF_TARGET_NAME} to Station Mode
+###############################################
+
+
+1. **Power on {IDF_TARGET_NAME}**
+
+   Connect {IDF_TARGET_NAME} to your computer. The following log will be output to the serial port tool:
+
+   .. figure:: ../../../_static/blufi-init-finish.png
+        :align: center
+        :width: 70%
+
+
+2. **Connect via EspBlufi**
+
+   - Grant Wi-Fi, Bluetooth, and location permissions on your mobile phone.
+   - Open the EspBlufi app, and refresh the interface by swiping down. The nearby Bluetooth-enabled devices will be displayed.
+
+     .. figure:: ../../../_static/espblufi-interface.jpg
+         :align: center
+         :scale: 20%
+         :alt: EspBlufi Interface
+
+         EspBlufi Interface
+
+
+   - Click on the {IDF_TARGET_NAME} device, and click **Connect** to establish a Bluetooth connection. A successful connection will display the following interface:
+
+     .. figure:: ../../../_static/interface-success-connection.jpg
+         :align: center
+         :scale: 20%
+         :alt: Successful Connection
+
+         Successful Connection
+
+
+     Meanwhile, the following log will be output to the serial port tool:
+
+     .. figure:: ../../../_static/blufi-ble-connect.png
+         :align: center
+         :width: 80%
+
+     .. note::
+
+        If the **Networking** button is missing or unresponsive, restart {IDF_TARGET_NAME} and ensure Bluetooth permissions are granted.
+
+
+3. **Configure Wi-Fi**
+
+   - Click on the **Networking** button to open the network configuration menu:
+
+     .. figure:: ../../../_static/network-config-interface.jpg
+         :align: center
+         :scale: 20%
+         :alt: Network Configuration Interface
+
+         Network Configuration Interface
+
+   - Select a device mode from the dropdown list. BluFi supports the following three modes:
+
+     - **Station:** Connects to an existing Wi-Fi network.
+     - **SoftAP:** Creates a Wi-Fi access point.
+     - **SoftAP/Station:** Enables both modes simultaneously.
+
+     .. figure:: ../../../_static/select-device-mode.jpg
+         :align: center
+         :scale: 20%
+         :alt: Selecting Device Mode
+
+         Selecting Device Mode
+
+   - Select **Station** mode, click on the refresh button, and choose a Wi-FI SSID. Then, enter the password.
+
+     .. figure:: ../../../_static/config-station-mode.jpg
+         :align: center
+         :scale: 20%
+         :alt: Configuring Station Mode
+
+         Configuring Station Mode
+
+     .. only:: esp32
+
+        .. note::
+
+           {IDF_TARGET_NAME} only supports 2.4 GHz Wi-Fi. Ensure you select a compatible network.
+
+
+   - Click on the **Confirm** button to complete the configuration. A successful connection will display the following interface. The information marked in red in shows the Wi-Fi mode (which is Station mode in this example) and the connection information (such as the AP’s BSSID and SSID, as well as the connection status).
+
+     .. figure:: ../../../_static/station-connection-info.jpg
+         :align: center
+         :scale: 20%
+         :alt: Station Connection Information
+
+         Station Connection Information
+
+     Meanwhile, the following log will be output to the serial port tool:
+
+     .. figure:: ../../../_static/station-connection-log.png
+         :align: center
+         :width: 80%
+
+
+Setting {IDF_TARGET_NAME} as a SoftAP
+###############################################
+
+
+1. **Connect via EspBlufi**
+
+   - Power on the module. Connect the EspBlufi app to {IDF_TARGET_NAME} via Bluetooth.
+   - In the network configuration menu, select **SoftAP** mode:
+
+     .. figure:: ../../../_static/select-softap-mode.jpg
+         :align: center
+         :scale: 20%
+         :alt: Selecting SoftAP Mode
+
+         Selecting SoftAP Mode
+
+
+2. **Configure SoftAP**
+
+   - Select the security encryption mode, channel, and maximum number of Stations to be connected.
+   - Enter the SoftAP’s SSID and password.
+   - Click on the **Confirm** button to complete the configuration.
+
+     .. figure:: ../../../_static/config-softap-mode.jpg
+         :align: center
+         :scale: 20%
+         :alt: Configuring SoftAP Mode
+
+         Configuring SoftAP Mode
+
+
+3. **Verify SoftAP**
+
+   A successful SoftAP configuration will display the following interface, showing the current Wi-Fi mode and connection status:
+
+   .. figure:: ../../../_static/softap-connection-info.jpg
+       :align: center
+       :scale: 20%
+       :alt: SoftAP Connection Information
+
+       SoftAP Connection Information
+
+   Meanwhile, the following log will be output to the serial port tool:
+
+   .. figure:: ../../../_static/softap-connection-log.png
+       :align: center
+       :width: 70%
+
+
+4. **Connect to SoftAP**
+
+   - Enable Wi-Fi on your mobile phone. The configured SoftAP will appear in the network list:
+
+     .. figure:: ../../../_static/configured-softap.png
+         :align: center
+         :height: 370
+         :alt: The Configured SoftAP
+
+         The Configured SoftAP
+
+   - Connect to the SoftAP. A successful connection will be indicated as follows:
+
+     .. figure:: ../../../_static/wifi-connection-prompt.png
+         :align: center
+         :height: 370
+         :alt: Wi-Fi Connection Prompt
+
+         Wi-Fi Connection Prompt
+
+     Meanwhile, the following log will be output to the serial port tool:
+
+     .. figure:: ../../../_static/wifi-connection-log.png
+         :align: center
+         :width: 80%
+
+    The {IDF_TARGET_NAME} device is now successfully connected to Wi-Fi using Bluetooth networking.
+
+
 The BluFi Flow
 ----------------
 
@@ -485,7 +697,7 @@ GATT Related Instructions
 ----------------------------
 
 UUID
->>>>>
+^^^^^
 
 BluFi Service UUID: 0xFFFF, 16 bit
 

docs/zh_CN/api-guides/ble/blufi.rst

@@ -1,5 +1,5 @@
 BluFi
-^^^^^^
+=======
 
 :link_to_translation:`en:[English]`
 
@@ -12,6 +12,218 @@ BluFi 流程的关键部分包括数据的分片、加密以及校验和验证
 
 用户可按需自定义用于对称加密、非对称加密以及校验的算法。此处，我们采用 DH 算法进行密钥协商，128-AES 算法用于数据加密，CRC16 算法用于校验和验证。
 
+
+快速入门
+--------
+
+本节将指导您使用 EspBlufi 应用程序在 {IDF_TARGET_NAME} 设备上配置 Wi-Fi。
+
+
+硬件及软件准备
+^^^^^^^^^^^^^^^^
+
+硬件：
+
+* {IDF_TARGET_NAME} 模组一个
+* 电脑一台，并与模组连接，为模组供电并提供串口打印
+* 运行 Android 或 iOS 的手机一台
+
+
+软件：
+
+* BluFi 示例: :example:`bluetooth/blufi` （需烧录至 {IDF_TARGET_NAME}）
+* 手机应用程序：EspBlufi
+
+    - Android 版本: `EspBlufi For Android <https://github.com/EspressifApp/EspBlufiForAndroid>`_
+    - iOS 版本: `EspBlufi For iOS <https://github.com/EspressifApp/EspBlufiForiOS>`_
+
+关于 BluFi 示例烧录的详细说明，请参考 ESP-IDF :doc:`../../get-started/index` 文档。
+
+
+通过 EspBlufi 应用配置 Wi-Fi
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Station 模式配置示例
+###################################
+
+
+1. **给 {IDF_TARGET_NAME} 上电**
+
+   将 {IDF_TARGET_NAME} 连接至电脑，可通过串口工具看到如下打印：
+
+   .. figure:: ../../../_static/blufi-init-finish.png
+        :align: center
+        :width: 70%
+
+
+2. **通过 EspBlufi 建立连接**
+
+   - 在手机上开启 Wi-Fi、蓝牙和位置权限。
+   - 打开 EspBlufi 应用程序，下拉刷新界面，扫描附近的蓝牙设备。
+
+     .. figure:: ../../../_static/espblufi-interface.jpg
+         :align: center
+         :scale: 20%
+         :alt: EspBlufi 界面
+
+         EspBlufi 界面
+
+
+   - 点击目标 {IDF_TARGET_NAME} 设备，选择 **连接** 建立蓝牙连接。连接成功后界面显示如下：
+
+     .. figure:: ../../../_static/interface-success-connection.jpg
+         :align: center
+         :scale: 20%
+         :alt: 蓝牙连接成功界面
+
+         蓝牙连接成功界面
+
+
+     同时，串口工具中会出现如下图中的打印：
+
+     .. figure:: ../../../_static/blufi-ble-connect.png
+         :align: center
+         :width: 80%
+
+     .. note::
+
+        若界面未显示 **配网** 按钮，或按钮无法点击，请重启 {IDF_TARGET_NAME} 并确认已开启蓝牙权限。
+
+
+3. **配置 Wi-Fi 网络**
+
+   - 点击 **配网** 按钮进入网络配置界面：
+
+     .. figure:: ../../../_static/network-config-interface.jpg
+         :align: center
+         :scale: 20%
+         :alt: 网络配置界面
+
+         网络配置界面
+
+   - 从下拉列表中选择设备模式。BluFi 支持以下三种模式：
+
+     - **Station:** 连接至现有 Wi-Fi 网络。
+     - **SoftAP:** 创建 Wi-Fi 热点。
+     - **SoftAP/Station:** 同时启用 SoftAP 和 Station 模式。
+
+     .. figure:: ../../../_static/select-device-mode.jpg
+         :align: center
+         :scale: 20%
+         :alt: 选择设备模式
+
+         选择设备模式
+
+   - 选择 **Station** 模式，点击刷新按钮，选择目标 Wi-Fi 名称，并输入密码。
+
+     .. figure:: ../../../_static/config-station-mode.jpg
+         :align: center
+         :scale: 20%
+         :alt: 配置 Station 模式
+
+         配置 Station 模式
+
+     .. only:: esp32
+
+        .. note::
+
+           {IDF_TARGET_NAME} 仅支持 2.4 GHz Wi-Fi，请确保选择兼容的网络。
+
+
+   - 点击 **确定** 按钮完成配置。成功连接后界面显示如下。标红部分显示当前 Wi-Fi 模式（本例为 Station 模式）及连接信息（如 AP 的 BSSID、SSID 和连接状态）。
+
+     .. figure:: ../../../_static/station-connection-info.jpg
+         :align: center
+         :scale: 20%
+         :alt: Station 连接信息
+
+         Station 连接信息
+
+     同时，串口工具会打印如下信息：
+
+     .. figure:: ../../../_static/station-connection-log.png
+         :align: center
+         :width: 80%
+
+
+SoftAP 模式配置示例
+###############################
+
+
+1. **通过 EspBlufi 建立连接**
+
+   - 将模组上电。使用 EspBlufi 应用程序通过蓝牙连接 {IDF_TARGET_NAME}。
+   - 在配网界面选择 **SoftAP** 模式：
+
+     .. figure:: ../../../_static/select-softap-mode.jpg
+         :align: center
+         :scale: 20%
+         :alt: 选择 SoftAP 模式
+
+         选择 SoftAP 模式
+
+
+2. **配置 SoftAP 参数**
+
+   - 选择加密方式、信道和最大连接数。
+   - 输入 SoftAP 的 SSID 和密码。
+   - 点击 **确定** 按钮完成配置。
+
+     .. figure:: ../../../_static/config-softap-mode.jpg
+         :align: center
+         :scale: 20%
+         :alt: 配置 SoftAP 模式
+
+         配置 SoftAP 模式
+
+
+3. **验证 SoftAP 配置**
+
+   成功配置 SoftAP 后，界面显示当前 Wi-Fi 模式和连接状态：
+
+   .. figure:: ../../../_static/softap-connection-info.jpg
+       :align: center
+       :scale: 20%
+       :alt: SoftAP 连接信息
+
+       SoftAP 连接信息
+
+   同时，串口工具会打印如下信息：
+
+   .. figure:: ../../../_static/softap-connection-log.png
+       :align: center
+       :width: 70%
+
+
+4. **连接 SoftAP 热点**
+
+   - 打开手机 Wi-Fi，可以搜索到已配置的 SoftAP：
+
+     .. figure:: ../../../_static/configured-softap.png
+         :align: center
+         :height: 370
+         :alt: 已配置的 SoftAP
+
+         已配置的 SoftAP
+
+   - 连接该热点，成功连接后界面如下：
+
+     .. figure:: ../../../_static/wifi-connection-prompt.png
+         :align: center
+         :height: 370
+         :alt: Wi-Fi 连接提示
+
+         Wi-Fi 连接提示
+
+     同时，串口工具打印如下信息：
+
+     .. figure:: ../../../_static/wifi-connection-log.png
+         :align: center
+         :width: 80%
+
+    至此，{IDF_TARGET_NAME} 已通过蓝牙配网成功连接 Wi-Fi 网络。
+
+
 BluFi 流程
 -----------
 
@@ -485,7 +697,7 @@ GATT 相关说明
 -------------
 
 UUID
->>>>>
+^^^^^
 
 BluFi Service UUID： 0xFFFF，16 bit