Getting Started

SimpleBLE is a cross-platform C++ library for Bluetooth Low Energy. An adapter can be used in two roles:

• Central: scan for nearby devices and connect to them as a GATT client. That remote device is a SimpleBLE::Peripheral.
• Peripheral: advertise and serve local GATT services. This host is a SimpleBLE::Local::Peripheral.

This page gets you to a first success in each role. Scan, Connect, Read and Advertise, Serve, Publish go deeper.

If you are new to BLE or platform-specific permissions, it is worth taking a quick look at Bluetooth LE Basics and Bluetooth Permissions before you begin.

Prerequisites

Before we start building the sample application, make sure your machine and development environment are ready:

• A C++17-compatible compiler
• CMake 3.21 or newer
• A machine with Bluetooth Low Energy support enabled
• The platform dependencies described in the usage guide
• On Windows with MSVC, a C++20-capable toolchain such as Visual Studio 2019 16.11 or newer

If you are developing on macOS, iOS, or Android, make sure your app has the required Bluetooth permission entries before testing.

Install SimpleBLE

Start by cloning the SimpleBLE repository locally:

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

With the source available locally, the next step is to build and install the library:

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

On Linux and macOS, you may need elevated privileges for the install step:

sudo cmake --install build_simpleble

Once that finishes, SimpleBLE is installed on your machine and ready to be used from your own CMake project. If you need platform-specific setup details, refer to the usage page and platform notes.

Create your application

Now that SimpleBLE is installed, we can create a small sample project that links against it. Start with this structure:

my-simpleble-app/
|-- CMakeLists.txt
|-- src/
    |-- main.cpp

Add CMakeLists.txt

In the project root, create CMakeLists.txt:

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)

This gives your sample project a standard CMake setup and tells it to locate the installed SimpleBLE package and link it to your executable.

Get a Bluetooth adapter

Every SimpleBLE program starts the same way: confirm Bluetooth is available, then pick an adapter. SimpleBLE manages multiple backends representing different under-the-hood implementations (such as BlueZ, CoreBluetooth, WinRT, or Dongl), but provides a consolidated method to fetch all available adapters.

#include <iostream>
#include <simpleble/SimpleBLE.h>

int main() {
    if (!SimpleBLE::Adapter::bluetooth_enabled()) {
        std::cerr << "Bluetooth is not enabled or permission has not been granted." << 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;
    return EXIT_SUCCESS;
}

Act as a central

With an adapter, scan for nearby devices. This listens for advertisements and prints each peripheral as it is found:

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

adapter.scan_for(5000);

SimpleBLE::Peripheral here is a remote device. Connecting to one, listing its GATT table, and reading a characteristic is covered in Scan, Connect, Read.

Act as a peripheral

SimpleBLE::Local::Peripheral is this host advertising and serving GATT. Configure the advertisement and at least one characteristic, then call start():

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");
service.add_characteristic("12345678-1234-5678-1234-56789abcdef1",
                           {SimpleBLE::Local::CharacteristicCapability::READ});

peripheral.start();
std::cout << "Local peripheral is advertising." << std::endl;

The portable advertisement does not select a local name. Windows and Android use their system-owned Bluetooth name. Linux, macOS, and iOS expose an optional advertised-name override through their SimpleBLE::Advanced namespaces.

Keep the process alive after start(), then call peripheral.stop() when you are done. Writes, notifications, and client connection callbacks are covered in Advertise, Serve, Publish.

Build and run

From your project directory:

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

Where to next?

• Scan, Connect, Read to pick a device, connect, and read a characteristic
• Advertise, Serve, Publish to serve GATT and publish value updates
• Recipes for task-based snippets across the supported bindings
• API reference for the complete C++ surface area
• Examples for the programs in the repository
• FAQ for common questions and troubleshooting tips