mirror of
https://github.com/espressif/esp-idf.git
synced 2026-09-22 13:01:16 +03:00
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:
@@ -1,4 +1,4 @@
|
||||
menu "BLE UART library"
|
||||
menu "ESP-BLE-UART library"
|
||||
|
||||
config BLE_UART_DEVICE_NAME_PREFIX
|
||||
string "BLE device name prefix"
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user