Usage

SimpleCBLE is the C interface to SimpleBLE. It supports pure C applications and bindings for other languages. Include <simplecble/simplecble.h> for the public API. Existing users should read the migration guide before updating their declarations and data layouts.

System requirements

SimpleCBLE shares the SimpleBLE system requirements. Building the library requires a C++ compiler, even when your application uses only C.

Build SimpleCBLE

From the repository root:

git clone https://github.com/simpleble/simpleble.git
cd simpleble
cmake -S simplecble -B build_simplecble -DCMAKE_BUILD_TYPE=Release
cmake --build build_simplecble

This builds both simplecble and its simpleble dependency. Add -DBUILD_SHARED_LIBS=ON for shared libraries. SIMPLEBLE_LOG_LEVEL controls compiled logging verbosity; the default is INFO.

To install the headers and libraries into a chosen prefix:

cmake --install build_simplecble --prefix /path/to/install

Use libraries built for the same platform and architecture as your application.

Add to a CMake project

For an installed library, use its exported CMake target:

cmake_minimum_required(VERSION 3.21)
project(ble_app LANGUAGES C CXX)

find_package(simplecble CONFIG REQUIRED)
add_executable(ble_app main.c)
target_link_libraries(ble_app PRIVATE simplecble::simplecble)

Configure the application with -DCMAKE_PREFIX_PATH=/path/to/install. The package finds its SimpleBLE dependency automatically.

Alternatively, with a SimpleBLE checkout at vendor/simpleble, use the source targets directly:

cmake_minimum_required(VERSION 3.21)
project(ble_app LANGUAGES C CXX)

add_subdirectory(vendor/simpleble/simplecble)
add_executable(ble_app main.c)
target_link_libraries(ble_app PRIVATE simplecble::simplecble)

CMake supplies the include paths and links the C++ implementation and platform dependencies. Put the scan tutorial in main.c to try it.

For manual or FFI loading, ship the matching SimpleCBLE and SimpleBLE shared libraries and make their dependent libraries discoverable by the platform loader. Match the current headers exactly: opaque handles and array fields are pointers, and lengths/counts use size_t. Use the library's release functions for returned allocations.

Runtime configuration

Set configuration before the first backend or adapter enumeration. Configuration and logging functions do not take an error slot.

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

int main(void) {
    simpleble_config_android_set_connection_priority(SIMPLEBLE_CONFIG_ANDROID_CONNECTION_PRIORITY_HIGH);

    simpleble_error_t* error = NULL;
    size_t count = simpleble_adapter_get_count(&error);
    if (error) {
        fprintf(stderr, "%s\n", simpleble_error_message(error));
        simpleble_error_release(&error);
        return EXIT_FAILURE;
    }
    printf("Available adapters: %zu\n", count);
    return EXIT_SUCCESS;
}

Use backend enumeration when selecting a particular implementation; see Choose a backend.

The public CMake definitions SIMPLEBLE_BACKEND_* describe which backends were built. The simpleble target propagates them to targets that link it; SIMPLEBLE_BACKEND_DONGL is always 1. Runtime enumeration and Bluetooth-status queries determine what is actually available to the application.