GATT Configuration Guide¶
The purpose of this section is to show you how to setup a GATT table on the peripheral server using ABle. Do note that this requires prior knowledge on what GATT services and characteristics are, if you need a refresher check out the references on this page 1 2.
Do note that ABle currently does not support descriptors.
Adding a Service¶
Adding services is super easy, using the template provided in the getting started guide, we can add a service.
service = ABleService(uuid.uuid4())
able_peripheral.add_service(service)
This will add a service with a random UUID, but you can swap the param that the ABleService is initialized with to a string or another python UUID.
Note
If you are interested more in how the ABleService works, check out its base class documentation here.
Adding a Characteristic¶
After you add a service, you can add a characteristic to that service. Characteristics require their own UUID as well as a link to the service that it will be under so this step has to be after adding a service.
new_char = ABleCharacteristic(characteristic_uuid=uuid.uuid4())
able_peripheral.add_characteristic(service, new_char)
Similar to the service, this will create a characteristic with a random UUID, but it can be initialized with an instance of uuid.UUID.
At this point your GATT Table has a service with one characteristic, this is sufficient to progress in the guide to connections and communications, however if you wish to configure the table more, read on!
Note
If you are interested more in how the ABleCharacteristic works, check out its base class documentation here.
Configuring Characteristics¶
Characteristics are very configurable, ABle characteristics currently support modifying the flags/permissions on that characteristic to (dis/en)able writing, reading, indications, notifications, reliable writes, as well as initializing the characteristic with bytes already on it.
Flags and Permissions¶
By default ABleCharacteristics are configured for reading, writing and notifications, but if you wish to change these you can pass in a list of flags in the initialization of the characteristic. For example we can create a characteristic to send indications instead of notifications.
from able.characteristic import CharacteristicFlags
characteristic = ABleCharacteristic(
characteristic_uuid=uuid.uuid4(),
flags=[
CharacteristicFlags.READ,
CharacteristicFlags.WRITE,
CharacteristicFlags.INDICATE,
],
)
Poke around the characteristic flags enum to see all the ways a characteristic can be configured.
Default Value¶
A characteristic can also be initialized with a value already on it. Note that only bytes are valid to be the initial value of the characteristic and if the data is too long it may be truncated.
characteristic = ABleCharacteristic(
characteristic_uuid=uuid.uuid4(),
value=b"1234",
)
Nickname¶
Often times we’ve been bewildered trying to keep track of everything that is happening with characteristics, so there is an optional name parameter that can be used in initializing the characteristic that will be used to identify the characteristic in logs to make them more human friendly.
characteristic = ABleCharacteristic(
characteristic_uuid=uuid.uuid4(),
name="CommunicationCharacteristic",
)