WiBLE - Your Gateway Between BLE and Wi-Fi

A production-grade, secure, and scalable BLE provisioning library for ESP32/ESP32-C6

Features • Quick Start • Documentation • Examples • Contributing

🎯 Overview

WiBLE is a next-generation provisioning framework that seamlessly combines Bluetooth Low Energy (BLE) and Wi-Fi connectivity into a unified, developer-friendly library. It enables IoT devices to be configured securely and reliably through mobile apps, eliminating the complexity of manual network setup.

Why WiBLE?

Feature	Traditional Approach	WiBLE
Security	Basic or None	ECDH + AES-256 by default
Error Handling	Manual retries	Automatic with exponential backoff
State Management	Boolean flags	Finite State Machine (FSM)
Connection Time	30-60s	< 18s
Testing	Manual only	Unit + Integration tests
Documentation	Basic README	Comprehensive API docs

✨ Features

🔒 Security First

ECDH Key Exchange - Perfect Forward Secrecy
AES-256 Encryption - Military-grade credential protection
Multiple Security Levels - From hobbyist to enterprise
Secure Storage - Encrypted credentials in NVS

🚀 Performance Optimized

< 18s Total Provisioning - 50% faster than alternatives
MTU Negotiation - Up to 512 bytes per packet
Chunked Transfer - Handle large data seamlessly
Connection Pooling - Multi-device support

🛡️ Production Ready

Finite State Machine - Predictable state transitions
Circuit Breaker - Prevent cascading failures
Auto-Reconnect - WiFi resilience with exponential backoff
Comprehensive Logging - Structured, filterable logs

👨‍💻 Developer Friendly

Simple API - 5 lines to get started
Event-Driven - Reactive callbacks
80+ Unit Tests - High code quality
Rich Examples - Learn by doing

📦 Partition Scheme (Critical!)

WiBLE requires a larger app partition than the default. The combined size of the WiFi stack, BLE stack (Bluedroid), and security libraries exceeds the standard 1.3MB app partition.

Arduino IDE

Go to Tools > Partition Scheme.
Select "Huge APP (3MB No OTA/1MB SPIFFS)" or "Minimal SPIFFS (1.9MB APP with OTA)".

PlatformIO

Add this to your platformio.ini:

board_build.partitions = huge_app.csv
; OR for OTA support:
; board_build.partitions = min_spiffs.csv

🚀 Quick Start

1. Installation

PlatformIO (Recommended)

[env:esp32]
platform = espressif32
board = esp32dev
framework = arduino
lib_deps = 
    Chamath-Adithya/WiBLE@^2.0.0

Arduino IDE

Download latest release from GitHub Releases
Extract to Arduino/libraries/WiBLE/
Restart Arduino IDE

2. Basic Example

#include <WiBLE.h>

using namespace WiBLE;
WiBLE provisioner;

void setup() {
    Serial.begin(115200);
    
    // Configure library
    ProvisioningConfig config;
    config.deviceName = "MyIoTDevice";
    config.securityLevel = SecurityLevel::SECURE;
    
    // Initialize
    provisioner.begin(config);
    
    // Register callbacks
    provisioner.onWiFiConnected([](String ssid, String ip) {
        Serial.printf("Connected to %s with IP %s\n", ssid.c_str(), ip.c_str());
    });
    
    provisioner.onError([](ErrorCode code, String msg, bool canRetry) {
        Serial.printf("Error: %s\n", msg.c_str());
    });
    
    // Start provisioning
    provisioner.startProvisioning();
}

void loop() {
    provisioner.loop();  // CRITICAL: Call every iteration
}

3. Mobile App Setup

Download WiBLE Companion App:
- iOS App Store
- Google Play Store
Open app and scan for devices
Select your device
Enter WiFi credentials
Wait for provisioning to complete

📖 Documentation

Architecture

WiBLE uses a five-layer architecture for maximum flexibility:

graph TD
    App["Application Layer (Your Code)"] --> Core["Core Services Layer"]
    
    subgraph Core ["Core Services Layer"]
        State["State Machine"]
        Sec["Security Manager"]
        Orch["Provisioning Orchestrator"]
    end
    
    Core --> Proto["Protocol Layer"]
    
    subgraph Proto ["Protocol Layer"]
        BLE["BLE Manager"]
        WiFi["WiFi Manager"]
    end
    
    Proto --> HAL["Platform Abstraction Layer (ESP32 APIs)"]
    
    Cross["Cross-Cutting Concerns"] -.-> Core
    Cross -.-> Proto

