blatann.gatt.gatts module

class blatann.gatt.gatts.GattsUserDescriptionProperties(value, write=False, security_level=SecurityLevel.OPEN, max_length=0, variable_length=False)

Bases: GattsAttributeProperties

Properties used to configure the User Description characteristic descriptor.

The most basic, set-once, read-only usage of this is GattsUserDescriptionProperties("my description")

class blatann.gatt.gatts.GattsCharacteristicProperties(read=True, write=False, notify=False, indicate=False, broadcast=False, write_no_response=False, signed_write=False, security_level=SecurityLevel.OPEN, max_length=20, variable_length=True, sccd=False, user_description=None, presentation_format=None, cccd_write_security_level=SecurityLevel.OPEN)

Bases: CharacteristicProperties

Properties for Gatt Server characeristics

class blatann.gatt.gatts.GattsCharacteristic(ble_device, peer, uuid, properties, value_handle, cccd_handle, sccd_handle, user_desc_handle, notification_manager, value=b'', prefer_indications=True, string_encoding='utf8')

Bases: Characteristic

Represents a single characteristic within a service. This class is usually not instantiated directly; it is added to a service through GattsService.add_characteristic()

set_value(value, notify_client=False)

Sets the value of the characteristic.

Parameters:

value – The value to set to. Must be an iterable type such as a str, bytes, or list of uint8 values, or a BleDataStream object. Length must be less than or equal to the characteristic’s max length. If a string is given, it will be encoded using the string_encoding property of the characteristic.
notify_client – Flag whether or not to notify the client. If indications and notifications are not set up for the characteristic, will raise an InvalidOperationException

Raises:

InvalidOperationException if value length is too long, or notify client set and characteristic is not notifiable

Raises:

InvalidStateException if the client is not currently subscribed to the characteristic

Returns:

If notify_client is true, this method will return the waitable for when the notification is sent to the client

notify(data)

Notifies the client with the data provided without setting the data into the characteristic value. If data is not provided (None), will notify with the currently-set value of the characteristic

Parameters:: data – Optional data to notify the client with. If supplied, must be an iterable type such as a str, bytes, or list of uint8 values, or a BleDataStream object. Length must be less than or equal to the characteristic’s max length. If a string is given, it will be encoded using the string_encoding property of the characteristic.
Raises:: InvalidStateException if the client is not subscribed to the characteristic
Raises:: InvalidOperationException if the characteristic is not configured for notifications/indications
Returns:: An EventWaitable that will trigger when the notification is successfully sent to the client. The waitable also contains the ID of the sent notification which is used in the on_notify_complete event

add_descriptor(uuid, properties, initial_value=b'', string_encoding='utf8')

Creates and adds a descriptor to the characteristic

Note

Due to limitations of the BLE stack, the CCCD, SCCD, User Description, Extended Properties, and Presentation Format descriptors cannot be added through this method. They must be added through the GattsCharacteristicProperties fields when creating the characteristic.

Parameters:

uuid (Uuid) – The UUID of the descriptor to add, and cannot be the UUIDs of any of the reserved descriptor UUIDs in the note
properties (GattsAttributeProperties) – The properties of the descriptor
initial_value – The initial value to set the descriptor to
string_encoding – The string encoding to use, if a string is set

Return type:

GattsAttribute

Returns:

the descriptor that was created and added to the characteristic

add_constant_value_descriptor(uuid, value, security_level=SecurityLevel.OPEN)

Adds a descriptor to the characteristic which is a constant, read-only value that cannot be updated after this call. This is a simplified parameter set built on top of add_descriptor() for this common use-case.

Note

See note on add_descriptor() for limitations on descriptors that can be added through this method.

Parameters:

uuid (Uuid) – The UUID of the descriptor to add
value (bytes) – The value to set the descriptor to
security_level – The security level for the descriptor

Return type:

GattsAttribute

Returns:

The descriptor that was created and added to the characteristic

property max_length: int

Read Only

The max possible the value the characteristic can be set to

property notifiable: bool

Read Only

Gets if the characteristic is set up to asynchonously notify clients via notifications or indications

property value: bytes

Read Only

Gets the current value of the characteristic. Value is updated using set_value()

property client_subscribed: bool

Read Only

Gets if the client is currently subscribed (notify or indicate) to this characteristic

property attributes: Iterable[GattsAttribute]

Read Only

Gets all of the attributes and descriptors associated with this characteristic

property user_description: GattsAttribute | None

Read Only

Gets the User Description attribute for the characteristic if set in the properties. If the user description was not configured for the characteristic, returns None

