diff --git a/docs/_static/bluetooth-architecture-no-ble-mesh.png b/docs/_static/bluetooth-architecture-no-ble-mesh.png new file mode 100644 index 0000000000..1924684fd6 Binary files /dev/null and b/docs/_static/bluetooth-architecture-no-ble-mesh.png differ diff --git a/docs/_static/bluetooth-architecture-no-blufi.png b/docs/_static/bluetooth-architecture-no-blufi.png new file mode 100644 index 0000000000..3963b7eb1c Binary files /dev/null and b/docs/_static/bluetooth-architecture-no-blufi.png differ diff --git a/docs/_static/bluetooth-architecture.png b/docs/_static/bluetooth-architecture.png new file mode 100644 index 0000000000..bfa42f6e47 Binary files /dev/null and b/docs/_static/bluetooth-architecture.png differ diff --git a/docs/conf_common.py b/docs/conf_common.py index 9045718684..ce8c97ff43 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -19,7 +19,8 @@ from esp_docs.conf_docs import * # noqa: F403,F401 if os.environ.get('IDF_PATH') is None: raise RuntimeError('IDF_PATH should be set, run export.sh before building docs') -BT_DOCS = ['api-reference/bluetooth/bt_le.rst', +BT_DOCS = ['api-guides/bluetooth.rst', + 'api-reference/bluetooth/bt_le.rst', 'api-reference/bluetooth/esp_bt_defs.rst', 'api-reference/bluetooth/esp_bt_device.rst', 'api-reference/bluetooth/esp_bt_main.rst', diff --git a/docs/en/api-guides/bluetooth.rst b/docs/en/api-guides/bluetooth.rst new file mode 100644 index 0000000000..ac17c40b2c --- /dev/null +++ b/docs/en/api-guides/bluetooth.rst @@ -0,0 +1,193 @@ +Bluetooth® Overview +=================== + +:link_to_translation:`zh_CN:[中文]` + +This document provides an architecture overview of the Bluetooth stack in ESP-IDF and some quick links to related documents and application examples. + +.. only:: esp32 + + {IDF_TARGET_NAME} supports Dual-Mode Bluetooth 4.2 and is certified for Bluetooth 4.2. + +.. only:: esp32c3 or esp32s3 + + {IDF_TARGET_NAME} supports Bluetooth 5.0 (LE) and is certified for Bluetooth LE 5.0. + +.. only:: esp32c2 or esp32c6 or esp32h2 + + {IDF_TARGET_NAME} supports Bluetooth 5.0 (LE) and is certified for Bluetooth LE 5.3. + +The Bluetooth stack in ESP-IDF is a layered architecture that enables Bluetooth functionality on {IDF_TARGET_NAME} chip series. The table below shows its architecture. + +.. only:: esp32 or esp32s3 or esp32c3 or esp32c6 + + .. figure:: ../../_static/bluetooth-architecture.png + :align: center + :scale: 90% + :alt: {IDF_TARGET_NAME} Bluetooth Stack Architecture + + {IDF_TARGET_NAME} Bluetooth Stack Architecture + +.. only:: esp32c2 + + .. figure:: ../../_static/bluetooth-architecture-no-ble-mesh.png + :align: center + :scale: 90% + :alt: {IDF_TARGET_NAME} Bluetooth Stack Architecture + + {IDF_TARGET_NAME} Bluetooth Stack Architecture + +.. only:: esp32h2 + + .. figure:: ../../_static/bluetooth-architecture-no-blufi.png + :align: center + :scale: 90% + :alt: {IDF_TARGET_NAME} Bluetooth Stack Architecture + + {IDF_TARGET_NAME} Bluetooth Stack Architecture + +The table below shows whether the Bluetooth modules are supported in a specific chip series. + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + + * - Chip Series + - Controller + - ESP-Bluedroid + - ESP-NimBLE + - ESP-BLE-MESH + - BluFi + * - ESP32 + - Y + - Y + - Y + - Y + - Y + * - ESP32-S2 + - \– + - \– + - \– + - \– + - \– + * - ESP32-S3 + - Y + - Y + - Y + - Y + - Y + * - ESP32-C2 + - Y + - Y + - Y + - \– + - Y + * - ESP32-C3 + - Y + - Y + - Y + - Y + - Y + * - ESP32-C6 + - Y + - Y + - Y + - Y + - Y + * - ESP32-H2 + - Y + - Y + - Y + - Y + - \– + +The following sections briefly describe each layer and provide quick links to the related documents and application examples. + +ESP Bluetooth Controller +------------------------ + +At the bottom layer is ESP Bluetooth Controller, which encompasses various modules such as PHY, Baseband, Link Controller, Link Manager, Device Manager, and HCI. It handles hardware interface management and link management. It provides functions in the form of libraries and is accessible through APIs. This layer directly interacts with the hardware and low-level Bluetooth protocols. + +- :doc:`API reference <../api-reference/bluetooth/controller_vhci>` +- :example:`Application examples ` + +Hosts +----- + +There are two hosts, ESP-Bluedroid and ESP-NimBLE. The major difference between them is as follows: + +- Although both support Bluetooth LE, ESP-NimBLE requires less heap and flash size. + +.. only:: esp32 + + - ESP-Bluedroid supports both Classic Bluetooth and Bluetooth LE, while ESP-NimBLE only supports Bluetooth LE. + +ESP-Bluedroid +^^^^^^^^^^^^^ + +ESP-Bluedroid is a modified version of the native Android Bluetooth stack, Bluedroid. It consists of two layers: the Bluetooth Upper Layer (BTU) and the Bluetooth Transport Controller layer (BTC). The BTU layer is responsible for processing bottom layer Bluetooth protocols such as L2CAP, GATT/ATT, SMP, GAP, and other profiles. The BTU layer provides an interface prefixed with "bta". The BTC layer is mainly responsible for providing a supported interface, prefixed with “esp”, to the application layer, processing GATT-based profiles and handling miscellaneous tasks. All the APIs are located in the ESP_API layer. Developers should use the Bluetooth APIs prefixed with “esp". + +.. only:: esp32 + + ESP-Bluedroid for {IDF_TARGET_NAME} supports Classic Bluetooth and Bluetooth LE. + +.. only:: not esp32 + + ESP-Bluedroid for {IDF_TARGET_NAME} supports Bluetooth LE only. Classic Bluetooth is not supported. + +- API references + + - :doc:`../api-reference/bluetooth/bt_common` + - :doc:`Bluetooth LE <../api-reference/bluetooth/bt_le>` + + .. only:: esp32 + + - :doc:`../api-reference/bluetooth/classic_bt` + +- :example:`Application examples ` + +ESP-NimBLE +^^^^^^^^^^ + +ESP-NimBLE is a host stack built on top of the NimBLE host stack developed by Apache Mynewt. The NimBLE host stack is ported for {IDF_TARGET_NAME} chip series and FreeRTOS. The porting layer is kept clean by maintaining all the existing APIs of NimBLE along with a single ESP-NimBLE API for initialization, making it simpler for the application developers. + +ESP-NimBLE supports Bluetooth LE only. Classic Bluetooth is not supported. + +- `Apache Mynewt NimBLE User Guide `__ +- API references + + - `NimBLE API references `__ + - :doc:`ESP-NimBLE API references for initialization <../api-reference/bluetooth/nimble/index>` + +- :example:`Application examples ` + +Profiles +-------- + +Above the host stacks are the profile implementations by Espressif and some common profiles. Depending on your configuration, these profiles can run on ESP-Bluedroid or ESP-NimBLE. + +.. only:: SOC_BLE_MESH_SUPPORTED + + ESP-BLE-MESH + ^^^^^^^^^^^^ + + Built on top of Zephyr Bluetooth Mesh stack, the ESP-BLE-MESH implementation supports device provisioning and node control. It also supports such node features as Proxy, Relay, Low power and Friend. + + - :doc:`ESP-BLE-MESH documentation `: feature list, get started, architecture, description of application examples, frequently asked questions, etc. + - :example:`Application examples ` + +.. only:: SOC_BLUFI_SUPPORTED + + BluFi + ^^^^^ + + The BluFi for {IDF_TARGET_NAME} is a Wi-Fi network configuration function via Bluetooth channel. It provides a secure protocol to pass Wi-Fi configuration and credentials to {IDF_TARGET_NAME}. Using this information, {IDF_TARGET_NAME} can then connect to an AP or establish a softAP. + + - :doc:`BluFi documentation ` + - :example:`Application examples ` + +Applications +------------ + +At the uppermost layer are applications. You can build your own applications on top of the ESP-Bluedroid and ESP-NimBLE stacks, leveraging the provided APIs and profiles to create Bluetooth-enabled applications tailored to specific use cases. \ No newline at end of file diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst index e716ec91a1..4ebda350c0 100644 --- a/docs/en/api-guides/index.rst +++ b/docs/en/api-guides/index.rst @@ -8,6 +8,7 @@ API Guides app_trace startup :SOC_BLUFI_SUPPORTED: blufi + :SOC_BT_SUPPORTED: bluetooth bootloader build-system :SOC_SUPPORT_COEXISTENCE: coexist diff --git a/docs/zh_CN/api-guides/bluetooth.rst b/docs/zh_CN/api-guides/bluetooth.rst new file mode 100644 index 0000000000..36795781ea --- /dev/null +++ b/docs/zh_CN/api-guides/bluetooth.rst @@ -0,0 +1 @@ +.. include:: ../../en/api-guides/bluetooth.rst \ No newline at end of file diff --git a/docs/zh_CN/api-guides/index.rst b/docs/zh_CN/api-guides/index.rst index d963866b71..60f1095c40 100644 --- a/docs/zh_CN/api-guides/index.rst +++ b/docs/zh_CN/api-guides/index.rst @@ -8,6 +8,7 @@ API 指南 app_trace startup :SOC_BLUFI_SUPPORTED: blufi + :SOC_BT_SUPPORTED: bluetooth bootloader build-system :SOC_SUPPORT_COEXISTENCE: coexist