Skip to content

Commit d0d53c4

Browse files
eivindj-nordicsondrepasilz
committed
lib: db_discovery: add database discovery library
Add db_discovery library. Co-authored-by: Sondre Pettersen <[email protected]> Co-authored-by: Asil Zogby <[email protected]> Signed-off-by: Eivind Jølsgard <[email protected]>
1 parent a78223b commit d0d53c4

File tree

17 files changed

+1678
-1
lines changed

17 files changed

+1678
-1
lines changed

‎CODEOWNERS‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@
4949
/lib/bluetooth/ble_adv/ @nrfconnect/ncs-bm
5050
/lib/bluetooth/ble_conn_params/ @nrfconnect/ncs-bm
5151
/lib/bluetooth/ble_conn_state/ @nrfconnect/ncs-bm
52+
/lib/bluetooth/ble_db_discovery/ @nrfconnect/ncs-bm
5253
/lib/bluetooth/ble_gq/ @nrfconnect/ncs-bm
5354
/lib/bluetooth/ble_qwr/ @nrfconnect/ncs-bm
5455
/lib/bluetooth/ble_racp/ @nrfconnect/ncs-bm
@@ -101,6 +102,7 @@
101102
/tests/lib/bluetooth/ble_conn_params/ @nrfconnect/ncs-bm
102103
/tests/lib/bluetooth/ble_conn_state/ @nrfconnect/ncs-bm
103104
/tests/lib/bluetooth/ble_gq/ @nrfconnect/ncs-bm
105+
/tests/lib/bluetooth/ble_db_discovery/ @nrfconnect/ncs-bm
104106
/tests/lib/bluetooth/ble_qwr/ @nrfconnect/ncs-bm
105107
/tests/lib/bluetooth/ble_racp/ @nrfconnect/ncs-bm
106108
/tests/lib/bluetooth/ble_radio_notif/ @nrfconnect/ncs-bm

‎doc/nrf-bm/api/api.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,15 @@ Bluetooth LE Connection State library
4848
:inner:
4949
:members:
5050

51+
.. _api_ble_db_discovery:
52+
53+
Bluetooth LE Database Discovery library
54+
=======================================
55+
56+
.. doxygengroup:: ble_db_discovery
57+
:inner:
58+
:members:
59+
5160
.. _api_ble_radio_notif:
5261

5362
Bluetooth LE Radio Notification library

‎doc/nrf-bm/libraries/bluetooth/ble_db_discovery.rst‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
.. _lib_ble_db_discovery:
2+
3+
Bluetooth: Database Discovery library
4+
#####################################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
This module contains the APIs and types exposed by the Database Discovery module.
11+
These APIs and types can be used by the application to perform discovery of a service and its characteristics at the peer server.
12+
This module can also be used to discover the desired services in multiple remote devices.
13+
14+
Overview
15+
********
16+
17+
The library allows registration of callbacks that trigger upon discoveering selected services and characteristics in the peer device.
18+
19+
.. _lib_ble_db_discovery_configure:
20+
21+
Configuration
22+
*************
23+
24+
To enable and configure the library, use the following Kconfig options:
25+
26+
* :kconfig:option:`CONFIG_BLE_DB_DISCOVERY` - Enables the database discovery library.
27+
* :kconfig:option:`CONFIG_BLE_DB_DISCOVERY_MAX_SRV`- Sets the maximum number of services that can be discovered.
28+
* :kconfig:option:`CONFIG_BLE_DB_DISCOVERY_SRV_DISC_START_HANDLE`- Sets the start value used durning discovery.
29+
30+
31+
Initialization
32+
==============
33+
34+
The library is initialized by calling the :c:func:`ble_db_discovery_init` function.
35+
See the :c:struct:`ble_db_discovery_config` structure for configuration details.
36+
37+
Usage
38+
*****
39+
40+
After initialization, use the :c:func:`ble_db_discovery_service_register` function to register a callback that triggers when a service is discovered with a specific UUID.
41+
To start discovering from a peer, you must use the :c:func:`ble_db_discovery_start` function with the connection handle of the peer device.
42+
For example, you can call the :c:func:`ble_db_discovery_start` function when the ble event :c:enum:`BLE_GAP_EVT_CONNECTED` event is triggered and use the connection handle from the event as the second argument in the :c:func:`ble_db_discovery_start` function.
43+
44+
Dependencies
45+
************
46+
47+
This library uses the following |BMshort| libraries:
48+
49+
* SoftDevice - :kconfig:option:`CONFIG_SOFTDEVICE`
50+
* SoftDevice handler - :kconfig:option:`CONFIG_NRF_SDH`
51+
52+
API documentation
53+
*****************
54+
55+
| Header file: :file:`include/bm/bluetooth/ble_db_discovery.h`
56+
| Source files: :file:`lib/bluetooth/ble_db_discovery/`
57+
58+
:ref:`Bluetooth LE Database Discovery library API reference <api_ble_db_discovery>`

