{"id":6552,"library":"bluetooth-data-tools","title":"Bluetooth Data Tools","description":"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.","status":"active","version":"1.28.4","language":"en","source_language":"en","source_url":"https://github.com/Bluetooth-Devices/bluetooth-data-tools","tags":["bluetooth","BLE","parsing","advertisement","data conversion","GAP"],"install":[{"cmd":"pip install bluetooth-data-tools","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for cryptographic operations, likely related to secure Bluetooth features or address resolution.","package":"cryptography","optional":false}],"imports":[{"note":"Primary function for parsing raw BLE advertisement data.","symbol":"parse_advertisement_data_bytes","correct":"from bluetooth_data_tools import parse_advertisement_data_bytes"},{"note":"Object-oriented interface for parsed BLE advertisement data.","symbol":"BLEGAPAdvertisement","correct":"from bluetooth_data_tools import BLEGAPAdvertisement"},{"note":"Utility for converting integer to MAC address string.","symbol":"int_to_bluetooth_address","correct":"from bluetooth_data_tools import int_to_bluetooth_address"},{"note":"Utility for estimating distance from TX power and RSSI.","symbol":"calculate_distance_meters","correct":"from bluetooth_data_tools import calculate_distance_meters"}],"quickstart":{"code":"from bluetooth_data_tools import parse_advertisement_data_bytes\n\n# Example raw BLE advertisement bytes (replace with actual data)\n# This example is illustrative; real data would come from a BLE scan.\n# For a simple test, you could use data from a known device.\nraw_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])\n\nparsed_data = parse_advertisement_data_bytes(raw_advertisement_bytes)\n\n# The parsed_data is a tuple: (local_name, service_uuids, service_data, manufacturer_data, tx_power)\nlocal_name, service_uuids, service_data, manufacturer_data, tx_power = parsed_data\n\nprint(f\"Local Name: {local_name}\")\nprint(f\"Service UUIDs: {service_uuids}\")\nprint(f\"Service Data: {service_data}\")\nprint(f\"Manufacturer Data: {manufacturer_data}\")\nprint(f\"TX Power: {tx_power}\")\n\n# Using the object-oriented interface (requires a list of raw bytes, even if one)\nfrom bluetooth_data_tools import BLEGAPAdvertisement, parse_advertisement_data\nadv = parse_advertisement_data([raw_advertisement_bytes])\n\nprint(f\"\\nObject-oriented parsing:\")\nprint(f\"Local Name: {adv.local_name}\")\nprint(f\"Service UUIDs: {adv.service_uuids}\")","lang":"python","description":"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`."},"warnings":[{"fix":"Upgrade to v1.26.5 or newer to avoid the segfault issue. Always use the latest stable release for critical fixes.","message":"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.","severity":"breaking","affected_versions":"1.26.2, 1.26.3, 1.26.4"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.28.4"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.28.2"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}