| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-S3 | | ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | -------- | # Throughput blecent Example (See the README.md file in the upper level 'examples' directory for more information about examples.) `blecent_throughput` demonstrates client side implementation required for NimBLE throughput example. It connects to `bleprph_throughput` based on name string `nimble_prph`. It has interactive CLI support to start READ/WRITE/NOTIFY GATT operation for user specified time. It performs read operations on the peripheral's `THRPT_LONG_CHR_READ_WRITE` characteristic (510 bytes), write operations on `THRPT_CHR_READ_WRITE` (509-byte payload), and subscribes to `THRPT_CHR_NOTIFY` for notifications. If the user does not specify a throughput test method within 30 seconds (`BLE_RX_TIMEOUT`), the program defaults to READ operations for 60 seconds. `blecent_throughput` uses the `NimBLE` as BLE host. ### Procedure to Use This Demo Example * `idf.py menuconfig` and configure the parameters as needed (connection related parameters in Example Configuration). * The default connection interval is set to 7.5ms (6 units) for maximum throughput. This can be changed via menuconfig or at runtime. * To test throughput on 1M PHY, make sure to disable the Example Configuration -> Enable Extended Adv flag in menuconfig on both sides. * To test on 2M PHY or Coded PHY (S2/S8), you must enable the Example Configuration -> Enable Extended Adv flag on both sides. * `bleprph_throughput` example needs to be run along with this client side example. * After the connection link is established between the two devices, the user is given a window of `YES_NO_PARAM` (5 seconds) to customize connection parameters. If the user has configured parameters from menuconfig, this step can be skipped by either waiting it out or entering `Insert No`. * Enter `Insert Yes` to customize connection parameters. Enter `MTU` and other connection parameters as directed on console instructions, e.g. `MTU 512` for MTU and `conn 6 6 0 500 12 24` for connection parameters in sequence of `min conn_itvl`, `max conn_itvl`, `latency`, `supervision timeout`, `min conn_evt_len` and `max_conn_evt_len`. * The user will be presented with throughput test related console prints. The prints may appear like below ``` ==================================================================================== | Steps to test nimble throughput | | | | 1. Enter throughput [--Type] [--Test time] [--Phy] | | Type: read/write/notify. | | Test time: Enter value in seconds. | | Phy mode: Enter value in 0 for 1M, 1 for 2M ,2 for Coded S2, | | 3 for Coded S8. | | | | e.g. throughput read 600 3 | | | | ** Enter 'throughput read 60 0' for reading char for 60 seconds on 1M phy | | OR 'throughput write 60 1' for writing to char for 60 seconds on 2M phy | | OR 'throughput notify 60 2' for notifications (for 60 seconds on s=2 coded phy)**| | | ===================================================================================== ``` * If the user fails to enter any values within 30 seconds, the app falls to the default behavior of READ for 60 seconds on 1M PHY. * Read and write throughput numbers are displayed on the `blecent_throughput` console. For notification throughput, refer to the `bleprph_throughput` console, as the peripheral is the one sending notifications. Below is sample output: ``` Type 'help' to get the list of commands. Use UP/DOWN arrows to navigate through command history. Press TAB when typing command name to auto-complete. I (1123) CLI: BLE CLI registered I (1123) blecent_throughput: BLE Host Task Started =============================================================================================== | Steps to test nimble throughput | | | | 1. Print 'help' to gain overview of commands | | | I (1163) blecent_throughput: Do you want to configure connection params ? I (1183) blecent_throughput: If yes then enter in this format: `Insert Yes` =============================================================================================== Throughput demo >> GAP procedure initiated: discovery; own_addr_type=0 filter_policy=0 passive=1 limited=0 filter_duplicates=1 duration=forever I (6213) blecent_throughput: Event DISC I (6213) blecent_throughput: connect; fields.num_uuids128 =0 I (6223) blecent_throughput: central connect to `nimble_prph` success GAP procedure initiated: connect; peer_addr_type=1 peer_addr=14:58:11:c1:d0:2d 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 E (36243) blecent_throughput: Error: Connection failed; status = 13 GAP procedure initiated: discovery; own_addr_type=0 filter_policy=0 passive=1 limited=0 filter_duplicates=1 duration=forever I (36293) blecent_throughput: Event DISC I (36293) blecent_throughput: connect; fields.num_uuids128 =0 I (36293) blecent_throughput: Name = nimble_prph ל�j6�^n���� I (36303) blecent_throughput: central connect to `nimble_prph` success GAP procedure initiated: connect; peer_addr_type=0 peer_addr=84:0d:8e:e6:83:de 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 (36393) blecent_throughput: Connection established GATT procedure initiated: exchange mtu GAP procedure initiated: connection parameter update; conn_handle=0 itvl_min=6 itvl_max=6 latency=0 supervision_timeout=500 min_ce_len=8 max_ce_len=768 GATT procedure initiated: discover all services I (36783) blecent_throughput: mtu update event; conn_handle = 0 cid = 4 mtu = 512 GATT procedure initiated: discover all characteristics; start_handle=1 end_handle=5 GATT procedure initiated: discover all characteristics; start_handle=6 end_handle=9 GATT procedure initiated: discover all characteristics; start_handle=10 end_handle=65535 GATT procedure initiated: discover all descriptors; chr_val_handle=8 end_handle=9 GATT procedure initiated: discover all descriptors; chr_val_handle=14 end_handle=15 GATT procedure initiated: discover all descriptors; chr_val_handle=17 end_handle=65535 I (36933) blecent_throughput: Service discovery complete; status=0 conn_handle=0 I (36933) blecent_throughput: Format for throughput demo:: throughput read 100 ==================================================================================== | Steps to test nimble throughput | | | | 1. Enter throughput [--Type] [--Test time] [--Phy] | | Type: read/write/notify. | | Test time: Enter value in seconds. | | Phy mode: Enter value in 0 for 1M, 1 for 2M ,2 for Coded S2, | | 3 for Coded S8. | | | | e.g. throughput read 600 3 | | | | ** Enter 'throughput read 60 0' for reading char for 60 seconds on 1M phy | | OR 'throughput write 60 1' for writing to char for 60 seconds on 2M phy | | OR 'throughput notify 60 2' for notifications (for 60 seconds on s=2 coded phy)**| | | ===================================================================================== Throughput demo >> throughput read 10 I (55333) Throughput demo handler: throughput read 10 GATT procedure initiated: read; att_handle=17 GATT procedure initiated: read; att_handle=17 GATT procedure initiated: read; att_handle=17 GATT procedure initiated: read; att_handle=17 Throughput demo >> GATT procedure initiated: read; att_handle=17 GATT procedure initiated: read; att_handle=17 GATT procedure initiated: read; att_handle=17 GATT procedure initiated: read; att_handle=17 GATT procedure initiated: read; att_handle=17 GATT procedure initiated: read; att_handle=17 GATT procedure initiated: read; att_handle=17 GATT procedure initiated: read; att_handle=17 GATT procedure initiated: read; att_handle=17 GATT procedure initiated: read; att_handle=17 GATT procedure initiated: read; att_handle=17 ``` ### Build and Flash Build the project and flash it to the board, then run monitor tool to view serial output: ``` idf.py -p PORT flash monitor ``` (To exit the serial monitor, type ``Ctrl-]``.) See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects. ## Example Scope This demo example demonstrates stable GATT read/write and notify operations at high throughput. The READ and WRITE GATT operations require an ACK from the peer, so this central app ensures that the next GATT operation is performed after completion of the previous one. For write operations, `ble_gattc_write_no_rsp_flat` is used (Write Without Response) which does not require an ATT-level ACK, allowing higher write throughput. If the mbuf pool is exhausted (`BLE_HS_ENOMEM`), the app yields briefly and retries. For notifications (`bleprph_throughput` sends), the peripheral uses pipelined notification sending with a configurable pipeline depth, allowing the controller to pack multiple PDUs per connection event. Both sides are configured with `CONFIG_BT_NIMBLE_MSYS_1_BLOCK_COUNT=50` to provide sufficient buffer space for high-throughput operations. ## Example output The `Procedure to use this demo example` section above covers initial console outputs. In this section we provide final console output depicting throughput numbers ``` GATT procedure initiated: read; att_handle=17 GATT procedure initiated: read; att_handle=17 GATT procedure initiated: read; att_handle=17 GATT procedure initiated: read; att_handle=17 **************************************************************** I (65363) blecent_throughput: Application Read throughput = 106800 bps, Read op counter = 268 **************************************************************** ```