SimpleBLE: one Bluetooth LE stack for five platforms

Five platforms, four native stacks, one API

SimpleBLE is the cross-platform Bluetooth Low Energy stack for Windows, macOS, Linux, iOS and Android, and the tagline captures the intent better than the feature list does. Build Bluetooth once, ship it everywhere.

The why section is four bullets and the second one is the important one. There is one cross-platform API, so application-facing BLE logic stays consistent across desktop and mobile. Underneath, it is native: WinRT on Windows, CoreBluetooth on Apple platforms, BlueZ on Linux and the Android Bluetooth stack, all driven through one maintained stack. Central and peripheral role support works across all supported platforms. And it is built for real products, with commercial licensing and direct technical support available.

That last point is the framing device for the whole project, because the licence is not a permissive one. SimpleBLE is available under the Business Source License 1.1. It is free to use for non-commercial purposes and requires a commercial license for commercial use. Each version converts to the GNU General Public License version 3 four years after its initial release. Qualifying non-commercial users may instead continue using and distributing that version under the original BUSL-1.1 terms through the Non-Commercial Perpetual Use Grant in the licence file. And free commercial licenses are available for qualifying small projects and early-stage companies.

So the practical shape is a delay, not a prohibition, with an exception carved out for small commercial users. Read the licence file rather than this summary before you ship.

Nine language bindings, one directory per binding

You can use SimpleBLE from C++, C, C#, Python, Java, Go or Rust, with dedicated APIs for Kotlin on Android and for Unreal Engine, and the repository is arranged one directory per binding so that the structure tells you the whole surface.

The naming is a little tongue in cheek and entirely consistent. simpleble/ is the core C++ library, simpleaible/ covers Apple platforms, simplecble/ covers Windows, simplebluez/ covers Linux through BlueZ, and simpledbus/ sits under it. Then there is simplegoble/ for Go, simplejavable/ for Java, simplepyble/ for Python, simplersble/ for Rust and simplesharpble/ for C#.

The examples directory mirrors that, with a sample project per binding plus a simpleble-android/ example and a simplesharpble-android/ example, and a simpleble/ example for the plain C++ interface.

That last grouping is the one to notice. There is a simpleble/ example that is not tied to a language binding, which is the C++ API everyone else is a wrapper around, and the language bindings are thin enough that the examples are short enough to read as documentation.

The Rust binding is the most recent in the repository and the one with the most visible structure, because the Cargo manifest lists exactly what it needs: the cxx crate for the bridge, tokio with the full feature set, tokio-stream and futures, and build dependencies on cmake and cxx-build. Its own rust-version is 1.82, and the manifest declares links = simpleble, which is the Cargo mechanism for a native library that other crates need to find at link time.

SimpleBluez and SimpleDBus, the layers you can drop to

The documentation section points at the lower-level SimpleBluez and SimpleDBus libraries as separate things to explore, and they are in the repository as their own directories.

That is a deliberate part of the design rather than an implementation detail. SimpleBLE gives you one API on top of a platform abstraction, and it is the right level for most products. But a project that needs to do something the abstraction does not cover, or that wants to work on Linux against BlueZ directly, can drop a level and use the BlueZ implementation, or the D-Bus layer underneath it, without leaving the project.

The name gives the shape of the stack. On Linux, the platform BLE daemon is BlueZ, and BlueZ speaks D-Bus, so there is a BlueZ library and a D-Bus library, and SimpleBLE sits above both. A team that has to support a Linux box with an unusual BlueZ setup, or that wants to bypass the abstraction for performance reasons, has a supported path to do it.

The same idea shows up in the Android side, where simpledroidble/ and simpledroidbridge/ sit alongside the other bindings, and it explains why the repository has a hitl/ directory as well, alongside the util/ and utils/ directories and a scripts/ folder, since a project that ships a dozen bindings needs a shared place for the code generation and per platform plumbing.

A simulated backend, so the tests do not need hardware

The Rust manifest has a comment that is worth reading twice, because it explains a whole testing strategy in one line. It runs against the simulated backend, and the test target is named plain, with the instruction to run it with SIMPLERSBLE_PLAIN=1.

SIMPLERSBLE_PLAIN=1 cargo test

The same idea appears on the Python side. The setup script accepts a --plain flag, which sets SIMPLEBLE_PLAIN=ON as a CMake option, and the Python package is built with scikit-build and pybind11, so the plain build is a compile time switch rather than a runtime setting.

This matters more in Bluetooth than in most libraries. A BLE test that needs a real radio needs a real peripheral, a real central, and a way to keep them in range and in sync, which turns a unit test into a hardware lab exercise. A simulated backend means the parts of your code that orchestrate connections, discoveries and state machines can be tested on a machine with no radio at all, and the hardware tests become the small set of things that genuinely need hardware.

The Python packaging shows the same care elsewhere. The version comes from a VERSION file rather than being duplicated, the macOS deployment target is pinned to 13.0, the Windows system version is pinned to 10.0.19041.0, and when building for a wheel index the vendored libfmt is turned off so the system library is used.

Dongl, the hardware the project controls

Dongl is the official SimpleBLE hardware companion, and it exists for a reason that is spelled out in the README: firmware visibility, customizability and direct support from the team building SimpleBLE.

The firmware is available for nRF52840 based boards, so you can flash the Dongl N-Series firmware onto existing nRF52840 hardware for prototyping, and pre-loaded production hardware is coming soon, with a waitlist for the official units.

The appeal is easy to see from a developer's position. A Bluetooth peripheral used in testing is normally a development board, which means the firmware is whatever the vendor shipped, which means the test rig depends on a part you do not control. Dongl makes the peripheral part of the project, so the firmware is something the same team maintains, can change, and can support.

The repository also has a SimpleBLE Store, which is the commercial side of the same idea, and the support section points at both a Discord community and the project's announcements and blog.

The project is powered by the California Open Source Company, which is the entity behind the commercial licensing that the licence section describes.

Editorial conclusion

SimpleBLE fits a product team that needs Bluetooth on more than one operating system and would otherwise maintain a Windows path, a macOS path and an Android path separately, and that is prepared to buy a commercial licence. It does not fit a hobby project shipping a commercial app without a licence, and it does not fit a team that needs an open source dependency its customers can audit and redistribute. Verify three things before you start: which licence terms apply to you, because the Non-Commercial Perpetual Use Grant covers some users of a released version and the conversion to GPL version 3 happens four years after the initial release, which native backend you actually need, since the project is built on four different platform stacks rather than one, and whether the plain, simulated backend is enough for your test suite, because that is the difference between a test run that needs hardware and one that does not.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. simpleble/simpleble on GitHub