SimpleBLE

https://docs.simpleble.org
Admin
SimpleBLE is a cross-platform Bluetooth Low Energy library with bindings for multiple languages,...
Tokens:151,413
Snippets:1,284
Trust Score:6
Update:1 week ago
Show doc for...
Tokens:
Raw
### void start()

Source: https://docs.simpleble.org/simpleble/api

Starts advertising the peripheral.

```APIDOC
## void start()

### Description
Starts advertising the peripheral. This makes the peripheral discoverable by remote devices.

### Method
Member function

### Signature
void start()
```

--------------------------------

### Install with Sudo Privileges

Source: https://docs.simpleble.org/simpledbus/usage

Run the installation command with elevated privileges for system-wide installation.

```bash
sudo cmake --install build_simpledbus
```

--------------------------------

### CMakeLists.txt for SimpleBLE quickstart

Source: https://docs.simpleble.org/simpleble/tutorial

CMake configuration for a SimpleBLE quickstart project. Requires CMake 3.21 or later, C++17, and the installed SimpleBLE package. Links the executable to simpleble::simpleble.

```cmake
cmake_minimum_required(VERSION 3.21)
project(simpleble_quickstart LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

find_package(simpleble REQUIRED CONFIG)

add_executable(simpleble_quickstart src/main.cpp)
target_link_libraries(simpleble_quickstart PRIVATE simpleble::simpleble)
```

--------------------------------

### Core scan call in Python

Source: https://docs.simpleble.org/recipes/scan

Python example using simplepyble to get the first adapter, set a scan-found callback, scan for 5000 ms, and print connectable peripherals from the results.

```Python
adapter = simplepyble.Adapter.get_adapters()[0]

adapter.set_callback_on_scan_found(
    lambda peripheral: print(f"Found {peripheral.identifier()} [{peripheral.address()}]")
)

adapter.scan_for(5000)

for peripheral in adapter.scan_get_results():
    if peripheral.is_connectable():
        print(f"{peripheral.identifier()} is connectable")
```

--------------------------------

### Core scan call in Java

Source: https://docs.simpleble.org/recipes/scan

Java example using Adapter.getAdapters() to get the first adapter, set an EventListener for onScanFound, scan for 5000 ms, and print connectable peripherals from scanGetResults().

```Java
Adapter adapter = Adapter.getAdapters().get(0);

adapter.setEventListener(new Adapter.EventListener() {
    @Override
    public void onScanFound(Peripheral peripheral) {
        System.out.println("Found " + peripheral.getIdentifier() + " [" + peripheral.getAddress() + "]");
    }
});

adapter.scanFor(5000);

for (Peripheral peripheral : adapter.scanGetResults()) {
    if (peripheral.isConnectable()) {
        System.out.println(peripheral.getIdentifier() + " is connectable");
    }
}
```

--------------------------------

### Install SimpleAIBLE

Source: https://docs.simpleble.org/installation

Commands to install the tool using uv or pip.

```bash
uv tool install simpleaible
```

```bash
pip install simpleaible
```

--------------------------------

### Build and install C wrapper from source

Source: https://docs.simpleble.org/installation

Commands to clone, build, and install the C wrapper library.

```bash
git clone https://github.com/simpleble/simpleble.git
cd simpleble

cmake -S simplecble -B build_simplecble
cmake --build build_simplecble -j
cmake --install build_simplecble --prefix "$PWD/install_simplecble"
```

--------------------------------

### Core scan call in C++

Source: https://docs.simpleble.org/recipes/scan

C++ example using SimpleBLE::Adapter to get adapters, set a scan-found callback, scan for 5000 ms, and print connectable peripherals from the results.

