API Reference

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

class Adapter

Subclassed by SimpleBLE::Safe::Adapter

Public Functions

Adapter() = default

virtual ~Adapter() = default

bool initialized() const

void *underlying() const

std::string identifier()

BluetoothAddress address()

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()

Public Static Functions

static bool bluetooth_enabled()

static std::vector<Adapter> get_adapters()

Fetches a list of all available adapters.

class Peripheral

Subclassed by SimpleBLE::Safe::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()

Provides the advertised transmit power in dBm.

Note

If the field has not been advertised by the peripheral, the returned value will be -32768.

uint16_t mtu()

void connect()

void disconnect()

bool is_connected()

bool is_connectable()

bool is_paired()

void unpair()

std::vector<Service> services()

Provides a list of all services that are available on the peripheral.

Note

If the peripheral is not connected, it will return a list of services that were advertised by the device.

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)

class Service

Public Functions

Service() = default

virtual ~Service() = default

BluetoothUUID uuid()

ByteArray data()

std::vector<Characteristic> characteristics()

class Characteristic

Public Functions

Characteristic() = default

virtual ~Characteristic() = default

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()

class Descriptor

Public Functions

Descriptor() = default

virtual ~Descriptor() = default

BluetoothUUID uuid()

Safe API

class Adapter : public SimpleBLE::Adapter

Public Functions

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

Public Static Functions

static std::optional<bool> bluetooth_enabled() noexcept

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

class Peripheral : public SimpleBLE::Peripheral

Public Functions

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

C API

Functions

bool simpleble_adapter_is_bluetooth_enabled(void)

Returns

bool

size_t simpleble_adapter_get_count(void)

Returns

size_t

simpleble_adapter_t simpleble_adapter_get_handle(size_t index)

Note

The user is responsible for freeing the returned adapter object by calling simpleble_adapter_release_handle.

Parameters

index –

Returns

simpleble_adapter_t

void simpleble_adapter_release_handle(simpleble_adapter_t handle)

Releases all memory and resources consumed by the specific instance of simpleble_adapter_t.

Parameters

handle –

char *simpleble_adapter_identifier(simpleble_adapter_t handle)

Returns the identifier of a given adapter.

Note

The user is responsible for freeing the returned value.

Parameters

handle –

Returns

char*

char *simpleble_adapter_address(simpleble_adapter_t handle)

Returns the MAC address of a given adapter.

Note

The user is responsible for freeing the returned value.

Parameters

handle –

Returns

char*

simpleble_err_t simpleble_adapter_scan_start(simpleble_adapter_t handle)

Parameters

handle –

Returns

simpleble_err_t

simpleble_err_t simpleble_adapter_scan_stop(simpleble_adapter_t handle)

Parameters

handle –

Returns

simpleble_err_t

simpleble_err_t simpleble_adapter_scan_is_active(simpleble_adapter_t handle, bool *active)

Parameters

• handle –

• active –

Returns

simpleble_err_t

simpleble_err_t simpleble_adapter_scan_for(simpleble_adapter_t handle, int timeout_ms)

Parameters

• handle –

• timeout_ms –

Returns

simpleble_err_t

size_t simpleble_adapter_scan_get_results_count(simpleble_adapter_t handle)

Parameters

handle –

Returns

size_t

simpleble_peripheral_t simpleble_adapter_scan_get_results_handle(simpleble_adapter_t handle, size_t index)

Note

The user is responsible for freeing the returned peripheral object by calling simpleble_peripheral_release_handle.

Parameters

• handle –

• index –

Returns

simpleble_peripheral_t

size_t simpleble_adapter_get_paired_peripherals_count(simpleble_adapter_t handle)

Parameters

handle –

Returns

size_t

simpleble_peripheral_t simpleble_adapter_get_paired_peripherals_handle(simpleble_adapter_t handle, size_t index)

Note

The user is responsible for freeing the returned peripheral object by calling simpleble_peripheral_release_handle.

Parameters

• handle –

• index –

Returns

simpleble_peripheral_t

simpleble_err_t simpleble_adapter_set_callback_on_scan_start(simpleble_adapter_t handle, void (*callback)(simpleble_adapter_t adapter, void *userdata), void *userdata)

Parameters

• handle –

• callback –

Returns

simpleble_err_t

simpleble_err_t simpleble_adapter_set_callback_on_scan_stop(simpleble_adapter_t handle, void (*callback)(simpleble_adapter_t adapter, void *userdata), void *userdata)

Parameters

• handle –

• callback –

Returns

simpleble_err_t

simpleble_err_t simpleble_adapter_set_callback_on_scan_updated(simpleble_adapter_t handle, void (*callback)(simpleble_adapter_t adapter, simpleble_peripheral_t peripheral, void *userdata), void *userdata)

Parameters

• handle –

• callback –

Returns

simpleble_err_t

simpleble_err_t simpleble_adapter_set_callback_on_scan_found(simpleble_adapter_t handle, void (*callback)(simpleble_adapter_t adapter, simpleble_peripheral_t peripheral, void *userdata), void *userdata)

Parameters

• handle –

• callback –

Returns

simpleble_err_t

Functions

void simpleble_peripheral_release_handle(simpleble_peripheral_t handle)

Releases all memory and resources consumed by the specific instance of simpleble_peripheral_t.

Parameters

handle –

char *simpleble_peripheral_identifier(simpleble_peripheral_t handle)

Parameters

handle –

Returns

char*

char *simpleble_peripheral_address(simpleble_peripheral_t handle)

Parameters

handle –

Returns

char*

