Skip to content

Commit 303b180

Browse files
eivindj-nordiceivindj-nordic
committed
lib: add conn_state
Add Connection state library. Signed-off-by: Eivind Jølsgard <[email protected]>
1 parent 35b28db commit 303b180

File tree

6 files changed

+800
-0
lines changed

6 files changed

+800
-0
lines changed

‎include/ble_conn_state.h

Lines changed: 298 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,298 @@
1+
/*
2+
* Copyright (c) 2015 - 2025 Nordic Semiconductor ASA
3+
*
4+
* SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
*/
6+
7+
/**
8+
* @file
9+
*
10+
* @defgroup ble_conn_state Connection state
11+
* @ingroup ble_sdk_lib
12+
* @{
13+
* @brief Module for storing data on BLE connections.
14+
*
15+
* @details This module stores certain states for each connection, which can be queried by
16+
* connection handle. The module uses BLE events to keep the states updated.
17+
*
18+
* In addition to the preprogrammed states, this module can also keep track of a number of
19+
* binary user states, or <i>user flags</i>. These are reset to 0 for new connections, but
20+
* otherwise not touched by this module.
21+
*
22+
* This module uses atomics to make the flag operations thread-safe.
23+
*
24+
* @note A connection handle is not immediately invalidated when it is disconnected. Certain states,
25+
* such as the role, can still be queried until the next time a new connection is established
26+
* to any device.
27+
*
28+
*/
29+
30+
#ifndef BLE_CONN_STATE_H__
31+
#define BLE_CONN_STATE_H__
32+
33+
#include <stdbool.h>
34+
#include <stdint.h>
35+
#include <ble.h>
36+
#include <ble_gap.h>
37+
38+
#ifdef __cplusplus
39+
extern "C" {
40+
#endif
41+
42+
/** @brief Connection handle statuses. */
43+
enum ble_conn_state_status {
44+
/** The connection handle is invalid. */
45+
BLE_CONN_STATUS_INVALID,
46+
/** The connection handle refers to a connection that has been disconnected,
47+
* but not yet invalidated.
48+
*/
49+
BLE_CONN_STATUS_DISCONNECTED,
50+
/** The connection handle refers to an active connection. */
51+
BLE_CONN_STATUS_CONNECTED,
52+
};
53+
54+
/** The maximum number of connections supported. */
55+
#define BLE_CONN_STATE_MAX_CONNECTIONS BLE_GAP_ROLE_COUNT_COMBINED_MAX
56+
57+
/** @brief Type used to present a list of conn_handles. */
58+
struct ble_conn_state_conn_handle_list {
59+
/** The length of the list. */
60+
uint32_t len;
61+
/** The list of handles. */
62+
uint16_t conn_handles[BLE_CONN_STATE_MAX_CONNECTIONS];
63+
};
64+
65+
/**
66+
* @brief Function to be called when a flag ID is set.
67+
*
68+
* See @ref ble_conn_state_for_each_set_user_flag.
69+
*
70+
* @param[in] conn_handle The connection the flag is set for.
71+
* @param[in] ctx Arbitrary pointer provided by the caller of
72+
* @ref ble_conn_state_for_each_set_user_flag.
73+
*/
74+
typedef void (*ble_conn_state_user_function_t)(uint16_t conn_handle, void *ctx);
75+
76+
/**
77+
* @defgroup ble_conn_state_functions BLE connection state functions
78+
* @{
79+
*/
80+
81+
/**
82+
* @brief Initialize or reset the module.
83+
*
84+
* @details This function sets all states to their default,
85+
* removing all records of connection handles.
86+
*/
87+
void ble_conn_state_init(void);
88+
89+
/**
90+
* @brief Check whether a connection handle represents a valid connection.
91+
*
92+
* @details A connection might be valid and have a BLE_CONN_STATUS_DISCONNECTED status.
93+
* Those connections are invalidated after a new connection occurs.
94+
*
95+
* @param[in] conn_handle Handle of the connection.
96+
*
97+
* @retval true If @c conn_handle represents a valid connection, thus a connection for which
98+
we have a record.
99+
* @retval false If @c conn_handle is @ref BLE_GAP_ROLE_INVALID, or if it has never been recorded.
100+
*/
101+
bool ble_conn_state_valid(uint16_t conn_handle);
102+
103+
/**
104+
* @brief Get the role of the local device in a connection.
105+
*
106+
* @param[in] conn_handle Handle of the connection to get the role for.
107+
*
108+
* @return The role of the local device in the connection (see @ref BLE_GAP_ROLES).
109+
* If conn_handle is not valid, the function returns @ref BLE_GAP_ROLE_INVALID.
110+
*/
111+
uint8_t ble_conn_state_role(uint16_t conn_handle);
112+
113+
/**
114+
* @brief Get the status of a connection.
115+
*
116+
* @param[in] conn_handle Handle of the connection.
117+
*
118+
* @return The status of the connection.
119+
* If conn_handle is not valid, the function returns @ref BLE_CONN_STATE_INVALID.
120+
*/
121+
enum ble_conn_state_status ble_conn_state_status(uint16_t conn_handle);
122+
123+
/**
124+
* @brief Check whether a connection is encrypted.
125+
*
126+
* @param[in] conn_handle Handle of connection to get the encryption state for.
127+
*
128+
* @retval true If the connection is encrypted.
129+
* @retval false If the connection is not encrypted or conn_handle is invalid.
130+
*/
131+
bool ble_conn_state_encrypted(uint16_t conn_handle);
132+
133+
/**
134+
* @brief Check whether a connection encryption is protected from Man in the Middle
135+
* (MITM) attacks.
136+
*
137+
* @param[in] conn_handle Handle of connection to get the MITM state for.
138+
*
139+
* @retval true If the connection is encrypted with MITM protection.
140+
* @retval false If the connection is not encrypted, or encryption is not MITM protected, or
141+
* conn_handle is invalid.
142+
*/
143+
bool ble_conn_state_mitm_protected(uint16_t conn_handle);
144+
145+
/**
146+
* @brief Check whether a connection was bonded using LE Secure Connections (LESC).
147+
*
148+
* The connection must currently be encrypted.
149+
*
150+
* @note This function will report false if bonded, and the LESC bonding was unauthenticated
151+
* ("Just Works") and happened in a previous connection. To detect such cases as well, check
152+
* the stored bonding key, e.g. in Peer Manager, which has a LESC flag associated with it.
153+
*
154+
* @param[in] conn_handle Handle of connection to get the LESC state for.
155+
*
156+
* @retval true If the connection was bonded using LESC.
157+
* @retval false If the connection has not been bonded using LESC, or @c conn_handle is invalid.
158+
*/
159+
bool ble_conn_state_lesc(uint16_t conn_handle);
160+
161+
/**
162+
* @brief Get the total number of connections.
163+
*
164+
* @return The total number of valid connections for which the module has a record.
165+
*/
166+
uint32_t ble_conn_state_conn_count(void);
167+
168+
/**
169+
* @brief Get the total number of connections in which the role of the local
170+
* device is @ref BLE_GAP_ROLE_CENTRAL.
171+
*
172+
* @return The number of connections in which the role of the local device is
173+
* @ref BLE_GAP_ROLE_CENTRAL.
174+
*/
175+
uint32_t ble_conn_state_central_conn_count(void);
176+
177+
/**
178+
* @brief Get the total number of connections in which the role of the local
179+
* device is @ref BLE_GAP_ROLE_PERIPH.
180+
*
181+
* @return The number of connections in which the role of the local device is
182+
* @ref BLE_GAP_ROLE_PERIPH.
183+
*/
184+
uint32_t ble_conn_state_peripheral_conn_count(void);
185+
186+
/**
187+
* @brief Get a list of all connection handles for which the module has a record.
188+
*
189+
* @details This function takes into account connections whose state is
190+
* @ref BLE_CONN_STATUS_DISCONNECTED.
191+
*
192+
* @return A list of all valid connection handles for which the module has a record.
193+
*/
194+
struct ble_conn_state_conn_handle_list ble_conn_state_conn_handles(void);
195+
196+
/**
197+
* @brief Get a list of connection handles in which the role of the local
198+
* device is @ref BLE_GAP_ROLE_CENTRAL.
199+
*
200+
* @details This function takes into account connections whose state is
201+
* @ref BLE_CONN_STATUS_DISCONNECTED.
202+
*
203+
* @return A list of all valid connection handles for which the module has a record and in which
204+
* the role of local device is @ref BLE_GAP_ROLE_CENTRAL.
205+
*/
206+
struct ble_conn_state_conn_handle_list ble_conn_state_central_handles(void);
207+
208+
/**
209+
* @brief Get the handle for the connection in which the role of the local device
210+
* is @ref BLE_GAP_ROLE_PERIPH.
211+
*
212+
* @details This function takes into account connections whose state is
213+
* @ref BLE_CONN_STATUS_DISCONNECTED.
214+
*
215+
* @return A list of all valid connection handles for which the module has a record and in which
216+
* the role of local device is @ref BLE_GAP_ROLE_PERIPH.
217+
*/
218+
struct ble_conn_state_conn_handle_list ble_conn_state_periph_handles(void);
219+
220+
/**
221+
* @brief Translate a connection handle to a value that can be used as an array index.
222+
*
223+
* @details Function for mapping connection handles onto the range <0 - MAX_CONNECTIONS>.
224+
*
225+
* @note The index will be the same as long as a connection is invalid. A subsequent connection with
226+
* the same connection handle might have a different index.
227+
*
228+
* @param[in] conn_handle The connection for which to retrieve an index.
229+
*
230+
* @return An index unique to this connection. Or @ref BLE_CONN_STATE_MAX_CONNECTIONS if
231+
* @c conn_handle refers to an invalid connection.
232+
*/
233+
uint16_t ble_conn_state_conn_idx(uint16_t conn_handle);
234+
235+
/**
236+
* @brief Obtain exclusive access to one of the user flag collections.
237+
*
238+
* @details The acquired collection contains one flag for each connection. These flags can be set
239+
* and read individually for each connection.
240+
*
241+
* The state of user flags will not be modified by the connection state module, except to
242+
* set it to 0 for a connection when that connection is invalidated.
243+
*
244+
* @return The index of the acquired flag, or -1 if none are available.
245+
*/
246+
int ble_conn_state_user_flag_acquire(void);
247+
248+
/**
249+
* @brief Read the value of a user flag.
250+
*
251+
* @param[in] conn_handle Handle of connection to get the flag state for.
252+
* @param[in] flag_index Which flag to get the state for.
253+
*
254+
* @return The state of the flag. If @c conn_handle is invalid, the function returns false.
255+
*/
256+
bool ble_conn_state_user_flag_get(uint16_t conn_handle, uint16_t flag_index);
257+
258+
/**
259+
* @brief Set the value of a user flag.
260+
*
261+
* @param[in] conn_handle Handle of connection to set the flag state for.
262+
* @param[in] flag_id Which flag to set the state for.
263+
* @param[in] value Value to set the flag state to.
264+
*/
265+
void ble_conn_state_user_flag_set(uint16_t conn_handle, uint16_t flag_index, bool value);
266+
267+
/**
268+
* @brief Run a function for each active connection.
269+
*
270+
* @param[in] user_function The function to run for each connection.
271+
* @param[in] ctx Arbitrary context to be passed to @p user_function.
272+
*
273+
* @return The number of times @p user_function was run.
274+
*/
275+
uint32_t ble_conn_state_for_each_connected(ble_conn_state_user_function_t user_function,
276+
void *ctx);
277+
278+
/**
279+
* @brief Run a function for each connection that has a user flag set.
280+
*
281+
* @param[in] flag_index Which flag to check.
282+
* @param[in] user_function The function to run when a flag is set.
283+
* @param[in] ctx Arbitrary context to be passed to @p user_function.
284+
*
285+
* @return The number of times @p user_function was run.
286+
*/
287+
uint32_t ble_conn_state_for_each_set_user_flag(uint16_t flag_index,
288+
ble_conn_state_user_function_t user_function,
289+
void *ctx);
290+
291+
/** @} */
292+
/** @} */
293+
294+
#ifdef __cplusplus
295+
}
296+
#endif
297+
298+
#endif /* BLE_CONN_STATE_H__ */