Key Components

1. State Machine

Manages provisioning lifecycle with predictable transitions:

IDLE → BLE_ADVERTISING → BLE_CONNECTED → AUTHENTICATING
  → RECEIVING_CREDENTIALS → CONNECTING_WIFI → PROVISIONED

2. Security Manager

Handles all cryptographic operations:

ECDH-P256 key exchange
AES-256-CBC/GCM encryption
HMAC-SHA256 message authentication
Secure random number generation

3. BLE Manager

Manages Bluetooth operations:

GATT service/characteristic handling
MTU negotiation (up to 512 bytes)
Operation queue (serialized GATT ops)
RSSI monitoring

4. WiFi Manager

Handles network connectivity:

Network scanning
Connection with retry logic
Auto-reconnect with circuit breaker
Multi-network support

🎓 Examples

Basic Provisioning

Simple example showing minimal setup:

examples/BasicProvisioning/BasicProvisioning.ino

More Examples (Coming Soon)

Secure Provisioning: Advanced security with PIN authentication
Multi-Device: Provision multiple devices simultaneously
Custom Protocol: Extend provisioning with custom data
Background Operation: Long-running provisioning with power management

🔧 Configuration

Security Levels

// No encryption (dev only)
config.securityLevel = SecurityLevel::NONE;

// Basic pairing
config.securityLevel = SecurityLevel::BASIC;

// ECDH + AES-256 (recommended)
config.securityLevel = SecurityLevel::SECURE;

// Certificate pinning + AES-256-GCM
config.securityLevel = SecurityLevel::ENTERPRISE;

Connection Parameters

// Fast provisioning (high power)
config.connectionInterval = 24;      // 30ms
config.mtuSize = 512;
config.enablePowerSaving = false;

// Power-efficient (slower)
config.connectionInterval = 80;      // 100ms
config.mtuSize = 185;
config.enablePowerSaving = true;

WiFi Settings

config.wifiConnectTimeoutMs = 20000;  // 20s
config.wifiMaxRetries = 3;
config.autoReconnect = true;
config.persistCredentials = true;     // Save to NVS

🧪 Testing

Run Unit Tests

# PlatformIO
pio test -e native

# Arduino
# Use Arduino IDE's built-in test runner

Run Integration Tests

pio test -e esp32

Test Coverage

# Generate coverage report
pio test -e native --coverage
lcov --capture --directory .pio/build/native --output-file coverage.info
genhtml coverage.info --output-directory coverage_html

Current coverage: 85% (target: 80%)

📊 Performance Metrics

Provisioning Time

Phase	Time	Optimizations
BLE Scan	2-3s	Pre-scanning
BLE Connection	1-2s	Fast intervals
Authentication	1-2s	ECDH caching
Credential Transfer	0.5-1s	MTU 512
WiFi Connection	5-10s	Retry backoff
Total	10-18s	50% improvement

Memory Usage

Component	RAM	Flash
WiBLE Core	45KB	180KB
BLE Stack	50KB	200KB
WiFi Stack	40KB	150KB
Total	135KB	530KB

Power Consumption

State	Current	Duration
BLE Advertising	25mA	Variable
BLE Connected	20mA	5-10s
WiFi Connecting	100mA	5-10s
WiFi Connected	80mA	Continuous
Deep Sleep	10μA	When idle

🔍 Debugging

Enable Verbose Logging

config.logLevel = LogLevel::VERBOSE;
config.enableSerialLog = true;

Dump State Information

provisioner.dumpState();

Output:

Current State: BLE_CONNECTED
Previous State: BLE_ADVERTISING
Time in State: 5234ms
BLE Connected: true
WiFi Connected: false
Secure Session: true
MTU: 512 bytes

Monitor Metrics

auto metrics = provisioner.getMetrics();
Serial.printf("Success Rate: %.1f%%\n", 
    (float)metrics.successfulProvisionings / 
    metrics.totalProvisioningAttempts * 100);

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development Setup