```C++
auto adapters = SimpleBLE::Adapter::get_adapters();
auto adapter = adapters.front();

adapter.set_callback_on_scan_found([](SimpleBLE::Peripheral peripheral) {
    std::cout << "Found " << peripheral.identifier()
              << " [" << peripheral.address() << "]" << std::endl;
});

adapter.scan_for(5000);

for (auto& peripheral : adapter.scan_get_results()) {
    if (peripheral.is_connectable()) {
        std::cout << peripheral.identifier() << " is connectable." << std::endl;
    }
}
```

--------------------------------

### Create and start a local peripheral with a GATT service

Source: https://docs.simpleble.org/simpleble/peripheral/advertise-serve-publish

Creates a local peripheral from the first adapter, adds an advertised service and a characteristic with READ, WRITE_REQUEST, and NOTIFY capabilities, sets an initial value, and starts the peripheral. Configuration must be done before start(); set_value() and callbacks are the only ways to change data after start.

```cpp
auto adapters = SimpleBLE::Adapter::get_adapters();
auto adapter = adapters.front();
auto peripheral = adapter.create_local_peripheral();

peripheral.add_advertised_service("12345678-1234-5678-1234-56789abcdef0");

auto service = peripheral.add_service("12345678-1234-5678-1234-56789abcdef0");
auto characteristic = service.add_characteristic(
    "12345678-1234-5678-1234-56789abcdef1",
    {SimpleBLE::Local::CharacteristicCapability::READ,
     SimpleBLE::Local::CharacteristicCapability::WRITE_REQUEST,
     SimpleBLE::Local::CharacteristicCapability::NOTIFY});
characteristic.set_value(SimpleBLE::ByteArray("ready"));

peripheral.start();
```

--------------------------------

### Runtime configuration example

Source: https://docs.simpleble.org/simplecble/usage

Example of setting Android connection priority and enumerating adapters in C.

```c
#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;
}
```

--------------------------------

### Install SimpleBLE with cmake --install

Source: https://docs.simpleble.org/simpleble/usage

Install the built library using the default installation prefix.

```bash
cmake --install build_simpleble
```

--------------------------------

### Install SimpleDBus

Source: https://docs.simpleble.org/simpledbus/usage

Standard command to install the built library.

```bash
cmake --install build_simpledbus
```

--------------------------------

### Build SimpleCBLE examples with CMake

Source: https://docs.simpleble.org/simplecble/examples

Builds the SimpleCBLE examples using CMake. Run the executables from build_examples/bin.

```bash
cmake -S examples/simplecble -B build_examples
cmake --build build_examples
```

--------------------------------

### Install SimpleCBLE headers and libraries

Source: https://docs.simpleble.org/simplecble/usage

Command to install the built headers and libraries to a specific prefix.

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

--------------------------------

### Install documentation dependencies

Source: https://docs.simpleble.org/extras

Install the required dependencies for the documentation site using npm or bun.

```bash
cd <path-to-repository>/docs
npm install
# or
bun install
```

--------------------------------

### Install Python binding from local checkout

Source: https://docs.simpleble.org/installation

Commands to install from a local source repository.

```bash
git clone https://github.com/simpleble/simpleble.git
cd simpleble
pip install .
```

--------------------------------

### Install SimplePyBLE locally

Source: https://docs.simpleble.org/simplepyble/usage

Steps to install the library from a local repository clone.

```bash
cd <path-to-simpleble>/simplepyble
pip install .
```

--------------------------------

### Run scan example

Source: https://docs.simpleble.org/simplersble/examples

Command to execute the scan example from the repository root using cargo.

```bash
cargo run --manifest-path examples/simplersble/Cargo.toml --bin scan
```

--------------------------------

### simpleble_local_peripheral_start

Source: https://docs.simpleble.org/simplecble/api

Starts the local peripheral.

```APIDOC
## simpleble_local_peripheral_start

### Description
Starts the local peripheral.

### Function Signature
```c
void simpleble_local_peripheral_start(simpleble_local_peripheral_t handle, simpleble_error_t** out_error)
```

### Parameters
- **handle** (simpleble_local_peripheral_t) - Required - The local peripheral handle.
- **out_error** (simpleble_error_t**) - Optional - Pointer to store error information.

### Returns
void
```

