BluetoothModule

A lightweight Arduino library for BLE (Bluetooth Low Energy) JSON communication on ESP32. Provides a simple, secure interface for receiving JSON messages over BLE with support for multiple callbacks, bonding, and connection management.

Features

• JSON Message Bus: Receive JSON messages over BLE with automatic parsing
• Multiple Callbacks: Register multiple callback functions to handle incoming messages
• Security: Built-in passkey authentication and bonding support
• Connection Management: Configurable maximum client connections
• Automatic Device Naming: Device names include MAC address suffix for unique identification
• MTU Management: Automatic MTU negotiation for efficient data transfer
• Buffer Management: Automatic handling of fragmented messages with timeout protection

Quick Start

#include <Arduino.h>
#include "BluetoothModule/BleJsonBus.h"

// Create BLE JSON Bus instance
BleJsonBus bleBus("MyDevice");

// Callback function to handle received JSON
void onJsonReceive(JsonDocument& doc) {
    Serial.println("Received JSON:");
    
    if (!doc["message"].isNull()) {
        Serial.print("Message: ");
        Serial.println(doc["message"].as<String>());
    }
    
    if (!doc["value"].isNull()) {
        int value = doc["value"].as<int>();
        Serial.print("Value: ");
        Serial.println(value);
    }
}

void setup() {
    Serial.begin(115200);
    delay(1000);
    
    // Start BLE JSON Bus
    bleBus.start();
    
    // Register callback
    bleBus.onReceive(onJsonReceive);
    
    Serial.println("BLE JSON Bus started");
}

void loop() {
    // Your code here
    delay(100);
}

Basic Usage

Creating an Instance

BleJsonBus bleBus("DeviceName");

The device name will be automatically suffixed with the last 2 bytes of the MAC address (e.g., "DeviceName-A1B2").

Starting the Bus

bleBus.start();

This initializes BLE, sets up the service, and starts advertising.

Registering Callbacks

You can register multiple callbacks to handle incoming JSON messages:

// Function callback
void myCallback(JsonDocument& doc) {
    // Handle JSON
}

bleBus.onReceive(myCallback);

// Lambda callback
bleBus.onReceive([](JsonDocument& doc) {
    Serial.println("Received via lambda");
});

// Member function callback
class MyClass {
public:
    void handleJson(JsonDocument& doc) {
        // Handle JSON
    }
};

MyClass obj;
bleBus.onReceive(std::bind(&MyClass::handleJson, &obj, std::placeholders::_1));

Unsubscribing Callbacks

// Get handle when registering
BleJsonBusHandle handle = bleBus.onReceive(myCallback);

// Later, unsubscribe
handle.unsubscribe();

// Or unsubscribe all callbacks
bleBus.clearCallbacks();

Security Configuration

Setting a Passkey

bleBus.setPasskey(123456);  // Must be called before start()

Bonded-Only Mode

By default, bonded-only mode is enabled. To allow connections without bonding:

bleBus.setBondedOnly(false);  // Must be called before start()

Clearing Bonds

bleBus.clearBondsAndResetPasskey();

Connection Management

Maximum Clients

Limit the number of simultaneous connections:

bleBus.setMaxClients(1);  // Default is 1

Message Format

Messages should be sent as newline-delimited JSON strings:

{"key": "value"}\n
{"another": "message"}\n

The library automatically handles:

• Fragmented messages (accumulates until newline)
• Multiple messages in a single BLE packet
• Both \n and \r\n line endings
• Partial frame timeout (500ms)

Requirements

• Arduino IDE 1.8.0 or later
• ESP32 board support
• PlatformIO (recommended) or Arduino IDE
• ArduinoJson library (^7.4.2)
• NimBLE-Arduino library (^2.1.0)

Installation

PlatformIO

Add to your platformio.ini:

lib_deps = 
    bblanchon/ArduinoJson@^7.4.2
    h2zero/NimBLE-Arduino@^2.1.0

Arduino IDE

Install via Library Manager or clone this repository to your Arduino libraries folder.

License

This library is released under the MIT License. See LICENSE file for details.