src.bluetooth_sig.core.translator

Core Bluetooth SIG standards translator — thin composition facade.

This module provides the public BluetoothSIGTranslator class, which delegates all work to five focused components:

The facade preserves every public method signature, @overload decorator, async wrapper, and the singleton pattern from the original monolithic implementation.

Attributes

Name

Description

BluetoothSIG

Classes

Name

Description

BluetoothSIGTranslator

Pure Bluetooth SIG standards translator for characteristic and service interpretation.

Module Contents

class src.bluetooth_sig.core.translator.BluetoothSIGTranslator

Pure Bluetooth SIG standards translator for characteristic and service interpretation.

This class provides the primary API surface for Bluetooth SIG standards translation, covering characteristic parsing, service discovery, UUID resolution, and registry management.

Singleton Pattern:

This class is implemented as a singleton to provide a global registry for custom characteristics and services. Access the singleton instance using BluetoothSIGTranslator.get_instance() or the module-level translator variable.

Key features: - Parse raw BLE characteristic data using Bluetooth SIG specifications - Resolve UUIDs to [CharacteristicInfo][bluetooth_sig.types.CharacteristicInfo]

and [ServiceInfo][bluetooth_sig.types.ServiceInfo]

  • Create BaseGattService instances from service UUIDs

  • Access comprehensive registry of supported characteristics and services

Note: This class intentionally has >20 public methods as it serves as the primary API surface for Bluetooth SIG standards translation. The methods are organized by functionality and reducing them would harm API clarity.

clear_services() → None

Clear all discovered services.

create_value(uuid: str, **kwargs: Any) → Any

Create a properly typed value instance for a characteristic.

Parameters:

  • uuid – The characteristic UUID

  • **kwargs – Field values for the characteristic’s type

Returns:

Properly typed value instance

Raises:

  • ValueError – If UUID is invalid or characteristic not found

  • TypeError – If kwargs don’t match the characteristic’s expected fields

Example:

from bluetooth_sig import BluetoothSIGTranslator

translator = BluetoothSIGTranslator()
accel = translator.create_value("2C1D", x_axis=1.5, y_axis=0.5, z_axis=9.8)
data = translator.encode_characteristic("2C1D", accel)
encode_characteristic(char: type[src.bluetooth_sig.gatt.characteristics.base.BaseCharacteristic[T]], value: T, validate: bool = ...) → bytes
encode_characteristic(char: str, value: Any, validate: bool = ...) → bytes

Encode a value for writing to a characteristic.

Parameters:

  • char – Characteristic class (type-safe) or UUID string (not type-safe).

  • value – The value to encode. Type is checked when using characteristic class.

  • validate – If True, validates the value before encoding (default: True)

Returns:

Encoded bytes ready to write to the characteristic

Raises:

Example:

from bluetooth_sig import BluetoothSIGTranslator
from bluetooth_sig.gatt.characteristics import AlertLevelCharacteristic
from bluetooth_sig.gatt.characteristics.alert_level import AlertLevel

translator = BluetoothSIGTranslator()

# Type-safe: pass characteristic class and typed value
data: bytes = translator.encode_characteristic(AlertLevelCharacteristic, AlertLevel.HIGH)

# Not type-safe: pass UUID string
data = translator.encode_characteristic("2A06", 2)
async encode_characteristic_async(char: type[src.bluetooth_sig.gatt.characteristics.base.BaseCharacteristic[T]], value: T, validate: bool = ...) → bytes
async encode_characteristic_async(char: str | src.bluetooth_sig.types.uuid.BluetoothUUID, value: Any, validate: bool = ...) → bytes

Encode characteristic value in an async-compatible manner.

Parameters:

  • char – Characteristic class (type-safe) or UUID string/BluetoothUUID.

  • value – The value to encode.

  • validate – If True, validates before encoding (default: True)

Returns:

Encoded bytes ready to write

get_characteristic_info_by_name(name: src.bluetooth_sig.types.gatt_enums.CharacteristicName) → src.bluetooth_sig.types.CharacteristicInfo | None

Get characteristic info by enum name.

Parameters:

name – CharacteristicName enum

Returns:

CharacteristicInfo if found, None otherwise

get_characteristic_info_by_uuid(uuid: str) → src.bluetooth_sig.types.CharacteristicInfo | None

Get information about a characteristic by UUID.

Parameters:

uuid – The characteristic UUID (16-bit short form or full 128-bit)

Returns:

CharacteristicInfo with metadata or None if not found

get_characteristic_uuid_by_name(name: src.bluetooth_sig.types.gatt_enums.CharacteristicName) → src.bluetooth_sig.types.uuid.BluetoothUUID | None

Get the UUID for a characteristic name enum.

