Bluetooth SIG Standards Library¶

A pure Python library for Bluetooth SIG standards interpretation

Welcome¶

The Bluetooth SIG Standards Library provides comprehensive GATT characteristic and service parsing with automatic UUID resolution. Built on the official Bluetooth SIG specifications, it offers a robust, standards-compliant architecture for Bluetooth device communication with type-safe data parsing and clean API design.

Key Features¶

✅ Standards-Based: Official Bluetooth SIG YAML registry with automatic UUID resolution
✅ Type-Safe: Characteristic classes provide compile-time type checking and IDE autocomplete
✅ Modern Python: msgspec-based design with Python 3.9+ compatibility
✅ Comprehensive: Support for 200+ GATT characteristics across multiple service categories
✅ Framework Agnostic: Works with any BLE connection library (bleak, simplepyble, etc.)

Quick Example¶

Device abstraction (recommended for backend abstraction):

# SKIP: Requires actual BLE device connection
from bluetooth_sig import BluetoothSIGTranslator, Device
from bluetooth_sig.gatt.characteristics import BatteryLevelCharacteristic

# Connection manager for your BLE backend
from examples.connection_managers.bleak_retry import (
    BleakRetryClientManager,
)


async def main():
    translator = BluetoothSIGTranslator()
    device = Device(
        BleakRetryClientManager("AA:BB:CC:DD:EE:FF"), translator
    )

    await device.connect()
    battery = await device.read(BatteryLevelCharacteristic)  # IDE knows: int
    print(f"Battery: {battery}%")
    await device.disconnect()

Type-safe parsing (direct characteristic access):

from bluetooth_sig.gatt.characteristics import BatteryLevelCharacteristic

battery = BatteryLevelCharacteristic()
level = battery.parse_value(bytearray([85]))  # IDE infers int
print(f"Battery: {level}%")  # Battery: 85%

Dynamic parsing (for scanning unknown devices):

from bluetooth_sig import BluetoothSIGTranslator

translator = BluetoothSIGTranslator()
result = translator.parse_characteristic("2A19", bytearray([85]))
print(f"Battery Level: {result}%")  # Battery Level: 85%

Getting Started¶

⚡ Quick Start

Get up and running in minutes

Quick Start

📦 Installation

Install via pip or from source

Installation

📖 Usage Guide

Real-world usage patterns

Usage

📚 API Reference

Detailed API documentation

API Reference

Which Guide Should I Read?¶

I want to…	Read this
Get started quickly	Quick Start
Choose the right API approach	Choosing the Right API
Integrate with bleak or other BLE libraries	BLE Integration Guide
See real-world usage patterns	Usage Guide
Use async patterns	Async Usage
Understand the library’s purpose	Why Use This Library

Why Choose This Library?¶

Unlike other Bluetooth libraries that focus on device connectivity, this library specializes in standards interpretation. It bridges the gap between raw BLE data and meaningful application-level information.

Learn more about what this library solves →

Support¶

Issues: GitHub Issues
Source Code: GitHub Repository
Documentation: You’re here! 🎉
Test Coverage: Available in CI artifacts

License¶

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