Fundamentals

Welcome to the Fundamentals section. Whether you are new to Bluetooth Low Energy or an experienced developer looking to understand SimpleBLE's internals, these guides cover the essential knowledge required to build robust applications.

In this section

Bluetooth LE Basics

A high-level introduction to how Bluetooth Low Energy works, including device roles (Central/Peripheral), the GATT hierarchy (Services/Characteristics), and UUIDs.

Bluetooth UUIDs

How 16-bit and 128-bit UUIDs relate, standard and custom UUIDs, and the format SimpleBLE uses for every UUID it reports.

BLE Advertising

How advertising packets, scan responses and extended advertising work, and how SimpleBLE reports advertising data.

Bluetooth Addresses

Address types, why BLE devices change their address, why macOS and iOS report a UUID instead, and how to recognize a device again.

CMake Primer

A beginner-friendly guide to using CMake to configure, build, and install SimpleBLE in your own projects.

Permissions

A guide to the various permissions required by different operating systems (Windows, macOS, Linux, Android, and iOS) to access Bluetooth functionality.

Error Handling

SimpleBLE's exception taxonomy, which errors are worth retrying, what timeouts actually mean, and how in-flight operations behave when a device disconnects.

Disconnects and Android Error 133

How a connection is lost, what the disconnect reason codes and Android's status 133 mean, and how SimpleBLE reports disconnections.

Concurrency

The threading and callback contract for SimpleBLE's synchronous API: which threads run your callbacks on each platform, what you can safely call from inside a callback, every timeout in the library, and how to integrate with UI frameworks like Qt, WinForms, or Unity.