Skip to content

Commit e20c85f

Browse files
eivindj-nordiceivindj-nordic
committed
services: add ble_bms
Add bond management service. Signed-off-by: Eivind Jølsgard <[email protected]>
1 parent 47cb066 commit e20c85f

File tree

6 files changed

+1025
-0
lines changed

6 files changed

+1025
-0
lines changed

‎include/bluetooth/services/ble_bms.h‎

Lines changed: 387 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,387 @@
1+
/*
2+
* Copyright (c) 2012 - 2025 Nordic Semiconductor ASA
3+
*
4+
* SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
*/
6+
7+
/** @file
8+
*
9+
* @defgroup ble_bms Bond Management Service
10+
* @{
11+
* @ingroup ble_sdk_srv
12+
* @brief Bond Management Service (BMS) module.
13+
*
14+
* @details This module implements the Bond Management Service (BMS).
15+
* By writing to the Bond Management Control Point, the connected peer can request the
16+
* deletion of bond information from the device.
17+
* If authorization is configured, the application must supply an event handler for
18+
* receiving Bond Management Service events. Using this handler, the service requests
19+
* authorization when a procedure is requested by writing to the
20+
* Bond Management Control Point.
21+
*
22+
* @msc
23+
* hscale = "1.3";
24+
* APP,BMS,PEER;
25+
* |||;
26+
* APP rbox PEER [label="Connection established"];
27+
* |||;
28+
* BMS<=PEER [label="BMCP write request {procedure}"];
29+
* APP<-BMS [label="NRF_BLE_BMS_EVT_AUTH {auth_code}"];
30+
* --- [label="Variant #1: app grants authorization"];
31+
* APP->BMS [label="nrf_ble_bms_auth_response (true)"];
32+
* BMS>>APP [label="NRF_SUCCESS"];
33+
* BMS=>PEER [label="BMCP write response"];
34+
* BMS rbox BMS [label="Procedure initiated"];
35+
* --- [label="Variant #2: app denies authorization"];
36+
* APP->BMS [label="nrf_ble_bms_auth_response (false)"];
37+
* BMS>>APP [label="NRF_SUCCESS"];
38+
* BMS=>PEER [label="BMCP error response"];
39+
* @endmsc
40+
*/
41+
42+
#ifndef NRFLITE_BLE_BMS_H__
43+
#define NRFLITE_BLE_BMS_H__
44+
45+
#include <stdint.h>
46+
#include <stdbool.h>
47+
#include <ble.h>
48+
#include <nrf_sdh_ble.h>
49+
#include <nrf_ble_qwr.h>
50+
51+
#ifdef __cplusplus
52+
extern "C" {
53+
#endif
54+
55+
/**
56+
* @brief Macro for defining a nrf_ble_bms instance.
57+
*
58+
* @param _name Name of the instance.
59+
* @hideinitializer
60+
*/
61+
#define NRF_BLE_BMS_DEF(_name) \
62+
static struct nrf_ble_bms _name; \
63+
NRF_SDH_BLE_OBSERVER(_name ## _obs, \
64+
nrf_ble_bms_on_ble_evt, &_name, \
65+
CONFIG_NRF_BLE_BMS_BLE_OBSERVER_PRIO)
66+
67+
/** Length of the Feature Characteristic (in bytes). */
68+
#define NRF_BLE_BMS_FEATURE_LEN 3
69+
/** Maximum length of the Bond Management Control Point Characteristic (in bytes). */
70+
#define NRF_BLE_BMS_CTRLPT_MAX_LEN 128
71+
/** Minimum length of the Bond Management Control Point Characteristic (in bytes). */
72+
#define NRF_BLE_BMS_CTRLPT_MIN_LEN 1
73+
/** Maximum length of the Bond Management Control Point Authorization Code (in bytes). */
74+
#define NRF_BLE_BMS_AUTH_CODE_MAX_LEN NRF_BLE_BMS_CTRLPT_MAX_LEN - 1
75+
76+
/** @defgroup NRF_BLE_BMS_FEATURES BMS feature bits
77+
* @{
78+
*/
79+
/** Delete bond of the requesting device (BR/EDR and LE). */
80+
#define NRF_BLE_BMS_REQUESTING_DEVICE_BR_LE (0x01 << 0)
81+
/** Delete bond of the requesting device (BR/EDR and LE) with an authorization code. */
82+
#define NRF_BLE_BMS_REQUESTING_DEVICE_BR_LE_AUTH_CODE (0x01 << 1)
83+
/** Delete bond of the requesting device (BR/EDR transport only). */
84+
#define NRF_BLE_BMS_REQUESTING_DEVICE_BR (0x01 << 2)
85+
/** Delete bond of the requesting device (BR/EDR transport only) with an authorization code. */
86+
#define NRF_BLE_BMS_REQUESTING_DEVICE_BR_AUTH_CODE (0x01 << 3)
87+
/** Delete bond of the requesting device (LE transport only). */
88+
#define NRF_BLE_BMS_REQUESTING_DEVICE_LE (0x01 << 4)
89+
/** Delete bond of the requesting device (LE transport only) with an authorization code. */
90+
#define NRF_BLE_BMS_REQUESTING_DEVICE_LE_AUTH_CODE (0x01 << 5)
91+
/** Delete all bonds on the device (BR/EDR and LE). */
92+
#define NRF_BLE_BMS_ALL_BONDS_BR_LE (0x01 << 6)
93+
/** Delete all bonds on the device (BR/EDR and LE) with an authorization code. */
94+
#define NRF_BLE_BMS_ALL_BONDS_BR_LE_AUTH_CODE (0x01 << 7)
95+
/** Delete all bonds on the device (BR/EDR transport only). */
96+
#define NRF_BLE_BMS_ALL_BONDS_BR (0x01 << 8)
97+
/** Delete all bonds on the device (BR/EDR transport only) with an authorization code. */
98+
#define NRF_BLE_BMS_ALL_BONDS_BR_AUTH_CODE (0x01 << 9)
99+
/** Delete all bonds on the device (LE transport only). */
100+
#define NRF_BLE_BMS_ALL_BONDS_LE (0x01 << 10)
101+
/** Delete all bonds on the device (LE transport only) with an authorization code. */
102+
#define NRF_BLE_BMS_ALL_BONDS_LE_AUTH_CODE (0x01 << 11)
103+
/** Delete all bonds on the device except for the bond of the requesting device
104+
* (BR/EDR and LE).
105+
*/
106+
#define NRF_BLE_BMS_ALL_EXCEPT_REQUESTING_DEVICE_BR_LE (0x01 << 12)
107+
/** Delete all bonds on the device except for the bond of the requesting device
108+
* (BR/EDR and LE) with an authorization code.
109+
*/
110+
#define NRF_BLE_BMS_ALL_EXCEPT_REQUESTING_DEVICE_BR_LE_AUTH_CODE (0x01 << 13)
111+
/** Delete all bonds on the device except for the bond of the requesting device
112+
* (BR/EDR transport only).
113+
*/
114+
#define NRF_BLE_BMS_ALL_EXCEPT_REQUESTING_DEVICE_BR (0x01 << 14)
115+
/** Delete all bonds on the device except for the bond of the requesting device
116+
* (BR/EDR transport only) with an authorization code.
117+
*/
118+
#define NRF_BLE_BMS_ALL_EXCEPT_REQUESTING_DEVICE_BR_AUTH_CODE (0x01 << 15)
119+
/** Delete all bonds on the device except for the bond of the requesting device
120+
* (LE transport only).
121+
*/
122+
#define NRF_BLE_BMS_ALL_EXCEPT_REQUESTING_DEVICE_LE (0x01 << 16)
123+
/** Delete all bonds on the device except for the bond of the requesting device
124+
* (LE transport only) with an authorization code.
125+
*/
126+
#define NRF_BLE_BMS_ALL_EXCEPT_REQUESTING_DEVICE_LE_AUTH_CODE (0x01 << 17)
127+
/** @} */
128+
129+
/** Error sent back when receiving a control point write with an unsupported opcode. */
130+
#define NRF_BLE_BMS_OPCODE_NOT_SUPPORTED (BLE_GATT_STATUS_ATTERR_APP_BEGIN + 0)
131+
/** Error sent back when a control point operation fails. */
132+
#define NRF_BLE_BMS_OPERATION_FAILED (BLE_GATT_STATUS_ATTERR_APP_BEGIN + 1)
133+
134+
135+
/** @brief Supported features. */
136+
struct nrf_ble_bms_features {
137+
/** Indicates whether the application wants to support the operation to delete all bonds. */
138+
bool delete_all : 1;
139+
/** Indicates whether the application wants to support the operation to delete all bonds
140+
* with authorization code.
141+
*/
142+
bool delete_all_auth : 1;
143+
/** Indicates whether the application wants to support the operation to delete the bonds of
144+
* the requesting device.
145+
*/
146+
bool delete_requesting : 1;
147+
/** Indicates whether the application wants to support the operation to delete the bonds of
148+
* therequesting device with authorization code.
149+
*/
150+
bool delete_requesting_auth : 1;
151+
/** Indicates whether the application wants to support the operation to delete all bonds
152+
* except for the bond of the requesting device.
153+
*/
154+
bool delete_all_but_requesting : 1;
155+
/** Indicates whether the application wants to support the operation to delete all bonds
156+
* except for the bond of the requesting device with authorization code.
157+
*/
158+
bool delete_all_but_requesting_auth : 1;
159+
};
160+
161+
/** @brief BMS Control Point opcodes. */
162+
enum nrf_ble_bms_op {
163+
/** Initiates the procedure to delete the bond of the requesting device on
164+
* BR/EDR and LE transports.
165+
*/
166+
NRF_BLE_BMS_OP_DEL_BOND_REQ_DEVICE_BR_LE = 0x01,
167+
/** Initiates the procedure to delete the bond of the requesting device on BR/EDR transport.
168+
*/
169+
NRF_BLE_BMS_OP_DEL_BOND_REQ_DEVICE_BR_ONLY = 0x02,
170+
/** Initiates the procedure to delete the bond of the requesting device on LE transport. */
171+
NRF_BLE_BMS_OP_DEL_BOND_REQ_DEVICE_LE_ONLY = 0x03,
172+
/** Initiates the procedure to delete all bonds on the device on BR/EDR and LE transports.
173+
*/
174+
NRF_BLE_BMS_OP_DEL_ALL_BONDS_ON_SERVER_BR_LE = 0x04,
175+
/** Initiates the procedure to delete all bonds on the device on BR/EDR transport. */
176+
NRF_BLE_BMS_OP_DEL_ALL_BONDS_ON_SERVER_BR_ONLY = 0x05,
177+
/** Initiates the procedure to delete all bonds on the device on LE transport. */
178+
NRF_BLE_BMS_OP_DEL_ALL_BONDS_ON_SERVER_LE_ONLY = 0x06,
179+
/** Initiates the procedure to delete all bonds except for the one of the requesting device
180+
* on BR/EDR and LE transports.
181+
*/
182+
NRF_BLE_BMS_OP_DEL_ALL_BUT_ACTIVE_BOND_BR_LE = 0x07,
183+
/** Initiates the procedure to delete all bonds except for the one of the requesting device
184+
* on BR/EDR transport.
185+
*/
186+
NRF_BLE_BMS_OP_DEL_ALL_BUT_ACTIVE_BOND_BR_ONLY = 0x08,
187+
/** Initiates the procedure to delete all bonds except for the one of the requesting device
188+
* on LE transport.
189+
*/
190+
NRF_BLE_BMS_OP_DEL_ALL_BUT_ACTIVE_BOND_LE_ONLY = 0x09,
191+
/** Indicates an invalid opcode or no pending opcode. */
192+
NRF_BLE_BMS_OP_NONE = 0xFF
193+
};
194+
195+
/** @brief Authorization status values. */
196+
enum nrf_ble_bms_auth_status {
197+
/** Authorization is granted. */
198+
NRF_BLE_BMS_AUTH_STATUS_ALLOWED,
199+
/** Authorization is denied. */
200+
NRF_BLE_BMS_AUTH_STATUS_DENIED,
201+
/** Authorization is pending. */
202+
NRF_BLE_BMS_AUTH_STATUS_PENDING
203+
};
204+
205+
/** @brief Received authorization codes. */
206+
struct nrf_ble_bms_auth_code {
207+
/** Authorization code. */
208+
uint8_t code[NRF_BLE_BMS_AUTH_CODE_MAX_LEN];
209+
/** Length of the authorization code. */
210+
uint16_t len;
211+
};
212+
213+
/** @brief BMS event types. */
214+
enum nrf_ble_bms_evt_type {
215+
/** Event that indicates that the application shall verify the supplied
216+
* authentication code.
217+
*/
218+
NRF_BLE_BMS_EVT_AUTH,
219+
};
220+
221+
/** @brief BMS events. */
222+
struct nrf_ble_bms_evt {
223+
/** Type of event. */
224+
enum nrf_ble_bms_evt_type evt_type;
225+
/** Received authorization code. */
226+
struct nrf_ble_bms_auth_code auth_code;
227+
};
228+
229+
/** @brief BMS control points. */
230+
struct nrf_ble_bms_ctrlpt {
231+
/** Control Point Op Code. */
232+
enum nrf_ble_bms_op op_code;
233+
/** Control Point Authorization Code. */
234+
struct nrf_ble_bms_auth_code auth_code;
235+
};
236+
237+
/* Forward declaration of the struct nrf_ble_bms. */
238+
struct nrf_ble_bms;
239+
240+
/** @brief BMS event handler type. */
241+
typedef void (*nrf_ble_bms_bond_handler) (struct nrf_ble_bms const *bms);
242+
243+
/** @brief BMS bond management callbacks. */
244+
struct nrf_ble_bms_bond_cbs {
245+
/** Function to be called to delete the bonding information of the requesting device. */
246+
nrf_ble_bms_bond_handler delete_requesting;
247+
/** Function to be called to delete the bonding information of all bonded devices. */
248+
nrf_ble_bms_bond_handler delete_all;
249+
/** Function to be called to delete the bonding information of all bonded devices
250+
* except for the requesting device.
251+
*/
252+
nrf_ble_bms_bond_handler delete_all_except_requesting;
253+
};
254+
255+
/** @brief BMS event handler type.
256+
*
257+
* The event handler returns a @ref BLE_GATT_STATUS_CODES "BLE GATT status code".
258+
*/
259+
typedef void (*ble_bms_evt_handler_t)(struct nrf_ble_bms *bms, struct nrf_ble_bms_evt *evt);
260+
261+
/** @brief Type definition for BMS error handler function that will be called in case of an error in
262+
* the BMS library module.
263+
*/
264+
typedef void (*ble_bms_error_handler_t)(uint32_t err);
265+
266+
/** @brief BMS initialization structure with all information needed to initialize the service. */
267+
struct nrf_ble_bms_config {
268+
/** Event handler to be called for handling events in the Bond Management Service. */
269+
ble_bms_evt_handler_t evt_handler;
270+
/** Function to be called if an error occurs. */
271+
ble_bms_error_handler_t error_handler;
272+
/** Initial value for features of the service. */
273+
struct nrf_ble_bms_features feature;
274+
/** Initial security level for the Feature characteristic. */
275+
ble_gap_conn_sec_mode_t bms_feature_sec;
276+
/** Initial security level for the Control Point characteristic. */
277+
ble_gap_conn_sec_mode_t bms_ctrlpt_sec;
278+
/** Pointer to the initialized Queued Write contexts. */
279+
struct nrf_ble_qwr *qwr;
280+
/** Initialized Queue Write contexts count. */
281+
uint8_t qwr_count;
282+
/** Callback functions for deleting bonds. */
283+
struct nrf_ble_bms_bond_cbs bond_callbacks;
284+
};
285+
286+
/**@brief Status information for the service. */
287+
struct nrf_ble_bms {
288+
/** Handle of the Bond Management Service (as provided by the BLE stack). */
289+
uint16_t service_handle;
290+
/** Handle of the current connection (as provided by the BLE stack).
291+
* @ref BLE_CONN_HANDLE_INVALID if not in a connection.
292+
*/
293+
uint16_t conn_handle;
294+
/** Event handler to be called for handling events in the Bond Management Service. */
295+
ble_bms_evt_handler_t evt_handler;
296+
/** Function to be called if an error occurs. */
297+
ble_bms_error_handler_t error_handler;
298+
/** Value for features of the service (see @ref NRF_BLE_BMS_FEATURES). */
299+
struct nrf_ble_bms_features feature;
300+
/** Handles related to the Bond Management Feature characteristic. */
301+
ble_gatts_char_handles_t feature_handles;
302+
/** Handles related to the Bond Management Control Point characteristic. */
303+
ble_gatts_char_handles_t ctrlpt_handles;
304+
/** Callback functions for deleting bonds. */
305+
struct nrf_ble_bms_bond_cbs bond_callbacks;
306+
/** Authorization status. */
307+
enum nrf_ble_bms_auth_status auth_status;
308+
};
309+
310+
/**
311+
* @brief Function for responding to an authorization request.
312+
*
313+
* @details This function should be called when receiving the @ref NRF_BLE_BMS_EVT_AUTH event to
314+
* respond to the service with an authorization result.
315+
*
316+
* @param[in] bms BMS structure.
317+
* @param[in] authorize Authorization response. True if the authorization is considered successful.
318+
*
319+
* @retval NRF_ERROR_NULL If @p bms was NULL.
320+
* @retval NRF_ERROR_INVALID_STATE If no authorization request was pending.
321+
* @retval NRF_SUCCESS If the response was received successfully.
322+
*/
323+
int nrf_ble_bms_auth_response(struct nrf_ble_bms *bms, bool authorize);
324+
325+
/**
326+
* @brief Function for initializing the Bond Management Service.
327+
*
328+
* @param[out] bms BMS structure.
329+
* @param[in] bms_config Information needed to initialize the service.
330+
*
331+
* @retval NRF_ERROR_NULL If @p bms or @p bms_config was NULL.
332+
* @retval NRF_SUCCESS If the service was initialized successfully.
333+
* Otherwise, an error code is returned.
334+
*/
335+
int nrf_ble_bms_init(struct nrf_ble_bms *bms, struct nrf_ble_bms_config *bms_config);
336+
337+
/**
338+
* @brief Function for assigning handles to the Bond Management Service instance.
339+
*
340+
* @details Call this function when a link with a peer has been established to
341+
* associate the link to this instance of the module.
342+
*
343+
* @note Currently this function is deprecated.
344+
*
345+
* @param[in] bms Pointer to the BMS structure instance to associate.
346+
* @param[in] conn_handle Connection handle to be associated with the given BMS instance.
347+
*
348+
* @retval NRF_ERROR_NULL If @p bms was NULL.
349+
* @retval NRF_SUCCESS If the operation was successful.
350+
*/
351+
int nrf_ble_bms_set_conn_handle(struct nrf_ble_bms *bms, uint16_t conn_handle);
352+
353+
/**
354+
* @brief Function for handling Bond Management BLE stack events.
355+
*
356+
* @details This function handles all events from the BLE stack that are of interest to the
357+
* Bond Management Service.
358+
*
359+
* @param[in] ble_evt Event received from the BLE stack.
360+
* @param[in] context BMS structure.
361+
*/
362+
void nrf_ble_bms_on_ble_evt(ble_evt_t const *ble_evt, void *context);
363+
364+
/**
365+
* @brief Function for handling events from the @ref nrf_ble_qwr.
366+
*
367+
* @param[in] bms BMS structure.
368+
* @param[in] qwr Queued Write structure.
369+
* @param[in] evt Event received from the Queued Writes module.
370+
*
371+
* @retval BLE_GATT_STATUS_SUCCESS If the received event is accepted.
372+
* @retval NRF_BLE_QWR_REJ_REQUEST_ERR_CODE If the received event is not relevant for any of this
373+
* module's attributes.
374+
* @retval BLE_BMS_OPCODE_NOT_SUPPORTED If the received opcode is not supported.
375+
* @retval BLE_GATT_STATUS_ATTERR_INSUF_AUTHORIZATION If the application handler returns that the
376+
* authorization code is not valid.
377+
*/
378+
uint16_t nrf_ble_bms_on_qwr_evt(struct nrf_ble_bms *bms, struct nrf_ble_qwr *qwr,
379+
struct nrf_ble_qwr_evt *evt);
380+
381+
#ifdef __cplusplus
382+
}
383+
#endif
384+
385+
#endif /* NRFLITE_BLE_BMS_H__ */
386+
387+
/** @} */

‎subsys/bluetooth/services/CMakeLists.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
55
#
66
add_subdirectory_ifdef(CONFIG_BLE_BAS ble_bas)
7+
add_subdirectory_ifdef(CONFIG_BLE_BMS ble_bms)
78
add_subdirectory_ifdef(CONFIG_BLE_CGMS ble_cgms)
89
add_subdirectory_ifdef(CONFIG_BLE_DIS ble_dis)
910
add_subdirectory_ifdef(CONFIG_BLE_HRS ble_hrs)

0 commit comments

Comments
 (0)