wehub-resource-sync
245 lines
14 KiB
Markdown
245 lines
14 KiB
Markdown
| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-S3 | ESP32-S31 |
|
|
| ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | --------- |
|
|
|
|
# BLE Central Example
|
|
|
|
(See the README.md file in the upper level 'examples' directory for more information about examples.)
|
|
|
|
This example creates GATT client and performs passive scan, it then connects to peripheral device if the device advertises connectability and the device advertises support for the Alert Notification service (0x1811) as primary service UUID.
|
|
|
|
After connection it enables bonding and link encryprion if the `Enable Link Encryption` flag is set in the example config.
|
|
|
|
It performs six GATT operations against the specified peer:
|
|
|
|
* Reads the ANS Supported New Alert Category characteristic.
|
|
|
|
* After the read operation is completed, writes the ANS Alert Notification Control Point characteristic.
|
|
|
|
* After the write operation is completed, subscribes to notifications for the ANS Unread Alert Status characteristic.
|
|
|
|
* After the subscribe operation is completed, it subscribes to notifications for a user defined characteristic.
|
|
|
|
* After this subscribe operation is completed, it writes to the user defined characteristic.
|
|
|
|
* After the write operation is completed, it reads from the user defined characteristic.
|
|
|
|
If the peer does not support a required service, characteristic, or descriptor, then the peer lied when it claimed support for the alert notification service! When this happens, or if a GATT procedure fails, this function immediately terminates the connection.
|
|
|
|
It uses ESP32's Bluetooth controller and NimBLE stack based BLE host.
|
|
|
|
This example aims at understanding BLE service discovery, connection, encryption and characteristic operations.
|
|
|
|
To test this demo, use any BLE GATT server app that advertises support for the Alert Notification service (0x1811) and includes it in the GATT database.
|
|
|
|
Note :
|
|
|
|
* To install the dependency packages needed, please refer to the top level [README file](../../../README.md#running-test-python-script-pytest).
|
|
|
|
## How to Use Example
|
|
|
|
Before project configuration and build, be sure to set the correct chip target using:
|
|
|
|
```bash
|
|
idf.py set-target <chip_name>
|
|
```
|
|
|
|
### Hardware Required
|
|
|
|
* A development board with ESP32/ESP32-C2/ESP32-C3/ESP32-S3 SoC (e.g., ESP32-DevKitC, ESP-WROVER-KIT, etc.)
|
|
* A USB cable for Power supply and programming
|
|
|
|
See [Development Boards](https://www.espressif.com/en/products/devkits) for more information about it.
|
|
|
|
### Configure the Project
|
|
|
|
Open the project configuration menu:
|
|
|
|
```bash
|
|
idf.py menuconfig
|
|
```
|
|
|
|
In the `Example Configuration` menu:
|
|
|
|
* Change the `Peer Address` option if needed.
|
|
* Optional: enable static passkey support via `Component config -> Bluetooth -> NimBLE -> Enable support for Static Passkey`.
|
|
|
|
Static passkey mode is useful for demos where you want to avoid interactive passkey entry.
|
|
When enabled, the example calls `ble_sm_configure_static_passkey(456789, true)` and NimBLE
|
|
automatically injects the passkey during pairing. Update the passkey in
|
|
`examples/bluetooth/nimble/blecent/main/main.c` if you want a different value.
|
|
Both devices must use the same 6-digit passkey, and you should only use a fixed
|
|
passkey for development or controlled environments.
|
|
|
|
### Build and Flash
|
|
|
|
Run `idf.py -p PORT flash monitor` to build, flash and monitor the project.
|
|
|
|
(To exit the serial monitor, type ``Ctrl-]``.)
|
|
|
|
See the [Getting Started Guide](https://idf.espressif.com/) for full steps to configure and use ESP-IDF to build projects.
|
|
|
|
### Configuration Option - EATT
|
|
|
|
There are two key configurations that control the flow of this example regarding EATT:
|
|
|
|
* `MYNEWT_VAL(BLE_EATT_CHAN_NUM)`: This value is the number of EATT channels the user wants to create.
|
|
* `Enable Link Encryption` (`EXAMPLE_ENCRYPTION`): This option, found in `Example Configuration` -> `Enable Link Encryption`, determines whether to enable encryption before performing GATT operations.
|
|
|
|
These configurations affect when the GATT operations (initiated by `peer_disc_all`) begin:
|
|
|
|
1. **Encryption off, EATT off**: GATT operations resume immediately after connection establishment in `BLE_GAP_EVENT_CONNECT`.
|
|
2. **Encryption on, EATT off**: GATT operations resume after encryption is established in `BLE_GAP_EVENT_ENC_CHANGE`.
|
|
3. **Encryption off, EATT on**: GATT operations resume after connection. EATT establishment requires encryption, so with encryption off, EATT bearers cannot be created.
|
|
4. **Encryption on, EATT on**: This is the correct way to use EATT. GATT operations resume in `BLE_GAP_EVENT_EATT`. After connection, the application waits for encryption. Once encrypted, the host automatically attempts to establish EATT bearers. Upon success, the `BLE_GAP_EVENT_EATT` event is triggered, and GATT operations resume.
|
|
|
|
The example uses `ble_att_set_default_bearer_using_cid` to set the CID for upcoming GATT operations. A similar API, `ble_att_get_default_bearer_cid`, can be used to retrieve the current default bearer CID.
|
|
|
|
## Example Output
|
|
|
|
This is the console output on successful connection:
|
|
|
|
```
|
|
I (...) NimBLE_BLE_CENT: BLE Host Task Started
|
|
I (...) NimBLE: GAP procedure initiated: discovery;
|
|
I (...) NimBLE: own_addr_type=0 filter_policy=0 passive=1 limited=0 filter_duplicates=1
|
|
I (...) NimBLE: duration=forever
|
|
I (...) NimBLE:
|
|
|
|
I (...) NimBLE: GAP procedure initiated: connect;
|
|
I (...) NimBLE: peer_addr_type=0 peer_addr=
|
|
I (...) NimBLE: xx:xx:xx:xx:xx:xx
|
|
I (...) NimBLE: scan_itvl=16 scan_window=16 itvl_min=24 itvl_max=40 latency=0 supervision_timeout=256 min_ce_len=0 max_ce_len=0 own_addr_type=0
|
|
I (...) NimBLE:
|
|
|
|
I (...) NimBLE: Connection established
|
|
I (...) NimBLE:
|
|
I (...) NimBLE: GATT procedure initiated: discover all services
|
|
I (...) NimBLE: GATT procedure initiated: discover all characteristics;
|
|
I (...) NimBLE: start_handle=...
|
|
I (...) NimBLE: GATT procedure initiated: discover all descriptors;
|
|
I (...) NimBLE: chr_val_handle=...
|
|
I (...) NimBLE: Service discovery complete; status=0 conn_handle=0
|
|
|
|
I (...) NimBLE: GATT procedure initiated: read;
|
|
I (...) NimBLE: att_handle=<ans_supported_new_alert_cat_handle>
|
|
I (...) NimBLE: Read complete; status=0 conn_handle=0
|
|
I (...) NimBLE: attr_handle=<ans_supported_new_alert_cat_handle> value=
|
|
I (...) NimBLE: 0x00
|
|
I (...) NimBLE:
|
|
|
|
I (...) NimBLE: GATT procedure initiated: write;
|
|
I (...) NimBLE: att_handle=<ans_alert_ctrl_pt_handle> len=2
|
|
I (...) NimBLE: Write complete; status=270 conn_handle=0 attr_handle=<ans_alert_ctrl_pt_handle>
|
|
|
|
I (...) NimBLE: GATT procedure initiated: write;
|
|
I (...) NimBLE: att_handle=<ans_unread_alert_cccd_handle> len=2
|
|
I (...) NimBLE: Subscribe complete; status=0 conn_handle=0 attr_handle=<ans_unread_alert_cccd_handle>
|
|
|
|
I (...) NimBLE: GATT procedure initiated: write;
|
|
I (...) NimBLE: att_handle=<custom_cccd_handle> len=2
|
|
I (...) NimBLE: Subscribe to the custom subscribable characteristic complete; status=0 conn_handle=0
|
|
|
|
I (...) NimBLE: GATT procedure initiated: write;
|
|
I (...) NimBLE: att_handle=<custom_value_handle> len=1
|
|
I (...) NimBLE: Write to the custom subscribable characteristic complete; status=0 conn_handle=0 attr_handle=<custom_value_handle>
|
|
I (...) NimBLE: GATT procedure initiated: read;
|
|
I (...) NimBLE: att_handle=<custom_value_handle>
|
|
I (...) NimBLE: received notification; conn_handle=0 attr_handle=<custom_value_handle> attr_len=1
|
|
I (...) NimBLE: Read complete for the subscribable characteristic; status=0 conn_handle=0
|
|
I (...) NimBLE: attr_handle=<custom_value_handle> value=
|
|
I (...) NimBLE: 0x19
|
|
I (...) NimBLE:
|
|
```
|
|
|
|
`Write complete` status for the ANS Alert Notification Control Point may vary by peer implementation.
|
|
For example, `status=270` can occur while the example still proceeds with subsequent subscribe/read flows.
|
|
|
|
This is the console output on failure (or peripheral does not support New Alert Service category):
|
|
|
|
```
|
|
I (180) BTDM_INIT: BT controller compile version [8e87ec7]
|
|
I (180) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
|
|
I (250) phy: phy_version: 4000, b6198fa, Sep 3 2018, 15:11:06, 0, 0
|
|
I (480) NimBLE_BLE_CENT: BLE Host Task Started
|
|
GAP procedure initiated: stop advertising.
|
|
GAP procedure initiated: discovery; own_addr_type=0 filter_policy=0 passive=1 limited=0 filter_duplicates=1 duration=forever
|
|
GAP procedure initiated: connect; peer_addr_type=1 peer_addr=xx:xx:xx:xx:xx:xx scan_itvl=16 scan_window=16 itvl_min=24 itvl_max=40 latency=0 supervision_timeout=256 min_ce_len=16 max_ce_len=768 own_addr_type=0
|
|
Connection established
|
|
GATT procedure initiated: discover all services
|
|
GATT procedure initiated: discover all characteristics; start_handle=1 end_handle=3
|
|
GATT procedure initiated: discover all characteristics; start_handle=20 end_handle=26
|
|
GATT procedure initiated: discover all characteristics; start_handle=40 end_handle=65535
|
|
GATT procedure initiated: discover all descriptors; chr_val_handle=42 end_handle=43
|
|
GATT procedure initiated: discover all descriptors; chr_val_handle=47 end_handle=65535
|
|
Service discovery complete; status=0 conn_handle=0
|
|
Error: Peer doesn't support the Supported New Alert Category characteristic
|
|
GAP procedure initiated: terminate connection; conn_handle=0 hci_reason=19
|
|
disconnect; reason=534
|
|
```
|
|
|
|
The following configuration flags can be adjusted to significantly reduce RAM usage in your ESP-IDF project while retaining basic BLE functionality.
|
|
|
|
| Config Option | Old → New Value | RAM Saved (Bytes) |
|
|
| ----------------------------------------------- | --------------- | ----------------- |
|
|
| CONFIG_BT_NIMBLE_SM_SC | y → n | 2040 |
|
|
| CONFIG_BT_NIMBLE_LL_CFG_FEAT_LE_ENCRYPTION | y → n | 32 |
|
|
| CONFIG_BT_NIMBLE_GATT_MAX_PROCS | 4 → 2 | 112 |
|
|
| CONFIG_BT_NIMBLE_MAX_CONNECTIONS | 3 → 1 | 480 |
|
|
| CONFIG_BT_NIMBLE_MAX_BONDS | 3 → 1 | 448 |
|
|
| CONFIG_BT_NIMBLE_MAX_CCCDS | 8 → 1 | 112 |
|
|
| CONFIG_BT_NIMBLE_ENABLE_CONN_REATTEMPT | y → n | 256 |
|
|
| CONFIG_BT_NIMBLE_TRANSPORT_EVT_COUNT | 30 → 15 | 240 |
|
|
| CONFIG_BT_NIMBLE_SECURITY_ENABLE | y → n | 2072 |
|
|
| CONFIG_SPI_FLASH_ROM_IMPL | n → y | 9804 |
|
|
| CONFIG_SPI_FLASH_SUPPORT_ISSI_CHIP | y → n | 0 |
|
|
| CONFIG_SPI_FLASH_SUPPORT_MXIC_CHIP | y → n | 140 |
|
|
| CONFIG_SPI_FLASH_SUPPORT_GD_CHIP | y → n | 648 |
|
|
| CONFIG_SPI_FLASH_SUPPORT_WINBOND_CHIP | y → n | 8 |
|
|
| CONFIG_SPI_FLASH_SUPPORT_BOYA_CHIP | y → n | 140 |
|
|
| CONFIG_SPI_FLASH_SUPPORT_TH_CHIP | y → n | 136 |
|
|
| CONFIG_SPI_FLASH_ENABLE_ENCRYPTED_READ_WRITE | y → n | 704 |
|
|
| CONFIG_VFS_SUPPORT_TERMIOS | y → n | 424 |
|
|
| CONFIG_VFS_SUPPORT_IO | y → n | 2008 |
|
|
| CONFIG_COMPILER_OPTIMIZATION_SIZE | n → y | 8408 |
|
|
| CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_DISABLE | n → y | 5896 |
|
|
| CONFIG_ESP_COEX_SW_COEXIST_ENABLE | y → n | 896 |
|
|
| CONFIG_ESP_TASK_WDT_EN | y → n | 528 |
|
|
| CONFIG_LOG_DEFAULT_LEVEL_NONE | n → y | 2592 |
|
|
|
|
## Enhanced Attribute Protocol (EATT)
|
|
|
|
The Enhanced Attribute Protocol (EATT) is an updated version of the Attribute Protocol (ATT) introduced in Bluetooth 5.2. It upgrades the transport mechanism for GATT operations.
|
|
|
|
### How EATT Works in NimBLE
|
|
Unlike legacy ATT, which forces all GATT transactions to be serialized over a single fixed L2CAP channel (CID 4), EATT runs over multiple **L2CAP Enhanced Credit Based Flow Control (ECFC)** channels.
|
|
|
|
1. **Multiple Bearers**: The `MYNEWT_VAL(BLE_EATT_CHAN_NUM)` configuration determines how many parallel L2CAP channels the host will attempt to establish with the peer.
|
|
2. **Concurrency**: In the NimBLE host (`ble_eatt.c`), the `ble_eatt_get_available_chan_cid()` function dynamically selects an idle channel for outgoing GATT requests. This means if Channel A is blocked waiting for a Read Response, the application can still send a Notification immediately on Channel B.
|
|
3. **L2CAP Independence**: Each EATT channel has its own flow control credits and MTU. A stall or large transfer on one channel does not block operations on others.
|
|
|
|
### Implementation Flow
|
|
The setup process in this example follows the logic in `ble_eatt.c`:
|
|
1. **Encryption Trigger**: EATT strictly requires an encrypted link. The host listens for `BLE_GAP_EVENT_ENC_CHANGE`.
|
|
2. **Handshake**: Once encrypted, the host automatically reads the peer's "Server Supported Features" and writes its own "Client Supported Features" to verify EATT support.
|
|
3. **Connection**: The host then initiates L2CAP connections for the number of channels defined in `BLE_EATT_CHAN_NUM`.
|
|
4. **Ready State**: When the channels are established, the application receives `BLE_GAP_EVENT_EATT`, signaling that high-performance, concurrent GATT operations can begin.
|
|
5. **Channel Selection**: The application can direct GATT operations to specific channels using `ble_att_set_default_bearer_using_cid()` or retrieve the current bearer with `ble_att_get_default_bearer_cid()`. This allows precise control over which L2CAP channel executes a transaction.
|
|
|
|
### NimBLE Documentation
|
|
For more detailed information, refer to the NimBLE documentation located in `components/bt/host/nimble/nimble/docs`.
|
|
|
|
To build the documentation with Doxygen:
|
|
```bash
|
|
make clean
|
|
make preview
|
|
```
|
|
|
|
To host the generated documentation locally:
|
|
```bash
|
|
cd _build/html && python3 -m http.server 8080
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon.
|