--------------------------------

### Install with a custom prefix

Source: https://docs.simpleble.org/fundamentals/cmake_primer

Specify a custom installation directory using the --prefix flag.

```bash
cmake --install <your-build-directory> --prefix <your-installation-directory>
```

--------------------------------

### Host a local GATT service with simpleble_adapter_create_local_peripheral

Source: https://docs.simpleble.org/simplecble/tutorial

Creates a local peripheral, adds an advertised service and a readable/notifiable characteristic, then starts advertising. The example stores a value and enables notifications; the application retains ownership of the input buffer. Each returned local handle requires its matching release function. Stop the host before releasing it. A backend without local hosting reports SIMPLEBLE_ERROR_OPERATION_NOT_SUPPORTED.

```c
bool host_service(simpleble_adapter_t adapter) {
    simpleble_error_t* error = NULL;
    const simpleble_uuid_t service_uuid = {"12345678-1234-5678-1234-56789abcdef0"};
    const simpleble_uuid_t characteristic_uuid = {"12345678-1234-5678-1234-56789abcdef1"};

    simpleble_local_peripheral_t host = simpleble_adapter_create_local_peripheral(adapter, &error);
    if (!error) simpleble_local_peripheral_add_advertised_service(host, service_uuid, &error);

    simpleble_local_service_t service = NULL;
    if (!error) service = simpleble_local_peripheral_add_service(host, service_uuid, &error);

    simpleble_local_characteristic_t characteristic = NULL;
    if (!error) {
        characteristic = simpleble_local_service_add_characteristic(
            service, characteristic_uuid,
            SIMPLEBLE_LOCAL_CHARACTERISTIC_READ | SIMPLEBLE_LOCAL_CHARACTERISTIC_NOTIFY, &error);
    }

    const uint8_t value[] = {'r', 'e', 'a', 'd', 'y'};
    if (!error) simpleble_local_characteristic_set_value(characteristic, value, sizeof(value), &error);
    if (!error) simpleble_local_peripheral_start(host, &error);
    if (!error) {
        printf("Advertising. Press Enter to stop.\n");
        getchar();
        simpleble_local_peripheral_stop(host, &error);
    }

    bool success = error == NULL;
    if (error) fprintf(stderr, "%s\n", simpleble_error_message(error));
    simpleble_local_characteristic_release_handle(characteristic);
    simpleble_local_service_release_handle(service);
    simpleble_local_peripheral_release_handle(host);
    simpleble_error_release(&error);
    return success;
}
```

--------------------------------

### Install SimpleBluez

Source: https://docs.simpleble.org/simplebluez/usage

Installs the built SimpleBluez library to the default location.

```bash
cmake --install build_simplebluez
```

--------------------------------

### Core scan call in C

Source: https://docs.simpleble.org/recipes/scan

C example using simplecble to get an adapter handle, scan for 5000 ms, and iterate over scan results, printing each peripheral's identifier. Includes error handling with simpleble_error_t.

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

int main(void) {
    simpleble_error_t* error = NULL;
    simpleble_adapter_t adapter = simpleble_adapter_get_handle(0, &error);
    if (error) {
        fprintf(stderr, "%s\n", simpleble_error_message(error));
        simpleble_error_release(&error);
        return EXIT_FAILURE;
    }

    simpleble_adapter_scan_for(adapter, 5000, &error);
    if (!error) {
        size_t count = simpleble_adapter_scan_get_results_count(adapter, &error);
        for (size_t i = 0; i < count && !error; i++) {
            simpleble_peripheral_t peripheral = simpleble_adapter_scan_get_results_handle(adapter, i, &error);
            if (error) break;

            char* identifier = simpleble_peripheral_identifier(peripheral, &error);
            if (!error) printf("Found: %s\n", identifier);
            simpleble_free(identifier);
            simpleble_peripheral_release_handle(peripheral);
        }
    }

    int result = error ? EXIT_FAILURE : EXIT_SUCCESS;
    if (error) fprintf(stderr, "%s\n", simpleble_error_message(error));
    simpleble_error_release(&error);
    simpleble_adapter_release_handle(adapter);
    return result;
}
```

--------------------------------

### Install SimpleAIBLE via uv

Source: https://docs.simpleble.org/simpleaible/tutorial

Installs the SimpleAIBLE MCP server using the uv tool.

```bash
uv tool install simpleaible
```

--------------------------------

### Build and install C++ library from source

Source: https://docs.simpleble.org/installation

Commands to clone, build, and install the C++ library using CMake.

```bash
git clone https://github.com/simpleble/simpleble.git
cd simpleble