Parameters:

name – CharacteristicName enum

Returns:

Characteristic UUID or None if not found

get_characteristics_info_by_uuids(uuids: list[str]) → dict[str, src.bluetooth_sig.types.CharacteristicInfo | None]

Get information about multiple characteristics by UUID.

Parameters:

uuids – List of characteristic UUIDs

Returns:

Dictionary mapping UUIDs to CharacteristicInfo (or None if not found)

classmethod get_instance() → BluetoothSIGTranslator

Get the singleton instance of BluetoothSIGTranslator.

Returns:

The singleton BluetoothSIGTranslator instance

Example:

from bluetooth_sig import BluetoothSIGTranslator

# Get the singleton instance
translator = BluetoothSIGTranslator.get_instance()
get_service_by_uuid(uuid: str) → src.bluetooth_sig.gatt.services.base.BaseGattService | None

Get a service instance by UUID.

Parameters:

uuid – The service UUID

Returns:

Service instance if found, None otherwise

get_service_characteristics(service_uuid: str) → list[src.bluetooth_sig.gatt.characteristics.base.BaseCharacteristic[Any]]

Get the characteristic instances associated with a service.

Instantiates each required characteristic class from the service definition and returns the live objects.

Parameters:

service_uuid – The service UUID

Returns:

List of BaseCharacteristic instances for this service’s required characteristics.

get_service_info_by_name(name: str | src.bluetooth_sig.gatt.services.ServiceName) → src.bluetooth_sig.types.ServiceInfo | None

Get service info by name or enum.

Parameters:

name – Service name string or ServiceName enum

Returns:

ServiceInfo if found, None otherwise

get_service_info_by_uuid(uuid: str) → src.bluetooth_sig.types.ServiceInfo | None

Get information about a service by UUID.

Parameters:

uuid – The service UUID

Returns:

ServiceInfo with metadata or None if not found

get_service_uuid_by_name(name: str | src.bluetooth_sig.gatt.services.ServiceName) → src.bluetooth_sig.types.uuid.BluetoothUUID | None

Get the UUID for a service name or enum.

Parameters:

name – Service name or enum

Returns:

Service UUID or None if not found

get_sig_info_by_name(name: str) → src.bluetooth_sig.types.SIGInfo | None

Get Bluetooth SIG information for a characteristic or service by name.

Parameters:

name – Characteristic or service name

Returns:

CharacteristicInfo or ServiceInfo if found, None otherwise

get_sig_info_by_uuid(uuid: str) → src.bluetooth_sig.types.SIGInfo | None

Get Bluetooth SIG information for a UUID.

Parameters:

uuid – UUID string (with or without dashes)

Returns:

CharacteristicInfo or ServiceInfo if found, None otherwise

get_value_type(uuid: str) → type | str | None

Get the expected Python type for a characteristic.

Parameters:

uuid – The characteristic UUID (16-bit short form or full 128-bit)

Returns:

Python type if characteristic is found, None otherwise

list_supported_characteristics() → dict[str, str]

List all supported characteristics with their names and UUIDs.

Returns:

Dictionary mapping characteristic names to UUIDs

list_supported_services() → dict[str, str]

List all supported services with their names and UUIDs.

Returns:

Dictionary mapping service names to UUIDs

parse_characteristic(char: type[src.bluetooth_sig.gatt.characteristics.base.BaseCharacteristic[T]], raw_data: bytes | bytearray, ctx: src.bluetooth_sig.types.CharacteristicContext | None = ...) → T
parse_characteristic(char: str, raw_data: bytes | bytearray, ctx: src.bluetooth_sig.types.CharacteristicContext | None = ...) → Any

Parse a characteristic’s raw data using Bluetooth SIG standards.

Parameters:

  • char – Characteristic class (type-safe) or UUID string (not type-safe).

  • raw_data – Raw bytes from the characteristic (bytes or bytearray)

  • ctx – Optional CharacteristicContext providing device-level info

Returns:

Parsed value. Return type is inferred when passing characteristic class.

Raises:

Example:

from bluetooth_sig import BluetoothSIGTranslator
from bluetooth_sig.gatt.characteristics import BatteryLevelCharacteristic

translator = BluetoothSIGTranslator()

# Type-safe: pass characteristic class, return type is inferred
level: int = translator.parse_characteristic(BatteryLevelCharacteristic, b"\\x64")

# Not type-safe: pass UUID string, returns Any
value = translator.parse_characteristic("2A19", b"\\x64")
async parse_characteristic_async(char: type[src.bluetooth_sig.gatt.characteristics.base.BaseCharacteristic[T]], raw_data: bytes, ctx: src.bluetooth_sig.types.CharacteristicContext | None = ...) → T
async parse_characteristic_async(char: str | src.bluetooth_sig.types.uuid.BluetoothUUID, raw_data: bytes, ctx: src.bluetooth_sig.types.CharacteristicContext | None = ...) → Any

