The Database Discovery Module handles service discovery on GATT servers. When a client connects to a peer device that has a desired server, service discovery is necessary to ensure that the client interacts with the servers characteristics using the correct attributes handles. Service discovery is also important because Bluetooth LE advertising does not mandate that all services are advertised. To actually know if a service is present on a peer device, you can perform a service discovery. This module can be used for many typical discovery scenarios, and is used for all the client implementations in the SDK.
The Database Discovery Module will find registered services on the peer, along with the characteristics in each service.
- Note
- Only the following descriptors will be searched for at the peer:
- Client Characteristic Configuration
- Characteristic Extended Properties
- Characteristic User Description
- Report Reference.
- No Services other than the primary Service will be searched for at the peer.
This module uses the BLE GATT Queue module to buffer the SoftDevice requests if SoftDevice is not able to handle them at the moment.
Configuration of number of services and characteristics to discover.
Memory must be allocated depending on the number of services and characteristics you need to discover. The maximum number of services to discover is BLE_DB_DISCOVERY_MAX_SRV. The maximum number of characteristics per service is BLE_GATT_DB_MAX_CHARS. These defines are set to work with most of the examples in the SDK but may have to be increased if your application needs to discover more characteristics or services. If fewer characteristics or services are needed in your application, you can reduce these defines to reduce memory use. If the peer device has more than the supported number of characteristics, then the first ones found are reported back as discovered and any further characteristics will be ignored.
Usage
Registering UUIDs
First, the module must be initialized using ble_db_discovery_init , including an event handler. After that, you can register the UUIDs to search for in peer databases using ble_db_discovery_evt_register. Implementations of Service Clients in the SDK examples will register the UUIDs of the Server they want to interact with. When all desired services have been registered, you can run ble_db_discovery_start to do a discovery on a given connection. Each UUID discovered will trigger the discovery event handler with the BLE_DB_DISCOVERY_COMPLETE event. This event contains the handles and UUIDS of the discovered service.
Event Handler
In your discovery event handler, forward the incoming discovery events to the client modules using their "on_db_disc_evt" functions. For example, heart rate client has ble_hrs_on_db_disc_evt function. This allows the client modules to decide if the discovered attributes are relevant to them. If they are relevant, the client module can trigger it's own "discovery complete" events. For example, Heart Rate Service Client will trigger a BLE_HRS_C_EVT_DISCOVERY_COMPLETE event based on the BLE_DB_DISCOVERY_COMPLETE event that was forwarded from the discovery event handler.
Assigning handles
In the event handler for your client module (such as hrs_c_evt_handler in the BLE Heart Rate Collector Example), you now have all the correct attribute handles for the service you wish to interact with. These handles should be linked with the client instance you want to use over this connection. Most of the client implementations in the SDK will have a "handles_assign" function to make this association. For example, the heart rate client has ble_hrs_c_handles_assign function.
- Note
- The procedure of assigning handles may require additional logic depending on the goals of your applications. For example if your application has multiple connections, and/or multiple instances of clients and services.
Message Sequence Charts
Message Sequence Chart: Heart Rate Client Example
To give an idea about the flow and use of the Database Discovery Module, Let's look at a small example for a typical application. In this example, a central device has a Heart Rate Service client. It will want to find a peripheral device that has a Hear Rate Service server. It starts db_discovery module, registers a UUID, advertises, establishes a connection, performs a service discovery.
Message Sequence Chart: Multiple Clients Example
Now let's take a look at a bigger and more generic example, where two clients discover two servers.