property sccd: GattsAttribute | None

Read Only

Gets the Server Characteristic Configuration Descriptor (SCCD) attribute if set in the properties. If the SCCD was not configured for the characteristic, returns None

property presentation_format: PresentationFormat | None

Read Only

Gets the presentation format that was set for the characteristic. If the presentation format was not configured for the characteristic, returns None

property string_encoding: str

The default method for encoding strings into bytes when a string is provided as a value

Getter:: Gets the string encoding in use
Setter:: Sets the string encoding to use

property on_write: Event[GattsCharacteristic, WriteEventArgs]

Event generated whenever a client writes to this characteristic.

Returns:: an Event which can have handlers registered to and deregistered from

property on_read: Event[GattsCharacteristic, None]

Event generated whenever a client requests to read from this characteristic. At this point, the application may choose to update the value of the characteristic to a new value using set_value.

A good example of this is a “system time” characteristic which reports the applications system time in seconds. Instead of updating this characteristic every second, it can be “lazily” updated only when read from.

NOTE: if there are multiple handlers subscribed to this and each set the value differently, it may cause undefined behavior.

Returns:: an Event which can have handlers registered to and deregistered from

property on_subscription_change: Event[GattsCharacteristic, SubscriptionStateChangeEventArgs]

Event that is generated whenever a client changes its subscription state of the characteristic (notify, indicate, none).

Returns:: an Event which can have handlers registered to and deregistered from

property on_notify_complete: Event[GattsCharacteristic, NotificationCompleteEventArgs]

Event that is generated when a notification or indication sent to the client successfully

Returns:: an event which can have handlers registered to and deregistered from

write_queue_async(event_loop=None)

Warning

This API is experimental!

Provides a queue that can be asynchronously iterated over to receive write requests rather than a callback running in the event handler thread.

The iterator will continue until the peripheral is disconnected.

Example:

await client.wait_for_connection_async()
async for _, event_args in characteristic.write_queue_async():
    print(f"Got write event: {event_args}")
print("Peer disconnected")

Parameters:: event_loop (Optional[AbstractEventLoop]) – Optional event loop the async queue will be consumed on
Return type:: AsyncEventQueue[GattsCharacteristic, WriteEventArgs]
Returns:: The async event queue object

write_queue()

Warning

This API is experimental!

Provides a queue that can be synchronously iterated over to receive write requests rather than a callback running in the event handler thread.

The iterator will continue until the peripheral is disconnected.

Example:

client.wait_for_connection()
for _, event_args in characteristic.write_queue():
    print(f"Got write event: {event_args}")
print("Peer disconnected")

Return type:: EventQueue[GattsCharacteristic, WriteEventArgs]
Returns:: The event queue object

class blatann.gatt.gatts.GattsService(ble_device, peer, uuid, service_type, notification_manager, start_handle=0, end_handle=0)

Bases: Service

Represents a registered GATT service that lives locally on the device.

This class is usually not instantiated directly and is instead created through GattsDatabase.add_service().

property characteristics: List[GattsCharacteristic]

Read Only

Gets the list of characteristics in this service.

Characteristics are added through add_characteristic()

add_characteristic(uuid, properties, initial_value=b'', prefer_indications=True, string_encoding='utf8')

Adds a new characteristic to the service

Parameters:

uuid (Uuid) – The UUID of the characteristic to add
properties (GattsCharacteristicProperties) – The characteristic’s properties
initial_value (str or list or bytearray) – The initial value of the characteristic. May be a string, bytearray, or list of ints
prefer_indications – Flag for choosing indication/notification if a characteristic has both indications and notifications available
string_encoding – The encoding method to use when a string value is provided (utf8, ascii, etc.)

Returns:

The characteristic just added to the service

Return type:

GattsCharacteristic

class blatann.gatt.gatts.GattsDatabase(ble_device, peer, notification_hardware_queue_size=1)

Bases: GattDatabase

Represents the entire GATT server that lives locally on the device which clients read from and write to

property services: List[GattsService]

Read Only

The list of services registered in the database

iter_services()

Iterates through all of the registered services in the database

Return type:: Iterable[GattsService]
Returns:: Generator of the database’s services

add_service(uuid, service_type=ServiceType.PRIMARY)

Adds a service to the local database

Parameters:

uuid (Uuid) – The UUID for the service
service_type – The type of service (primary or secondary)

Return type:

GattsService

Returns:

The added and newly created service

clear_pending_notifications(): Clears all pending notifications that are queued to be sent to the client