Generic Attribute Profile (GATT)
GATT layer manages the service database providing APIs for service registration and attribute declaration.
Services can be registered using bt_gatt_service_register() API
which takes the bt_gatt_service struct that provides the list of
attributes the service contains. The helper macro BT_GATT_SERVICE()
can be used to declare a service.
Attributes can be declared using the bt_gatt_attr struct or using
one of the helper macros:
BT_GATT_PRIMARY_SERVICEDeclares a Primary Service.
BT_GATT_SECONDARY_SERVICEDeclares a Secondary Service.
BT_GATT_INCLUDE_SERVICEDeclares a Include Service.
BT_GATT_CHARACTERISTICDeclares a Characteristic.
BT_GATT_DESCRIPTORDeclares a Descriptor.
BT_GATT_ATTRIBUTEDeclares an Attribute.
BT_GATT_CCCDeclares a Client Characteristic Configuration.
BT_GATT_CEPDeclares a Characteristic Extended Properties.
BT_GATT_CUDDeclares a Characteristic User Format.
Each attribute contain a uuid, which describes their type, a read
callback, a write callback and a set of permission. Both read and write
callbacks can be set to NULL if the attribute permission don’t allow their
respective operations.
Note
32-bit UUIDs are not supported in GATT. All 32-bit UUIDs shall be converted to 128-bit UUIDs when the UUID is contained in an ATT PDU.
Note
Attribute read and write callbacks are called directly from RX Thread
thus it is not recommended to block for long periods of time in them.
Attribute value changes can be notified using bt_gatt_notify() API,
alternatively there is bt_gatt_notify_cb() where it is possible to
pass a callback to be called when it is necessary to know the exact instant when
the data has been transmitted over the air. Indications are supported by
bt_gatt_indicate() API.
Client procedures can be enabled with the configuration option:
CONFIG_BT_GATT_CLIENT
Discover procedures can be initiated with the use of
bt_gatt_discover() API which takes the
bt_gatt_discover_params struct which describes the type of
discovery. The parameters also serves as a filter when setting the uuid
field only attributes which matches will be discovered, in contrast setting it
to NULL allows all attributes to be discovered.
Note
Caching discovered attributes is not supported.
Read procedures are supported by bt_gatt_read() API which takes the
bt_gatt_read_params struct as parameters. In the parameters one or
more attributes can be set, though setting multiple handles requires the option:
CONFIG_BT_GATT_READ_MULTIPLE
Write procedures are supported by bt_gatt_write() API and takes
bt_gatt_write_params struct as parameters. In case the write
operation don’t require a response bt_gatt_write_without_response()
or bt_gatt_write_without_response_cb() APIs can be used, with the
later working similarly to bt_gatt_notify_cb().
Subscriptions to notification and indication can be initiated with use of
bt_gatt_subscribe() API which takes
bt_gatt_subscribe_params as parameters. Multiple subscriptions to
the same attribute are supported so there could be multiple notify callback
being triggered for the same attribute. Subscriptions can be removed with use of
bt_gatt_unsubscribe() API.
Note
When subscriptions are removed notify callback is called with the data
set to NULL.