wehub-resource-sync
1475 lines
64 KiB
Markdown
1475 lines
64 KiB
Markdown
# 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).
|
||
|
||
**Reference application:** use the **`examples/bluetooth/ble_uart_service`**
|
||
example as the working template. Its root `CMakeLists.txt` appends this
|
||
directory to **`EXTRA_COMPONENT_DIRS`** so `main` can `REQUIRES ble_uart`;
|
||
`main/main.c` initializes NVS, calls `ble_uart_install()` /
|
||
`ble_uart_open()` with the Kconfig-supplied GAP name and the default
|
||
encrypted UART-over-BLE echo path, and the tree ships
|
||
`sdkconfig.defaults` plus the Bluedroid overlay
|
||
(`sdkconfig.bluedroid`). Clone or diff that project when adapting to a new
|
||
target or host stack.
|
||
|
||
A complete guide to integrating `ble_uart` into any ESP-IDF project.
|
||
**Either** `EXTRA_COMPONENT_DIRS` pointing at this component **or** a few
|
||
copied source files **plus** the glue steps below are enough to bring an
|
||
encrypted BLE serial peripheral up in a fresh project — the same
|
||
`ble_uart.h` API works on top of either NimBLE or Bluedroid; pick the
|
||
host with a Kconfig knob.
|
||
|
||
This guide uses **NimBLE** as the running example because it is the
|
||
default on every ESP32 family target. The Bluedroid path is identical
|
||
from the application's point of view; the only differences are the
|
||
sdkconfig knobs called out in §4.3 and a few stack-specific notes
|
||
flagged inline.
|
||
|
||
---
|
||
|
||
## 1. What `ble_uart` Provides
|
||
|
||
| Capability | Description |
|
||
| --- | --- |
|
||
| Widely used BLE UART-over-GATT (RX/TX) | Interoperates with every generic BLE-serial tool (mobile GATT clients, Web Bluetooth, custom scripts) |
|
||
| LE Secure Connections + Bonding pairing | Single switch; when enabled, a fresh 6-digit passkey is printed to UART |
|
||
| Auto-reconnect | After a bonded central disconnects, advertising restarts immediately and the LTK is reused — no passkey prompt |
|
||
| Raw byte pass-through | RX is delivered via a callback; TX is exposed as `ble_uart_tx` |
|
||
| Auto-fragmentation | TX is sliced according to the negotiated ATT MTU |
|
||
| Fully wrapped | The user's `app_main` only calls two functions: `install` + `open` |
|
||
|
||
`ble_uart` is agnostic of any application-layer protocol (no JSON, no
|
||
line framing). It only delivers bytes — **what you do with those bytes
|
||
is entirely up to you**.
|
||
|
||
---
|
||
|
||
## 2. Prerequisites
|
||
|
||
| Requirement | Notes |
|
||
| --- | --- |
|
||
| ESP-IDF v5.0+ | v5.x or v6.x recommended |
|
||
| BT controller | Must support BLE (ESP32 / C2 / C3 / C5 / C6 / C61 / H2 / S3 / …) |
|
||
| Host stack | Exactly one of `CONFIG_BT_NIMBLE_ENABLED=y` (default, smaller) or `CONFIG_BT_BLUEDROID_ENABLED=y` in sdkconfig (covered in detail below) |
|
||
| Flash size | At least 2 MB (the default partition table is plenty) |
|
||
|
||
---
|
||
|
||
## 3. File Inventory
|
||
|
||
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` (device name + RX scratch;
|
||
`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.
|
||
|
||
**Option A — depend on the in-tree component (no copy):** add the component
|
||
directory to **`EXTRA_COMPONENT_DIRS` in the project root `CMakeLists.txt`
|
||
before `include($ENV{IDF_PATH}/tools/cmake/project.cmake)` / `project()`**,
|
||
then use `REQUIRES ble_uart` from `main/CMakeLists.txt` (see
|
||
`examples/bluetooth/ble_uart_service/CMakeLists.txt`). This ensures the
|
||
`ble_uart` target exists when CMake expands `main`'s requirements.
|
||
|
||
Kconfig options appear under
|
||
`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
|
||
> runs before the component manager injects that dependency, so CMake fails
|
||
> with *unknown component `ble_uart`*. Prefer `EXTRA_COMPONENT_DIRS` (as in the
|
||
> reference example) or copy the sources into a normal project component.
|
||
|
||
**Option B — copy into your project:** pick the backend you want and
|
||
copy that pair plus the public header (or copy both backends; each `.c`
|
||
gates on its Kconfig symbol):
|
||
|
||
```
|
||
your_project/main/
|
||
├── ble_uart.h ← copy from .../common/ble_uart/
|
||
├── ble_uart_nimble.c ← if you'll set CONFIG_BT_NIMBLE_ENABLED=y
|
||
└── ble_uart_bluedroid.c ← if you'll set CONFIG_BT_BLUEDROID_ENABLED=y
|
||
```
|
||
|
||
Optional: copy `Kconfig` from `common/ble_uart/` into your component (or merge
|
||
its symbols into your own `Kconfig`) if you want `BLE_UART_*` in `menuconfig`;
|
||
otherwise hard-code the device name and rely on the 1024-byte fallback for RX
|
||
scratch.
|
||
|
||
---
|
||
|
||
## 4. Step-by-Step Integration
|
||
|
||
Assume you already have an ESP-IDF project (`my_project/`).
|
||
|
||
### 4.1 Copy the files
|
||
|
||
```bash
|
||
cd my_project/main
|
||
BLE_UART_SRC="$IDF_PATH/examples/bluetooth/common/ble_uart"
|
||
# Stack-agnostic public header — always.
|
||
cp "$BLE_UART_SRC/ble_uart.h" .
|
||
# Pick one (or copy both — the inactive one compiles to nothing).
|
||
cp "$BLE_UART_SRC/ble_uart_nimble.c" .
|
||
cp "$BLE_UART_SRC/ble_uart_bluedroid.c" .
|
||
```
|
||
|
||
### 4.2 Edit `main/CMakeLists.txt`
|
||
|
||
```cmake
|
||
# List both backends; each .c file is gated on its matching Kconfig
|
||
# symbol, so only the active one contributes code.
|
||
idf_component_register(SRCS "main.c"
|
||
"ble_uart_nimble.c"
|
||
"ble_uart_bluedroid.c"
|
||
INCLUDE_DIRS "."
|
||
REQUIRES bt nvs_flash)
|
||
```
|
||
|
||
### 4.3 Edit `sdkconfig.defaults` (the 7 critical lines)
|
||
|
||
**NimBLE backend (default, smaller footprint):**
|
||
|
||
```ini
|
||
# Enable NimBLE
|
||
CONFIG_BT_ENABLED=y
|
||
CONFIG_BTDM_CTRL_MODE_BLE_ONLY=y # only needed on classic ESP32; C3/S3/C6/... will warn "unknown" — safe to ignore
|
||
CONFIG_BT_BLUEDROID_ENABLED=n
|
||
CONFIG_BT_NIMBLE_ENABLED=y
|
||
|
||
# Encryption + persistent bonds
|
||
CONFIG_BT_NIMBLE_SM_SC=y # LE Secure Connections
|
||
CONFIG_BT_NIMBLE_NVS_PERSIST=y # persist LTKs in NVS — passkey-free reconnects
|
||
```
|
||
|
||
`CONFIG_BT_NIMBLE_ATT_PREFERRED_MTU` is optional; the default (256) is
|
||
fine. Bumping it to 512 lets TX push larger chunks per notification, but
|
||
the central must support it.
|
||
|
||
**Bluedroid backend (drop-in alternative):**
|
||
|
||
Use the **`examples/bluetooth/ble_uart_service/sdkconfig.bluedroid`** file as
|
||
the authoritative Kconfig overlay: it enables the host stack, SMP, GATTS
|
||
(service-table API), and the BLE-only advertising knobs that
|
||
`ble_uart_bluedroid.c` expects. Either merge those lines into your own
|
||
`sdkconfig.defaults`, or pass them as a second defaults file:
|
||
|
||
```bash
|
||
idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.bluedroid" reconfigure
|
||
```
|
||
|
||
(Paths are relative to the example project root; copy `sdkconfig.bluedroid`
|
||
into your tree if you are not starting from `ble_uart_service`.)
|
||
|
||
A minimal inline sketch (may drift from IDF defaults — **diff against
|
||
`sdkconfig.bluedroid` after each IDF upgrade**):
|
||
|
||
```ini
|
||
CONFIG_BT_ENABLED=y
|
||
CONFIG_BT_NIMBLE_ENABLED=n
|
||
CONFIG_BT_BLUEDROID_ENABLED=y
|
||
|
||
# LE Secure Connections + bonding (Bluedroid persists LTKs by default)
|
||
CONFIG_BT_BLE_SMP_ENABLE=y
|
||
|
||
# Optional: bigger MTU (when supported by your IDF target / menuconfig)
|
||
# CONFIG_BT_GATT_MAX_MTU_SIZE=512
|
||
|
||
# BLE-only feature set (saves flash on classic-BT-capable parts)
|
||
CONFIG_BT_BLE_42_FEATURES_SUPPORTED=y
|
||
CONFIG_BT_BLE_42_ADV_EN=y
|
||
```
|
||
|
||
### 4.4 Write `app_main` (template)
|
||
|
||
Minimal working template:
|
||
|
||
```c
|
||
#include "esp_log.h"
|
||
#include "esp_mac.h"
|
||
#include "nvs_flash.h"
|
||
|
||
#include "ble_uart.h"
|
||
|
||
static const char *TAG = "app";
|
||
|
||
/* What to do with received bytes — up to you */
|
||
static void ble_uart_on_rx(const uint8_t *data, size_t len)
|
||
{
|
||
ESP_LOGI(TAG, "rx %u bytes", (unsigned)len);
|
||
/* echo it back as a demo */
|
||
ble_uart_tx(data, len);
|
||
}
|
||
|
||
void app_main(void)
|
||
{
|
||
/* 1. NVS: NimBLE uses it for PHY calibration and bond storage */
|
||
esp_err_t err = nvs_flash_init();
|
||
if (err == ESP_ERR_NVS_NO_FREE_PAGES || err == ESP_ERR_NVS_NEW_VERSION_FOUND) {
|
||
ESP_ERROR_CHECK(nvs_flash_erase());
|
||
err = nvs_flash_init();
|
||
}
|
||
ESP_ERROR_CHECK(err);
|
||
|
||
/* 2. Bring up ESP-BLE-UART */
|
||
ESP_ERROR_CHECK(ble_uart_install(&(ble_uart_config_t){
|
||
.encrypted = true,
|
||
.device_name = "MyDevice",
|
||
.ble_uart_on_rx = ble_uart_on_rx,
|
||
}));
|
||
|
||
/* 3. Take off */
|
||
ESP_ERROR_CHECK(ble_uart_open());
|
||
}
|
||
```
|
||
|
||
### 4.5 Build & flash
|
||
|
||
```bash
|
||
idf.py set-target esp32s3 # or whichever target you use
|
||
idf.py build flash monitor
|
||
```
|
||
|
||
Once flashed, the UART monitor should show (NimBLE backend):
|
||
|
||
```
|
||
I (xxx) ble_uart: registered service 6e400001-... handle=14
|
||
I (xxx) ble_uart: registered chr 6e400002-... def=15 val=16
|
||
I (xxx) ble_uart: registered chr 6e400003-... def=17 val=18
|
||
I (xxx) ble_uart: addr=...
|
||
I (xxx) ble_uart: BLE host task started
|
||
I (xxx) ble_uart: advertising as 'MyDevice'
|
||
```
|
||
|
||
…or with the Bluedroid backend:
|
||
|
||
```
|
||
I (xxx) ble_uart: gatts reg status=0 app_id=85 gatts_if=3
|
||
I (xxx) ble_uart: registered service svc_handle=40 rx=42 tx=44 cccd=45
|
||
I (xxx) ble_uart: advertising started
|
||
```
|
||
|
||
A phone GATT client app discovers `MyDevice`; connect, enter the
|
||
passkey, subscribe to TX, write to RX, and you will see the echo come
|
||
back.
|
||
|
||
---
|
||
|
||
## 5. API Reference
|
||
|
||
### 5.1 Configuration struct
|
||
|
||
```c
|
||
typedef struct {
|
||
bool encrypted; /* Preset shortcut for SC + Bonding + MITM */
|
||
ble_uart_security_t security; /* Per-feature overrides — see §5.6 */
|
||
|
||
const char *device_name; /* GAP service device name (UUID 0x2A00) */
|
||
|
||
/* Custom advertising bytes — see §5.9. NULL keeps the default
|
||
* payload. ble_uart prepends the 3-byte Flags AD itself; you don't. */
|
||
const uint8_t *adv_data;
|
||
size_t adv_data_len; /* ≤ BLE_UART_ADV_DATA_MAX (28) */
|
||
const uint8_t *scan_rsp_data;
|
||
size_t scan_rsp_data_len;/* ≤ BLE_UART_SCAN_RSP_DATA_MAX (31) */
|
||
|
||
ble_uart_rx_cb_t ble_uart_on_rx;/* RX byte callback */
|
||
ble_uart_evt_cb_t on_event; /* Lifecycle / link-state events */
|
||
} ble_uart_config_t;
|
||
```
|
||
|
||
| Field | Type | Required | Default / meaning |
|
||
| --- | --- | --- | --- |
|
||
| `encrypted` | `bool` | yes | One-line preset for the override fields under `security`: `true` = SC + Bonding + MITM + DisplayOnly + encrypted+authenticated GATT chars; `false` = fully plaintext (sniffable, lab use only). Override individual bits via `security.*` — see §5.6. |
|
||
| `security` | `ble_uart_security_t` | optional | A zero-initialised member (`security.{sc,bonding,mitm,io_cap} = AUTO`) inherits everything from `encrypted`. Set any sub-field to `OFF`/`ON` (or pick a specific `io_cap`) to override just that bit. Out-of-range enum values, or impossible combos like `mitm=ON` with `io_cap=NO_INPUT_OUTPUT`, fail `ble_uart_install()` with `BLE_UART_EINVAL`. Full reference in §5.6. |
|
||
| `device_name` | `const char *` | recommended | Set as the GAP-service Device Name (UUID 0x2A00). With the **default** advertising payload it is also placed in the primary adv as the Complete Local Name; with custom `adv_data` (see §5.9) it is **not** auto-included — the application owns the adv bytes. Length must be ≤ **`BLE_UART_DEVICE_NAME_MAX` = 26** (sized so the default Flags + Name AD layout always fits in a 31-byte primary packet). Longer names fail `ble_uart_install()` synchronously with `BLE_UART_EINVAL`. |
|
||
| `adv_data` / `adv_data_len` | bytes + length | optional | Application-controlled raw advertisement data. NULL keeps the built-in default (Complete Local Name only). Max length **`BLE_UART_ADV_DATA_MAX` = 28** (the 31-byte primary packet minus our 3-byte Flags AD). Buffer is copied in `install`; the pointer doesn't need to outlive the call. See §5.9. |
|
||
| `scan_rsp_data` / `scan_rsp_data_len` | bytes + length | optional | Application-controlled raw scan-response data. NULL keeps the built-in default (128-bit BLE UART service UUID). Max length **`BLE_UART_SCAN_RSP_DATA_MAX` = 31** (no Flags element here). Same copy semantics as `adv_data`. |
|
||
| `ble_uart_on_rx` | callback | optional | `NULL` discards every received byte |
|
||
| `on_event` | callback | optional | `NULL` drops every event (see §5.2.1). **Not required** for the default preset (`encrypted=true`, all `security.*` AUTO → Passkey Display): the port logs the 6-digit passkey to UART and completes pairing without a callback. **Required** when `io_cap` is `KEYBOARD_ONLY`, `DISPLAY_YES_NO`, or `KEYBOARD_DISPLAY` — otherwise `ble_uart_install()` returns `BLE_UART_EINVAL`. |
|
||
|
||
### 5.2 RX callback signature
|
||
|
||
```c
|
||
typedef void (*ble_uart_rx_cb_t)(const uint8_t *data, size_t len);
|
||
|
||
static void my_handler(const uint8_t *data, size_t len)
|
||
{
|
||
/* `data` is reused after the callback returns; memcpy into your own
|
||
* buffer if you need to keep it. */
|
||
}
|
||
```
|
||
|
||
**Caveats**:
|
||
|
||
- The callback runs on the BLE host task (NimBLE host task /
|
||
Bluedroid BTC task) — **do not block**; offload heavy work to your
|
||
own task.
|
||
- A single callback may carry only **part** of an upper-layer frame
|
||
(the central slices on ATT MTU). Framing logic (line / TLV /
|
||
length-prefixed) is your responsibility.
|
||
- The data carries **no `ctx` argument**. If your callback needs state,
|
||
use a file-scope `static` or a global.
|
||
|
||
### 5.2.1 Event callback
|
||
|
||
```c
|
||
typedef void (*ble_uart_evt_cb_t)(const ble_uart_evt_t *evt);
|
||
|
||
static void on_event(const ble_uart_evt_t *e)
|
||
{
|
||
switch (e->id) {
|
||
case BLE_UART_EVT_CONNECTED: /* link up */ break;
|
||
case BLE_UART_EVT_DISCONNECTED: /* e->disconnected.reason */ break;
|
||
case BLE_UART_EVT_SUBSCRIBED: /* e->subscribed.subscribed */ break;
|
||
case BLE_UART_EVT_LINK_SECURE:
|
||
if (e->link_secure.encrypted && e->link_secure.authenticated) {
|
||
/* Safe to forward sensitive payloads now */
|
||
}
|
||
break;
|
||
case BLE_UART_EVT_PASSKEY_DISPLAY: /* e->passkey.passkey */ break;
|
||
case BLE_UART_EVT_PASSKEY_REQUEST: /* user types peer's 6-digit;
|
||
ble_uart_passkey_reply(d) */ break;
|
||
case BLE_UART_EVT_NUMERIC_COMPARE: /* e->numeric_compare.passkey,
|
||
ble_uart_compare_reply(b) */ break;
|
||
case BLE_UART_EVT_PAIRING_FAILED: /* e->pairing_failed.reason */ break;
|
||
}
|
||
}
|
||
```
|
||
|
||
| `evt->id` | Payload (anonymous-union member) | Fires when |
|
||
| --- | --- | --- |
|
||
| `BLE_UART_EVT_CONNECTED` | — | Physical link up |
|
||
| `BLE_UART_EVT_DISCONNECTED` | `disconnected.reason` (int, stack-specific) | Physical link down — Bluedroid: `esp_gatt_conn_reason_t`; NimBLE: BLE host return code (`BLE_HS_HCI_ERR()` for HCI) |
|
||
| `BLE_UART_EVT_SUBSCRIBED` | `subscribed.subscribed` | CCCD on TX changed (edge-triggered) |
|
||
| `BLE_UART_EVT_LINK_SECURE` | `link_secure.{encrypted,authenticated,bonded,key_size}` | Pairing or bonded reconnect succeeds |
|
||
| `BLE_UART_EVT_PASSKEY_DISPLAY` | `passkey.passkey` (0..999999) | SM generated a passkey for the central to type (Passkey Display). **Optional** — the port always prints a banner to UART; with `on_event == NULL` the event is dropped and pairing still completes (NimBLE injects the passkey internally; Bluedroid needs no app reply). Register `on_event` only if you want a custom UI in addition to the log line. |
|
||
| `BLE_UART_EVT_PASSKEY_REQUEST` | — | SM asks the user to enter a passkey shown by the central — application **must** reply via `ble_uart_passkey_reply()` (see §5.6.1). Requires `on_event != NULL` at install time. |
|
||
| `BLE_UART_EVT_NUMERIC_COMPARE` | `numeric_compare.passkey` (0..999999) | SM asks the user to confirm the displayed value matches the central — application **must** reply via `ble_uart_compare_reply()` (see §5.6.1). Requires `on_event != NULL` at install time. |
|
||
| `BLE_UART_EVT_PAIRING_FAILED` | `pairing_failed.reason` | Pairing rejected or timed out (including no application reply for `PASSKEY_REQUEST` / `NUMERIC_COMPARE` before the SM's pairing timeout) |
|
||
| `BLE_UART_EVT_CLOSED` | `closed.status` (`BLE_UART_*` from the worker's `ble_uart_close()`) | `ble_uart_close_async()` worker finished — then `uninstall` on an app task (§5.3.2) |
|
||
|
||
**Use `LINK_SECURE`, not `is_connected()`, to gate any logic that
|
||
requires the link to be encrypted / authenticated** — bare
|
||
`is_connected()` returns `true` while the link is still plaintext, and
|
||
inferring security from `encrypted` / `authenticated` separately on the
|
||
caller side is exactly the kind of leak the callback is designed to
|
||
plug.
|
||
|
||
**Threading**: same context and rules as `ble_uart_on_rx` (NimBLE host
|
||
task / Bluedroid BTC task). Don't block, don't call `ble_uart_close` /
|
||
`ble_uart_uninstall` from inside the callback — use
|
||
`ble_uart_close_async()` (§5.3.2) if you need to teardown in response
|
||
to an event.
|
||
|
||
**Exception — `BLE_UART_EVT_CLOSED`**: this single event fires from
|
||
the close-async worker task instead of the BLE host task; by the time
|
||
it runs the host task is already gone. Keep the handler short: set a
|
||
flag or notify an app task — do **not** call `ble_uart_uninstall()`
|
||
here (see §5.3.2). The worker clears `s_closing` only after your
|
||
handler returns.
|
||
|
||
**Ordering contracts (both backends)**:
|
||
|
||
- A single CCCD value change fires exactly one `SUBSCRIBED` event
|
||
(edge-triggered — repeating the same write is a no-op).
|
||
- If the central was subscribed at the moment the link drops, you get
|
||
`SUBSCRIBED(false)` **before** `DISCONNECTED`. NimBLE does this
|
||
natively (`BLE_GAP_SUBSCRIBE_REASON_TERM`); the Bluedroid backend
|
||
synthesizes the same sequence so consumers can write a single state
|
||
machine that works on either host.
|
||
- `LINK_SECURE` always arrives after `CONNECTED` — pairing can't run
|
||
without a link.
|
||
- `BLE_UART_EVT_CLOSED` always arrives **after**
|
||
`BLE_UART_EVT_DISCONNECTED` (when there was a peer) — the
|
||
close-async worker calls the same disconnect+wait sequence as the
|
||
synchronous `ble_uart_close()` before firing CLOSED.
|
||
|
||
**Backend differences**:
|
||
|
||
- `BLE_UART_EVT_LINK_SECURE.key_size`: NimBLE reports the negotiated
|
||
size (7..16); Bluedroid surfaces a fixed 16 — Bluedroid sets
|
||
`ESP_BLE_SM_MAX_KEY_SIZE=16` at install time and does not expose the
|
||
negotiated size on `AUTH_CMPL`.
|
||
- Bonded reconnects: NimBLE re-fires `LINK_SECURE` on every encryption
|
||
change; Bluedroid only fires `AUTH_CMPL_EVT` when the SM exchange
|
||
actually runs, so a pure LTK-restart may not refire the event.
|
||
- CCCD persistence on bonded reconnect: NimBLE re-fires
|
||
`SUBSCRIBED(true)` automatically (via `BLE_GAP_SUBSCRIBE_REASON_RESTORE`)
|
||
when the bonded peer reconnects; Bluedroid does not persist CCCD
|
||
across connections, so the central has to write CCCD again to
|
||
resubscribe.
|
||
|
||
### 5.3 Lifecycle — bring-up and release
|
||
|
||
#### API summary
|
||
|
||
```c
|
||
int ble_uart_install(const ble_uart_config_t *cfg);
|
||
int ble_uart_open(void);
|
||
int ble_uart_close(void);
|
||
int ble_uart_close_async(void); /* fire-and-forget, see §5.3.2–5.3.4 */
|
||
int ble_uart_uninstall(void);
|
||
```
|
||
|
||
| Function | What it does (NimBLE) | What it does (Bluedroid) | When to call | Blocking? |
|
||
| --- | --- | --- | --- | --- |
|
||
| `install` | `nimble_port_init` + `ble_hs_cfg` + SM + SIG services + UART GATT | `controller_init/enable` + `bluedroid_init/enable` + SM + `esp_ble_gatts_create_attr_tab` (waits ≤500 ms for the attr-table event) | After `nvs_flash_init()`, before `open` | No, ~50 ms (NimBLE) / ~150 ms (Bluedroid) |
|
||
| `open` | Spawn host task + `ble_hs_start` (first time via `BLE_HS_AUTO_START`, later via `ble_hs_sched_start`) + advertising once synced; after a prior `close`, re-queues GAP/GATT/UART svc defs (§5.3.1a) | Configure adv data + scan rsp + start advertising (GATT table from `install` stays up) | After `install` | No, host runs in the background |
|
||
| `close` | Stop adv → graceful disconnect (≤500 ms) → `nimble_port_stop()` → `ble_gatts_reset()` | Stop adv → graceful disconnect (≤500 ms); host + GATT table stay up | After `open`, before `uninstall`; **not** from host-task callbacks (§5.3.2) | Yes, up to ~500 ms (NimBLE) |
|
||
| `close_async` | Worker runs the same body as `close`, then `BLE_UART_EVT_CLOSED` | Same | From `on_event` / `on_rx` (host task) when sync `close` would deadlock | No (returns once worker is spawned) |
|
||
| `uninstall` | `close` if still open (+ poll in-flight `close_async` ≤~5 s), then `nimble_port_deinit`, wipe module state | Same + controller deinit | After the radio is fully closed (§5.3.2); **not** from host-task callbacks | Yes |
|
||
|
||
**Bring-up** (every product):
|
||
|
||
```text
|
||
nvs_flash_init()
|
||
└── ble_uart_install(&cfg) /* once per uninstall cycle */
|
||
└── ble_uart_open() /* advertising + pairing; BLE is live */
|
||
```
|
||
|
||
Run-forever firmware can stop here — no `close` / `uninstall` required.
|
||
|
||
**Release** — pick **one** path below. `close` stops the radio but keeps
|
||
`install` state (you can `open()` again). `uninstall` tears the host +
|
||
controller down so `install()` can run from scratch.
|
||
|
||
| Goal | Call sequence | Who calls `close` / `uninstall` |
|
||
| --- | --- | --- |
|
||
| Power BLE off from a **normal app task** (button, Wi-Fi, `app_main` shutdown) | `ble_uart_close()` → `ble_uart_uninstall()` | That app task only |
|
||
| Power BLE off **because of a BLE event** (RX command, failed pairing, policy) | `ble_uart_close_async()` in `on_event` / `on_rx` → wait for `BLE_UART_EVT_CLOSED` → `ble_uart_uninstall()` on an **app task** (§5.3.2) | `close_async` in callback; `uninstall` deferred |
|
||
|
||
Each API returns `BLE_UART_EALREADY` when the module is already in the
|
||
target state, so defensive `close` / `uninstall` at shutdown without
|
||
manual state checks is fine **as long as** you follow the release path
|
||
for your scenario.
|
||
|
||
#### 5.3.1 Path A — synchronous release (recommended default)
|
||
|
||
Use when teardown is **not** triggered from inside `on_event` /
|
||
`on_rx` (NimBLE host task / Bluedroid BTC task). This is what the
|
||
`ble_uart_service` example does.
|
||
|
||
```c
|
||
void shutdown_ble_from_app_task(void)
|
||
{
|
||
int rc;
|
||
|
||
rc = ble_uart_close();
|
||
if (rc != BLE_UART_OK && rc != BLE_UART_EALREADY) {
|
||
ESP_LOGE(TAG, "ble_uart_close rc=%d", rc);
|
||
}
|
||
|
||
rc = ble_uart_uninstall();
|
||
if (rc != BLE_UART_OK && rc != BLE_UART_EALREADY) {
|
||
ESP_LOGE(TAG, "ble_uart_uninstall rc=%d", rc);
|
||
}
|
||
/* BLE UART fully released — safe to ble_uart_install() again */
|
||
}
|
||
```
|
||
|
||
```text
|
||
ble_uart_open() /* running */
|
||
│
|
||
▼
|
||
ble_uart_close() /* same app task; not from on_event / on_rx */
|
||
│
|
||
▼
|
||
ble_uart_uninstall()
|
||
```
|
||
|
||
- `uninstall` may call `close` internally if you skipped `close` — still
|
||
call both explicitly so return codes are obvious in your logs.
|
||
- Do **not** call `close` or `uninstall` from `on_event` / `on_rx` — use
|
||
Path B instead.
|
||
|
||
#### 5.3.1a Pausing and resuming (`close` then `open` again)
|
||
|
||
`install` state is preserved across `close()` — you may call `open()`
|
||
again without `uninstall()`. This is what the `ble_uart_service` example
|
||
exercises in `app_main` (open → close → open) to prove the cycle.
|
||
|
||
**NimBLE backend**
|
||
|
||
| Topic | Behaviour |
|
||
| --- | --- |
|
||
| GATT services | Same set as after `install`: GAP (`0x1800`), GATT (`0x1801`), BLE UART (NUS). `close()` calls the public `ble_gatts_reset()`; the next `open()` re-runs `ble_svc_gap_init()`, `ble_svc_gatt_init()`, and re-adds the UART service. |
|
||
| ATT handles | **Not stable** — centrals must run a full service discovery after each reconnect; do not cache handles across a `close`/`open` cycle. |
|
||
| Subscriptions | Cleared — the central must re-enable TX notifications (CCCD). |
|
||
| Bonds | NVS bond store is unchanged (still configured at `install()`). |
|
||
| First vs later `open` | With default `BLE_HS_AUTO_START`, the first `open()` consumes the one-shot auto-start queued by `nimble_port_init()`; every later `open()` must call `ble_hs_sched_start()` (handled inside `ble_uart_open()`). |
|
||
|
||
**Bluedroid backend**
|
||
|
||
`close()` only stops advertising and disconnects; the host and attribute
|
||
table created at `install()` stay registered. A second `open()` restarts
|
||
advertising. GATT handles are typically unchanged.
|
||
|
||
**Extra GATT services (§6.3)**
|
||
|
||
Services you register with `ble_gatts_add_svcs()` / `ble_svc_*_init()`
|
||
at `install()` time are **not** automatically re-registered by
|
||
`ble_uart` on a later `open()` after `close()` (NimBLE only re-adds
|
||
GAP, GATT, and UART). Either call your init/add functions again inside
|
||
your own `open()` hook after `ble_uart_close()`, or use
|
||
`close()` → `uninstall()` → `install()` → `open()` for a full rebuild.
|
||
|
||
#### 5.3.2 Path B — release after a BLE event (`close_async`)
|
||
|
||
Use when the **reason** to shut down arrives on the host task (e.g.
|
||
`BLE_UART_EVT_PAIRING_FAILED`, an RX “power off” byte, or
|
||
`LINK_SECURE` policy). Synchronous `close()` deadlocks there; use
|
||
`close_async()` and **defer** `uninstall()` to a normal task.
|
||
|
||
```c
|
||
static volatile bool s_ble_closed_ok;
|
||
|
||
static void on_event(const ble_uart_evt_t *e)
|
||
{
|
||
switch (e->id) {
|
||
case BLE_UART_EVT_PAIRING_FAILED:
|
||
ble_uart_close_async(); /* OK: host-task context */
|
||
break;
|
||
|
||
case BLE_UART_EVT_CLOSED:
|
||
/* Runs on the close-async worker — keep this short. Do NOT call
|
||
* ble_uart_uninstall() here (s_closing is still set; see §5.3.3). */
|
||
if (e->closed.status == BLE_UART_OK) {
|
||
s_ble_closed_ok = true; /* or xTaskNotifyGive / queue */
|
||
}
|
||
break;
|
||
default:
|
||
break;
|
||
}
|
||
}
|
||
|
||
void ble_shutdown_task(void *arg)
|
||
{
|
||
(void)arg;
|
||
for (;;) {
|
||
if (s_ble_closed_ok) {
|
||
s_ble_closed_ok = false;
|
||
ble_uart_uninstall(); /* normal app task */
|
||
break;
|
||
}
|
||
vTaskDelay(pdMS_TO_TICKS(50));
|
||
}
|
||
vTaskDelete(NULL);
|
||
}
|
||
```
|
||
|
||
```text
|
||
on_event / on_rx (host task):
|
||
ble_uart_close_async()
|
||
│
|
||
▼
|
||
[worker: do_close ≈ sync close]
|
||
│
|
||
├── BLE_UART_EVT_DISCONNECTED (if peer was connected)
|
||
└── BLE_UART_EVT_CLOSED (worker task; set flag only)
|
||
│
|
||
▼
|
||
app task (not host, not inside CLOSED handler):
|
||
ble_uart_uninstall()
|
||
```
|
||
|
||
- `close_async` returns `BLE_UART_OK` once the worker is **spawned**, not
|
||
when close finishes.
|
||
- Only `BLE_UART_EVT_CLOSED` with `.closed.status == BLE_UART_OK` means
|
||
the same quiesced state as `ble_uart_close()` — then it is safe to
|
||
`uninstall()` from your app task.
|
||
- On failure (`BLE_UART_EFAIL`, etc.) the port may still be open; retry
|
||
`ble_uart_close()` / `ble_uart_close_async()` from an app task.
|
||
|
||
#### 5.3.3 `close_async` + `uninstall` — rules and pitfalls
|
||
|
||
`ble_uart_uninstall()` **polls** an in-flight `close_async` worker for
|
||
up to **~5 s**. If the worker has not exited it logs
|
||
`uninstall: close_async worker still running, tearing down anyway` and
|
||
continues anyway — treat that as an application bug, not a supported
|
||
path.
|
||
|
||
| Do | Don't |
|
||
| --- | --- |
|
||
| `close_async()` in `on_event` / `on_rx`; `uninstall()` later on **one** app task after `CLOSED` + `BLE_UART_OK` | `uninstall()` in the same task right after `close_async()` without waiting |
|
||
| Set a flag / queue in `BLE_UART_EVT_CLOSED`; return immediately | `ble_uart_uninstall()` **inside** `BLE_UART_EVT_CLOSED` (worker still holds `s_closing`) |
|
||
| Sync `close` + `uninstall` from a button / network task | `close` / `uninstall` from host-task callbacks |
|
||
| Keep `on_event` / `on_rx` short while a close is in flight | Multi-second blocking in callbacks during `close_async` |
|
||
| After a timeout log, fix ordering before `install()` again | Immediate `install()` + `open()` + `close_async()` after a wedged teardown |
|
||
|
||
If you see `uninstall: close_async worker still running, tearing down
|
||
anyway`, fix call ordering (§5.3.2) before calling `install()` again.
|
||
|
||
#### 5.3.4 `ble_uart_close_async()` — reference
|
||
|
||
Some applications need to teardown the radio in response to a BLE
|
||
event — examples: a "shutdown" command on RX, a `LINK_SECURE` whose
|
||
flags don't meet the application's policy, or a `PAIRING_FAILED` from
|
||
a peer that's been blacklisted. Because the synchronous `close()` is
|
||
called *from* the host task it would normally run on, calling it
|
||
inline would deadlock. `close_async()` papers over that: it spawns a
|
||
small worker task (~3 KB stack, idle+2 priority) that runs the same
|
||
close body, then signals completion via the event callback.
|
||
|
||
**Behaviour** (see §5.3.2 for the full release flow):
|
||
|
||
- `close_async` returns `BLE_UART_OK` once the worker has been spawned.
|
||
- `BLE_UART_EVT_DISCONNECTED` (if connected) then `BLE_UART_EVT_CLOSED`
|
||
with `.closed.status` — same ≤500 ms disconnect window as sync `close`.
|
||
- Second call while draining → `BLE_UART_EALREADY`; before `open` →
|
||
`BLE_UART_EALREADY`; spawn failure → `BLE_UART_ENOMEM` (latch reset).
|
||
|
||
### 5.4 TX interface
|
||
|
||
```c
|
||
int ble_uart_tx(const uint8_t *data, size_t len);
|
||
```
|
||
|
||
For formatted output, format into your own buffer with `snprintf` first
|
||
and pass it to `ble_uart_tx`:
|
||
|
||
```c
|
||
char line[64];
|
||
int n = snprintf(line, sizeof(line), "temp=%d.%d\n", t / 10, t % 10);
|
||
ble_uart_tx((const uint8_t *)line, (size_t)n);
|
||
```
|
||
|
||
**Return values**:
|
||
|
||
| Return | Meaning |
|
||
| --- | --- |
|
||
| `BLE_UART_OK` | Success (notification handed to the stack) |
|
||
| `BLE_UART_ENOTCONN` | No central connected; **this is normal — typically ignore** |
|
||
| `BLE_UART_EINVAL` | `data == NULL` or `len == 0` |
|
||
| `BLE_UART_ENOMEM` | Stack mbuf pool exhausted |
|
||
| `BLE_UART_EFAIL` | Internal stack error — see logs |
|
||
|
||
**Calling context**: any FreeRTOS task at any priority. **Not callable
|
||
from an ISR** — push the data to a queue from the ISR and let a task
|
||
call `ble_uart_tx`.
|
||
|
||
**Auto-fragmentation**: regardless of buffer size, the implementation
|
||
splits the payload into successive notifications of `(MTU - 3)` bytes.
|
||
The central receives them in transmission order.
|
||
|
||
### 5.5 Status queries
|
||
|
||
```c
|
||
bool ble_uart_is_connected(void);
|
||
bool ble_uart_is_subscribed(void);
|
||
```
|
||
|
||
- `is_connected()`: a central is connected (it may not be paired yet).
|
||
- `is_subscribed()`: the central has subscribed to TX notifications
|
||
(note: bonded reconnects often skip CCCD writes).
|
||
|
||
You usually **don't need** to query these up-front — `ble_uart_tx`
|
||
returns `ENOTCONN` to tell you.
|
||
|
||
### 5.6 Security configuration
|
||
|
||
`cfg.encrypted` is a one-line **preset** that turns on every part of
|
||
the stack's security toolbox at once — LE Secure Connections, bonding
|
||
(LTK persisted in NVS), MITM protection, DisplayOnly IO, and the
|
||
`_ENC | _AUTHEN` flags on the GATT characteristics. It maps to the
|
||
older two-state behaviour and is what the "secure by default" template
|
||
in §4.4 picks.
|
||
|
||
For applications that need finer control — a displayless gateway that
|
||
still wants encrypted bonding, a one-shot encrypted session that
|
||
doesn't keep an LTK, an interop test build that disables only MITM —
|
||
each component of the preset can be flipped individually through the
|
||
`cfg.security` sub-struct:
|
||
|
||
```c
|
||
typedef enum {
|
||
BLE_UART_SEC_AUTO = 0, /* follow cfg.encrypted */
|
||
BLE_UART_SEC_OFF = 1,
|
||
BLE_UART_SEC_ON = 2,
|
||
} ble_uart_sec_t;
|
||
|
||
typedef enum {
|
||
BLE_UART_IO_CAP_AUTO = 0, /* DisplayOnly when MITM is on;
|
||
NoInputNoOutput when off.
|
||
Passkey Display needs no on_event */
|
||
BLE_UART_IO_CAP_NO_INPUT_OUTPUT = 1, /* Just Works only */
|
||
BLE_UART_IO_CAP_DISPLAY_ONLY = 2, /* Passkey Display — UART banner
|
||
+ optional PASSKEY_DISPLAY;
|
||
no on_event required */
|
||
BLE_UART_IO_CAP_KEYBOARD_ONLY = 3, /* Passkey Entry — PASSKEY_REQUEST;
|
||
on_event required */
|
||
BLE_UART_IO_CAP_DISPLAY_YES_NO = 4, /* Numeric Comparison;
|
||
on_event required */
|
||
BLE_UART_IO_CAP_KEYBOARD_DISPLAY = 5, /* PASSKEY_REQUEST or NUMERIC_COMPARE;
|
||
on_event required */
|
||
} ble_uart_io_cap_t;
|
||
|
||
typedef struct {
|
||
ble_uart_sec_t sc; /* tri-state */
|
||
ble_uart_sec_t bonding; /* tri-state */
|
||
ble_uart_sec_t mitm; /* tri-state */
|
||
ble_uart_io_cap_t io_cap; /* AUTO + the five IO caps above */
|
||
} ble_uart_security_t;
|
||
```
|
||
|
||
Each of `cfg.security.{sc,bonding,mitm}` is a tri-state. `AUTO`
|
||
(the value of any zero-initialised member) inherits from
|
||
`cfg.encrypted`; `OFF` / `ON` override that specific bit only. The
|
||
resolution table:
|
||
|
||
| `cfg.encrypted` | Override field | Resolved bit |
|
||
| --- | --- | --- |
|
||
| `true` | `AUTO` | ON |
|
||
| `true` | `OFF` | OFF |
|
||
| `true` | `ON` | ON |
|
||
| `false` | `AUTO` | OFF |
|
||
| `false` | `OFF` | OFF |
|
||
| `false` | `ON` | ON |
|
||
|
||
`cfg.security.io_cap` follows the same `AUTO` / explicit pattern.
|
||
The application picks an IO cap matching its UI; the SM combines it
|
||
with the central's IO cap to elect the pairing model (see BT Core
|
||
Spec §2.3.5.1) and ble_uart fires the matching event:
|
||
|
||
| Pairing model | Trigger event | Application response |
|
||
| --- | --- | --- |
|
||
| Just Works | (none — pairs silently) | — |
|
||
| Passkey Display (we show) | `BLE_UART_EVT_PASSKEY_DISPLAY` (optional; UART banner always) | (none — port handles SM reply; central types the digits) |
|
||
| Passkey Entry (user types)| `BLE_UART_EVT_PASSKEY_REQUEST` | `ble_uart_passkey_reply(d)` — **`on_event` required** |
|
||
| Numeric Comparison | `BLE_UART_EVT_NUMERIC_COMPARE` | `ble_uart_compare_reply(b)` — **`on_event` required** |
|
||
|
||
Numeric Comparison additionally requires LE Secure Connections on
|
||
both sides (legacy SM doesn't support it); against a legacy peer a
|
||
`DISPLAY_YES_NO` / `KEYBOARD_DISPLAY` IO cap falls back to either
|
||
Passkey Entry (with our keypad) or Just Works.
|
||
|
||
#### What is checked synchronously
|
||
|
||
`ble_uart_install()` rejects the following with `BLE_UART_EINVAL`
|
||
**before** bringing the host stack up, so misconfigured applications
|
||
fail fast and predictably:
|
||
|
||
- `cfg.security.{sc,bonding,mitm}` outside `{AUTO, OFF, ON}`
|
||
- `cfg.security.io_cap` outside the six values listed above
|
||
- Resolved `mitm == ON` together with resolved
|
||
`io_cap == NO_INPUT_OUTPUT` — Just Works cannot satisfy MITM and
|
||
the SM would otherwise reject pairing in flight
|
||
- `cfg.on_event == NULL` together with a **configured** (not resolved)
|
||
input-capable `io_cap` — only `KEYBOARD_ONLY`, `DISPLAY_YES_NO`, and
|
||
`KEYBOARD_DISPLAY`. Without an event sink the application would never
|
||
see `PASSKEY_REQUEST` / `NUMERIC_COMPARE` and pairing would silently
|
||
stall until the SM times out. **`AUTO` (even when it resolves to
|
||
DisplayOnly because `mitm=ON`), `DISPLAY_ONLY`, and `NO_INPUT_OUTPUT`
|
||
do not require `on_event`** — Passkey Display is satisfied inside the
|
||
port (UART log + internal SM reply); `PASSKEY_DISPLAY` via `on_event`
|
||
is additive only.
|
||
|
||
#### How the resolved policy is applied
|
||
|
||
| Component | Effect |
|
||
| --- | --- |
|
||
| Resolved `sc` / `bonding` / `mitm` (any ON) | SM is enabled; `ble_gap_security_initiate` (NimBLE) / `esp_ble_set_encryption` (Bluedroid) runs on connect |
|
||
| Resolved `mitm` | `ESP_BLE_SEC_ENCRYPT_MITM` vs `_NO_MITM` (Bluedroid); `_AUTHEN` flag added to GATT chars |
|
||
| Any of the three on | Encrypted GATT permission flags (`_ENC` on NimBLE, `_ENCRYPTED` on Bluedroid) |
|
||
| All three off | Plain `READ`/`WRITE` permissions; SM disabled |
|
||
| Resolved `io_cap` | `BLE_HS_IO_*` (NimBLE) / `ESP_IO_CAP_*` (Bluedroid) |
|
||
|
||
#### Common combinations
|
||
|
||
```c
|
||
/* (a) Default — secure-by-default UART. SC + Bonding + MITM, DisplayOnly.
|
||
* on_event may be NULL: passkey is printed to UART and pairing
|
||
* completes without PASSKEY_DISPLAY / reply callbacks. */
|
||
ble_uart_install(&(ble_uart_config_t){
|
||
.encrypted = true,
|
||
/* security.{sc,bonding,mitm,io_cap} all AUTO → all ON. */
|
||
/* .on_event = NULL — valid for this preset */
|
||
});
|
||
|
||
/* (b) Displayless gateway. SC + Bonding + Just Works (no passkey UI). */
|
||
ble_uart_install(&(ble_uart_config_t){
|
||
.encrypted = true,
|
||
.security = {
|
||
.mitm = BLE_UART_SEC_OFF,
|
||
.io_cap = BLE_UART_IO_CAP_NO_INPUT_OUTPUT,
|
||
},
|
||
});
|
||
|
||
/* (c) Encrypted but ephemeral. Re-pair every reconnect, no NVS bond. */
|
||
ble_uart_install(&(ble_uart_config_t){
|
||
.encrypted = true,
|
||
.security = { .bonding = BLE_UART_SEC_OFF },
|
||
});
|
||
|
||
/* (d) Plaintext lab build. */
|
||
ble_uart_install(&(ble_uart_config_t){
|
||
.encrypted = false,
|
||
/* security.* all AUTO → all OFF. */
|
||
});
|
||
|
||
/* (e) Interop test — keep encryption + bonding, drop MITM only. */
|
||
ble_uart_install(&(ble_uart_config_t){
|
||
.encrypted = true,
|
||
.security = { .mitm = BLE_UART_SEC_OFF },
|
||
/* security.io_cap AUTO → NoInputNoOutput once MITM is gone. */
|
||
});
|
||
|
||
/* (f) Passkey Entry — peripheral has a keypad, central has a display.
|
||
* User reads the 6-digit code off the central and types it here.
|
||
* on_event MUST be set; the application wires PASSKEY_REQUEST to
|
||
* a UI prompt and feeds the digits to ble_uart_passkey_reply(). */
|
||
ble_uart_install(&(ble_uart_config_t){
|
||
.encrypted = true,
|
||
.security = { .io_cap = BLE_UART_IO_CAP_KEYBOARD_ONLY },
|
||
.on_event = on_event,
|
||
...
|
||
});
|
||
|
||
/* (g) Numeric Comparison — peripheral has display + yes/no button.
|
||
* Both sides see the same 6-digit value; user confirms match.
|
||
* Requires LE Secure Connections (so .sc must be ON, which it is
|
||
* by default with .encrypted=true). on_event MUST be set. */
|
||
ble_uart_install(&(ble_uart_config_t){
|
||
.encrypted = true,
|
||
.security = { .io_cap = BLE_UART_IO_CAP_DISPLAY_YES_NO },
|
||
.on_event = on_event,
|
||
...
|
||
});
|
||
|
||
/* (h) Touchscreen UI — full keypad+display. The SM elects either
|
||
* Passkey Entry or Numeric Comparison depending on the central;
|
||
* wire BOTH events. */
|
||
ble_uart_install(&(ble_uart_config_t){
|
||
.encrypted = true,
|
||
.security = { .io_cap = BLE_UART_IO_CAP_KEYBOARD_DISPLAY },
|
||
.on_event = on_event,
|
||
...
|
||
});
|
||
```
|
||
|
||
#### 5.6.1 Pairing reply API
|
||
|
||
**Passkey Display (default / `DISPLAY_ONLY` / `AUTO` + `mitm=ON`)** does
|
||
not use the reply APIs. The port generates the 6-digit value, logs it,
|
||
and drives the SM (NimBLE: `ble_sm_inject_io` on `BLE_SM_IOACT_DISP`;
|
||
Bluedroid: no `esp_ble_passkey_reply` needed on `PASSKEY_NOTIF`). You
|
||
only need `ble_uart_passkey_reply()` / `ble_uart_compare_reply()` for
|
||
the interactive models below.
|
||
|
||
`Passkey Entry` and `Numeric Comparison` are interactive — the SM
|
||
suspends pairing until the application reports the user's input.
|
||
`ble_uart` exposes one reply call per flavour:
|
||
|
||
```c
|
||
int ble_uart_passkey_reply(uint32_t passkey); /* 0..999999 */
|
||
int ble_uart_compare_reply(bool match);
|
||
```
|
||
|
||
Both are safe from any task, return immediately, and accept exactly
|
||
one reply per request. Subsequent calls (or calls with no request in
|
||
flight) return `BLE_UART_ENOTCONN`. `passkey > 999999` returns
|
||
`BLE_UART_EINVAL`. If the user fails to reply before the SM's pairing
|
||
timeout (controller default ≈ 30 s), the link surfaces
|
||
`BLE_UART_EVT_PAIRING_FAILED` and any later reply is silently dropped.
|
||
|
||
```c
|
||
static void on_event(const ble_uart_evt_t *e)
|
||
{
|
||
switch (e->id) {
|
||
case BLE_UART_EVT_PASSKEY_REQUEST:
|
||
/* Prompt the user; once digits are entered: */
|
||
ble_uart_passkey_reply(user_input); /* 0..999999 */
|
||
break;
|
||
|
||
case BLE_UART_EVT_NUMERIC_COMPARE:
|
||
ESP_LOGI(TAG, "compare %06" PRIu32, e->numeric_compare.passkey);
|
||
/* Once the user confirms: */
|
||
ble_uart_compare_reply(true /* or false on mismatch */);
|
||
break;
|
||
|
||
default: break;
|
||
}
|
||
}
|
||
```
|
||
|
||
A `false` reply to `compare_reply()` makes pairing fail with a
|
||
numeric-comparison mismatch — surfaced as
|
||
`BLE_UART_EVT_PAIRING_FAILED`. To cancel `PASSKEY_REQUEST` without a
|
||
mismatch event, just don't call `passkey_reply()`; the SM will time
|
||
out the pairing.
|
||
|
||
#### Backend differences
|
||
|
||
- **Passkey Display without `on_event`**: both backends complete pairing;
|
||
only `PASSKEY_DISPLAY` is suppressed when the callback is `NULL`. The
|
||
UART banner (`show_passkey`) is always emitted for log-scraping tests.
|
||
- **Numeric Comparison edge case**: if `io_cap` resolved to DisplayOnly
|
||
but the central still negotiates NC (rare), Bluedroid rejects the
|
||
request when `on_event == NULL`; NimBLE may stall until the SM times
|
||
out — use `DISPLAY_YES_NO` / `KEYBOARD_DISPLAY` with a registered
|
||
`on_event` if you need NC.
|
||
- **NimBLE** lets the application observe the negotiated `key_size`
|
||
on `BLE_UART_EVT_LINK_SECURE`; **Bluedroid** surfaces a fixed `16`
|
||
(the value forced via `ESP_BLE_SM_MAX_KEY_SIZE` at install time —
|
||
Bluedroid does not expose the negotiated size on `AUTH_CMPL`).
|
||
- With `mitm=OFF`, NimBLE pairs with `_AUTHEN` permissions still
|
||
off on the chars; Bluedroid uses `ESP_GATT_PERM_*_ENCRYPTED`
|
||
(the encryption-without-MITM tier) to match.
|
||
- `cfg.encrypted=false` plus any `cfg.security.*=ON` override is
|
||
allowed — it partially enables the SM, e.g.
|
||
`cfg.encrypted=false, cfg.security.sc=ON` is "SC pairing without
|
||
MITM and without persisted bond". Useful only for lab interop
|
||
tests; production firmware should keep `cfg.encrypted = true` and
|
||
only override surgically.
|
||
|
||
### 5.7 Bond management
|
||
|
||
```c
|
||
/* All three are usable as soon as ble_uart_install() returns; they
|
||
* do not require ble_uart_open() to have been called yet — clearing
|
||
* stale bonds before the first advertising window is the canonical
|
||
* use case. */
|
||
int ble_uart_get_bond_count(size_t *out_count);
|
||
int ble_uart_get_bonded_peers(ble_uart_addr_t *out, size_t cap, size_t *out_count);
|
||
int ble_uart_remove_peer(const ble_uart_addr_t *peer);
|
||
int ble_uart_clear_bonds(void);
|
||
|
||
/* Address type used by remove_peer and BLE_UART_EVT_CONNECTED. */
|
||
typedef struct {
|
||
uint8_t bytes[6]; /* big-endian: bytes[0] is the MSB octet */
|
||
uint8_t type; /* BLE_UART_ADDR_TYPE_PUBLIC or _RANDOM */
|
||
} ble_uart_addr_t;
|
||
```
|
||
|
||
| Function | Effect |
|
||
| --- | --- |
|
||
| `ble_uart_get_bond_count` | Number of peers in the persistent store; 0 means "no bonds yet". Pass `cap == 0` to `get_bonded_peers` for the same count without an address buffer. |
|
||
| `ble_uart_get_bonded_peers` | List bonded peer addresses; writes up to `cap`, reports total in `*out_count` (caller may re-call with a larger buffer if total > cap). `cap == 0` returns the count only. |
|
||
| `ble_uart_remove_peer` | Drop one peer's LTK / IRK / persisted CCCD. **Idempotent** — returns `BLE_UART_OK` even when the peer is not in the store (NimBLE: `ble_store_util_delete_peer` treats `BLE_HS_ENOENT` as success; Bluedroid: `esp_ble_remove_bond_device` does not fail on a missing entry). Call `get_bonded_peers()` first if you need to tell "removed" from "was never bonded". |
|
||
| `ble_uart_clear_bonds` | Drop *all* of the above; equivalent to a factory reset of the bond store, but does not touch any other NVS namespace |
|
||
|
||
`ble_uart_remove_peer` and `ble_uart_clear_bonds` do **not** actively
|
||
disconnect the current link (encrypted or not). Call `ble_uart_close()`
|
||
first if you need an immediate disconnect and re-pair.
|
||
|
||
**Where do I get the address?** From `BLE_UART_EVT_CONNECTED.connected.peer`
|
||
(see §5.2.1). Save it from your event handler the first time you see
|
||
each new peer, then pass it to `ble_uart_remove_peer` later when you
|
||
want to forget it.
|
||
|
||
**Backend notes**:
|
||
|
||
- Bluedroid matches bonds by BD address alone — `peer->type` is
|
||
ignored by `remove_peer`. If the peer first connected as
|
||
`address_A` and bonding succeeded, CONNECT and `get_bonded_peers()`
|
||
keep reporting `address_A` on later reconnects even when the
|
||
peer's over-the-air address has changed (e.g. a new RPA).
|
||
- NimBLE matches by `(type, identity-address)` — for an RPA peer this
|
||
is the resolved identity, **not** the random address you saw on the
|
||
wire. `BLE_UART_EVT_CONNECTED` reports the resolved identity when
|
||
it's known (post-pairing reconnect of a bonded RPA peer); on first
|
||
pair it equals the OTA random address, so the bond is recorded
|
||
under that random address and `remove_peer` works either way.
|
||
- Neither backend reports "peer not found" from `remove_peer` — a
|
||
wrong `(type, bytes)` pair that does not match any stored bond
|
||
still returns `BLE_UART_OK`. This mirrors the underlying stacks'
|
||
delete-if-present semantics, not a lookup-then-delete API.
|
||
- `ble_uart_clear_bonds` on Bluedroid iterates the bond list and
|
||
removes each entry; on NimBLE it calls `ble_store_clear()`, which
|
||
also wipes the local LTK and any persisted CCCD.
|
||
- **NimBLE** `get_bond_count` / `get_bonded_peers(cap=0)` heap-allocate a
|
||
scratch buffer sized to `BLE_STORE_MAX_BONDS` (not the caller's stack),
|
||
so they are safe from small-stack tasks regardless of
|
||
`CONFIG_BT_NIMBLE_MAX_BONDS`.
|
||
|
||
### 5.8 Service UUID constant
|
||
|
||
```c
|
||
extern const ble_uart_uuid128_t ble_uart_service_uuid;
|
||
```
|
||
|
||
Always `6e400001-b5a3-f393-e0a9-e50e24dcca9e` (the de-facto BLE UART service UUID). It is
|
||
already inserted into the scan response **by the default payload**, so
|
||
the application only needs to reference it when it takes over the adv
|
||
bytes itself (see §5.9) or otherwise replaces our advertising (see §6.3).
|
||
|
||
### 5.9 Custom advertising payloads
|
||
|
||
`ble_uart` builds a sensible default for both the primary advertisement
|
||
and the scan response:
|
||
|
||
| Packet | Default content | Why |
|
||
| --- | --- | --- |
|
||
| Primary adv (31 B max) | Flags AD + Complete Local Name (`device_name`) | Phones show the name; everything else in the 31 bytes is left for the application to add via `adv_data` |
|
||
| Scan response (31 B max) | Complete 128-bit BLE UART service UUID (18 B element) | The 128-bit UUID alone is too big to share the primary packet with a typical name |
|
||
|
||
Set `adv_data` / `scan_rsp_data` in the config to override **everything
|
||
the application sees** — only the 3-byte Flags AD element of the primary
|
||
packet stays library-controlled (the BT spec mandates a Flags element,
|
||
and a few of its bits — General Discoverable / BR-EDR Not Supported —
|
||
are state we already negotiated with the controller).
|
||
|
||
```c
|
||
/* +-- 31-byte primary advertisement packet ---------------------+
|
||
* | [02 01 06] ← Flags AD prepended by ble_uart (3 bytes) |
|
||
* | <up to BLE_UART_ADV_DATA_MAX = 28 bytes from your buffer> |
|
||
* +-------------------------------------------------------------+
|
||
*
|
||
* +-- 31-byte scan-response packet -----------------------------+
|
||
* | <up to BLE_UART_SCAN_RSP_DATA_MAX = 31 bytes from your buf> |
|
||
* +-------------------------------------------------------------+
|
||
*/
|
||
```
|
||
|
||
`adv_data_len` is checked at install time; oversized buffers fail with
|
||
`BLE_UART_EINVAL`. Both buffers are copied into module-private storage,
|
||
so the caller's pointers do not need to outlive the call.
|
||
|
||
**Format**: a sequence of standard BT Core "AD structure" triplets —
|
||
`[length(1)] [AD type(1)] [value(length-1)]`. AD-type values are
|
||
defined in the *Bluetooth Assigned Numbers* document
|
||
([Generic Access Profile, §1](https://www.bluetooth.com/specifications/assigned-numbers/)).
|
||
Common ones:
|
||
|
||
| Type | Name | Value format |
|
||
| --- | --- | --- |
|
||
| `0x09` | Complete Local Name | UTF-8 bytes |
|
||
| `0x08` | Shortened Local Name | UTF-8 bytes |
|
||
| `0x0A` | TX Power Level | 1 signed byte (dBm) |
|
||
| `0x07` | Complete List of 128-bit Service UUIDs | 16 bytes per UUID |
|
||
| `0xFF` | Manufacturer Specific Data | 2-byte company ID + payload |
|
||
|
||
**Example — replace the default with name + UUID + 4 bytes of vendor data**
|
||
|
||
```c
|
||
static const uint8_t adv_payload[] = {
|
||
/* Complete Local Name "MyDev" (1 + 1 + 5 = 7 bytes) */
|
||
0x06, 0x09, 'M', 'y', 'D', 'e', 'v',
|
||
|
||
/* Complete 128-bit Service UUID — bytes are little-endian on air,
|
||
* matching ble_uart_service_uuid.bytes[]. (1 + 1 + 16 = 18 bytes) */
|
||
0x11, 0x07,
|
||
0x9e, 0xca, 0xdc, 0x24, 0x0e, 0xe5, 0xa9, 0xe0,
|
||
0x93, 0xf3, 0xa3, 0xb5, 0x01, 0x00, 0x40, 0x6e,
|
||
/* total = 7 + 18 = 25 bytes (≤ BLE_UART_ADV_DATA_MAX = 28) */
|
||
};
|
||
|
||
static const uint8_t scan_rsp_payload[] = {
|
||
/* Manufacturer Specific Data: Espressif Systems (0x02E5) + 4 bytes */
|
||
0x07, 0xFF, 0xE5, 0x02, 0xDE, 0xAD, 0xBE, 0xEF,
|
||
};
|
||
|
||
ble_uart_install(&(ble_uart_config_t){
|
||
.encrypted = true,
|
||
.device_name = "MyDev", /* GAP service value, peer-readable */
|
||
.adv_data = adv_payload,
|
||
.adv_data_len = sizeof(adv_payload),
|
||
.scan_rsp_data = scan_rsp_payload,
|
||
.scan_rsp_data_len = sizeof(scan_rsp_payload),
|
||
.ble_uart_on_rx = on_rx,
|
||
.on_event = on_event,
|
||
});
|
||
```
|
||
|
||
**Notes**:
|
||
|
||
- `device_name` and `adv_data` are independent. The first is the GAP
|
||
service value that any connected peer can read over GATT; the second
|
||
is what scanners see before connecting. If you want the device name
|
||
visible during a scan, include a Complete-Local-Name AD element
|
||
(`0x09`) in `adv_data` yourself — providing custom `adv_data`
|
||
disables the auto-include path.
|
||
- The 31-byte packet limit is BLE 4.x legacy advertising. Extended
|
||
advertising (BLE 5.0) is **not** wired through this API — both
|
||
backends fall back to legacy advertising for portability.
|
||
- Set only one half if you want the other to keep its default — e.g.
|
||
custom `adv_data` with `scan_rsp_data = NULL` keeps the default
|
||
service-UUID scan response.
|
||
|
||
---
|
||
|
||
## 6. Advanced Usage
|
||
|
||
### 6.1 Different RX framing strategies
|
||
|
||
**A. Split on `\n` (suits ASCII protocols / JSON)**
|
||
|
||
```c
|
||
static uint8_t s_buf[1024];
|
||
static size_t s_len;
|
||
|
||
static void on_rx(const uint8_t *d, size_t n)
|
||
{
|
||
for (size_t i = 0; i < n; i++) {
|
||
if (d[i] == '\n') { handle_line(s_buf, s_len); s_len = 0; }
|
||
else if (s_len < sizeof s_buf) s_buf[s_len++] = d[i];
|
||
}
|
||
}
|
||
```
|
||
|
||
**B. Length-prefixed binary frames**
|
||
|
||
```c
|
||
static void on_rx(const uint8_t *d, size_t n)
|
||
{
|
||
static uint16_t need = 0;
|
||
static uint8_t frame[256];
|
||
static size_t got = 0;
|
||
|
||
for (size_t i = 0; i < n; i++) {
|
||
if (need == 0) { need = d[i]; got = 0; continue; }
|
||
frame[got++] = d[i];
|
||
if (got == need) { handle_frame(frame, got); need = 0; }
|
||
}
|
||
}
|
||
```
|
||
|
||
**C. Forward straight to UART**
|
||
|
||
```c
|
||
static void on_rx(const uint8_t *d, size_t n)
|
||
{
|
||
uart_write_bytes(UART_NUM_1, (const char *)d, n);
|
||
}
|
||
```
|
||
|
||
### 6.2 Disabling encryption (lab scenarios)
|
||
|
||
```c
|
||
ble_uart_install(&(ble_uart_config_t){
|
||
.encrypted = false, /* ← turn it off */
|
||
.device_name = "OpenDev",
|
||
.ble_uart_on_rx = ...,
|
||
});
|
||
```
|
||
|
||
Effect:
|
||
- GATT characteristics drop the `_ENC | _AUTHEN` flags.
|
||
- Any central can read/write — no pairing required.
|
||
- No passkey prompt.
|
||
- Data is sniffable by any nearby BLE sniffer or compromised radio in range.
|
||
|
||
**Do not ship this in production firmware.**
|
||
|
||
### 6.3 Coexisting with other GATT services
|
||
|
||
> The snippet below is for the **NimBLE backend**. With Bluedroid, register
|
||
> additional profiles via `esp_ble_gatts_app_register()` before calling
|
||
> `ble_uart_open()` — the gating rule is the same: extra services must
|
||
> be in place before advertising starts.
|
||
|
||
`ble_uart` registers its own service; you can call `ble_gatts_add_svcs()`
|
||
**multiple times** and NimBLE will build all of them into the GATT
|
||
table. **Caveat**: this must happen before the **first** `ble_uart_open()`
|
||
for that `install()` cycle, otherwise the host task is already running
|
||
and the GATT table is locked. If you use `ble_uart_close()` and later
|
||
`ble_uart_open()` without `uninstall()`, you must call your extra
|
||
`ble_svc_*_init()` / `ble_gatts_add_svcs()` again before that second
|
||
`open()` — see §5.3.1a.
|
||
|
||
```c
|
||
ble_uart_install(&cfg);
|
||
|
||
/* Register your extra services before open() */
|
||
ble_svc_dis_init(); /* Device Information Service */
|
||
my_battery_service_init(); /* your own battery service */
|
||
|
||
ble_uart_open();
|
||
```
|
||
|
||
> If your service must appear in the **advertising packet**, you have
|
||
> to bypass `ble_uart`'s internal advertising logic — override
|
||
> `ble_hs_cfg.sync_cb` with your own implementation after
|
||
> `ble_uart_install`, then call `ble_uart_open()`. Note that
|
||
> `ble_uart`'s internal `start_advertising` will not run, so you must
|
||
> call `ble_gap_adv_start` yourself. In that case, just fork
|
||
> `ble_uart_nimble.c` (or the matching `ble_uart_bluedroid.c`).
|
||
|
||
### 6.4 Configuring the device name via Kconfig
|
||
|
||
If you use the shared `ble_uart` component, options are already in
|
||
`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:
|
||
|
||
The bundled example builds a per-unit name as `<prefix>-XXXX` where
|
||
`XXXX` is the last two BT MAC bytes in hex:
|
||
|
||
```c
|
||
uint8_t mac[6] = {0};
|
||
esp_read_mac(mac, ESP_MAC_BT);
|
||
char name[BLE_UART_DEVICE_NAME_MAX + 1];
|
||
snprintf(name, sizeof(name), "%s-%02X%02X",
|
||
CONFIG_BLE_UART_DEVICE_NAME_PREFIX, mac[4], mac[5]);
|
||
|
||
ble_uart_install(&(ble_uart_config_t){
|
||
.encrypted = true,
|
||
.device_name = name,
|
||
.ble_uart_on_rx = on_rx,
|
||
});
|
||
```
|
||
|
||
Edit the prefix through `menuconfig → Component configuration →
|
||
ESP-BLE-UART library → BLE device name prefix`.
|
||
|
||
For a fixed name on every unit, skip the MAC suffix and pass any
|
||
string ≤ `BLE_UART_DEVICE_NAME_MAX` directly to `device_name`.
|
||
|
||
### 6.5 Pushing data proactively
|
||
|
||
You can call TX from any task:
|
||
|
||
```c
|
||
/* A periodic sensor-reporting task */
|
||
static void sensor_task(void *arg)
|
||
{
|
||
char line[64];
|
||
while (1) {
|
||
int t = read_temperature();
|
||
int n = snprintf(line, sizeof(line), "temp=%d.%d\n", t / 10, t % 10);
|
||
ble_uart_tx((const uint8_t *)line, (size_t)n);
|
||
vTaskDelay(pdMS_TO_TICKS(1000));
|
||
}
|
||
}
|
||
|
||
/* Spawn it from app_main */
|
||
xTaskCreate(sensor_task, "sensor", 3072, NULL, 5, NULL);
|
||
```
|
||
|
||
When nobody is subscribed, `ble_uart_tx` returns `BLE_UART_ENOTCONN` —
|
||
**just ignore it**.
|
||
|
||
---
|
||
|
||
## 7. Calling Context & Thread Safety
|
||
|
||
| Function | Calling context | Thread-safe |
|
||
| --- | --- | --- |
|
||
| `ble_uart_install` | Any task; once per uninstall cycle | One-shot until `uninstall` |
|
||
| `ble_uart_open` | Any task; after `install` | One-shot until `close` |
|
||
| `ble_uart_close` | Any task **except the BLE host task** (NimBLE host task / Bluedroid BTC task) | Idempotent; second call returns `EALREADY` |
|
||
| `ble_uart_close_async` | Any task — including the BLE host task (use this from inside `on_rx` / `on_event`) | Idempotent; second call while a worker is draining returns `EALREADY` |
|
||
| `ble_uart_uninstall` | Any task **except the BLE host task** | Idempotent; see §5.3 release paths; polls in-flight `close_async` ≤~5 s. Best-effort teardown: returns the **first** `BLE_UART_*` failure (`ble_uart_close` or translated `esp_err_t`) but always wipes module state so a retry is possible. |
|
||
| `ble_uart_tx` | Any FreeRTOS task | Yes — multi-task concurrent |
|
||
| `ble_uart_is_connected` / `is_subscribed` | Any context | Yes (bool read; best-effort snapshot) |
|
||
| `ble_uart_on_rx` / `on_event` callback | BLE host task (NimBLE host task / Bluedroid BTC task); **`BLE_UART_EVT_CLOSED` is the lone exception — fires on the close-async worker task** | Your code must not block, **must not call `close` / `uninstall`** — use `ble_uart_close_async()` instead |
|
||
| **Calling any `ble_uart` API from an ISR** | not allowed | Neither host stack supports it |
|
||
|
||
---
|
||
|
||
## 8. Memory / Performance
|
||
|
||
| Item | Footprint |
|
||
| --- | --- |
|
||
| Code segment (`ble_uart_nimble.c.o`) | ~14 KB (with `-Os`) |
|
||
| Code segment (`ble_uart_bluedroid.c.o`) | ~22 KB (with `-Os`; larger because long-write reassembly is open-coded) |
|
||
| Static RAM (globals + RX buffer) | ~1.1 KB (the bulk is `CONFIG_BLE_UART_RX_SCRATCH_SIZE`, default 1024 B) |
|
||
| Host task stack (NimBLE host / Bluedroid BTC) | 4 KB (default) |
|
||
| Controller task stack | ~3 KB (default) |
|
||
| Bond store (NVS) | ~80 bytes per bonded peer |
|
||
| ATT MTU | Negotiated; whatever you set in sdkconfig (247 / 256 / 512) |
|
||
|
||
Measured throughput (ESP32-S3, iPhone 14 Pro central, MTU 247):
|
||
- TX (notify): ~25 KB/s
|
||
- RX (write): ~20 KB/s
|
||
|
||
---
|
||
|
||
## 9. FAQ
|
||
|
||
| Symptom | Cause / fix |
|
||
| --- | --- |
|
||
| `nimble_port_init rc=...` | NVS not initialised, or BT controller not enabled |
|
||
| Compile error: `host/ble_hs.h` not found | `REQUIRES bt` is missing from CMakeLists |
|
||
| `ble_uart_install()` returns `BLE_UART_EINVAL` | Buffer too long (`device_name` / `adv_data` / `scan_rsp` limits in §5.9), impossible security (`mitm=ON` + `io_cap=NO_INPUT_OUTPUT`), **`io_cap` in `{KEYBOARD_ONLY, DISPLAY_YES_NO, KEYBOARD_DISPLAY}` with `on_event=NULL`** (note: default `AUTO` + `encrypted=true` and explicit `DISPLAY_ONLY` **do** allow `on_event=NULL`), or out-of-range `sc`/`bonding`/`mitm`/`io_cap`. See §5.6. |
|
||
| Pairing fails | Central uses "Just Works" but we require MITM (`encrypted=true`). Use a central that supports passkey entry |
|
||
| `enc_change status=13 encrypted=1 bonded=1` | `13 = BLE_HS_ETIMEOUT`. Bonded-reconnect race; **the link is actually encrypted — safe to ignore** |
|
||
| Notifications missing after a reconnect | Bonded centrals often skip the CCCD write; our TX path doesn't gate on subscription state, so notifications still go out — make sure the central side has its callback registered |
|
||
| Second connection rejected | `MAX_CONNECTIONS = 1` by default. For multi-connection support, bump the sdkconfig value and turn `s_conn_handle` (NimBLE backend) / `s_conn_id` (Bluedroid backend) into an array |
|
||
| Flash fills up | Bond entries accumulate. Periodically run `idf.py erase-flash`, or call `ble_store_clear()` in code |
|
||
|
||
---
|
||
|
||
## 10. Differences from This Example
|
||
|
||
If you **build directly on top of this example**:
|
||
|
||
| You already have | No further work needed |
|
||
| --- | --- |
|
||
| `main.c` echo template | Replace with your own `on_rx` body |
|
||
| `sdkconfig.defaults` | Reuse as-is |
|
||
| `sdkconfig.bluedroid` | Only if you switch to Bluedroid host — reuse as-is (see §4.3); omit for default NimBLE |
|
||
| Root `CMakeLists.txt` (`EXTRA_COMPONENT_DIRS` → `../common/ble_uart`) | Reuse as-is (or follow §3 option B) |
|
||
| `CMakeLists.txt` (root + main) | Reuse as-is |
|
||
|
||
If you **start from an empty project**:
|
||
|
||
| What you need to do | Source |
|
||
| --- | --- |
|
||
| Add `EXTRA_COMPONENT_DIRS` for `examples/bluetooth/common/ble_uart` in root `CMakeLists.txt`, **or** copy `ble_uart.h` + at least one of `ble_uart_nimble.c` / `ble_uart_bluedroid.c` into `main/` | §3 of this guide |
|
||
| Copy the key lines of `sdkconfig.defaults` | §4.3 of this guide |
|
||
| Add `REQUIRES ble_uart nvs_flash` (after `EXTRA_COMPONENT_DIRS`) **or** SRC + `REQUIRES bt nvs_flash` (copied sources) to `main/CMakeLists.txt` | §4.2 of this guide |
|
||
| Write `install` + `open` in `app_main` | §4.4 of this guide |
|
||
|
||
---
|
||
|
||
## 11. API Cheat Sheet (print and pin to the wall)
|
||
|
||
```c
|
||
#include "ble_uart.h"
|
||
|
||
/* === Types === */
|
||
typedef void (*ble_uart_rx_cb_t) (const uint8_t *data, size_t len);
|
||
typedef void (*ble_uart_evt_cb_t)(const ble_uart_evt_t *evt);
|
||
|
||
typedef struct {
|
||
ble_uart_sec_t sc; /* AUTO / OFF / ON — follow `encrypted` when AUTO */
|
||
ble_uart_sec_t bonding;
|
||
ble_uart_sec_t mitm;
|
||
ble_uart_io_cap_t io_cap; /* AUTO / NO_INPUT_OUTPUT / DISPLAY_ONLY /
|
||
KEYBOARD_ONLY / DISPLAY_YES_NO /
|
||
KEYBOARD_DISPLAY */
|
||
} ble_uart_security_t;
|
||
|
||
typedef struct {
|
||
bool encrypted; /* preset: SC + Bonding + MITM + DisplayOnly */
|
||
ble_uart_security_t security; /* per-feature overrides; see §5.6 */
|
||
|
||
const char *device_name; /* ≤ BLE_UART_DEVICE_NAME_MAX (26) */
|
||
/* Custom adv payloads (NULL → defaults).
|
||
* Limits: adv_data_len ≤ BLE_UART_ADV_DATA_MAX (28),
|
||
* scan_rsp_data_len ≤ BLE_UART_SCAN_RSP_DATA_MAX (31). */
|
||
const uint8_t *adv_data;
|
||
size_t adv_data_len;
|
||
const uint8_t *scan_rsp_data;
|
||
size_t scan_rsp_data_len;
|
||
ble_uart_rx_cb_t ble_uart_on_rx;
|
||
ble_uart_evt_cb_t on_event; /* optional for default Passkey Display;
|
||
required for KEYBOARD_ONLY /
|
||
DISPLAY_YES_NO / KEYBOARD_DISPLAY */
|
||
} ble_uart_config_t;
|
||
|
||
/* === Lifecycle === */
|
||
int ble_uart_install(const ble_uart_config_t *cfg); /* host + GATT */
|
||
int ble_uart_open(void); /* start advertising (NimBLE: spawn host task) */
|
||
int ble_uart_close(void); /* stop adv / disconnect / quiesce host */
|
||
int ble_uart_close_async(void); /* same, fire-and-forget; signals BLE_UART_EVT_CLOSED on completion */
|
||
int ble_uart_uninstall(void); /* best-effort teardown; first error, state always cleared */
|
||
|
||
/* === Send (callable from any task) === */
|
||
int ble_uart_tx(const uint8_t *data, size_t len);
|
||
|
||
/* === Receive === */
|
||
/* Via the cfg.ble_uart_on_rx callback, signature:
|
||
* void cb(const uint8_t *data, size_t len); */
|
||
|
||
/* === Pairing replies (PASSKEY_REQUEST / NUMERIC_COMPARE only) === */
|
||
int ble_uart_passkey_reply(uint32_t passkey); /* answer PASSKEY_REQUEST */
|
||
int ble_uart_compare_reply(bool match); /* answer NUMERIC_COMPARE */
|
||
|
||
/* === Status === */
|
||
bool ble_uart_is_connected(void);
|
||
bool ble_uart_is_subscribed(void);
|
||
|
||
/* === Bond management (works after install) === */
|
||
typedef struct {
|
||
uint8_t bytes[6]; /* big-endian: bytes[0] is MSB */
|
||
uint8_t type; /* BLE_UART_ADDR_TYPE_PUBLIC or _RANDOM */
|
||
} ble_uart_addr_t;
|
||
|
||
int ble_uart_get_bond_count(size_t *out_count);
|
||
int ble_uart_get_bonded_peers(ble_uart_addr_t *out, size_t cap, size_t *out_count);
|
||
int ble_uart_remove_peer(const ble_uart_addr_t *peer);
|
||
int ble_uart_clear_bonds(void);
|
||
|
||
/* === Service UUID (for advertising; usually no need to touch) === */
|
||
extern const ble_uart_uuid128_t ble_uart_service_uuid;
|
||
```
|
||
|
||
---
|
||
|
||
## 12. Minimal Project Template (ready to flash)
|
||
|
||
A complete flashable project takes a handful of files. The inactive
|
||
backend `.c` compiles to nothing if you ship both.
|
||
|
||
**Using the shared component (fewer copies):**
|
||
|
||
```
|
||
my_ble_uart_project/
|
||
├── CMakeLists.txt ← EXTRA_COMPONENT_DIRS → …/common/ble_uart (before project())
|
||
├── sdkconfig.defaults
|
||
└── main/
|
||
├── CMakeLists.txt ← REQUIRES ble_uart nvs_flash; SRCS main.c only
|
||
└── main.c
|
||
```
|
||
|
||
**Copying sources into `main/` (classic layout):**
|
||
|
||
```
|
||
my_ble_uart_project/
|
||
├── CMakeLists.txt
|
||
├── sdkconfig.defaults
|
||
└── main/
|
||
├── CMakeLists.txt
|
||
├── ble_uart.h ← from $IDF_PATH/examples/bluetooth/common/ble_uart/
|
||
├── ble_uart_nimble.c
|
||
├── ble_uart_bluedroid.c ← optional second backend
|
||
└── main.c
|
||
```
|
||
|
||
**Root `CMakeLists.txt`** (shared `ble_uart` via `EXTRA_COMPONENT_DIRS`):
|
||
```cmake
|
||
cmake_minimum_required(VERSION 3.16)
|
||
list(APPEND EXTRA_COMPONENT_DIRS "${CMAKE_CURRENT_LIST_DIR}/../path/to/common/ble_uart")
|
||
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
|
||
project(my_ble_uart)
|
||
```
|
||
|
||
**`main/CMakeLists.txt`** (shared component — no `.c` copies in `main/`):
|
||
```cmake
|
||
idf_component_register(SRCS "main.c"
|
||
INCLUDE_DIRS "."
|
||
REQUIRES ble_uart nvs_flash)
|
||
```
|
||
|
||
**`main/CMakeLists.txt`** (classic copy layout — both backends in `main/`):
|
||
```cmake
|
||
idf_component_register(SRCS "main.c"
|
||
"ble_uart_nimble.c"
|
||
"ble_uart_bluedroid.c"
|
||
INCLUDE_DIRS "."
|
||
REQUIRES bt nvs_flash)
|
||
```
|
||
|
||
**`sdkconfig.defaults`** (7 lines, NimBLE backend):
|
||
```ini
|
||
CONFIG_BT_ENABLED=y
|
||
CONFIG_BTDM_CTRL_MODE_BLE_ONLY=y
|
||
CONFIG_BT_BLUEDROID_ENABLED=n
|
||
CONFIG_BT_NIMBLE_ENABLED=y
|
||
CONFIG_BT_NIMBLE_SM_SC=y
|
||
CONFIG_BT_NIMBLE_NVS_PERSIST=y
|
||
CONFIG_BT_NIMBLE_ATT_PREFERRED_MTU=512
|
||
```
|
||
|
||
**Bluedroid host instead of NimBLE:** copy
|
||
`examples/bluetooth/ble_uart_service/sdkconfig.bluedroid` next to your
|
||
`sdkconfig.defaults` and pass
|
||
`-D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.bluedroid"` (see §4.3).
|
||
|
||
**`main/main.c`** — copy the §4.4 template verbatim.
|
||
|
||
Flash:
|
||
|
||
```bash
|
||
idf.py set-target esp32s3
|
||
idf.py build flash monitor
|
||
```
|
||
|
||
Done.
|