Bluetooth Data Tools

1.28.4 · active · verified Wed Apr 15

Bluetooth Data Tools is a Python library that provides utilities for converting Bluetooth data and packets. It's currently at version 1.28.4 and maintains an active release cadence, with frequent updates to address bugs and introduce features.

Warnings

breaking Versions 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.
Fix: Upgrade to v1.26.5 or newer to avoid the segfault issue. Always use the latest stable release for critical fixes.
gotcha Prior 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.
Fix: Upgrade 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.
gotcha In 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.
Fix: Upgrade 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.

Install

pip install bluetooth-data-tools Install with pip

Imports

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.

Quickstart

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}")

view raw JSON →