Parse characteristic data in an async-compatible manner.

Parameters:

  • char – Characteristic class (type-safe) or UUID string/BluetoothUUID.

  • raw_data – Raw bytes from the characteristic

  • ctx – Optional context providing device-level info

Returns:

Parsed value. Return type is inferred when passing characteristic class.

Raises:
parse_characteristics(char_data: dict[str, bytes], ctx: src.bluetooth_sig.types.CharacteristicContext | None = None) → dict[str, Any]

Parse multiple characteristics at once with dependency-aware ordering.

Parameters:

  • char_data – Dictionary mapping UUIDs to raw data bytes

  • ctx – Optional CharacteristicContext used as the starting context

Returns:

Dictionary mapping UUIDs to parsed values

Raises:

Example:

from bluetooth_sig import BluetoothSIGTranslator

translator = BluetoothSIGTranslator()
data = {
    "2A6E": b"\\x0A\\x00",  # Temperature
    "2A6F": b"\\x32\\x00",  # Humidity
}
try:
    results = translator.parse_characteristics(data)
except CharacteristicParseError as e:
    print(f"Parse failed: {e}")
async parse_characteristics_async(char_data: dict[str, bytes], ctx: src.bluetooth_sig.types.CharacteristicContext | None = None) → dict[str, Any]

Parse multiple characteristics in an async-compatible manner.

Parameters:

  • char_data – Dictionary mapping UUIDs to raw data bytes

  • ctx – Optional context

Returns:

Dictionary mapping UUIDs to parsed values

process_services(services: dict[str, dict[str, src.bluetooth_sig.core.service_manager.CharacteristicDataDict]]) → None

Process discovered services and their characteristics.

Parameters:

services – Dictionary of service UUIDs to their characteristics

register_custom_characteristic_class(uuid_or_name: str, cls: type[src.bluetooth_sig.gatt.characteristics.base.BaseCharacteristic[Any]], info: src.bluetooth_sig.types.CharacteristicInfo | None = None, override: bool = False) → None

Register a custom characteristic class at runtime.

Parameters:

  • uuid_or_name – The characteristic UUID or name

  • cls – The characteristic class to register

  • info – Optional CharacteristicInfo with metadata (name, unit, python_type)

  • override – Whether to override existing registrations

Raises:

  • TypeError – If cls does not inherit from BaseCharacteristic

  • ValueError – If UUID conflicts with existing registration and override=False

Example:

from bluetooth_sig import BluetoothSIGTranslator, CharacteristicInfo
from bluetooth_sig.types import BluetoothUUID

translator = BluetoothSIGTranslator()
info = CharacteristicInfo(
    uuid=BluetoothUUID("12345678-1234-1234-1234-123456789abc"),
    name="Custom Temperature",
    unit="°C",
    python_type=float,
)
translator.register_custom_characteristic_class(str(info.uuid), MyCustomChar, info=info)
register_custom_service_class(uuid_or_name: str, cls: type[src.bluetooth_sig.gatt.services.base.BaseGattService], info: src.bluetooth_sig.types.ServiceInfo | None = None, override: bool = False) → None

Register a custom service class at runtime.

Parameters:

  • uuid_or_name – The service UUID or name

  • cls – The service class to register

  • info – Optional ServiceInfo with metadata (name)

  • override – Whether to override existing registrations

Raises:

  • TypeError – If cls does not inherit from BaseGattService

  • ValueError – If UUID conflicts with existing registration and override=False

Example:

from bluetooth_sig import BluetoothSIGTranslator, ServiceInfo
from bluetooth_sig.types import BluetoothUUID

translator = BluetoothSIGTranslator()
info = ServiceInfo(uuid=BluetoothUUID("12345678-..."), name="Custom Service")
translator.register_custom_service_class(str(info.uuid), MyService, info=info)
supports(uuid: str) → bool

Check if a characteristic UUID is supported.

Parameters:

uuid – The characteristic UUID to check

Returns:

True if the characteristic has a parser/encoder, False otherwise

validate_characteristic_data(uuid: str, data: bytes) → src.bluetooth_sig.types.ValidationResult

Validate characteristic data format against SIG specifications.

Parameters:

  • uuid – The characteristic UUID

  • data – Raw data bytes to validate

Returns:

ValidationResult with validation details

property discovered_services: list[src.bluetooth_sig.gatt.services.base.BaseGattService]

Get list of discovered service instances.

Returns:

List of discovered service instances

src.bluetooth_sig.core.translator.BluetoothSIG