cmake -S simpleble -B build_simpleble
cmake --build build_simpleble -j
cmake --install build_simpleble --prefix "$PWD/install_simpleble"
```

--------------------------------

### Install BlueZ and D-Bus on Ubuntu

Source: https://docs.simpleble.org/simplesharpble/usage

Installs required system dependencies for SimpleSharpBLE on Ubuntu. Requires sudo privileges.

```bash
sudo apt-get install bluez libdbus-1-3
```

--------------------------------

### Configure and install with a persistent prefix

Source: https://docs.simpleble.org/fundamentals/cmake_primer

Set the installation prefix during the configuration phase to make it persistent for subsequent build and install commands.

```bash
cmake -S <path-to-source> -B <your-build-directory> -DCMAKE_INSTALL_PREFIX=<your-installation-directory>
cmake --build <your-build-directory> -j4
cmake --install <your-build-directory>
```

--------------------------------

### Install and run SimpleAIBLE HTTP server

Source: https://docs.simpleble.org/simpleaible/http

Install the simpleaible package and then run the built-in HTTP server, which by default listens on http://127.0.0.1:8000. The server command specifies host and port options.

```bash
pip install simpleaible
```

```bash
python3 -m simpleaible.http --host 127.0.0.1 --port 8000
```

--------------------------------

### Install Python binding

Source: https://docs.simpleble.org/installation

Command to install the Python package from PyPI.

```bash
pip install simplepyble
```

--------------------------------

### Install with administrative privileges

Source: https://docs.simpleble.org/fundamentals/cmake_primer

Use sudo when installing to system directories on Linux or MacOS.

```bash
sudo cmake --install <your-build-directory>
```

--------------------------------

### Install SimpleBLE with sudo

Source: https://docs.simpleble.org/simpleble/usage

On Linux and MacOS, run cmake --install with sudo privileges.

```bash
sudo cmake --install build_simpleble
```

--------------------------------

### Build SimpleBluez examples with CMake

Source: https://docs.simpleble.org/simplebluez/usage

Configure and build the SimpleBluez examples using CMake. Requires the path to the SimpleBluez source and enables the SIMPLEBLUEZ_LOCAL option.

```bash
cmake -S <path-to-simplebluez>/examples/simplebluez -B build_simplebluez_examples -DSIMPLEBLUEZ_LOCAL=ON
cmake --build build_simplebluez_examples -j7
```

--------------------------------

### Build SimpleDBus examples with CMake

Source: https://docs.simpleble.org/simpledbus/usage

Configure and build the SimpleDBus examples using CMake. Requires the SIMPLEDBUS_LOCAL=ON option to use the local SimpleDBus source.

```bash
cmake -S <path-to-simpledbus>/examples/simpledbus -B build_simpledbus_examples -DSIMPLEDBUS_LOCAL=ON
cmake --build build_simpledbus_examples -j7
```

--------------------------------

### Build SimpleBLE examples with CMake

Source: https://docs.simpleble.org/simpleble/usage

Configures and builds the SimpleBLE examples using CMake. The -DSIMPLEBLE_LOCAL=ON flag enables local SimpleBLE usage.

```bash
cmake -S <path-to-simpleble>/examples/simpleble -B build_simpleble_examples -DSIMPLEBLE_LOCAL=ON
cmake --build build_simpleble_examples -j7
```

--------------------------------

### Build SimpleBLE peripheral example with CMake

Source: https://docs.simpleble.org/simpleble/peripheral/advertise-serve-publish

Configures and builds the SimpleBLE examples with local peripheral support enabled (SIMPLEBLE_LOCAL=ON). Use -j7 for parallel compilation.

```bash
cmake -S <path-to-simpleble>/examples/simpleble -B build_simpleble_examples -DSIMPLEBLE_LOCAL=ON
cmake --build build_simpleble_examples -j7

