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
- Return type
Optional
[IdBasedEventWaitable
[GattsCharacteristic
,NotificationCompleteEventArgs
]]- 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
- Return type
IdBasedEventWaitable
[GattsCharacteristic
,NotificationCompleteEventArgs
]- 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 noteproperties (
GattsAttributeProperties
) – The properties of the descriptorinitial_value – The initial value to set the descriptor to
string_encoding – The string encoding to use, if a string is set
- Return type
- 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
- Return type
- Returns
The descriptor that was created and added to the characteristic
- 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: Optional[GattsAttribute]¶
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: Optional[GattsAttribute]¶
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: Optional[PresentationFormat]¶
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
- 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 addproperties (
GattsCharacteristicProperties
) – The characteristic’s propertiesinitial_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
- 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
- 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 serviceservice_type – The type of service (primary or secondary)
- Return type
- Returns
The added and newly created service
- clear_pending_notifications()¶
Clears all pending notifications that are queued to be sent to the client