SimpleBLE

API Reference

Architecture overview and API documentation for SimpleBLE.

The following notes provide an overview of the architecture of some of the higher-level classes in the library, as to facilitate their understanding.

Standard API

SimpleBLE::Backend

SimpleBLE::Backend

Public Functions

Backend()=default
virtual ~Backend()=default
bool initialized() const
std::string identifier() const noexcept
bool bluetooth_enabled()
std::vector< Adapter > adapters()

Public Static Functions

static std::vector< Backend > get_backends()

SimpleBLE::Adapter

SimpleBLE::Adapter

Bluetooth Adapter. A default-constructed Adapter object is not initialized. Calling any method other than initialized() on an uninitialized Adapter will throw an exception of type SimpleBLE::Exception::NotInitialized.

Note

This class is intended to be used by the user only. Library developers should use shared pointers to AdapterBase instead.

Public Functions

Adapter()=default
virtual ~Adapter()=default
bool initialized() const
void * underlying() const
std::string identifier()
BluetoothAddress address()
void power_on()
void power_off()
bool is_powered()
void set_callback_on_power_on(std::function< void()> on_power_on)
void set_callback_on_power_off(std::function< void()> on_power_off)
void scan_start()
void scan_stop()
void scan_for(int timeout_ms)
bool scan_is_active()
std::vector< Peripheral > scan_get_results()
void set_callback_on_scan_start(std::function< void()> on_scan_start)
void set_callback_on_scan_stop(std::function< void()> on_scan_stop)
void set_callback_on_scan_updated(std::function< void(Peripheral)> on_scan_updated)
void set_callback_on_scan_found(std::function< void(Peripheral)> on_scan_found)
std::vector< Peripheral > get_paired_peripherals()
std::vector< Peripheral > get_connected_peripherals()
Local::Peripheral create_local_peripheral()

Public Static Functions

static bool bluetooth_enabled()
static std::vector< Adapter > get_adapters()

SimpleBLE::Peripheral

SimpleBLE::Peripheral

Public Functions

Peripheral()=default
virtual ~Peripheral()=default
bool initialized() const
void * underlying() const
std::string identifier()
BluetoothAddress address()
BluetoothAddressType address_type()
int16_t rssi()
int16_t tx_power()
uint16_t mtu()
void connect()
void disconnect()
bool is_connected()
bool is_connectable()
bool is_paired()
void unpair()
std::vector< Service > services()
std::map< uint16_t, ByteArray > manufacturer_data()
ByteArray read(BluetoothUUID const &service, BluetoothUUID const &characteristic)
void write_request(BluetoothUUID const &service, BluetoothUUID const &characteristic, ByteArray const &data)
void write_command(BluetoothUUID const &service, BluetoothUUID const &characteristic, ByteArray const &data)
void notify(BluetoothUUID const &service, BluetoothUUID const &characteristic, std::function< void(ByteArray payload)> callback)
void indicate(BluetoothUUID const &service, BluetoothUUID const &characteristic, std::function< void(ByteArray payload)> callback)
void unsubscribe(BluetoothUUID const &service, BluetoothUUID const &characteristic)
ByteArray read(BluetoothUUID const &service, BluetoothUUID const &characteristic, BluetoothUUID const &descriptor)
void write(BluetoothUUID const &service, BluetoothUUID const &characteristic, BluetoothUUID const &descriptor, ByteArray const &data)
void set_callback_on_connected(std::function< void()> on_connected)
void set_callback_on_disconnected(std::function< void()> on_disconnected)

SimpleBLE::Service

SimpleBLE::Service

Public Functions

Service()=default
virtual ~Service()=default
bool initialized() const
BluetoothUUID uuid()
ByteArray data()
std::vector< Characteristic > characteristics()

SimpleBLE::Characteristic

SimpleBLE::Characteristic

Public Functions

Characteristic()=default
virtual ~Characteristic()=default
bool initialized() const
BluetoothUUID uuid()
std::vector< Descriptor > descriptors()
std::vector< std::string > capabilities()
bool can_read()
bool can_write_request()
bool can_write_command()
bool can_notify()
bool can_indicate()

SimpleBLE::Descriptor

SimpleBLE::Descriptor

Public Functions

