Tutorial

This tutorial will guide you through the basics of using SimpleCBLE to scan for and connect to Bluetooth Low Energy devices.

Header Files

To use SimpleCBLE, you need to include the main header file:

#include <simplecble/simpleble.h>

Initialization

There is no global initialization function, but you should usually start by getting the list of adapters.

Adapters

Everything in SimpleBLE starts with an adapter. You can check if Bluetooth is enabled and list available adapters.

#include <stdio.h>
#include <simplecble/simpleble.h>

int main() {
    // Check if Bluetooth is enabled
    if (!simpleble_adapter_is_bluetooth_enabled()) {
        printf("Bluetooth is not enabled.
");
        return 1;
    }

    // Get the number of adapters
    size_t adapter_count = simpleble_adapter_get_count();
    if (adapter_count == 0) {
        printf("No adapters found.
");
        return 1;
    }

    // Get the handle for the first adapter
    // Note: You must release this handle when done!
    simpleble_adapter_t adapter = simpleble_adapter_get_handle(0);

    if (adapter == NULL) {
        printf("Failed to get adapter handle.
");
        return 1;
    }

    // Get adapter details
    char* identifier = simpleble_adapter_identifier(adapter);
    char* address = simpleble_adapter_address(adapter);

    printf("Adapter: %s [%s]
", identifier, address);

    // Clean up strings
    simpleble_free(identifier);
    simpleble_free(address);

    // Clean up adapter handle
    simpleble_adapter_release_handle(adapter);

    return 0;
}

Scanning

To scan for peripherals, you use simpleble_adapter_scan_for or the async methods.

// Start scanning for 5 seconds (5000 ms)
simpleble_adapter_scan_for(adapter, 5000);

// Get results
size_t results_count = simpleble_adapter_scan_get_results_count(adapter);

for (size_t i = 0; i < results_count; i++) {
    // Get peripheral handle
    // Note: You must release this handle when done!
    simpleble_peripheral_t peripheral = simpleble_adapter_scan_get_results_handle(adapter, i);

    char* identifier = simpleble_peripheral_identifier(peripheral);
    char* address = simpleble_peripheral_address(peripheral);
    int16_t rssi = simpleble_peripheral_rssi(peripheral);

    printf("Found: %s [%s] RSSI: %d
", identifier, address, rssi);

    simpleble_free(identifier);
    simpleble_free(address);
    simpleble_peripheral_release_handle(peripheral);
}

Connecting

To connect, you need a peripheral handle.

simpleble_peripheral_t peripheral = simpleble_adapter_scan_get_results_handle(adapter, 0);

if (simpleble_peripheral_connect(peripheral) == SIMPLEBLE_SUCCESS) {
    printf("Connected!
");

    // Do something...

    simpleble_peripheral_disconnect(peripheral);
} else {
    printf("Failed to connect.
");
}

simpleble_peripheral_release_handle(peripheral);

Services and Characteristics

Once connected, you can explore services and characteristics.

size_t services_count = simpleble_peripheral_services_count(peripheral);

for (size_t i = 0; i < services_count; i++) {
    simpleble_service_t service;
    if (simpleble_peripheral_services_get(peripheral, i, &service) == SIMPLEBLE_SUCCESS) {
        printf("Service UUID: %s
", service.uuid.value);

        for (size_t j = 0; j < service.characteristic_count; j++) {
            printf("  Characteristic UUID: %s
", service.characteristics[j].uuid.value);
        }
    }
}

Reading and Writing

(Add examples for reading/writing using simpleble_peripheral_read, simpleble_peripheral_write_request, etc.)

Notifications

(Add example for simpleble_peripheral_notify)

Memory Management

It is critical to release handles and free strings returned by the library.

Use simpleble_free() for any string (char*) returned by the API.
Use simpleble_adapter_release_handle() for simpleble_adapter_t.
Use simpleble_peripheral_release_handle() for simpleble_peripheral_t.

Failure to do so will result in memory leaks.