‎include/bm/bluetooth/ble_db_discovery.h‎

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
1+
/*
2+
* Copyright (c) 2013 - 2025 Nordic Semiconductor ASA
3+
*
4+
* SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
*/
6+
7+
/** @file
8+
*
9+
* @defgroup ble_db_discovery BLE Nordic database discovery library
10+
* @{
11+
* @brief Library for discovery of a service and its characteristics at the peer server.
12+
*/
13+
14+
#include <stdint.h>
15+
#include <zephyr/kernel.h>
16+
#include <ble_gattc.h>
17+
#include <bm/bluetooth/ble_gq.h>
18+
#include <bm/bluetooth/ble_gatt_db.h>
19+
20+
#ifndef BLE_DB_DISCOVERY_H__
21+
#define BLE_DB_DISCOVERY_H__
22+
23+
/**
24+
* @brief Macro for defining a ble_db_discovery instance.
25+
*
26+
* @param _name Name of the instance.
27+
*/
28+
#define BLE_DB_DISCOVERY_DEF(_name) \
29+
static struct ble_db_discovery _name = {.discovery_in_progress = 0, \
30+
.conn_handle = BLE_CONN_HANDLE_INVALID}; \
31+
NRF_SDH_BLE_OBSERVER(_name##_obs, ble_db_discovery_on_ble_evt, &_name, HIGH);
32+
33+
/**
34+
* @brief BLE database discovery event type.
35+
*/
36+
enum ble_db_discovery_evt_type {
37+
/**
38+
* @brief Event indicating that the discovery of one service is complete.
39+
*/
40+
BLE_DB_DISCOVERY_COMPLETE,
41+
/**
42+
* @brief Event indicating that the service was not found at the peer.
43+
*/
44+
BLE_DB_DISCOVERY_SRV_NOT_FOUND,
45+
/**
46+
* @brief Event indicating that the DB discovery instance is available.
47+
*/
48+
BLE_DB_DISCOVERY_AVAILABLE,
49+
/**
50+
* @brief Event indicating that an internal error has occurred in the DB Discovery module.
51+
*
52+
* This could typically be because of the SoftDevice API returning an error code during the
53+
* DB discover.
54+
*/
55+
BLE_DB_DISCOVERY_ERROR,
56+
};
57+
58+
/**
59+
* @brief BLE database discovery event.
60+
*/
61+
struct ble_db_discovery_evt {
62+
/**
63+
* @brief Type of event.
64+
*/
65+
enum ble_db_discovery_evt_type evt_type;
66+
/**
67+
* @brief Handle of the connection for which this event has occurred.
68+
*/
69+
uint16_t conn_handle;
70+
union {
71+
/**
72+
* @brief Structure containing the information about the GATT Database at the
73+
* server.
74+
*
75+
* This will be filled when the event type is @ref BLE_DB_DISCOVERY_COMPLETE. The
76+
* UUID field of this will be filled when the event type is @ref
77+
* BLE_DB_DISCOVERY_SRV_NOT_FOUND.
78+
*/
79+
struct ble_gatt_db_srv discovered_db;
80+
/**
81+
* @brief nRF Error code indicating the type of error which occurred in the DB
82+
* Discovery module.
83+
*
84+
* This will be filled when the event type is @ref BLE_DB_DISCOVERY_ERROR.
85+
*/
86+
struct {
87+
/**
88+
* @brief nRF Error code indicating the type of error which occurred in the
89+
* DB Discovery module.
90+
*/
91+
uint32_t reason;
92+
} error;
93+
} params;
94+
};
95+
96+
/* Forward declaration. */
97+
struct ble_db_discovery;
98+
99+
/**
100+
* @brief DB discovery event handler type.
101+
*/
102+
typedef void (*ble_db_discovery_evt_handler)(struct ble_db_discovery *db_discovery,
103+
struct ble_db_discovery_evt *evt);
104+
105+
/**
106+
* @brief BLE database discovery configuration.
107+
*/
108+
struct ble_db_discovery_config {
109+
/**
110+
* @brief Event handler to be called by the DB Discovery module.
111+
*/
112+
ble_db_discovery_evt_handler evt_handler;
113+
/**
114+
* @brief Pointer to BLE GATT Queue instance.
115+
*/
116+
const struct ble_gq *gatt_queue;
117+
};
118+
119+
/**
120+
* @brief BLE database discovery user event.
121+
*/
122+
struct ble_db_discovery_user_evt {
123+
/**
124+
* @brief Pending event.
125+
*/
126+
struct ble_db_discovery_evt evt;
127+
/**
128+
* @brief Event handler which should be called to raise this event.
129+
*/
130+
ble_db_discovery_evt_handler evt_handler;
131+
};
132+
133+
/**
134+
* @brief BLE database discovery.
135+
*/
136+
struct ble_db_discovery {
137+
/**
138+
* @brief Information related to the current service being discovered.
139+
*
140+
* This is intended for internal use during service discovery.
141+
*/
142+
struct ble_gatt_db_srv services[CONFIG_BLE_DB_DISCOVERY_MAX_SRV];
143+
/**
144+
* @brief UUID of registered handlers
145+
*/
146+
ble_uuid_t registered_uuids[CONFIG_BLE_DB_DISCOVERY_MAX_SRV];
147+
/**
148+
* @brief Instance event handler.
149+
*/
150+
ble_db_discovery_evt_handler evt_handler;
151+
/**
152+
* @brief BLE GATT Queue instance.
153+
*/
154+
const struct ble_gq *gatt_queue;
155+
/**
156+
* @brief The number of UUIDs registered with the DB Discovery module.
157+
*/
158+
uint32_t num_registered_uuids;
159+
/**
160+
* @brief Number of services at the peer's GATT database.
161+
*/
162+
uint8_t srv_count;
163+
/**
164+
* @brief Index of the current characteristic being discovered.
165+
*
166+
* This is intended for internal use during service discovery.
167+
*/
168+
uint8_t curr_char_ind;
169+
/**
170+
* @brief Index of the current service being discovered.
171+
*
172+
* This is intended for internal use during service discovery.
173+
*/
174+
uint8_t curr_srv_ind;
175+
/**
176+
* @brief Number of service discoveries made, both successful and unsuccessful.
177+
*/
178+
uint8_t discoveries_count;
179+
/**
180+
* @brief Variable to indicate whether there is a service discovery in progress.
181+
*/
182+
bool discovery_in_progress;
183+
/**
184+
* @brief Connection handle on which the discovery is started.
185+
*/
186+
uint16_t conn_handle;
187+
/**
188+
* @brief The index to the pending user event array, pointing to the last added pending user
189+
* event.
190+
*/
191+
uint32_t pending_usr_evt_index;
192+
/**
193+
* @brief Whenever a discovery related event is to be raised to a user module, it is stored
194+
* in this array first.
195+
*
196+
* When all expected services have been discovered, all pending events are sent to the
197+
* corresponding user modules.
198+
*/
199+
struct ble_db_discovery_user_evt pending_usr_evts[CONFIG_BLE_DB_DISCOVERY_MAX_SRV];
200+
};
201+
202+
/**
203+
* @brief Initialize the DB Discovery module.
204+
*
205+
* @param[in] db_discovery BLE DB discovery instance.
206+
* @param[in] db_config DB discovery initialization structure.
207+
*
208+
* @retval NRF_SUCCESS On successful initialization.
209+
* @retval NRF_ERROR_NULL If the initialization structure was NULL or
210+
* the structure content is empty.
211+
*/
212+
uint32_t ble_db_discovery_init(struct ble_db_discovery *db_discovery,
213+
struct ble_db_discovery_config *db_config);
214+
215+
/**
216+
* @brief Start the discovery of the GATT database at the server.
217+
*
218+
* @param[out] db_discovery BLE DB Discovery instance.
219+
* @param[in] conn_handle The handle of the connection for which the discovery should be
220+
* started.
221+
*
222+
* @retval NRF_SUCCESS Operation success.
223+
* @retval NRF_ERROR_NULL When a NULL pointer is passed as input.
224+
* @retval NRF_ERROR_INVALID_STATE If this function is called without calling the
225+
* @ref ble_db_discovery_init, or without calling
226+
* @ref ble_db_discovery_service_register.
227+
* @retval NRF_ERROR_BUSY If a discovery is already in progress using @p db_discovery.
228+
* Use a different @ref struct ble_db_discovery structure,
229+
* or wait for a DB Discovery event before retrying.
230+
* @return This API propagates the error code returned by functions:
231+
* @ref nrf_ble_gq_conn_handle_register and @ref nrf_ble_gq_item_add.
232+
*/
233+
uint32_t ble_db_discovery_start(struct ble_db_discovery *db_discovery, uint16_t conn_handle);
234+
235+
/**
236+
* @brief Register service with the DB Discovery module.
237+
*
238+
* @details The application can use this function to inform which service it is interested in
239+
* discovering at the server.
240+
*
241+
* @param[in] db_discovery BLE DB discovery instance.
242+
* @param[in] uuid UUID of the service to be discovered at the server.
243+
*
244+
* @note The total number of services that can be discovered by this module is @ref
245+
* CONFIG_BLE_DB_DISCOVERY_MAX_SRV. This effectively means that the maximum number of
246+
* registrations possible is equal to the @ref CONFIG_BLE_DB_DISCOVERY_MAX_SRV.
247+
*
248+
* @retval NRF_SUCCESS Operation success.
249+
* @retval NRF_ERROR_NULL When a NULL pointer is passed as input.
250+
* @retval NRF_ERROR_INVALID_STATE If this function is called without calling the
251+
* @ref ble_db_discovery_init.
252+
* @retval NRF_ERROR_NO_MEM The maximum number of registrations allowed by this module
253+
* has been reached.
254+
*/
255+
uint32_t ble_db_discovery_service_register(struct ble_db_discovery *db_discovery,
256+
const ble_uuid_t *const uuid);
257+
258+
/**
259+
* @brief Application's BLE Stack event handler.
260+
*
261+
* @param[in] ble_evt BLE event received.
262+
* @param[in,out] context BLE DB discovery instance.
263+
*/
264+
void ble_db_discovery_on_ble_evt(ble_evt_t const *ble_evt, void *context);
265+
266+
#endif /* BLE_DB_DISCOVERY_H__ */
267+
268+
/** @} */

include/bm/bluetooth/peer_manager/ble_gatt_db.h renamed to include/bm/bluetooth/ble_gatt_db.h

File renamed without changes.

‎include/bm/bluetooth/peer_manager/peer_manager_types.h‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
#include <nrf.h>
2121
#include <ble_gap.h>
2222
#include <ble_hci.h>
23-
#include <bm/bluetooth/peer_manager/ble_gatt_db.h>
23+
#include <bm/bluetooth/ble_gatt_db.h>
2424

2525
#ifdef __cplusplus
2626
extern "C" {

‎lib/bluetooth/CMakeLists.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
add_subdirectory_ifdef(CONFIG_BLE_ADV ble_adv)
88
add_subdirectory_ifdef(CONFIG_BLE_CONN_PARAMS ble_conn_params)
99
add_subdirectory_ifdef(CONFIG_BLE_CONN_STATE ble_conn_state)
10+
add_subdirectory_ifdef(CONFIG_BLE_DB_DISCOVERY ble_db_discovery)
1011
add_subdirectory_ifdef(CONFIG_BLE_GATT_QUEUE ble_gq)
1112
add_subdirectory_ifdef(CONFIG_BLE_RACP ble_racp)
1213
add_subdirectory_ifdef(CONFIG_BLE_RADIO_NOTIFICATION ble_radio_notification)

‎lib/bluetooth/Kconfig‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ menu "Bluetooth libraries"
88
rsource "ble_adv/Kconfig"
99
rsource "ble_conn_params/Kconfig"
1010
rsource "ble_conn_state/Kconfig"
11+
rsource "ble_db_discovery/Kconfig"
1112
rsource "ble_gq/Kconfig"
1213
rsource "ble_racp/Kconfig"
1314
rsource "ble_radio_notification/Kconfig"

‎lib/bluetooth/ble_db_discovery/CMakeLists.txt‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
#
2+
# Copyright (c) 2025 Nordic Semiconductor ASA
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
zephyr_library()
7+
zephyr_library_sources(
8+
ble_db_discovery.c
9+
)

0 commit comments

Comments
 (0)