simpleble_address_type_t simpleble_peripheral_address_type(simpleble_peripheral_t handle)

Parameters

handle –

Returns

simpleble_address_type_t

int16_t simpleble_peripheral_rssi(simpleble_peripheral_t handle)

Parameters

handle –

Returns

int16_t

int16_t simpleble_peripheral_tx_power(simpleble_peripheral_t handle)

Parameters

handle –

Returns

int16_t

uint16_t simpleble_peripheral_mtu(simpleble_peripheral_t handle)

Parameters

handle –

Returns

uint16_t

simpleble_err_t simpleble_peripheral_connect(simpleble_peripheral_t handle)

Parameters

handle –

Returns

simpleble_err_t

simpleble_err_t simpleble_peripheral_disconnect(simpleble_peripheral_t handle)

Parameters

handle –

Returns

simpleble_err_t

simpleble_err_t simpleble_peripheral_is_connected(simpleble_peripheral_t handle, bool *connected)

Parameters

• handle –

• connected –

Returns

simpleble_err_t

simpleble_err_t simpleble_peripheral_is_connectable(simpleble_peripheral_t handle, bool *connectable)

Parameters

• handle –

• connectable –

Returns

simpleble_err_t

simpleble_err_t simpleble_peripheral_is_paired(simpleble_peripheral_t handle, bool *paired)

Parameters

• handle –

• paired –

Returns

simpleble_err_t

simpleble_err_t simpleble_peripheral_unpair(simpleble_peripheral_t handle)

Parameters

handle –

Returns

simpleble_err_t

size_t simpleble_peripheral_services_count(simpleble_peripheral_t handle)

Parameters

handle –

Returns

size_t

simpleble_err_t simpleble_peripheral_services_get(simpleble_peripheral_t handle, size_t index, simpleble_service_t *services)

Parameters

• handle –

• index –

• services –

Returns

simpleble_err_t

size_t simpleble_peripheral_manufacturer_data_count(simpleble_peripheral_t handle)

Parameters

handle –

Returns

size_t

simpleble_err_t simpleble_peripheral_manufacturer_data_get(simpleble_peripheral_t handle, size_t index, simpleble_manufacturer_data_t *manufacturer_data)

Parameters

• handle –

• index –

• manufacturer_data –

Returns

simpleble_err_t

simpleble_err_t simpleble_peripheral_read(simpleble_peripheral_t handle, simpleble_uuid_t service, simpleble_uuid_t characteristic, uint8_t **data, size_t *data_length)

Note

The user is responsible for freeing the pointer returned in data.

Parameters

• handle –

• service –

• characteristic –

• data –

• data_length –

Returns

simpleble_err_t

simpleble_err_t simpleble_peripheral_write_request(simpleble_peripheral_t handle, simpleble_uuid_t service, simpleble_uuid_t characteristic, const uint8_t *data, size_t data_length)

Parameters

• handle –

• service –

• characteristic –

• data –

• data_length –

Returns

simpleble_err_t

simpleble_err_t simpleble_peripheral_write_command(simpleble_peripheral_t handle, simpleble_uuid_t service, simpleble_uuid_t characteristic, const uint8_t *data, size_t data_length)

Parameters

• handle –

• service –

• characteristic –

• data –

• data_length –

Returns

simpleble_err_t

simpleble_err_t simpleble_peripheral_notify(simpleble_peripheral_t handle, simpleble_uuid_t service, simpleble_uuid_t characteristic, void (*callback)(simpleble_uuid_t service, simpleble_uuid_t characteristic, const uint8_t *data, size_t data_length, void *userdata), void *userdata)

Parameters

• handle –

• service –

• characteristic –

• callback –

Returns

simpleble_err_t

simpleble_err_t simpleble_peripheral_indicate(simpleble_peripheral_t handle, simpleble_uuid_t service, simpleble_uuid_t characteristic, void (*callback)(simpleble_uuid_t service, simpleble_uuid_t characteristic, const uint8_t *data, size_t data_length, void *userdata), void *userdata)

Parameters

• handle –

• service –

• characteristic –

• callback –

Returns

simpleble_err_t

simpleble_err_t simpleble_peripheral_unsubscribe(simpleble_peripheral_t handle, simpleble_uuid_t service, simpleble_uuid_t characteristic)

Parameters

• handle –

• service –

• characteristic –

Returns

simpleble_err_t

simpleble_err_t simpleble_peripheral_read_descriptor(simpleble_peripheral_t handle, simpleble_uuid_t service, simpleble_uuid_t characteristic, simpleble_uuid_t descriptor, uint8_t **data, size_t *data_length)

Parameters

• handle –

• service –

• characteristic –

• descriptor –

• data –

• data_length –

Returns

simpleble_err_t

simpleble_err_t simpleble_peripheral_write_descriptor(simpleble_peripheral_t handle, simpleble_uuid_t service, simpleble_uuid_t characteristic, simpleble_uuid_t descriptor, const uint8_t *data, size_t data_length)

Parameters

• handle –

• service –

• characteristic –

• descriptor –

• data –

• data_length –

Returns

simpleble_err_t

simpleble_err_t simpleble_peripheral_set_callback_on_connected(simpleble_peripheral_t handle, void (*callback)(simpleble_peripheral_t peripheral, void *userdata), void *userdata)

Parameters

• handle –

• callback –

Returns

simpleble_err_t

simpleble_err_t simpleble_peripheral_set_callback_on_disconnected(simpleble_peripheral_t handle, void (*callback)(simpleble_peripheral_t peripheral, void *userdata), void *userdata)

Parameters

• handle –

• callback –

Returns

simpleble_err_t