| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Database Discovery Module
This information applies to the following SoftDevices: S130, S132, S332

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
  No descriptors other than Client Characteristic Configuration Descriptors will be searched for at the peer.
  No Services other than the primary Service will be searched for at the peer.

# 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.