src.bluetooth_sig.device.characteristic_io

Characteristic I/O operations for BLE devices.

Encapsulates read, write, and notification operations for GATT characteristics, including type-safe overloads for class-based and string/enum-based access.

Attributes

Name	Description
T
logger

Classes

Name	Description
CharacteristicIO	Read, write, and notification operations for GATT characteristics.

Module Contents

class src.bluetooth_sig.device.characteristic_io.CharacteristicIO(connection_manager: src.bluetooth_sig.device.client.ClientManagerProtocol, translator: src.bluetooth_sig.device.protocols.SIGTranslatorProtocol, dep_resolver: src.bluetooth_sig.device.dependency_resolver.DependencyResolver, device_info_factory: collections.abc.Callable[[], src.bluetooth_sig.gatt.context.DeviceInfo])

Read, write, and notification operations for GATT characteristics.

Encapsulates the I/O logic extracted from Device, handling both type-safe (class-based) and dynamic (string/enum-based) characteristic access patterns.

Uses DependencyResolver for automatic dependency resolution before reads, and a device_info_factory callable to get current DeviceInfo without a back-reference to the owning Device.

async read(char: type[src.bluetooth_sig.gatt.characteristics.base.BaseCharacteristic[T]], resolution_mode: src.bluetooth_sig.device.dependency_resolver.DependencyResolutionMode = ...) → T | None

async read(char: str | src.bluetooth_sig.gatt.characteristics.CharacteristicName, resolution_mode: src.bluetooth_sig.device.dependency_resolver.DependencyResolutionMode = ...) → Any | None

Read a characteristic value from the device.

Parameters:

• char – Name, enum, or characteristic class to read. Passing the class enables type-safe return values.

• resolution_mode – How to handle automatic dependency resolution: - NORMAL: Auto-resolve dependencies, use cache when available (default) - SKIP_DEPENDENCIES: Skip dependency resolution and validation - FORCE_REFRESH: Re-read dependencies from device, ignoring cache

Returns:

Parsed characteristic value or None if read fails. Return type is inferred from characteristic class when provided.

Raises:

• RuntimeError – If no connection manager is attached

• ValueError – If required dependencies cannot be resolved

async read_multiple(char_names: list[str | src.bluetooth_sig.gatt.characteristics.CharacteristicName]) → dict[str, Any | None]

Read multiple characteristics in batch.

Parameters:

char_names – List of characteristic names or enums to read

Returns:

Dictionary mapping characteristic UUIDs to parsed values

async start_notify(char: type[src.bluetooth_sig.gatt.characteristics.base.BaseCharacteristic[T]], callback: collections.abc.Callable[[T], None]) → None

async start_notify(char: str | src.bluetooth_sig.gatt.characteristics.CharacteristicName, callback: collections.abc.Callable[[Any], None]) → None

Start notifications for a characteristic.

Parameters:

• char – Name, enum, or characteristic class to monitor. Passing the class enables type-safe callbacks.

• callback – Function to call when notifications are received. Callback parameter type is inferred from characteristic class.

Raises:

RuntimeError – If no connection manager is attached

async stop_notify(char_name: str | src.bluetooth_sig.gatt.characteristics.CharacteristicName) → None

Stop notifications for a characteristic.

Parameters:

char_name – Characteristic name or UUID

async write(char: type[src.bluetooth_sig.gatt.characteristics.base.BaseCharacteristic[T]], data: T, response: bool = ...) → None

async write(char: str | src.bluetooth_sig.gatt.characteristics.CharacteristicName, data: bytes, response: bool = ...) → None

Write data to a characteristic on the device.

Parameters:

• char – Name, enum, or characteristic class to write to. Passing the class enables type-safe value encoding.

• data – Raw bytes (for string/enum) or typed value (for characteristic class). When using characteristic class, the value is encoded using build_value().

• response – If True, use write-with-response (wait for acknowledgment). If False, use write-without-response (faster but no confirmation). Default is True for reliability.

Raises:

• RuntimeError – If no connection manager is attached

• CharacteristicEncodeError – If encoding fails (when using characteristic class)

async write_multiple(data_map: dict[str | src.bluetooth_sig.gatt.characteristics.CharacteristicName, bytes], response: bool = True) → dict[str, bool]

Write to multiple characteristics in batch.

Parameters:

• data_map – Dictionary mapping characteristic names/enums to data bytes

• response – If True, use write-with-response for all writes. If False, use write-without-response for all writes.

Returns:

Dictionary mapping characteristic UUIDs to success status

src.bluetooth_sig.device.characteristic_io.T

src.bluetooth_sig.device.characteristic_io.logger