src.bluetooth_sig.device.peripheral_device

High-level peripheral (GATT server) abstraction.

Provides PeripheralDevice, a server-side helper that hosts GATT services and encodes values for remote centrals to read.

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.

Deprecated since version 0.5.0: Scheduled for removal; see docs/source/explanation/limitations.md.

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:

  1. Create a PeripheralDevice wrapping a backend.

  2. Add services with add_service() (typed helpers encode initial values).

  3. Start advertising with start().

  4. Update characteristic values with update_value().

  5. 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

Register a characteristic on a service, encoding the initial value.

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

Register a pre-built service definition directly.

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

Register pending services on the backend and start advertising.

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.