Descriptor()=default
virtual ~Descriptor()=default
bool initialized() const
BluetoothUUID uuid()

Local API

The Local API is how this host advertises and serves GATT. SimpleBLE::Peripheral is a remote device; SimpleBLE::Local::Peripheral is this host. Create a local peripheral with Adapter::create_local_peripheral().

SimpleBLE::Local::CharacteristicCapability

Capabilities are passed to add_characteristic as a std::set. Each characteristic needs at least one.

EnumeratorMeaning
READRemote centrals can read
WRITE_REQUESTRemote centrals can write with a response
WRITE_COMMANDRemote centrals can write without a response
NOTIFYRemote centrals can subscribe to notifications
INDICATERemote centrals can subscribe to indications

SimpleBLE::Local::Peripheral

SimpleBLE::Local::Peripheral

Local BLE peripheral hosted by this process. A default-constructed Peripheral object is not initialized. Calling any method other than initialized() on an uninitialized object will throw SimpleBLE::Exception::NotInitialized.

Note

SimpleBLE::Peripheral is a remote device discovered by this host. SimpleBLE::Local::Peripheral is this host exposing local GATT services.

Public Functions

Peripheral()=default
virtual ~Peripheral()=default
bool initialized() const
void * underlying() const
void add_advertised_service(BluetoothUUID service_uuid)
void add_advertised_service(std::vector< BluetoothUUID > service_uuids)

The portable API does not select a local name. Linux, macOS, and iOS expose their native advertisement-specific name through SimpleBLE::Advanced::Linux::set_advertisement_local_name(), SimpleBLE::Advanced::MacOS::set_advertisement_local_name(), and SimpleBLE::Advanced::iOS::set_advertisement_local_name(). Each function accepts a Local::Peripheral& and an std::optional<std::string>, must be called before start(), and changes only the advertisement payload. Passing std::nullopt removes the override.

Service add_service(BluetoothUUID uuid)
std::vector< Service > services()
void remove_all_services()
void start()
void stop()
bool is_started()
bool is_advertising()
void set_callback_on_client_connected(std::function< void(BluetoothAddress client_address)> on_client_connected)
void set_callback_on_client_disconnected(std::function< void(BluetoothAddress client_address)> on_client_disconnected)

SimpleBLE::Local::Service

SimpleBLE::Local::Service

Public Functions

Service()=default
virtual ~Service()=default
bool initialized() const
BluetoothUUID uuid()
Characteristic add_characteristic(BluetoothUUID uuid, std::set< CharacteristicCapability > capabilities)
std::vector< Characteristic > characteristics()

SimpleBLE::Local::Characteristic

SimpleBLE::Local::Characteristic

Public Functions

Characteristic()=default
virtual ~Characteristic()=default
bool initialized() const
BluetoothUUID uuid()
std::set< CharacteristicCapability > capabilities()
ByteArray value()
void set_value(ByteArray value)
void set_callback_on_read(std::function< ByteArray()> on_read)
void set_callback_on_write(std::function< void(ByteArray value)> on_write)
void set_callback_on_subscribed(std::function< void()> on_subscribed)
void set_callback_on_unsubscribed(std::function< void()> on_unsubscribed)

Safe API

SimpleBLE::Safe::Adapter

SimpleBLE::Safe::Adapter

Wrapper around the Adapter class that provides a noexcept interface. We use instances of this class directly and not through shared_ptr because this is just a wrapper around the Adapter class, which is already managed by shared_ptr.

Public Functions

Adapter(SimpleBLE::Adapter &adapter)
Adapter(SimpleBLE::Adapter &&adapter)
virtual ~Adapter()=default
std::optional< std::string > identifier() noexcept
std::optional< BluetoothAddress > address() noexcept
bool scan_start() noexcept
bool scan_stop() noexcept
bool scan_for(int timeout_ms) noexcept
std::optional< bool > scan_is_active() noexcept
std::optional< std::vector< SimpleBLE::Safe::Peripheral > > scan_get_results() noexcept
bool set_callback_on_scan_start(std::function< void()> on_scan_start) noexcept
bool set_callback_on_scan_stop(std::function< void()> on_scan_stop) noexcept
bool set_callback_on_scan_updated(std::function< void(SimpleBLE::Safe::Peripheral)> on_scan_updated) noexcept
bool set_callback_on_scan_found(std::function< void(SimpleBLE::Safe::Peripheral)> on_scan_found) noexcept
std::optional< std::vector< SimpleBLE::Safe::Peripheral > > get_paired_peripherals() noexcept
operator SimpleBLE::Adapter() const noexcept

