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()
static Backend get_native()
static Backend get_dongl()
static Backend get_simulator()

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)
void set_advertised_manufacturer_data(uint16_t company_id, ByteArray data)
void set_connectable(bool connectable)

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)

Simulation API

The classes in SimpleBLE::Simulation build a simulated BLE environment of adapters and devices. While an Environment is active, the Simulator backend reports its adapters, and the regular Adapter and Peripheral API scans for, connects to and talks with the simulated devices. Include <simpleble/Simulation.h> to use them.

Experimental

The Simulation API is experimental and may change between minor releases. It is available in C++ only for now.

For a walkthrough, see Build a Simulation. Timing and Radio Model explains how traffic is timed, and Fidelity and Limits covers what the simulation does and does not model.

SimpleBLE::Simulation::Environment

SimpleBLE::Simulation::Environment

Owns simulated adapters and devices. Only one environment can be active at a time. Destroying an active environment deactivates it, which closes its connections. Environments cannot be copied.

Public Functions

Environment()
~Environment()
Adapter add_adapter(const std::string& identifier, const BluetoothAddress& address)
void add_device(std::shared_ptr< Device > device)
template <typename T, typename... Args> std::shared_ptr< T > add_device(Args&&... args)
Link link(const Adapter& adapter, const std::shared_ptr< Device >& device)
void activate()
void deactivate()
bool is_active() const

SimpleBLE::Simulation::Device

SimpleBLE::Simulation::Device

A simulated peripheral. Subclass it to give the device behavior. The device declares its GATT database with its own methods, addressed by UUID, and every event reaches the device through the virtual on_* methods. Events for one device never run concurrently, like callbacks in single-threaded firmware. Configuration takes effect for later advertisements and connections. Devices cannot be copied.

Public Functions

Device(std::string name, BluetoothAddress address)
virtual ~Device()
std::string name() const
BluetoothAddress address() const

Advertising

void set_advertising_interval(std::chrono::milliseconds interval)
void set_connectable(bool connectable)
void set_tx_power(int16_t tx_power)
void add_advertised_service(const BluetoothUUID& service)
void set_manufacturer_data(uint16_t company_id, const ByteArray& data)
void set_service_data(const BluetoothUUID& service, const ByteArray& data)

Link layer

void set_preferred_connection_interval(std::chrono::microseconds min, std::chrono::microseconds max)
void set_max_mtu(uint16_t mtu)
void set_max_data_length(uint16_t octets)
void set_max_event_length(std::chrono::microseconds length)
void set_tx_buffers(size_t count)
void set_max_connections(size_t count)

GATT database

void add_service(const BluetoothUUID& service)
void add_characteristic(const BluetoothUUID& service, const BluetoothUUID& characteristic, std::set< Property > properties)
void add_descriptor(const BluetoothUUID& service, const BluetoothUUID& characteristic, const BluetoothUUID& descriptor)
ByteArray value(const BluetoothUUID& service, const BluetoothUUID& characteristic) const
void set_value(const BluetoothUUID& service, const BluetoothUUID& characteristic, const ByteArray& value)
ByteArray value(const BluetoothUUID& service, const BluetoothUUID& characteristic, const BluetoothUUID& descriptor) const
void set_value(const BluetoothUUID& service, const BluetoothUUID& characteristic, const BluetoothUUID& descriptor, const ByteArray& value)

Actions

std::vector< Connection > connections() const
TxStatus notify(const Connection& connection, const BluetoothUUID& service, const BluetoothUUID& characteristic, const ByteArray& value)
TxStatus indicate(const Connection& connection, const BluetoothUUID& service, const BluetoothUUID& characteristic, const ByteArray& value)
void disconnect(const Connection& connection)
void request_connection_interval(const Connection& connection, std::chrono::microseconds min, std::chrono::microseconds max)
void start_timer(int id, std::chrono::milliseconds period)
void stop_timer(int id)

Events

The simulation calls these methods on the device's executor with lowercase UUIDs. Default read and write handlers use stored values. Overrides own storage and can call the base handler to keep the default behavior. If a handler for a read or write request throws, the exception is logged and the request is answered with UNLIKELY_ERROR (0x0E).

virtual void on_connected(Connection connection)
virtual void on_disconnected(Connection connection)
virtual void on_mtu_changed(Connection connection, uint16_t mtu)
virtual void on_connection_interval_changed(Connection connection, std::chrono::microseconds interval)
virtual ReadResult on_read(Connection connection, const BluetoothUUID& service, const BluetoothUUID& characteristic)
virtual AttStatus on_write_request(Connection connection, const BluetoothUUID& service, const BluetoothUUID& characteristic, const ByteArray& value)
virtual void on_write_command(Connection connection, const BluetoothUUID& service, const BluetoothUUID& characteristic, const ByteArray& value)
virtual void on_subscribed(Connection connection, const BluetoothUUID& service, const BluetoothUUID& characteristic, SubscriptionKind kind)
virtual void on_unsubscribed(Connection connection, const BluetoothUUID& service, const BluetoothUUID& characteristic)
virtual void on_indication_confirmed(Connection connection, const BluetoothUUID& service, const BluetoothUUID& characteristic)
virtual void on_tx_complete(Connection connection)
virtual ReadResult on_read_descriptor(Connection connection, const BluetoothUUID& service, const BluetoothUUID& characteristic, const BluetoothUUID& descriptor)
virtual AttStatus on_write_descriptor(Connection connection, const BluetoothUUID& service, const BluetoothUUID& characteristic, const BluetoothUUID& descriptor, const ByteArray& value)
virtual void on_timer(int id)

