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

subscribe(on_notification_handler, 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 (Callable[[GattcCharacteristic, NotificationReceivedEventArgs], None]) – The 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