```

--------------------------------

### Add SimpleCBLE to a CMake project (installed)

Source: https://docs.simpleble.org/simplecble/usage

Example CMake configuration for using an installed SimpleCBLE library.

```cmake
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)
```

--------------------------------

### Install SimpleBLE to custom prefix with CMAKE_INSTALL_PREFIX

Source: https://docs.simpleble.org/simpleble/usage

Install to a specific location by setting CMAKE_INSTALL_PREFIX. This example uses /usr/local.

```bash
cmake --install build_simpleble --prefix /usr/local
```

--------------------------------

### Build and run the SimpleBLE quickstart application

Source: https://docs.simpleble.org/simpleble/central/scan-connect-read

Run these commands from the project directory to configure, build, and launch the application. The final command executes the compiled binary named simpleble_quickstart.

```bash
cmake -S . -B build
cmake --build build
./build/simpleble_quickstart
```

--------------------------------

### Scan with a lower-level adapter

Source: https://docs.simpleble.org/simpleunrealble/quickstart

Uses the lower-level API to get adapters, bind peripheral found and scan finished delegates, and start a 5-second scan on the first adapter.

```cpp
#include "SimpleBLE/Adapter.h"
#include "SimpleBLE/Manager.h"
#include "SimpleBLE/PayloadLibrary.h"
#include "SimpleBLE/Peripheral.h"

void UMyBluetoothController::ScanWithAdapter()
{
    Manager = NewObject<USimpleBLEManager>(this);

    const TArray<USimpleBLEAdapter*> Adapters = Manager->GetAdapters();
    if (Adapters.IsEmpty())
    {
        return;
    }

    Adapter = Adapters[0];
    Adapter->OnPeripheralFound.AddDynamic(this, &UMyBluetoothController::HandlePeripheralFound);
    Adapter->OnScanFinished.AddDynamic(this, &UMyBluetoothController::HandleAdapterScanFinished);
    Adapter->ScanFor(5000);
}
```

--------------------------------

### Core scan call in Rust

Source: https://docs.simpleble.org/recipes/scan

Rust example using simplersble to get the first adapter, scan for 5000 ms, and print identifier and address for each peripheral in the scan results.

```Rust
let mut adapters = simplersble::Adapter::get_adapters().unwrap();
let adapter = adapters.remove(0);

adapter.scan_for(5000).unwrap();

for peripheral in adapter.scan_get_results().unwrap() {
    println!(
        "{} [{}]",
        peripheral.identifier().unwrap(),
        peripheral.address().unwrap()
    );
}
```

--------------------------------

### Build documentation for production

Source: https://docs.simpleble.org/extras

Build the documentation site for production deployment.

```bash
npm run build
# or
bun run build
```

--------------------------------

### Complete SimpleBLE peripheral example (peripheral.cpp)

Source: https://docs.simpleble.org/simpleble/peripheral/advertise-serve-publish

Creates a local peripheral, adds an advertised service with a characteristic supporting READ, WRITE_REQUEST, and NOTIFY, sets an initial value, echoes writes, and handles client connections. Run and press Ctrl+C to stop.

```cpp
#include <simpleble/SimpleBLE.h>

