src.bluetooth_sig.device.peripheral_device¶

High-level peripheral (GATT server) abstraction.

Provides PeripheralDevice, the server-side counterpart to Device. Where Device connects TO remote peripherals and reads GATT data, PeripheralDevice hosts GATT services and encodes values for remote centrals to read.

Composes PeripheralManagerProtocol with BaseCharacteristic instances that handle value encoding via build_value().

Classes¶

Name	Description
`HostedCharacteristic`	Tracks a hosted characteristic with its definition and class instance.
`PeripheralDevice`	High-level BLE peripheral abstraction using composition pattern.

Module Contents¶

class src.bluetooth_sig.device.peripheral_device.HostedCharacteristic(definition: bluetooth_sig.types.peripheral_types.CharacteristicDefinition, characteristic: bluetooth_sig.gatt.characteristics.base.BaseCharacteristic[Any], initial_value: Any = None)¶

Tracks a hosted characteristic with its definition and class instance.

definition¶: The GATT characteristic definition registered on the peripheral.

characteristic¶: The SIG characteristic class instance used for encoding/decoding.

last_value¶: The last Python value that was encoded and set on this characteristic.

characteristic¶

definition¶

last_value: Any = None¶

class src.bluetooth_sig.device.peripheral_device.PeripheralDevice(peripheral_manager: src.bluetooth_sig.device.peripheral.PeripheralManagerProtocol)¶

High-level BLE peripheral abstraction using composition pattern.

Coordinates between PeripheralManagerProtocol (backend) and BaseCharacteristic instances (encoding) so callers work with typed Python values.

Encoding is handled directly by the characteristic’s build_value() method — no translator is needed on the peripheral (server) side.

The workflow mirrors Device but for the server role:

Create a PeripheralDevice wrapping a backend.
Add services with add_service() (typed helpers encode initial values).
Start advertising with start().
Update characteristic values with update_value().
Stop with stop().

Example:

>>> from bluetooth_sig.gatt.characteristics import BatteryLevelCharacteristic
>>> from bluetooth_sig.gatt.services import BatteryService
>>>
>>> peripheral = PeripheralDevice(backend)
>>> battery_char = BatteryLevelCharacteristic()
>>> peripheral.add_characteristic(
...     service_uuid=BatteryService.get_class_uuid(),
...     characteristic=battery_char,
...     initial_value=85,
... )
>>> await peripheral.start()
>>> await peripheral.update_value(battery_char, 72)

add_characteristic(service_uuid: str | bluetooth_sig.types.uuid.BluetoothUUID, characteristic: bluetooth_sig.gatt.characteristics.base.BaseCharacteristic[Any], initial_value: Any, *, properties: bluetooth_sig.types.gatt_enums.GattProperty | None = None) → bluetooth_sig.types.peripheral_types.CharacteristicDefinition¶

If the service has not been seen before, a new primary ServiceDefinition is created automatically.

Parameters:

service_uuid – UUID of the parent service.
characteristic – SIG characteristic class instance.
initial_value – Python value to encode as the initial value.
properties – GATT properties. Defaults to READ | NOTIFY.

Returns:

The created CharacteristicDefinition.

Raises:

RuntimeError – If the peripheral has already started advertising.

async add_service(service: bluetooth_sig.types.peripheral_types.ServiceDefinition) → None¶

For full control over the service definition. If you prefer typed helpers, use add_characteristic() instead.

Parameters:: service – Complete service definition.
Raises:: RuntimeError – If the peripheral has already started advertising.

async get_current_value(characteristic: bluetooth_sig.gatt.characteristics.base.BaseCharacteristic[Any] | str | bluetooth_sig.types.uuid.BluetoothUUID) → Any¶

Get the last Python value set for a hosted characteristic.

Parameters:: characteristic – The characteristic instance, UUID string, or BluetoothUUID.
Returns:: The last value passed to update_value(), or the initial value.
Raises:: KeyError – If the characteristic is not hosted.

async start() → None¶

All services added via add_characteristic() are flushed to the backend before start() is called on the manager.

Raises:: RuntimeError – If the peripheral has already started.

async stop() → None¶: Stop advertising and disconnect all clients.

async update_raw(char_uuid: str | bluetooth_sig.types.uuid.BluetoothUUID, raw_value: bytearray, *, notify: bool = True) → None¶

Push pre-encoded bytes to a hosted characteristic.

Use this when you already have the encoded value or the characteristic does not have a SIG class registered.

Parameters:

char_uuid – UUID of the characteristic.
raw_value – Pre-encoded bytes to set.
notify – Whether to notify subscribed centrals.

Raises:

KeyError – If the characteristic UUID is not hosted.
RuntimeError – If the peripheral has not started.

async update_value(characteristic: bluetooth_sig.gatt.characteristics.base.BaseCharacteristic[Any] | str | bluetooth_sig.types.uuid.BluetoothUUID, value: Any, *, notify: bool = True) → None¶

Encode a typed value and push it to the hosted characteristic.

Parameters:

characteristic – The characteristic instance, UUID string, or BluetoothUUID.
value – Python value to encode via build_value().
notify – Whether to notify subscribed centrals. Default True.

Raises:

KeyError – If the characteristic is not hosted on this peripheral.
RuntimeError – If the peripheral has not started.

with_connectable(connectable: bool) → PeripheralDevice¶

Set whether the peripheral accepts connections.

Parameters:: connectable – True to accept connections.
Returns:: Self for method chaining.

with_discoverable(discoverable: bool) → PeripheralDevice¶

Set whether the peripheral is discoverable.

Parameters:: discoverable – True to be discoverable.
Returns:: Self for method chaining.

with_manufacturer_data(company_id: int, payload: bytes) → PeripheralDevice¶

Configure manufacturer data for advertising.

Parameters:

company_id – Bluetooth SIG company identifier.
payload – Manufacturer-specific payload bytes.

Returns:

Self for method chaining.

with_tx_power(power_dbm: int) → PeripheralDevice¶

Set TX power level.

Parameters:: power_dbm – Transmission power in dBm.
Returns:: Self for method chaining.

property hosted_characteristics: dict[str, HostedCharacteristic]¶: Map of UUID → HostedCharacteristic for all hosted characteristics.

property is_advertising: bool¶: Whether the peripheral is currently advertising.

property name: str¶: Advertised device name.

property services: list[bluetooth_sig.types.peripheral_types.ServiceDefinition]¶: Registered GATT services.