SimpleBLE::Simulation::Adapter

SimpleBLE::Simulation::Adapter

A simulated adapter, reported through SimpleBLE::Adapter while its environment is active. Create one with Environment::add_adapter(). The connection policy setters apply to the adapter as the central.

Note

SimpleBLE::Simulation::Adapter configures a simulated adapter. Scanning and connecting go through the matching SimpleBLE::Adapter.

Public Functions

Adapter() = default
bool initialized() const
std::string identifier() const
BluetoothAddress address() const
void set_connection_interval(std::chrono::microseconds interval)
void set_accepted_connection_intervals(std::chrono::microseconds min, std::chrono::microseconds max)
void set_max_event_length(std::chrono::microseconds length)
void set_supervision_timeout(std::chrono::milliseconds timeout)

SimpleBLE::Simulation::Link

SimpleBLE::Simulation::Link

Radio conditions between one adapter and one device. Changes take effect immediately, including on an open connection. Get one with Environment::link().

Public Functions

Link() = default
void set_in_range(bool in_range)
bool is_in_range() const
void set_packet_error_rate(float rate)
float packet_error_rate() const
void set_rssi(int16_t rssi)
int16_t rssi() const

SimpleBLE::Simulation::Connection

SimpleBLE::Simulation::Connection

Handle to a connection between a simulated adapter and a device. Copies refer to the same connection and may be kept after the callback that provided them. Once the connection closes, actions on it report NOT_CONNECTED.

Public Functions

Connection() = default
bool is_connected() const
uint16_t mtu() const
std::chrono::microseconds interval() const
bool operator==(const Connection& other) const
bool operator!=(const Connection& other) const

SimpleBLE::Simulation::Property

Characteristic properties that SimpleBLE exposes to the central. They are passed to Device::add_characteristic() as a std::set.

EnumeratorMeaning
READThe central can read
WRITE_REQUESTThe central can write with a response
WRITE_COMMANDThe central can write without a response
NOTIFYThe central can subscribe to notifications
INDICATEThe central can subscribe to indications

SimpleBLE::Simulation::SubscriptionKind

Passed to Device::on_subscribed().

EnumeratorMeaning
NOTIFYThe central subscribed to notifications
INDICATEThe central subscribed to indications

SimpleBLE::Simulation::AttStatus

ATT status returned by a device to a request. The underlying type is uint8_t. Application errors (0x80-0x9F) can be returned with a static_cast.

EnumeratorValue
SUCCESS0x00
INVALID_HANDLE0x01
READ_NOT_PERMITTED0x02
WRITE_NOT_PERMITTED0x03
INSUFFICIENT_AUTHORIZATION0x08
INVALID_ATTRIBUTE_VALUE_LENGTH0x0D
UNLIKELY_ERROR0x0E
VALUE_NOT_ALLOWED0x13

SimpleBLE::Simulation::TxStatus

Result of queueing a notification or indication with Device::notify() or Device::indicate().

EnumeratorMeaning
QUEUEDQueued for the next connection events
BUSYTX buffers are full, or an indication awaits confirmation
NOT_SUBSCRIBEDThe central has not subscribed to this characteristic
NOT_CONNECTEDThe connection has closed

SimpleBLE::Simulation::ReadResult

SimpleBLE::Simulation::ReadResult

Reply to a read: a value, or an ATT error. Returned by Device::on_read() and Device::on_read_descriptor(). The constructors are not explicit, so a handler can return a ByteArray or an AttStatus directly.

Public Functions

ReadResult() = default
ReadResult(ByteArray value)
ReadResult(AttStatus status)

Public Attributes

AttStatus status = AttStatus::SUCCESS
ByteArray value

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::Simulation::EnvironmentSimpleBLE::Simulation::DeviceSimpleBLE::Simulation::AdapterSimpleBLE::Simulation::LinkSimpleBLE::Simulation::ConnectionSimpleBLE::Simulation::PropertySimpleBLE::Simulation::SubscriptionKindSimpleBLE::Simulation::AttStatusSimpleBLE::Simulation::TxStatusSimpleBLE::Simulation::ReadResultSimpleBLE::Safe::AdapterSimpleBLE::Safe::Peripheralkvn::bytearray