#include <atomic>
#include <chrono>
#include <csignal>
#include <cstdlib>
#include <iostream>
#include <thread>
#include <utility>

namespace {

constexpr auto SERVICE_UUID = "12345678-1234-5678-1234-56789abcdef0";
constexpr auto CHARACTERISTIC_UUID = "12345678-1234-5678-1234-56789abcdef1";

std::atomic_bool running{true};

void signal_handler(int) { running = false; }

}  // namespace

int main() {
    std::signal(SIGINT, signal_handler);

    auto adapters = SimpleBLE::Adapter::get_adapters();
    if (adapters.empty()) {
        std::cerr << "No Bluetooth adapters found." << std::endl;
        return EXIT_FAILURE;
    }

    auto adapter = adapters.front();
    auto peripheral = adapter.create_local_peripheral();

    peripheral.add_advertised_service(SERVICE_UUID);

    auto service = peripheral.add_service(SERVICE_UUID);
    auto characteristic = service.add_characteristic(
        CHARACTERISTIC_UUID,
        {SimpleBLE::Local::CharacteristicCapability::READ, SimpleBLE::Local::CharacteristicCapability::WRITE_REQUEST,
         SimpleBLE::Local::CharacteristicCapability::NOTIFY});
    characteristic.set_value(SimpleBLE::ByteArray("ready"));

    characteristic.set_callback_on_write([&characteristic](SimpleBLE::ByteArray value) {
        std::cout << "Write: " << value << std::endl;
        // Echo the written value to subscribed clients.
        characteristic.set_value(std::move(value));
    });

    peripheral.set_callback_on_client_connected(
        [](SimpleBLE::BluetoothAddress address) { std::cout << "Client connected: " << address << std::endl; });

    peripheral.start();
    std::cout << "Local peripheral is advertising. Press Ctrl+C to stop." << std::endl;

    while (running) {
        std::this_thread::sleep_for(std::chrono::milliseconds(100));
    }

    characteristic.set_callback_on_write({});
    peripheral.stop();
    return EXIT_SUCCESS;
}

```

--------------------------------

### Run server manually with HTTP transport

Source: https://docs.simpleble.org/simpleaible/mcp

Starts the SimpleAIBLE MCP server manually with HTTP transport, binding to 127.0.0.1 on port 8000. This allows clients like the FastMCP example to connect.

```bash
simpleaible --transport http --host 127.0.0.1 --port 8000
```

--------------------------------

### Core scan call in Android (Kotlin)

Source: https://docs.simpleble.org/recipes/scan

Android Kotlin example using Adapter.getAdapters() to get the first adapter, collect onScanFound events in a coroutine, scan for 5000 ms, and retrieve scan results.

```Kotlin
val adapter = Adapter.getAdapters().first()

coroutineScope {
    val events = launch {
        adapter.onScanFound.collect { peripheral ->
            Log.d("SimpleBLE", "Found ${peripheral.identifier} [${peripheral.address}]")
        }
    }

    try {
        adapter.scanFor(5000)
    } finally {
        events.cancelAndJoin()
    }

    val results = adapter.scanGetResults()
}
```

--------------------------------

### Scan for peripherals and collect scan events

Source: https://docs.simpleble.org/simpledroidble/usage

Gets the first adapter, launches a coroutine to collect scan-found events, then starts a scan for 5 seconds and cancels the collection job. Safe to call from the main thread.

```kotlin
val adapter = Adapter.getAdapters().first()

val scanJob = lifecycleScope.launch {
    adapter.onScanFound.collect { peripheral ->
        Log.d("SimpleBLE", "Found ${peripheral.identifier} [${peripheral.address}]")
    }
}

lifecycleScope.launch {
    adapter.scanFor(5_000)
    scanJob.cancelAndJoin()
}
```

--------------------------------

### Scan for BLE devices with simplepyble

Source: https://docs.simpleble.org/quickstart

Python example using the simplepyble binding to scan for BLE peripherals. Gets the first adapter, sets a scan-found callback, scans for 5000 ms, and prints results with connectability status.

```python
import simplepyble