Public Static Functions

static std::optional< bool > bluetooth_enabled() noexcept
static std::optional< std::vector< SimpleBLE::Safe::Adapter > > get_adapters() noexcept

SimpleBLE::Safe::Peripheral

SimpleBLE::Safe::Peripheral

Public Functions

Peripheral(SimpleBLE::Peripheral &peripheral)
Peripheral(SimpleBLE::Peripheral &&peripheral)
virtual ~Peripheral()=default
std::optional< std::string > identifier() noexcept
std::optional< BluetoothAddress > address() noexcept
std::optional< BluetoothAddressType > address_type() noexcept
std::optional< int16_t > rssi() noexcept
std::optional< int16_t > tx_power() noexcept
std::optional< uint16_t > mtu() noexcept
bool connect() noexcept
bool disconnect() noexcept
std::optional< bool > is_connected() noexcept
std::optional< bool > is_connectable() noexcept
std::optional< bool > is_paired() noexcept
bool unpair() noexcept
std::optional< std::vector< Service > > services() noexcept
std::optional< std::map< uint16_t, ByteArray > > manufacturer_data() noexcept
std::optional< ByteArray > read(BluetoothUUID const &service, BluetoothUUID const &characteristic) noexcept
bool write_request(BluetoothUUID const &service, BluetoothUUID const &characteristic, ByteArray const &data) noexcept
bool write_command(BluetoothUUID const &service, BluetoothUUID const &characteristic, ByteArray const &data) noexcept
bool notify(BluetoothUUID const &service, BluetoothUUID const &characteristic, std::function< void(ByteArray payload)> callback) noexcept
bool indicate(BluetoothUUID const &service, BluetoothUUID const &characteristic, std::function< void(ByteArray payload)> callback) noexcept
bool unsubscribe(BluetoothUUID const &service, BluetoothUUID const &characteristic) noexcept
std::optional< ByteArray > read(BluetoothUUID const &service, BluetoothUUID const &characteristic, BluetoothUUID const &descriptor) noexcept
bool write(BluetoothUUID const &service, BluetoothUUID const &characteristic, BluetoothUUID const &descriptor, ByteArray const &data) noexcept
bool set_callback_on_connected(std::function< void()> on_connected) noexcept
bool set_callback_on_disconnected(std::function< void()> on_disconnected) noexcept
operator SimpleBLE::Peripheral() const noexcept

External API

kvn::bytearray

kvn::bytearray

A class to handle byte arrays and their conversion from/to hex strings.

Public Functions

bytearray()=default
bytearray(const std::vector< uint8_t > &vec)
bytearray(std::initializer_list< uint8_t > list)
bytearray(const uint8_t *ptr, size_t size)
bytearray(InputIt first, InputIt last)
bytearray(const std::string &byteArr)
bytearray(const char *byteArr, size_t size)
bytearray(const char *byteArr)
bytearray(size_t size)
std::string toHex(bool spacing=false) const
bytearray slice(size_t start, size_t end) const
bytearray slice_from(size_t start) const
bytearray slice_to(size_t end) const
operator std::string() const
operator std::vector< uint8_t >() const

Public Static Functions

static bytearray fromHex(const std::string &hexStr)
static bytearray fromHex(const char *byteArr)
static bytearray fromHex(const char *byteArr, size_t size)

Advertise, Serve, Publish

Host a local BLE peripheral, serve GATT characteristics, and publish value updates to connected clients.

Examples

Code examples for SimpleBLE.

On this page

SimpleBLE::BackendSimpleBLE::AdapterSimpleBLE::PeripheralSimpleBLE::ServiceSimpleBLE::CharacteristicSimpleBLE::DescriptorSimpleBLE::Local::CharacteristicCapabilitySimpleBLE::Local::PeripheralSimpleBLE::Local::ServiceSimpleBLE::Local::CharacteristicSimpleBLE::Safe::AdapterSimpleBLE::Safe::Peripheralkvn::bytearray