docs(ble): add ESP-BLE-UART companion guide

Move the OpenCode companion guide into the ble_uart_service example.

Add English and Chinese Markdown guides with image assets.

Keep ESP-BLE-UART naming consistent across the example and bridge tooling.


(cherry picked from commit 926111e721)

Co-authored-by: Zhou Xiao <zhouxiao@espressif.com>
This commit is contained in:
Zhou Xiao
2026-06-08 14:14:49 +08:00
parent c3640229af
commit 6766a9ba67
30 changed files with 1072 additions and 112 deletions

View File

@@ -1,4 +1,4 @@
menu "BLE UART library"
menu "ESP-BLE-UART library"
config BLE_UART_DEVICE_NAME_PREFIX
string "BLE device name prefix"

View File

@@ -1,4 +1,6 @@
# BLE UART Porting & API Guide
# ESP-BLE-UART Porting & API Guide
> **Naming convention:** Use **ESP-BLE-UART** for Espressif-owned product names (Bridge, Console, Daemon, Echo Server, the `ble_uart` component, and the `ble_uart_service` example). Use **BLE UART** for the generic GATT service convention, transport layer, and compatible third-party devices. This follows the same pattern as ESP-BLE-MESH.
This document lives in **`examples/bluetooth/common/ble_uart/`** next to the
`ble_uart` component sources (`ble_uart.h`, backend `.c` files).
@@ -60,7 +62,7 @@ is entirely up to you**.
Canonical sources live under **`$IDF_PATH/examples/bluetooth/common/ble_uart/`**
(component name `ble_uart`): `ble_uart.h`, `ble_uart_nimble.c`,
`ble_uart_bluedroid.c`, `CMakeLists.txt`, and `Kconfig` (prefix + RX scratch;
`menuconfig → Component configuration → BLE UART library`). When reusing
`menuconfig → Component configuration → ESP-BLE-UART library`). When reusing
outside this tree, copy the whole `common/ble_uart/` directory or at least
merge `Kconfig` into your component so the same `CONFIG_BLE_UART_*` symbols
exist.
@@ -73,7 +75,7 @@ then use `REQUIRES ble_uart` from `main/CMakeLists.txt` (see
`ble_uart` target exists when CMake expands `main`'s requirements.
Kconfig options appear under
`menuconfig → Component configuration → BLE UART library`.
`menuconfig → Component configuration → ESP-BLE-UART library`.
> A `main/idf_component.yml` path dependency alone is **not** sufficient if
> `main/CMakeLists.txt` lists `REQUIRES ble_uart`: the early requirement scan
@@ -212,7 +214,7 @@ void app_main(void)
}
ESP_ERROR_CHECK(err);
/* 2. Bring up BLE UART */
/* 2. Bring up ESP-BLE-UART */
ESP_ERROR_CHECK(ble_uart_install(&(ble_uart_config_t){
.encrypted = true,
.device_name = "MyDevice",
@@ -489,7 +491,7 @@ ble_uart_open();
### 6.4 Configuring the device-name prefix via Kconfig
If you use the shared `ble_uart` component, options are already in
`menuconfig → Component configuration → BLE UART library`. If you copied only
`menuconfig → Component configuration → ESP-BLE-UART library`. If you copied only
the `.c` / `.h` files into `main/`, copy `Kconfig` from `common/ble_uart/` as
well (or merge its symbols into your own `Kconfig.projbuild`), then:
@@ -505,7 +507,7 @@ ble_uart_install(&(ble_uart_config_t){
});
```
Edit the default through `menuconfig → Component configuration → BLE UART
Edit the default through `menuconfig → Component configuration → ESP-BLE-UART
library → BLE device name prefix`.
### 6.5 Pushing data proactively

View File

@@ -3,7 +3,7 @@
*
* SPDX-License-Identifier: Unlicense OR CC0-1.0
*
* BLE UART — turnkey serial-over-BLE peripheral.
* ESP-BLE-UART — turnkey serial-over-BLE peripheral.
*
* Implements the de-facto BLE UART-over-GATT layout (RX write, TX notify;
* fixed 128-bit UUIDs below) on top of either NimBLE or Bluedroid; the
@@ -101,7 +101,7 @@ int ble_uart_install(const ble_uart_config_t *cfg);
* Bluedroid: triggers adv-data + scan-response config; advertising
* begins once the stack acknowledges both.
*
* Returns immediately; the BLE UART then runs autonomously
* Returns immediately; the ESP-BLE-UART then runs autonomously
* (connect, pairing, passkey display, RX delivery all via internal
* callbacks). Single-shot. */
int ble_uart_open(void);

View File

@@ -3,7 +3,7 @@
*
* SPDX-License-Identifier: Unlicense OR CC0-1.0
*
* BLE UART — Bluedroid backend. Implements the lifecycle declared in
* ESP-BLE-UART — Bluedroid backend. Implements the lifecycle declared in
* ble_uart.h on top of the Bluedroid host using the service-table API
* (esp_ble_gatts_create_attr_tab). Active when
* CONFIG_BT_BLUEDROID_ENABLED=y; otherwise ble_uart_nimble.c is used.

View File

@@ -3,7 +3,7 @@
*
* SPDX-License-Identifier: Unlicense OR CC0-1.0
*
* BLE UART — NimBLE backend. Implements the lifecycle declared in
* ESP-BLE-UART — NimBLE backend. Implements the lifecycle declared in
* ble_uart.h on top of the NimBLE host. Active when
* CONFIG_BT_NIMBLE_ENABLED=y; otherwise ble_uart_bluedroid.c is used.
*/
@@ -80,7 +80,7 @@ static const ble_uuid128_t s_chr_tx_uuid = BLE_UUID128_INIT(NUS_TX_BYTES);
/* ===== State =========================================================== */
/* RX scratch capacity. Tunable via menuconfig (Component config → BLE UART
/* RX scratch capacity. Tunable via menuconfig (Component config → ESP-BLE-UART
* library); fall
* back to 1024 if CONFIG_BLE_UART_RX_SCRATCH_SIZE is absent. */
#ifndef CONFIG_BLE_UART_RX_SCRATCH_SIZE