adapters = simplepyble.Adapter.get_adapters()
if not adapters:
    raise SystemExit("No Bluetooth adapters found.")

adapter = adapters[0]
print(f"Using adapter: {adapter.identifier()} [{adapter.address()}]")

adapter.set_callback_on_scan_found(
    lambda peripheral: print(
        f"Found: {peripheral.identifier()} [{peripheral.address()}] {peripheral.rssi()} dBm"
    )
)

adapter.scan_for(5000)

print("Scan results:")
for peripheral in adapter.scan_get_results():
    state = "connectable" if peripheral.is_connectable() else "not connectable"
    print(f"- {peripheral.identifier()} [{peripheral.address()}] {state}")
```

--------------------------------

### Run documentation in development mode

Source: https://docs.simpleble.org/extras

Start the documentation site with hot reload enabled.

```bash
npm run dev
# or
bun dev
```

--------------------------------

### Scan for BLE devices with SimpleBLE C++

Source: https://docs.simpleble.org/quickstart

C++ example using the SimpleBLE C++ API to scan for nearby BLE peripherals. Checks that Bluetooth is enabled, gets the first adapter, sets a scan-found callback, scans for 5000 ms, and prints the results with connectability status.

```cpp
#include <cstdlib>
#include <iostream>
#include <simpleble/SimpleBLE.h>

int main() {
    if (!SimpleBLE::Adapter::bluetooth_enabled()) {
        std::cerr << "Bluetooth is not enabled or permission is missing." << std::endl;
        return EXIT_FAILURE;
    }

    auto adapters = SimpleBLE::Adapter::get_adapters();
    if (adapters.empty()) {
        std::cerr << "No Bluetooth adapters found." << std::endl;
        return EXIT_FAILURE;
    }

    auto adapter = adapters.front();
    std::cout << "Using adapter: " << adapter.identifier() << " [" << adapter.address() << "]" << std::endl;

    adapter.set_callback_on_scan_found([](SimpleBLE::Peripheral peripheral) {
        std::cout << "Found: " << peripheral.identifier()
                  << " [" << peripheral.address() << "] "
                  << peripheral.rssi() << " dBm" << std::endl;
    });

    adapter.scan_for(5000);

    std::cout << "Scan results:" << std::endl;
    for (auto& peripheral : adapter.scan_get_results()) {
        std::cout << "- " << peripheral.identifier()
                  << " [" << peripheral.address() << "] "
                  << (peripheral.is_connectable() ? "connectable" : "not connectable")
                  << std::endl;
    }

    return EXIT_SUCCESS;
}
```

--------------------------------

### First simulation: create environment, add device, and scan

Source: https://docs.simpleble.org/simpleble/simulation/build-a-simulation

Creates a simulated battery device and environment, activates it, then scans and reads the battery level using the regular SimpleBLE API. The Simulator backend is selected by its identifier. Requires including <simpleble/Simulation.h>.

```cpp
#include <simpleble/Backend.h>
#include <simpleble/SimpleBLE.h>
#include <simpleble/Simulation.h>

#include <chrono>
#include <iostream>

using namespace std::chrono_literals;
namespace sim = SimpleBLE::Simulation;

const SimpleBLE::BluetoothUUID BATTERY_SERVICE = "0000180f-0000-1000-8000-00805f9b34fb";
const SimpleBLE::BluetoothUUID BATTERY_LEVEL = "00002a19-0000-1000-8000-00805f9b34fb";

class Battery : public sim::Device {
  public:
    Battery() : sim::Device("Simulated Battery", "C0:FF:EE:00:00:01") {
        add_advertised_service(BATTERY_SERVICE);
        add_service(BATTERY_SERVICE);
        add_characteristic(BATTERY_SERVICE, BATTERY_LEVEL, {sim::Property::READ});
        set_value(BATTERY_SERVICE, BATTERY_LEVEL, SimpleBLE::ByteArray{87});
    }
};

