Dynamic GATT server

A GATT server is composed of GATT attributes: services, characteristics, and descriptors. Services contain characteristics which contain data.

Characteristics may also contain descriptors which also may contain data. The data values for characteristics and descriptors are stored on the module and can be access via their value handle which is created when registering new services. GATT clients can also connect to the server and read or write data values if configured for these operations.

The max length of data values stored in characteristics and descriptors is 20 bytes.

CAUTION! Registered services will be lost if the module resets. We recommend registering GATT server services after a reset in a startup script to avoid losing server configuration.

See the BLE core specification, Vol 3, Part G, Section 3 for more information.

Property Flags

Available property flags are defined as constants on the digi.ble module. See the BLE core specification, Vol 3, Part G, Section 3.3.3.1 for more information-

Characteristic properties:

Note If a characteristic is configured to have the notify or indicate property, then it must have a Client Characteristic Configuration Descriptor (UUID 0x2902) with read and write properties defined in order to allow GATT clients to subscribe to data updates.

Descriptor properties:

Security Flags

Available security flags are defined as constants on the digi.ble module:

Note In order to use the bonded security level, the security option for `ble.config` needs to be configured with the ble.PAIRING_REQUIRE_BONDING constant.

gattdb_register_services ()

Registers the defined services to the local GATT database and removes any previously registered services.

ble.gattdb_register_services(service_definition)

<service_definition>

The <service_definition> parameter specifies the GATT attributes to register to as part of the GATT server. The parameter is a list of services where each service must be a two element tuple that contains a UUID and a list of at least one characteristic. Each characteristic is a two or three element tuple that must contain a UUID, configuration flags, and optionally a list of descriptors. Each descriptor is a two element tuple that must contain a UUID and a configurations flags value. The flags are a bitwise OR combination of defined property and security constants in the digi.ble module.

See the following example of the creation of a Heart Rate Service:

LOCATION_UUID = ble.UUID(0x2A38)
LOCATION_FLAGS = ble.GATTDB_CHARACTERISTIC_READ
LOCATION_CHAR = (LOCATION_UUID, LOCATION_FLAGS, )

CCC_FLAGS = ble.GATTDB_DESCRIPTOR_READ | ble.GATTDB_DESCRIPTOR_WRITE
CCC_UUID = ble.UUID(0x2902)
CLIENT_CHAR_CONFIG_DESCRIPTOR = (CCC_UUID, CCC_FLAGS)

MEASUREMENT_UUID = ble.UUID(0x2A37)
MEASUREMENT_FLAGS = ble.GATTDB_CHARACTERISTIC_NOTIFY
MEASUREMENT_CHAR = (MEASUREMENT_UUID, MEASUREMENT_FLAGS, (CLIENT_CHAR_CONFIG_DESCRIPTOR,))

HR_SERVICE_UUID = ble.UUID(0x180D)
HR_CHAR_LIST = (MEASUREMENT_CHAR, LOCATION_CHAR)
HR_SERVICE = (HR_SERVICE_UUID, HR_CHAR_LIST)

SERVICE_LIST = (HR_SERVICE,)
((measurement_handle, ccc_handle, location_handle),) = ble.gattdb_register_services(SERVICE_LIST)

Return value

If the operation is successful, a tuple of tuples per service which contain attribute handles for each characteristic and descriptor in the order they were specified.

If the operation is not successful, an OSError is raised.

gattdb_read ()

Reads data from the given GATT attribute handle that has been written either by gattdb_write or by a remote client.

ble.gattdb_read(handle)

<handle>

The <handle> parameter specifies the attribute handle to read data from.

Return value

If the operation is successful, returns the data read in bytes.

If the operation is not successful, an OSError is raised.

gattdb_write()

Writes data to the given GATT attribute handle and optionally sends the data to connected clients that have subscribed to indications or notifications. Attributes have a maximum data size of 20 bytes.

ble.gattdb_write(handle [, data][, send_update=False])

<handle>

The <handle> parameter specifies the attribute handle to write data to.

<data>

The <data> parameter specifies the bytes to write to the given attribute handle.

<send_update>

The <send_update> parameter is used to send data to GATT clients that have subscribed to notifications or indications.

Return value

If the operation is successful, nothing is returned.

If the operation is not successful, an OSError is raised.