diff --git a/docs/_static/blufi-ble-connect.png b/docs/_static/blufi-ble-connect.png new file mode 100644 index 0000000000..b816db6acc Binary files /dev/null and b/docs/_static/blufi-ble-connect.png differ diff --git a/docs/_static/blufi-init-finish.png b/docs/_static/blufi-init-finish.png new file mode 100644 index 0000000000..aafb9c59f2 Binary files /dev/null and b/docs/_static/blufi-init-finish.png differ diff --git a/docs/_static/config-softap-mode.jpg b/docs/_static/config-softap-mode.jpg new file mode 100644 index 0000000000..1f6a7a4308 Binary files /dev/null and b/docs/_static/config-softap-mode.jpg differ diff --git a/docs/_static/config-station-mode.jpg b/docs/_static/config-station-mode.jpg new file mode 100644 index 0000000000..6bfa83c8b0 Binary files /dev/null and b/docs/_static/config-station-mode.jpg differ diff --git a/docs/_static/configured-softap.png b/docs/_static/configured-softap.png new file mode 100644 index 0000000000..a39bec71ca Binary files /dev/null and b/docs/_static/configured-softap.png differ diff --git a/docs/_static/espblufi-interface.jpg b/docs/_static/espblufi-interface.jpg new file mode 100644 index 0000000000..9a2aef894a Binary files /dev/null and b/docs/_static/espblufi-interface.jpg differ diff --git a/docs/_static/interface-success-connection.jpg b/docs/_static/interface-success-connection.jpg new file mode 100644 index 0000000000..8432853e6f Binary files /dev/null and b/docs/_static/interface-success-connection.jpg differ diff --git a/docs/_static/network-config-interface.jpg b/docs/_static/network-config-interface.jpg new file mode 100644 index 0000000000..117fa369ce Binary files /dev/null and b/docs/_static/network-config-interface.jpg differ diff --git a/docs/_static/select-device-mode.jpg b/docs/_static/select-device-mode.jpg new file mode 100644 index 0000000000..f26f528e44 Binary files /dev/null and b/docs/_static/select-device-mode.jpg differ diff --git a/docs/_static/select-softap-mode.jpg b/docs/_static/select-softap-mode.jpg new file mode 100644 index 0000000000..994d84ead3 Binary files /dev/null and b/docs/_static/select-softap-mode.jpg differ diff --git a/docs/_static/softap-connection-info.jpg b/docs/_static/softap-connection-info.jpg new file mode 100644 index 0000000000..20528e6a60 Binary files /dev/null and b/docs/_static/softap-connection-info.jpg differ diff --git a/docs/_static/softap-connection-log.png b/docs/_static/softap-connection-log.png new file mode 100644 index 0000000000..159c642910 Binary files /dev/null and b/docs/_static/softap-connection-log.png differ diff --git a/docs/_static/station-connection-info.jpg b/docs/_static/station-connection-info.jpg new file mode 100644 index 0000000000..15981751e9 Binary files /dev/null and b/docs/_static/station-connection-info.jpg differ diff --git a/docs/_static/station-connection-log.png b/docs/_static/station-connection-log.png new file mode 100644 index 0000000000..46ca9439b3 Binary files /dev/null and b/docs/_static/station-connection-log.png differ diff --git a/docs/_static/wifi-connection-log.png b/docs/_static/wifi-connection-log.png new file mode 100644 index 0000000000..1d5a59fc37 Binary files /dev/null and b/docs/_static/wifi-connection-log.png differ diff --git a/docs/_static/wifi-connection-prompt.png b/docs/_static/wifi-connection-prompt.png new file mode 100644 index 0000000000..448c7578ee Binary files /dev/null and b/docs/_static/wifi-connection-prompt.png differ diff --git a/docs/en/api-guides/ble/blufi.rst b/docs/en/api-guides/ble/blufi.rst index ce60c53f46..c936f8b427 100644 --- a/docs/en/api-guides/ble/blufi.rst +++ b/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 `_ + - iOS: `EspBlufi For iOS `_ + +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 diff --git a/docs/zh_CN/api-guides/ble/blufi.rst b/docs/zh_CN/api-guides/ble/blufi.rst index 33737b6298..897ef35b13 100644 --- a/docs/zh_CN/api-guides/ble/blufi.rst +++ b/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 `_ + - iOS 版本: `EspBlufi For iOS `_ + +关于 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