int main() {
    sim::Environment environment;
    environment.add_adapter("sim0", "00:11:22:33:44:55");
    environment.add_device<Battery>();
    environment.activate();

    // From here on, this is ordinary SimpleBLE code.
    for (auto& backend : SimpleBLE::Backend::get_backends()) {
        if (backend.identifier() != "Simulator") continue;

        auto adapter = backend.adapters().at(0);
        adapter.scan_for(200);
        for (auto& peripheral : adapter.scan_get_results()) {
            peripheral.connect();
            auto level = peripheral.read(BATTERY_SERVICE, BATTERY_LEVEL);
            std::cout << peripheral.identifier() << ": " << int(level[0]) << "%" << std::endl;
            peripheral.disconnect();
        }
    }
    return 0;
}
```

--------------------------------

### Build and install SimpleBLE with CMake

Source: https://docs.simpleble.org/simpleble/tutorial

Configures, builds, and installs SimpleBLE using CMake. The install step may require elevated privileges on Linux and macOS.

```bash
cmake -S . -B build_simpleble
cmake --build build_simpleble -j7
cmake --install build_simpleble
```

--------------------------------

### Preview production build

Source: https://docs.simpleble.org/extras

Preview the production build of the documentation site locally.

```bash
npm run start
# or
bun start
```

--------------------------------

### Find and link SimpleBLE (installed)

Source: https://docs.simpleble.org/simpleble/usage

Use this CMake snippet to consume an installed SimpleBLE. It assumes SimpleBLE is installed in a location that is part of the default CMake module path.

```cmake
find_package(simpleble REQUIRED CONFIG)
target_link_libraries(<your-target> simpleble::simpleble)
```

--------------------------------

### Install SimpleAIBLE skill via CLI

Source: https://docs.simpleble.org/simpleaible/skills

Installs the SimpleAIBLE skill for all detected supported agents (Claude Code and Codex). Re-running after upgrading the package updates the installed skill.

```bash
simpleaible install
```

--------------------------------

### Build and run SimpleDBus unit tests

Source: https://docs.simpleble.org/simpledbus/usage

Configure with SIMPLEDBUS_TEST=ON, build, and run the unit test binary at build_simpledbus_test/bin/simpledbus_test.

```bash
cmake -S <path-to-simpledbus> -B build_simpledbus_test -DSIMPLEDBUS_TEST=ON
cmake --build build_simpledbus_test -j7
./build_simpledbus_test/bin/simpledbus_test
```

--------------------------------

### Build SimpleCBLE from source

Source: https://docs.simpleble.org/simplecble/usage

Commands to clone the repository and build the library using CMake.

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

--------------------------------

### Install to Custom Prefix

Source: https://docs.simpleble.org/simpledbus/usage

Install the library to a specific directory using the CMAKE_INSTALL_PREFIX variable.

```bash
cmake --install build_simpledbus --prefix /usr/local
```

--------------------------------

### Install SimpleBluez with sudo

Source: https://docs.simpleble.org/simplebluez/usage

Installs SimpleBluez with sudo privileges, required on Linux and macOS.

```bash
sudo cmake --install build_simplebluez
```

--------------------------------

### Perform a clean build

Source: https://docs.simpleble.org/fundamentals/cmake_primer

To start a fresh build, remove the existing build directory and re-run the configuration command.

```bash
rm -rf <your-build-directory>
cmake -S <path-to-source> -B <your-build-directory>
```

--------------------------------

### Consume Installed SimpleDBus with CMake

Source: https://docs.simpleble.org/simpledbus/usage

Use find_package to locate an installed SimpleDBus and link it to your target.

```cmake
find_package(simpledbus REQUIRED CONFIG)
target_link_libraries(<your-target> simpledbus::simpledbus)
```
Tokens:
Raw