Crate esp32_nimble

source ·
Expand description

§NimBLE Rust wrapper for ESP32

crates.io build License Documentation

This is a Rust wrapper for the NimBLE Bluetooth stack for ESP32. Inspired by NimBLE-Arduino.

§Usage

Add below settings to your project’s sdkconfig.defaults.

CONFIG_BT_ENABLED=y
CONFIG_BT_BLE_ENABLED=y
CONFIG_BT_BLUEDROID_ENABLED=n
CONFIG_BT_NIMBLE_ENABLED=y
  • To enable Extended advertising, additionally append CONFIG_BT_NIMBLE_EXT_ADV=y.
    (For use with ESP32C3, ESP32S3, ESP32H2 ONLY)

§Increasing esp-ble task stack size for heavier compute loads

In case you’re computing large(-ish) values to return via bluetooth le or if you’re running complicated / deeply nested code, you may have to increase the esp-ble task’s stack size. To do so, add the below setting to your project’s sdconfig.defaults

CONFIG_BT_NIMBLE_HOST_TASK_STACK_SIZE=7000

The default is defined in The ESP-IDf documentation and may vary between 4096 or 5120, depending on your settings.

§Configuring for iOS Auto-Reconnection

To enable seamless auto-reconnection of iOS devices with your ESP32 BLE server, you need to adjust settings in both the sdkconfig file and your Rust code.

§Update sdkconfig

Include this line in your sdkconfig:

CONFIG_BT_NIMBLE_NVS_PERSIST=y

Setting CONFIG_BT_NIMBLE_NVS_PERSIST to y ensures that bonding information is saved in the device’s Non-Volatile Storage (NVS). This step is crucial for allowing iOS devices to automatically reconnect without the need for rebonding after the ESP32 has been reset or powered off and on again.

§Configure Security Options in Rust Code

Properly setting the security options in your Rust implementation is key:

device
  .security()
  .set_auth(AuthReq::Bond) // Bonding enables key storage for reconnection
  .set_passkey(123456) // Optional, sets the passkey for pairing
  .set_io_cap(SecurityIOCap::NoInputNoOutput) // You can choose any IO capability
  .resolve_rpa(); // Crucial for managing iOS's dynamic Bluetooth addresses
  • .set_auth(AuthReq::Bond) sets up bonding, crucial for storing security keys that enable future automatic reconnections.
  • .resolve_rpa(): This function is essential for adapting to the changing Bluetooth addresses used by iOS devices, a feature known as Resolvable Private Address (RPA). It’s vital for maintaining reliable and seamless connections with iOS devices, ensuring that your ESP32 device can recognize and reconnect to an iOS device even when its Bluetooth address changes.
  • BLE Passkeys are exactly 6 digits by spec, so if you set a passkey of ‘1234’ it is actually ‘001234’ so to properly display the code to a user you must pad the left i.e. format!("{:0>6}",pkey)

Modules§

Macros§

  • uuid128
    Parse Uuid128 from string literals at compile time.

Structs§

Enums§