# Clone repository
git clone https://github.com/Chamath-Adithya/WiBLE.git
cd wible

# Install dependencies
pio lib install

# Build
pio run -e esp32

# Run tests
pio test -e native

# Format code
pio run -t format

# Note: If running locally, ensure you have PlatformIO installed.
# You may need to use a virtual environment if your system manages python packages externally:
# python3 -m venv venv
# source venv/bin/activate
# pip install platformio
# pio run -e esp32

Code Style

Follow Google C++ Style Guide
Use clang-format for formatting
Write tests for new features
Update documentation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Author

Chamath Adithya - SOLVEO

Email: achamth1@gmail.com
GitHub: Chamath-Adithya

🙏 Acknowledgments

Built on insights from:

❓ Frequently Asked Questions (FAQ)

How do I provision an ESP32 using Bluetooth?

WiBLE makes it easy. Simply include the library, set the security level, and call provisioner.startProvisioning(). The device will advertise via BLE, allowing your mobile app to connect and send WiFi credentials securely.

Is WiBLE secure?

Yes! WiBLE uses ECDH (Elliptic Curve Diffie-Hellman) for key exchange and AES-256 for encryption. This ensures that your WiFi credentials are never exposed in plain text over the air.

Does it support ESP32-C3 and ESP32-S3?

Yes, WiBLE supports all ESP32 variants including ESP32-C3, ESP32-S3, and ESP32-C6, as long as they support Bluetooth Low Energy.

Can I use this with Arduino IDE?

Absolutely. WiBLE is fully compatible with the Arduino framework and can be installed via the Library Manager or by downloading the release from GitHub.

📞 Support

📧 Email: achamth1@gmail.com
💬 Discord: Join our community
🐛 Issues: GitHub Issues
📖 GitHub: WiBLE Repository

🗺️ Roadmap

v2.1 (Q2 2025)

Bluetooth Mesh support
Matter/Thread integration
Flutter SDK
React Native SDK

v2.2 (Q3 2025)

OTA firmware updates
Cloud integration (AWS IoT, Azure)
Analytics dashboard
Multi-language support

v3.0 (Q4 2025)

BLE 5.3 features
Kubernetes deployment
Edge computing support
AI-powered diagnostics

📈 Statistics

Built with ❤️ by SOLVEO

Name		Name	Last commit message	Last commit date
Latest commit History 84 Commits
.github		.github
docs		docs
examples		examples
src		src
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
keywords.txt		keywords.txt
library.properties		library.properties
platformio.ini		platformio.ini
release_notes.md		release_notes.md

License

Chamath-Adithya/WiBLE

Folders and files

Latest commit

History

Repository files navigation

WiBLE - Your Gateway Between BLE and Wi-Fi

🎯 Overview

Why WiBLE?

✨ Features

🔒 Security First

🚀 Performance Optimized

🛡️ Production Ready

👨‍💻 Developer Friendly

📦 Partition Scheme (Critical!)

Arduino IDE

PlatformIO

🚀 Quick Start

1. Installation

PlatformIO (Recommended)

Arduino IDE

2. Basic Example

3. Mobile App Setup

📖 Documentation

Architecture

Key Components

1. State Machine

2. Security Manager

3. BLE Manager

4. WiFi Manager

🎓 Examples

Basic Provisioning

More Examples (Coming Soon)

🔧 Configuration

Security Levels

Connection Parameters

WiFi Settings

🧪 Testing

Run Unit Tests

Run Integration Tests

Test Coverage

📊 Performance Metrics

Provisioning Time

Memory Usage

Power Consumption

🔍 Debugging

Enable Verbose Logging

Dump State Information

Monitor Metrics

🤝 Contributing

Development Setup

Code Style

📄 License

👥 Author

🙏 Acknowledgments

❓ Frequently Asked Questions (FAQ)

How do I provision an ESP32 using Bluetooth?

Is WiBLE secure?

Does it support ESP32-C3 and ESP32-S3?

Can I use this with Arduino IDE?

📞 Support

🗺️ Roadmap

v2.1 (Q2 2025)

v2.2 (Q3 2025)

v3.0 (Q4 2025)

📈 Statistics

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages