Install & Compatibility
Where this runs
tested against v1.29.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.052s · 34.5MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.9s · import 0.046s · 35MB
29MB installed
● package 29MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parse_advertisement_data_bytes
✓ from bluetooth_data_tools import parse_advertisement_data_bytes
Primary function for parsing raw BLE advertisement data.
BLEGAPAdvertisement
✓ from bluetooth_data_tools import BLEGAPAdvertisement
Object-oriented interface for parsed BLE advertisement data.
int_to_bluetooth_address
✓ from bluetooth_data_tools import int_to_bluetooth_address
Utility for converting integer to MAC address string.
calculate_distance_meters
✓ from bluetooth_data_tools import calculate_distance_meters
Utility for estimating distance from TX power and RSSI.
This quickstart demonstrates how to parse raw BLE advertisement data using `parse_advertisement_data_bytes` to extract common fields like local name, service UUIDs, service data, manufacturer data, and TX power. It also shows the object-oriented approach using `BLEGAPAdvertisement` and `parse_advertisement_data`.
from bluetooth_data_tools import parse_advertisement_data_bytes
# Example raw BLE advertisement bytes (replace with actual data)
# This example is illustrative; real data would come from a BLE scan.
# For a simple test, you could use data from a known device.
raw_advertisement_bytes = bytes([0x02, 0x01, 0x06, 0x11, 0x07, 0x21, 0x91, 0x74, 0x76, 0x05, 0x46, 0x87, 0xB6, 0x74, 0x0E, 0x8C, 0x51, 0x0B, 0x40, 0x90, 0xA0, 0x00, 0x0A, 0xFF, 0x4C, 0x00, 0x10, 0x07, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])
parsed_data = parse_advertisement_data_bytes(raw_advertisement_bytes)
# The parsed_data is a tuple: (local_name, service_uuids, service_data, manufacturer_data, tx_power)
local_name, service_uuids, service_data, manufacturer_data, tx_power = parsed_data
print(f"Local Name: {local_name}")
print(f"Service UUIDs: {service_uuids}")
print(f"Service Data: {service_data}")
print(f"Manufacturer Data: {manufacturer_data}")
print(f"TX Power: {tx_power}")
# Using the object-oriented interface (requires a list of raw bytes, even if one)
from bluetooth_data_tools import BLEGAPAdvertisement, parse_advertisement_data
adv = parse_advertisement_data([raw_advertisement_bytes])
print(f"\nObject-oriented parsing:")
print(f"Local Name: {adv.local_name}")
print(f"Service UUIDs: {adv.service_uuids}")
Debug
Known issues
breakingVersions v1.26.2, v1.26.3, and v1.26.4 were yanked from PyPI due to a critical segfault. Using these specific versions may lead to application crashes.fixUpgrade to v1.26.5 or newer to avoid the segfault issue. Always use the latest stable release for critical fixes.
affects: 1.26.2, 1.26.3, 1.26.4
gotchaPrior to v1.28.4, the library might have had issues correctly processing BLE advertisement data that contained empty service and/or manufacturer data payloads, potentially leading to incomplete or incorrect parsing results.fixUpgrade to version 1.28.4 or newer. This version includes a fix to properly allow and handle empty service and manufacturer data payloads in GAP advertisements.
affects: <1.28.4
gotchaIn versions older than 1.28.2, the parsing of BLE advertisement data for multiple 16-bit and 32-bit Service UUIDs might have been incomplete or incorrect. This could result in not all advertised service UUIDs being reported.fixUpgrade to version 1.28.2 or newer. This version fixed an issue to correctly parse and extract all multiple 16-bit and 32-bit Service UUIDs present in BLE advertisement data.
affects: <1.28.2
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'bluetooth_data_tools'
The `bluetooth-data-tools` library is either not installed, or the Python environment where the script is being run does not have access to the installed package.
fixEnsure the library is installed in your active Python environment using pip: `pip install bluetooth-data-tools`
error: Microsoft Visual C++ 14.0 or greater is required.
On Windows, `bluetooth-data-tools` contains C extensions (e.g., Cython modules like `_utils_impl.pyx` and `_time_impl.pyx`) that require a C++ compiler to be built during installation. This error occurs when the necessary build tools are missing.
fixInstall 'Microsoft C++ Build Tools'. These can be obtained by installing the 'Desktop development with C++' workload from the Visual Studio Installer, or directly from the Microsoft C++ Build Tools website.
TypeError: 'str' object cannot be interpreted as an integer
This error can occur when functions within `bluetooth-data-tools` that expect byte-like objects (e.g., `bytes` or `bytearray`) receive a string instead, particularly when dealing with raw advertisement data or addresses. For example, the `parse_advertisement_data_bytes` function expects bytes.
fixEnsure that any string data being passed to functions expecting byte-like objects is first encoded into bytes. For example, if you have a hex string, convert it to bytes before passing it to the function.
Upgrade
Version history
1.29.18latest on PyPI · released May 22, 2026
Audit
Dependencies
cryptographyrequiredRequired for cryptographic operations, likely related to secure Bluetooth features or address resolution.