NimBLE-Arduino

Apache NimBLE is an open-source Bluetooth 5.4 stack (including both Host and Controller) that serves as a replacement for proprietary stacks like Nordic's SoftDevice. It is a component of the Apache Mynewt project.

Key Features:

• Packet Size: Supports up to 251 byte packet sizes.
• Roles: Supports Broadcaster, Observer, Peripheral, and Central roles concurrently.
• Connections: Supports up to 32 simultaneous connections.
• Security: Supports both Legacy and Secure Connections (SC) SMP (pairing and bonding).
• Advanced Bluetooth Features: Includes Advertising Extensions, Periodic Advertising, Coded (Long Range) PHY, and 2M PHY.
• Mesh: Includes support for Bluetooth Mesh.

NimBLE-Arduino supports the following hardware:

• Espressif: ESP32, ESP32C3, ESP32S3, ESP32C6, ESP32H2, ESP32C2, ESP32C5.
• Nordic: nRF51, nRF52 series. Note: Nordic support requires using the n-able arduino core.

Important Note for ESP-IDF users: This repository is designed for Arduino environments and will not compile correctly in ESP-IDF. For ESP-IDF, use the esp-nimble-cpp component instead.

NimBLE hardware support is divided between the Controller and the Host:

• Controller Support: Nordic nRF51, nRF52, and nRF5340 chipsets, as well as Renesas DA1469x (cmac).
• Host Support: Can run on any board or architecture supported by the Apache Mynewt OS.

A device's 'Local Name' is derived from two distinct sources. For consistent behavior across different Operating Systems (like iOS), it is recommended to set both.

1. Advertising "Local name": This is the name seen in scan results before connection. Set this using NimBLEAdvertising::setName().
2. GATT Device Name: This is the characteristic UUID 0x2A00 in the Generic Access service. Set this via NimBLEDevice::init() or NimBLEDevice::setDeviceName(). This is read after connecting.

Important Behaviors:

• Name Switching: If the Advertising name is "ABCD" and the GATT name is "12345", the device appears as "ABCD" while scanning, but the OS will update the name to "12345" once connected.
• Unnamed Devices: If no Advertising name is set, some OSes (like iOS) may display the device as 'Unnamed' until the connection is established and the GATT name is read.

You can customize NimBLE settings (such as increasing the default maximum connections from 3) using two methods:

1. nimconfig.h: Modify the settings directly in the nimconfig.h file within the library.
2. Build Flags: Use Arduino command line options or platformio.ini options to override settings without modifying the library source. See the Command line config for available options.

When CONFIG_BT_NIMBLE_EXT_ADV is enabled, several core classes and behaviors change to support Bluetooth 5 capabilities:

Advertising API Changes

• NimBLEAdvertising is replaced by NimBLEExtAdvertising. Calling NimBLEDevice::getAdvertising() will now return an instance of NimBLEExtAdvertising.
• NimBLEAdvertisementData is replaced by NimBLEExtAdvertisement. This new class is used to configure advertisement intervals and the advertisement ended callback.

Scanning and Connection Changes

• Scanning: NimBLEScan::start automatically scans on both the 1M PHY and the CODED PHY standards.
• Connecting: NimBLEClient::connect uses the primary PHY the device is listening on by default. You can use NimBLEClient::setConnectPhy to specify which PHYs to use for the connection.

Enabling extended advertising provides access to the following Bluetooth 5 features:

• Increased Payload: Supports 251 bytes of advertisement data, and up to 1650 bytes when chained (configuration dependent), compared to the 31 bytes available in legacy advertising.
• New Physical Layers (PHYs):
  • 2M PHY: Faster data rates.
  • CODED PHY: Long-range/slower data rates.
  • 1M PHY: The original standard.
• Periodic Advertising: Allows scanning devices to sync with beacon advertisements, enabling the scanner to sleep between expected advertisement intervals to save power (Note: implementation status may vary).

To use the library in your sketch, include the header and initialize the device in your setup() function.

#include "NimBLEDevice.h"

void setup() {
  NimBLEDevice::init("MyDevice");
  // ... rest of your setup
}

void loop() {
  // ... your loop
}

To test the stream server functionality:

1. Upload the NimBLE_Stream_Server sketch to your ESP32.
2. Look for an advertising device named "NimBLE-Stream" using a BLE scanner.
3. Connect using a BLE client (e.g., the NimBLE_Stream_Client example, nRF Connect, or a Serial Bluetooth Terminal app).
4. Observe the behavior: the server will send periodic messages, echo back received data, and output all communication to the Serial monitor.

When migrating an existing project from the original Bluedroid API to NimBLE, follow these general guidelines:

• Headers: Include NimBLEDevice.h to access all classes. For debugging with NIMBLE_LOGx macros (which behave like ESP_LOGx), include NimBLELog.h.
• Class Names: While NimBLE uses a Nim prefix (e.g., NimBLEDevice), convenience definitions are provided so you can continue using the original names (e.g., BLEDevice) without changing your code.
• BLE Addresses: The BLEAddress constructor now accepts an optional uint8_t type parameter to specify the address type (e.g., 1 for Random). The method getNative() has been renamed to getBase() and returns a pointer to const ble_addr_t.