blatann.gatt.gattc module

class blatann.gatt.gattc.GattcCharacteristic(ble_device, peer, uuid, properties, decl_attr, value_attr, cccd_attr=None, attributes=None)

Bases: Characteristic

Represents a characteristic that lives within a service in the server’s GATT database.

This class is normally not instantiated directly and instead created when the database is discovered via Peer.discover_services()

property declaration_attribute: GattcAttribute

Read Only

Gets the declaration attribute of the characteristic

property value_attribute: GattcAttribute

Read Only

Gets the value attribute of the characteristic

property value: bytes

Read Only

The current value of the characteristic. This is updated through read, write, and notify operations

property readable: bool

Read Only

Gets if the characteristic can be read from

property writable: bool

Read Only

Gets if the characteristic can be written to

property writable_without_response: bool

Read Only

Gets if the characteristic accepts write commands that don’t require a confirmation response

property subscribable: bool

Read Only

Gets if the characteristic can be subscribed to

property subscribable_indications: bool

Read Only

Gets if the characteristic can be subscribed to using indications

property subscribable_notifications: bool

Read Only

Gets if the characteristic can be subscribed to using notifications

property subscribed: bool

Read Only

Gets if the characteristic is currently subscribed to

property attributes: Iterable[GattcAttribute]

Read Only

Returns the list of all attributes/descriptors that reside in the characteristic. This includes the declaration attribute, value attribute, and descriptors (CCCD, Name, etc.)

property string_encoding: str

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

Getter:: Gets the current string encoding for the characteristic
Setter:: Sets the string encoding for the characteristic

property on_read_complete: Event[GattcCharacteristic, ReadCompleteEventArgs]: Event that is raised when a read operation from the characteristic is completed

property on_write_complete: Event[GattcCharacteristic, WriteCompleteEventArgs]: Event that is raised when a write operation to the characteristic is completed

property on_notification_received: Event[GattcCharacteristic, NotificationReceivedEventArgs]: Event that is raised when an indication or notification is received on the characteristic

notification_queue_async(event_loop=None)

Warning

This API is experimental!

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

The iterator will continue until the peripheral is disconnected.

Example:

await characteristic.subscribe().as_async()
async for _, event_args in characteristic.notification_queue_async():
    print(f"Got notification: {event_args}")
print("Peer disconnected")

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

notification_queue()

Warning

This API is experimental!

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

The iterator will continue until the peer is disconnected.

Example:

characteristic.subscribe().wait()
for _, event_args in characteristic.notification_queue():
    print(f"Got notification: {event_args}")
print("Peer disconnected")

Return type:: EventQueue[GattcCharacteristic, NotificationReceivedEventArgs]
Returns:: The event queue object

subscribe(on_notification_handler=None, prefer_indications=False)

Subscribes to the characteristic’s indications or notifications, depending on what’s available and the prefer_indications setting. Returns a Waitable that triggers when the subscription on the peripheral finishes.

Parameters:

on_notification_handler (Optional[Callable[[GattcCharacteristic, NotificationReceivedEventArgs], None]]) – Optional handler to be called when an indication or notification is received from the peripheral. Must take two parameters: (GattcCharacteristic this, NotificationReceivedEventArgs event args).
prefer_indications – If the peripheral supports both indications and notifications, will subscribe to indications instead of notifications

Return type:

EventWaitable[GattcCharacteristic, SubscriptionWriteCompleteEventArgs]

Returns:

A Waitable that will trigger when the subscription finishes

Raises:

InvalidOperationException if the characteristic cannot be subscribed to (characteristic does not support indications or notifications)

unsubscribe()

Unsubscribes from indications and notifications from the characteristic and clears out all handlers for the characteristic’s on_notification event handler. Returns a Waitable that triggers when the unsubscription finishes.

Return type:: EventWaitable[GattcCharacteristic, SubscriptionWriteCompleteEventArgs]
Returns:: A Waitable that will trigger when the unsubscription operation finishes
Raises:: InvalidOperationException if characteristic cannot be subscribed to (characteristic does not support indications or notifications)

read()

Initiates a read of the characteristic and returns a Waitable that triggers when the read finishes with the data read.

Return type:: EventWaitable[GattcCharacteristic, ReadCompleteEventArgs]
Returns:: A waitable that will trigger when the read finishes
Raises:: InvalidOperationException if characteristic not readable

write(data)

Performs a write request of the data provided to the characteristic and returns a Waitable that triggers when the write completes and the confirmation response is received from the other device.

Parameters:: data (str or bytes or bytearray) – The data to write. Can be a string, bytes, or anything that can be converted to bytes
Return type:: EventWaitable[GattcCharacteristic, WriteCompleteEventArgs]
Returns:: A waitable that returns when the write finishes
Raises:: InvalidOperationException if characteristic is not writable

write_without_response(data)

Performs a write command, which does not require the peripheral to send a confirmation response packet. This is a faster but lossy operation in the case that the packet is dropped/never received by the peer. This returns a waitable that triggers when the write is transmitted to the peripheral device.

Note

Data sent without responses must fit within a single MTU minus 3 bytes for the operation overhead.

Parameters:: data (str or bytes or bytearray) – The data to write. Can be a string, bytes, or anything that can be converted to bytes
Return type:: EventWaitable[GattcCharacteristic, WriteCompleteEventArgs]
Returns:: A waitable that returns when the write finishes
Raises:: InvalidOperationException if characteristic is not writable without responses

find_descriptor(uuid)

Searches for the descriptor/attribute matching the UUID provided and returns the attribute. If not found, returns None. If multiple attributes with the same UUID exist in the characteristic, this returns the first attribute found.

Parameters:: uuid (Uuid) – The UUID to search for
Return type:: Optional[GattcAttribute]
Returns:: THe descriptor attribute, if found

class blatann.gatt.gattc.GattcService(ble_device, peer, uuid, service_type, start_handle=0, end_handle=0)

Bases: Service

Represents a service that lives within the server’s GATT database.

This class is normally not instantiated directly and instead created when the database is discovered via Peer.discover_services()

property characteristics: List[GattcCharacteristic]: Gets the list of characteristics within the service

find_characteristic(characteristic_uuid)

Finds the characteristic matching the given UUID inside the service. If not found, returns None. If multiple characteristics with the same UUID exist within the service, this will return the first one found.

Parameters:: characteristic_uuid (Uuid) – The UUID of the characteristic to find
Return type:: Optional[GattcCharacteristic]
Returns:: The characteristic if found, otherwise None

class blatann.gatt.gattc.GattcDatabase(ble_device, peer, write_no_resp_queue_size=1)

Bases: GattDatabase

Represents a remote GATT Database which lives on a connected peripheral. Contains all discovered services, characteristics, and descriptors

property services: List[GattcService]: Gets the list of services within the database

find_service(service_uuid)

Finds the service matching the given UUID inside the database. If not found, returns None. If multiple services with the same UUID exist in the database, this will return the first service found.

Parameters:: service_uuid (Uuid) – The UUID of the service to find
Return type:: Optional[GattcService]
Returns:: The service if found, otherwise None

find_characteristic(characteristic_uuid)

Finds the characteristic matching the given UUID inside the database. If not found, returns None. If multiple characteristics with the same UUID exist in the database, this will return the first characteristic found.

Parameters:: characteristic_uuid (blatann.uuid.Uuid) – The UUID of the characteristic to find
Returns:: The characteristic if found, otherwise None
Return type:: GattcCharacteristic

iter_characteristics()

Iterates through all the characteristics in the database

Return type:: Iterable[GattcCharacteristic]
Returns:: An iterable of the characterisitcs in the database