‎lib/CMakeLists.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ 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_GATT_QUEUE ble_gq)
1010
add_subdirectory_ifdef(CONFIG_BLE_RACP ble_racp)
11+
add_subdirectory_ifdef(CONFIG_CONN_STATE conn_state)
1112
add_subdirectory_ifdef(CONFIG_EVENT_SCHEDULER event_scheduler)
1213
add_subdirectory_ifdef(CONFIG_BM_BUTTONS bm_buttons)
1314
add_subdirectory_ifdef(CONFIG_BM_STORAGE bm_storage)

‎lib/Kconfig

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ rsource "ble_adv/Kconfig"
99
rsource "ble_conn_params/Kconfig"
1010
rsource "ble_gq/Kconfig"
1111
rsource "ble_racp/Kconfig"
12+
rsource "conn_state/Kconfig"
1213
rsource "event_scheduler/Kconfig"
1314
rsource "bm_buttons/Kconfig"
1415
rsource "bm_storage/Kconfig"

‎lib/conn_state/CMakeLists.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
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(ble_conn_state.c)

‎lib/conn_state/Kconfig

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
#
2+
# Copyright (c) 2025 Nordic Semiconductor
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
menuconfig CONN_STATE
7+
bool "Event scheduler"
8+
help
9+
A library to defer event processing to main().
10+
11+
if CONN_STATE
12+
13+
config BLE_CONN_STATE_USER_FLAG_COUNT
14+
int "User flag count"
15+
range 0 24
16+
default 24
17+
help
18+
The number of available user flags.
19+
20+
config BLE_CONN_STATE_DEFAULT_FLAG_COLLECTION_COUNT
21+
int "Default flag collection count"
22+
default 6
23+
help
24+
The number of flags kept for each connection, excluding user flags.
25+
26+
module=CONN_STATE
27+
module-dep=LOG
28+
module-str=Connection state
29+
source "${ZEPHYR_BASE}/subsys/logging/Kconfig.template.log_config"
30+
31+
endif

0 commit comments

Comments
 (0)