libhbluetooth

June 23, 2026 ยท View on GitHub

A library to use Bluetooth Classic features.
Part of the cross-platform work for the bluetuith project.

This is alpha-grade software.

Funding

This project is funded through NGI Zero Core, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program. Learn more at the NLnet project page.

NLnet foundation logo NGI Zero Logo

Features

The available features per-platform are listed here.

Requirements

Windows

  • Windows 10 19041 or later.
  • Administrator access for certain Registry-related APIs.

Note

These builds are currently not signed, which means while launching this within an application, Microsoft SmartScreen warnings may pop up. Press "Run anyway" to run the application, and/or add an exclusion for both the application, 'libhbluetooth.dll' to Windows Defender and relaunch the application.

Download and Installation

All downloads can be found within the 'Releases' page of the repository. Select a download with the "win-" prefix and the appropriate CPU architecture.

  • Download the zip archive to a known path and extract it.
  • Dynamically load the library within an application.

MacOS

  • Preferably Ventura or later (The library was tested on Sequoia).

Caution

Do not attempt to execute this within an application as root. This library only requires the Bluetooth and Full Disk Access permissions.

Note

These builds are ad-hoc signed within the CI, which means additional steps must be done before executing the application, which is described in the next section.

Download and Installation

All downloads can be found within the 'Releases' page of the repository. Select a download with the "osx-" prefix and the appropriate CPU architecture.

  • Download the zip archive to a known path and extract it to a folder.

  • Execute the following commands, which removes the 'com.apple.quarantine' bit from the file, and code-signs it, so that it can be loaded:

    xattr -dr com.apple.quarantine /<path/to/downloaded/library>/libhbluetooth.dylib
codesign --force -s - /<path/to/downloaded/library>/libhbluetooth.dylib

  • Dynamically load the library within an application, If required, code-sign the application before running it.

Documentation

This library provides APIs to access Bluetooth Classic features in a cross-platform manner, by wrapping platform-specific APIs.

In addition to the features supported above, it also implements an event-based system (via callbacks), which can be used to monitor adapter/device changes, Object Push transfers and so on.

C header files are yet to be provided. However, there are bindings for Go, provided here, with documentation and sample usages of this library.

Additional Information

  • The 'libffi' builds are built from source and statically linked with no changes. The builds are published here.

Credits

These repositories were invaluable during the development of the library.
Please star these repositories individually, and possibly submit contributions to them.