Skip to content

Bluetooth SIG Standards Library

Coverage Status Python 3.9+ PyPI version License: MIT Documentation

A pure Python library for Bluetooth SIG standards interpretation, providing comprehensive GATT characteristic and service parsing with automatic UUID resolution.

📚 Full Documentation | 🚀 Quick Start | 📖 API Reference

Features

  • ✅ Standards-Based: Official Bluetooth SIG YAML registry with automatic UUID resolution
  • ✅ Type-Safe: Convert raw Bluetooth data to meaningful values with comprehensive typing
  • ✅ Modern Python: Dataclass-based design with Python 3.9+ compatibility
  • ✅ Comprehensive: Support for 70+ GATT characteristics across multiple service categories
  • ✅ Production Ready: Extensive validation and comprehensive testing
  • ✅ Framework Agnostic: Works with any BLE library (bleak, simplepyble, etc.)

Installation

pip install bluetooth-sig

Quick Start

from bluetooth_sig import BluetoothSIGTranslator

translator = BluetoothSIGTranslator()
service_info = translator.get_sig_info_by_uuid("180F")
print(service_info.name)  # "Battery Service"

Parse characteristic data

battery_data = translator.parse_characteristic("2A19", bytearray([85]), descriptor_data=None)
print(f"Battery: {battery_data.value}%")  # "Battery: 85%"

What This Library Does

  • ✅ Parse Bluetooth GATT characteristics according to official specifications
  • ✅ Resolve UUIDs to human-readable service and characteristic names
  • ✅ Provide type-safe data structures for all parsed values
  • ✅ Work with any BLE library (bleak, simplepyble, etc.)
  • ✅ Supports user created custom characteristics and services by allowing users to register their own UUIDs and parsing logic.

What This Library Does NOT Do

  • ❌ BLE device connections - Use bleak, simplepyble, or similar libraries
  • ❌ Firmware implementation - This is a client-side library

Learn more about what problems this solves →

Integration with BLE Libraries

Works seamlessly with any BLE connection library:

from bleak import BleakClient
from bluetooth_sig import BluetoothSIGTranslator

translator = BluetoothSIGTranslator()

async with BleakClient(address) as client:
    # bleak handles connection
    raw_data = await client.read_gatt_char("2A19")

    # bluetooth-sig handles parsing
    result = translator.parse_characteristic("2A19", raw_data, descriptor_data=None)
    print(f"Battery: {result.value}%")

See the BLE Integration Guide for examples with bleak, bleak-retry-connector, and simplepyble.

Supported Characteristics

70+ GATT characteristics across multiple categories:

  • Battery Service: Level, Power State
  • Environmental Sensing: Temperature, Humidity, Pressure, Air Quality
  • Health Monitoring: Heart Rate, Blood Pressure, Glucose
  • Fitness Tracking: Running/Cycling Speed, Cadence, Power
  • Device Information: Manufacturer, Model, Firmware Version
  • And many more...

View full list of supported services →

Documentation

Contributing

Contributions are welcome! Please see the Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.