1 /***************************************************************************//**
2 * @file
3 * @brief The BLE specific header file for the RAIL library.
4 *******************************************************************************
5 * # License
6 * <b>Copyright 2020 Silicon Laboratories Inc. www.silabs.com</b>
7 *******************************************************************************
8 *
9 * SPDX-License-Identifier: Zlib
10 *
11 * The licensor of this software is Silicon Laboratories Inc.
12 *
13 * This software is provided 'as-is', without any express or implied
14 * warranty. In no event will the authors be held liable for any damages
15 * arising from the use of this software.
16 *
17 * Permission is granted to anyone to use this software for any purpose,
18 * including commercial applications, and to alter it and redistribute it
19 * freely, subject to the following restrictions:
20 *
21 * 1. The origin of this software must not be misrepresented; you must not
22 * claim that you wrote the original software. If you use this software
23 * in a product, an acknowledgment in the product documentation would be
24 * appreciated but is not required.
25 * 2. Altered source versions must be plainly marked as such, and must not be
26 * misrepresented as being the original software.
27 * 3. This notice may not be removed or altered from any source distribution.
28 *
29 ******************************************************************************/
30
31 #ifndef __RAIL_BLE_H__
32 #define __RAIL_BLE_H__
33
34 // Get the standard include types
35 #include <stdint.h>
36 #include <stdbool.h>
37
38 // Get the RAIL specific structures and types
39 #include "rail_types.h"
40
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44
45 /// @addtogroup BLE
46 /// @ingroup Protocol_Specific
47 /// Accelerator routines for Bluetooth Low Energy (BLE).
48 ///
49 /// The APIs in this module configure the radio for BLE
50 /// operation and provide additional helper routines necessary for
51 /// normal BLE send/receive that aren't available directly in RAIL.
52 /// RAIL APIs should be used to set up the application. However,
53 /// RAIL_ConfigChannels() and RAIL_ConfigRadio() should not be called to set up
54 /// the PHY. Instead, RAIL_BLE_Config* APIs should be used to set up the
55 /// 1 Mbps, 2 Mbps, or Coded PHY configurations needed by the application. These
56 /// APIs will configure the hardware and also configure the set of valid BLE
57 /// channels.
58 ///
59 /// To implement a standard BLE link layer, you will also need to handle tight
60 /// turnaround times and send packets at specific instants. This can all be
61 /// managed through general RAIL functions, such as RAIL_ScheduleTx(),
62 /// RAIL_ScheduleRx(), and RAIL_SetStateTiming(). See RAIL APIs for more
63 /// useful functions.
64 ///
65 /// A simple example to set up the application to be in BLE mode is shown
66 /// below. Note that this will put the radio on the first advertising channel
67 /// with the advertising Access Address. In any full-featured BLE application you
68 /// will need to use the RAIL_BLE_ConfigChannelRadioParams() function to change
69 /// the sync word and other parameters as needed based on your connection.
70 ///
71 /// @code{.c}
72 ///
73 /// // RAIL Handle set at initialization time.
74 /// static RAIL_Handle_t gRailHandle = NULL;
75 ///
76 /// static void radioEventHandler(RAIL_Handle_t railHandle,
77 /// RAIL_Events_t events)
78 /// {
79 /// // ... handle RAIL events, e.g., receive and transmit completion
80 /// }
81 ///
82 /// #if MULTIPROTOCOL
83 /// // Allocate memory for RAIL to hold BLE-specific state information
84 /// static RAIL_BLE_State_t bleState; // Must never be const
85 /// static RAILSched_Config_t schedCfg; // Must never be const
86 /// static RAIL_Config_t railCfg = { // Must never be const
87 /// .eventsCallback = &radioEventHandler,
88 /// .protocol = &bleState, // For BLE, RAIL needs additional state memory
89 /// .scheduler = &schedCfg, // For MultiProtocol, additional scheduler memory
90 /// };
91 /// #else
92 /// static RAIL_Config_t railCfg = { // Must never be const
93 /// .eventsCallback = &radioEventHandler,
94 /// .protocol = NULL,
95 /// .scheduler = NULL,
96 /// };
97 /// #endif
98 ///
99 /// // Set the radio to receive on the first BLE advertising channel.
100 /// int bleAdvertiseEnable(void)
101 /// {
102 /// // Initializes the RAIL library and any internal state it requires.
103 /// gRailHandle = RAIL_Init(&railCfg, NULL);
104 ///
105 /// // Calls the BLE initialization function to load the right radio configuration.
106 /// RAIL_BLE_Init(gRailHandle);
107 ///
108 /// // Always choose the Viterbi PHY configuration if available on your chip
109 /// // for performance reasons.
110 /// RAIL_BLE_ConfigPhy1MbpsViterbi(gRailHandle);
111 ///
112 /// // Configures us for the first advertising channel (Physical: 0, Logical: 37).
113 /// // The CRC init value and Access Address come from the BLE specification.
114 /// RAIL_BLE_ConfigChannelRadioParams(gRailHandle,
115 /// 0x555555,
116 /// 0x8E89BED6,
117 /// 37,
118 /// false);
119 ///
120 /// // Starts receiving on physical channel 0 (logical channel 37).
121 /// RAIL_StartRx(gRailHandle, 0, NULL);
122 /// }
123 /// @endcode
124 ///
125 /// @{
126
127 /**
128 * @enum RAIL_BLE_Coding_t
129 * @brief The variant of the BLE Coded PHY.
130 */
RAIL_ENUM(RAIL_BLE_Coding_t)131 RAIL_ENUM(RAIL_BLE_Coding_t) {
132 /** Enables the 125 kbps variant of the BLE Coded PHY */
133 RAIL_BLE_Coding_125kbps = 0,
134 /** @deprecated Will be removed in a future version of RAIL */
135 RAIL_BLE_Coding_125kbps_DSA = 1,
136 /** Enables the 500 kbps variant of the BLE Coded PHY */
137 RAIL_BLE_Coding_500kbps = 2,
138 /** @deprecated Will be removed in a future version of RAIL */
139 RAIL_BLE_Coding_500kbps_DSA = 3,
140 };
141
142 #ifndef DOXYGEN_SHOULD_SKIP_THIS
143 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
144 #define RAIL_BLE_Coding_125kbps ((RAIL_BLE_Coding_t) RAIL_BLE_Coding_125kbps)
145 #define RAIL_BLE_Coding_125kbps_DSA ((RAIL_BLE_Coding_t) RAIL_BLE_Coding_125kbps_DSA)
146 #define RAIL_BLE_Coding_500kbps ((RAIL_BLE_Coding_t) RAIL_BLE_Coding_500kbps)
147 #define RAIL_BLE_Coding_500kbps_DSA ((RAIL_BLE_Coding_t) RAIL_BLE_Coding_500kbps_DSA)
148 #endif //DOXYGEN_SHOULD_SKIP_THIS
149
150 /**
151 * @enum RAIL_BLE_Phy_t
152 * @brief The variant of the BLE PHY.
153 */
RAIL_ENUM(RAIL_BLE_Phy_t)154 RAIL_ENUM(RAIL_BLE_Phy_t) {
155 /** Use the standard BLE 1Mbps PHY */
156 RAIL_BLE_1Mbps,
157 /** Use the high data rate BLE 2Mbps PHY */
158 RAIL_BLE_2Mbps,
159 /** Enables the 125 kbps variant of the BLE Coded PHY */
160 RAIL_BLE_Coded125kbps,
161 /** Enables the 500 kbps variant of the BLE Coded PHY */
162 RAIL_BLE_Coded500kbps,
163 };
164
165 #ifndef DOXYGEN_SHOULD_SKIP_THIS
166 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
167 #define RAIL_BLE_1Mbps ((RAIL_BLE_Phy_t) RAIL_BLE_1Mbps)
168 #define RAIL_BLE_2Mbps ((RAIL_BLE_Phy_t) RAIL_BLE_2Mbps)
169 #define RAIL_BLE_Coded125kbps ((RAIL_BLE_Phy_t) RAIL_BLE_Coded125kbps)
170 #define RAIL_BLE_Coded500kbps ((RAIL_BLE_Phy_t) RAIL_BLE_Coded500kbps)
171 #endif //DOXYGEN_SHOULD_SKIP_THIS
172
173 /// @addtogroup BLE_PHY BLE Radio Configurations
174 /// Radio configurations for the RAIL BLE Accelerator
175 ///
176 /// These radio configurations are used to configure BLE when a function such
177 /// as \ref RAIL_BLE_ConfigPhy1MbpsViterbi() is called. Each radio
178 /// configuration listed below is compiled into the RAIL library as a weak
179 /// symbol that will take into account per-die defaults. If the board
180 /// configuration in use has different settings than the default, such as a
181 /// different radio subsystem clock frequency, these radio configurations can
182 /// be overriden to account for those settings.
183 /// @{
184
185 /**
186 * Default PHY to use for BLE 1M non-Viterbi. Will be NULL if
187 * \ref RAIL_BLE_SUPPORTS_1MBPS_NON_VITERBI is 0.
188 */
189 extern const RAIL_ChannelConfig_t *const RAIL_BLE_Phy1Mbps;
190
191 /**
192 * Default PHY to use for BLE 2M non-Viterbi. Will be NULL if
193 * \ref RAIL_BLE_SUPPORTS_2MBPS_NON_VITERBI is 0.
194 */
195 extern const RAIL_ChannelConfig_t *const RAIL_BLE_Phy2Mbps;
196
197 /**
198 * Default PHY to use for BLE 1M Viterbi. Will be NULL if
199 * \ref RAIL_BLE_SUPPORTS_1MBPS_VITERBI is 0.
200 */
201 extern const RAIL_ChannelConfig_t *const RAIL_BLE_Phy1MbpsViterbi;
202
203 /**
204 * Default PHY to use for BLE 2M Viterbi. Will be NULL if
205 * \ref RAIL_BLE_SUPPORTS_2MBPS_VITERBI is 0.
206 */
207 extern const RAIL_ChannelConfig_t *const RAIL_BLE_Phy2MbpsViterbi;
208
209 /**
210 * PHY to use for BLE 2M with AoX functionality. Will be NULL if either
211 * \ref RAIL_BLE_SUPPORTS_2MBPS_VITERBI or \ref RAIL_BLE_SUPPORTS_AOX is 0.
212 */
213 extern const RAIL_ChannelConfig_t *const RAIL_BLE_Phy2MbpsAox;
214
215 /**
216 * Default PHY to use for BLE Coded 125kbps. Will be NULL if
217 * \ref RAIL_BLE_SUPPORTS_CODED_PHY is 0. This PHY can receive on both
218 * 125kbps and 500kbps BLE Coded, but will only transmit at 125kbps.
219 */
220 extern const RAIL_ChannelConfig_t *const RAIL_BLE_Phy125kbps;
221
222 /**
223 * Default PHY to use for BLE Coded 500kbps. Will be NULL if
224 * \ref RAIL_BLE_SUPPORTS_CODED_PHY is 0. This PHY can receive on both
225 * 125kbps and 500kbps BLE Coded, but will only transmit at 125kbps.
226 */
227 extern const RAIL_ChannelConfig_t *const RAIL_BLE_Phy500kbps;
228
229 /**
230 * Default PHY to use for BLE Simulscan. Will be NULL if
231 * \ref RAIL_BLE_SUPPORTS_SIMULSCAN_PHY is 0. This PHY can receive on 1Mbps
232 * as well as 125kbps and 500kbps BLE Coded, but will only transmit at 1Mbps.
233 */
234 extern const RAIL_ChannelConfig_t *const RAIL_BLE_PhySimulscan;
235
236 /**
237 * Default 1Mbps Quuppa PHY. Will be NULL if
238 * \ref RAIL_BLE_SUPPORTS_QUUPPA is 0.
239 */
240 extern const RAIL_ChannelConfig_t *const RAIL_BLE_PhyQuuppa;
241
242 /// @} // End of group BLE_PHY
243
244 // Defines for subPhyID field in RAIL_RxPacketDetails_t
245 /** subPhyId indicating a 500kbps packet */
246 #define RAIL_BLE_RX_SUBPHY_ID_500K (0U)
247 /** subPhyId indicating a 125kbps packet */
248 #define RAIL_BLE_RX_SUBPHY_ID_125K (1U)
249 /** subPhyId value indicating a 1Mbps packet */
250 #define RAIL_BLE_RX_SUBPHY_ID_1M (2U)
251 /** Invalid subPhyId value */
252 #define RAIL_BLE_RX_SUBPHY_ID_INVALID (3U)
253 /** subPhyId indicating the total count */
254 #define RAIL_BLE_RX_SUBPHY_COUNT (4U)
255
256 /**
257 * @enum RAIL_BLE_SignalIdentifierMode_t
258 * @brief Available Signal Identifier modes.
259 */
RAIL_ENUM(RAIL_BLE_SignalIdentifierMode_t)260 RAIL_ENUM(RAIL_BLE_SignalIdentifierMode_t) {
261 /* Disable signal detection mode. */
262 RAIL_BLE_SIGNAL_IDENTIFIER_MODE_DISABLE = 0,
263 /* BLE 1Mbps (GFSK) detection mode. */
264 RAIL_BLE_SIGNAL_IDENTIFIER_MODE_1MBPS,
265 /* BLE 2Mbps (GFSK) detection mode. */
266 RAIL_BLE_SIGNAL_IDENTIFIER_MODE_2MBPS
267 };
268
269 #ifndef DOXYGEN_SHOULD_SKIP_THIS
270 // Self-referencing defines minimize compiler complaints when using RAIL_ENUM
271 #define RAIL_BLE_SIGNAL_IDENTIFIER_MODE_DISABLE ((RAIL_BLE_SignalIdentifierMode_t)RAIL_BLE_SIGNAL_IDENTIFIER_MODE_DISABLE)
272 #define RAIL_BLE_SIGNAL_IDENTIFIER_MODE_1MBPS ((RAIL_BLE_SignalIdentifierMode_t)RAIL_BLE_SIGNAL_IDENTIFIER_MODE_1MBPS)
273 #define RAIL_BLE_SIGNAL_IDENTIFIER_MODE_2MBPS ((RAIL_BLE_SignalIdentifierMode_t)RAIL_BLE_SIGNAL_IDENTIFIER_MODE_2MBPS)
274 #endif
275
276 /**
277 * @struct RAIL_BLE_State_t
278 * @brief A state structure for BLE.
279 *
280 * This structure must be allocated in application global read-write memory
281 * that persists for the duration of BLE usage. It cannot be allocated
282 * in read-only memory or on the call stack.
283 */
284 typedef struct RAIL_BLE_State {
285 uint32_t crcInit; /**< The value used to initialize the CRC algorithm. */
286 uint32_t accessAddress; /**< The access address used for the connection. */
287 uint16_t channel; /**< The logical channel used. */
288 bool disableWhitening; /**< Indicates whether the whitening engine should be off. */
289 } RAIL_BLE_State_t;
290
291 /**
292 * Configure RAIL to run in BLE mode.
293 *
294 * @param[in] railHandle A handle for RAIL instance.
295 * This function changes your radio, channel configuration, and other
296 * parameters to match what is needed for BLE. To switch back to a
297 * default RAIL mode, call RAIL_BLE_Deinit() first. This function
298 * will configure the protocol output on PTI to \ref RAIL_PTI_PROTOCOL_BLE.
299 *
300 * @note BLE may not be enabled while Auto-ACKing is enabled.
301 */
302 void RAIL_BLE_Init(RAIL_Handle_t railHandle);
303
304 /**
305 * Take RAIL out of BLE mode.
306 *
307 * @param[in] railHandle A handle for RAIL instance.
308 * This function will undo some of the configuration that happens when you call
309 * RAIL_BLE_Init(). After this you can safely run your normal radio
310 * initialization code to use a non-BLE configuration. This function does \b
311 * not change back your radio or channel configurations so you must do this by
312 * manually reinitializing. This also resets the protocol output on PTI to \ref
313 * RAIL_PTI_PROTOCOL_CUSTOM.
314 */
315 void RAIL_BLE_Deinit(RAIL_Handle_t railHandle);
316
317 /**
318 * Determine whether BLE mode is enabled or not.
319 *
320 * @param[in] railHandle A handle for RAIL instance.
321 * @return True if BLE mode is enabled and false otherwise.
322 * This function returns the current status of RAIL's BLE mode. It is enabled by
323 * a call to RAIL_BLE_Init() and disabled by a call to RAIL_BLE_Deinit().
324 */
325 bool RAIL_BLE_IsEnabled(RAIL_Handle_t railHandle);
326
327 /**
328 * Switch to the 1 Mbps Quuppa PHY.
329 *
330 * @param[in] railHandle A handle for RAIL instance.
331 * @return Status code indicating success of the function call.
332 *
333 * You can use this function to switch to the Quuppa PHY.
334 *
335 * @note Not all chips support the 1Mbps Quuppa PHY. This API should return RAIL_STATUS_INVALID_CALL if
336 * unsupported by the hardware we're building for.
337 */
338 RAIL_Status_t RAIL_BLE_ConfigPhyQuuppa(RAIL_Handle_t railHandle);
339
340 /**
341 * Switch to the Viterbi 1 Mbps BLE PHY.
342 *
343 * @param[in] railHandle A handle for RAIL instance.
344 * @return A status code indicating success of the function call.
345 *
346 * Use this function to switch back to the default BLE 1 Mbps PHY if you
347 * have switched to the 2 Mbps or another configuration. You may only call this
348 * function after initializing BLE and while the radio is idle.
349 *
350 * @note The EFR32XG1 family does not support BLE Viterbi PHYs. However, calls
351 * to this function from that family will be silently redirected to the legacy
352 * \ref RAIL_BLE_ConfigPhy1Mbps().
353 */
354 RAIL_Status_t RAIL_BLE_ConfigPhy1MbpsViterbi(RAIL_Handle_t railHandle);
355
356 /**
357 * Switch to the legacy non-Viterbi 1 Mbps BLE PHY.
358 *
359 * @param[in] railHandle A handle for RAIL instance.
360 * @return A status code indicating success of the function call.
361 *
362 * Use this function to switch back to the legacy BLE 1 Mbps PHY if you
363 * have switched to the 2 Mbps or another configuration. You may only call this
364 * function after initializing BLE and while the radio is idle.
365 *
366 * @note The EFR32XG2x family does not support BLE non-Viterbi PHYs.
367 */
368 RAIL_Status_t RAIL_BLE_ConfigPhy1Mbps(RAIL_Handle_t railHandle);
369
370 /**
371 * Switch to the Viterbi 2 Mbps BLE PHY.
372 *
373 * @param[in] railHandle A handle for RAIL instance.
374 * @return A status code indicating success of the function call.
375 *
376 * Use this function to switch back to the BLE 2 Mbps PHY from the
377 * default 1 Mbps option. You may only call this function after initializing BLE
378 * and while the radio is idle.
379 *
380 * @note The EFR32XG1 family does not support BLE Viterbi PHYs.
381 */
382 RAIL_Status_t RAIL_BLE_ConfigPhy2MbpsViterbi(RAIL_Handle_t railHandle);
383
384 /**
385 * Switch to the legacy non-Viterbi 2 Mbps BLE PHY.
386 *
387 * @param[in] railHandle A handle for RAIL instance.
388 * @return A status code indicating success of the function call.
389 *
390 * Use this function to switch back to legacy BLE 2Mbps PHY from the
391 * default 1 Mbps option. You may only call this function after initializing BLE
392 * and while the radio is idle.
393 *
394 * @note The EFR32XG1 and EFR32XG2x families do not support BLE non-Viterbi
395 * 2 Mbps PHY.
396 */
397 RAIL_Status_t RAIL_BLE_ConfigPhy2Mbps(RAIL_Handle_t railHandle);
398
399 /**
400 * Switch to the BLE Coded PHY.
401 *
402 * @param[in] railHandle A handle for RAIL instance.
403 * @param[in] bleCoding The RAIL_BLE_Coding_t to use
404 * @return A status code indicating success of the function call.
405 *
406 * Use this function to switch back to BLE Coded PHY from the default
407 * 1 Mbps option. You may only call this function after initializing BLE and
408 * while the radio is idle. When using a BLE Coded PHY, the \ref
409 * RAIL_RxPacketDetails_t::subPhyId marks the coding of the received packet.
410 * A subPhyId of 0 marks a 500 kbps packet, and a subPhyId of 1 marks a 125
411 * kbps packet.
412 *
413 * @note The EFR32XG1, EFR32XG12, and EFR32XG14 families do not support BLE
414 * Coded PHYs.
415 */
416 RAIL_Status_t RAIL_BLE_ConfigPhyCoded(RAIL_Handle_t railHandle,
417 RAIL_BLE_Coding_t bleCoding);
418
419 /**
420 * Switch to the Simulscan PHY.
421 *
422 * @param[in] railHandle A handle for RAIL instance.
423 * @return A status code indicating success of the function call.
424 *
425 * Use this function to switch to the BLE Simulscan PHY. You may only
426 * call this function after initializing BLE and while the radio is idle.
427 * When using Simulscan PHY, the \ref RAIL_RxPacketDetails_t::subPhyId
428 * marks the coding of the received packet. A subPhyId of 0 marks a
429 * 500 kbps packet, a subPhyId of 1 marks a 125 kbps packet, and a
430 * subPhyId of 2 marks a 1 Mbps packet.
431 *
432 * @note: The Simulscan PHY is supported only on some 2.4 GHz Series-2 parts.
433 * The preprocessor symbol \ref RAIL_BLE_SUPPORTS_SIMULSCAN_PHY and the
434 * runtime function \ref RAIL_BLE_SupportsSimulscanPhy() may be used to
435 * test for support of the Simulscan PHY.
436 */
437 RAIL_Status_t RAIL_BLE_ConfigPhySimulscan(RAIL_Handle_t railHandle);
438
439 /**
440 * Change BLE radio parameters.
441 *
442 * @param[in] railHandle A handle for RAIL instance.
443 * @param[in] crcInit The value to use for CRC initialization.
444 * @param[in] accessAddress The access address to use for the connection. The
445 * bits of this parameter are transmitted or received LSB first.
446 * @param[in] channel The logical channel that you're changing to, which
447 * initializes the whitener if used.
448 * @param[in] disableWhitening This can turn off the whitening engine and is useful
449 * for sending BLE test mode packets that don't have this turned on.
450 * @return A status code indicating success of the function call.
451 *
452 * This function can be used to switch radio parameters on every connection
453 * and/or channel change. It is BLE-aware and will set the access address,
454 * preamble, CRC initialization value, and whitening configuration without
455 * requiring you to load a new radio configuration. This function should not be
456 * called while the radio is active.
457 */
458 RAIL_Status_t RAIL_BLE_ConfigChannelRadioParams(RAIL_Handle_t railHandle,
459 uint32_t crcInit,
460 uint32_t accessAddress,
461 uint16_t channel,
462 bool disableWhitening);
463
464 /**
465 * Change the current BLE PHY and go into receive.
466 *
467 * @param[in] railHandle A handle for RAIL instance.
468 * @param[in] phy Indicates which PHY to receive on
469 * @param[in] railChannel Which channel of the given PHY to receive on
470 * @param[in] startRxTime When to enter RX
471 * @param[in] crcInit The value to use for CRC initialization.
472 * @param[in] accessAddress The access address to use for the connection. The
473 * bits of this parameter are transmitted or received LSB first.
474 * @param[in] logicalChannel The logical channel that you're changing to, which
475 * initializes the whitener if used.
476 * @param[in] disableWhitening This can turn off the whitening engine and is useful
477 * for sending BLE test mode packets that don't have this turned on.
478 * @return A status code indicating success of the function call.
479 *
480 * This function is used to implement auxiliary packet reception, as defined in
481 * the BLE specification. The radio will be put into IDLE, the PHY and channel
482 * will be changed, and then receive will be entered at the start time given.
483 * The new receive will have a timeout of 30 us, which means that this function
484 * should only be called if the offset unit is 30 us.
485 *
486 * This function is extremely time-sensitive, and may only be called within the
487 * interrupt context of a \ref RAIL_EVENT_RX_PACKET_RECEIVED event.
488 */
489 RAIL_Status_t RAIL_BLE_PhySwitchToRx(RAIL_Handle_t railHandle,
490 RAIL_BLE_Phy_t phy,
491 uint16_t railChannel,
492 uint32_t startRxTime,
493 uint32_t crcInit,
494 uint32_t accessAddress,
495 uint16_t logicalChannel,
496 bool disableWhitening);
497
498 /**
499 * Configure and enable signal identifier for BLE signal detection.
500 *
501 * @param[in] railHandle A RAIL instance handle.
502 * @param[in] signalIdentifierMode Mode of signal identifier operation.
503 *
504 * This features allows detection of BLE signal on air based on the mode.
505 * This function must be called once before \ref RAIL_BLE_EnableSignalDetection
506 * to configure and enable signal identifier.
507 *
508 * To enable event for signal detection \ref RAIL_ConfigEvents() must be called
509 * for enabling \ref RAIL_EVENT_SIGNAL_DETECTED.
510 *
511 * This function is only supported by chips where
512 * \ref RAIL_BLE_SUPPORTS_SIGNAL_IDENTIFIER and
513 * \ref RAIL_BLE_SupportsSignalIdentifier() are true.
514 *
515 * @return Status code indicating success of the function call.
516 */
517 RAIL_Status_t RAIL_BLE_ConfigSignalIdentifier(RAIL_Handle_t railHandle,
518 RAIL_BLE_SignalIdentifierMode_t signalIdentifierMode);
519
520 /**
521 * Enable or Disable signal identifier interrupt for BLE signal detection.
522 *
523 * @param[in] railHandle A RAIL instance handle.
524 * @param[in] enable Signal detection is enabled if true, disabled if false.
525 *
526 * \ref RAIL_BLE_ConfigSignalIdentifier must be called once before calling this
527 * function to configure and enable signal identifier.
528 * Once a signal is detected signal detection will be turned off and this
529 * function should be called to re-enable the signal detection without needing
530 * to call \ref RAIL_BLE_ConfigSignalIdentifier if the signal identifier
531 * is already configured and enabled.
532 *
533 * This function is only supported by chips where
534 * \ref RAIL_BLE_SUPPORTS_SIGNAL_IDENTIFIER and
535 * \ref RAIL_BLE_SupportsSignalIdentifier() are true.
536 *
537 * @return Status code indicating success of the function call.
538 */
539 RAIL_Status_t RAIL_BLE_EnableSignalDetection(RAIL_Handle_t railHandle,
540 bool enable);
541
542 /**
543 * @brief Backward compatible name for the \ref
544 * RAIL_BLE_EnableSignalDetection API.
545 */
546 #define RAIL_BLE_EnableSignalIdentifier RAIL_BLE_EnableSignalDetection
547
548 /******************************************************************************
549 * Angle of Arrival/Departure (AoX)
550 *****************************************************************************/
551 /**
552 * @addtogroup AoX Angle of Arrival/Departure
553 * @{
554 * @brief These APIs are to a stack implementing BLE's angle of arrival and
555 * angle of departure functionality.
556 *
557 * They are designed for use by the Silicon Labs BLE stack only at this time and
558 * may cause problems if accessed directly.
559 */
560
561 /**
562 *
563 * The maximum number of GPIO pins used for AoX Antenna switching.
564 *
565 * If the user configures more pins using
566 * \ref RAIL_BLE_ConfigAoxAntenna than allowed
567 * \ref RAIL_BLE_AOX_ANTENNA_PIN_COUNT, then
568 * \ref RAIL_STATUS_INVALID_PARAMETER status will be returned.
569 *
570 * \ref RAIL_STATUS_INVALID_CALL is returned if :
571 * \ref RAIL_BLE_AOX_ANTENNA_PIN_COUNT is set to 0 or
572 * The user configures no pins.
573 *
574 * The maximum value \ref RAIL_BLE_AOX_ANTENNA_PIN_COUNT can take depends on
575 * number of Antenna route pins , a chip provides.
576 * For EFR32XG22, the maximum value of \ref RAIL_BLE_AOX_ANTENNA_PIN_COUNT is 6.
577 * If the user configures fewer pins than \ref RAIL_BLE_AOX_ANTENNA_PIN_COUNT,
578 * then only number of pins asked by user will be configured with
579 * \ref RAIL_STATUS_NO_ERROR.
580 *
581 */
582 #define RAIL_BLE_AOX_ANTENNA_PIN_COUNT (6U)
583
584 /**
585 * @enum RAIL_BLE_AoxOptions_t
586 * @brief Angle of Arrival/Departure options bit fields
587 */
RAIL_ENUM_GENERIC(RAIL_BLE_AoxOptions_t,uint16_t)588 RAIL_ENUM_GENERIC(RAIL_BLE_AoxOptions_t, uint16_t) {
589 /** Shift position of \ref RAIL_BLE_AOX_OPTIONS_SAMPLE_MODE bit */
590 RAIL_BLE_AOX_OPTIONS_SAMPLE_MODE_SHIFT = 0,
591 /** Shift position of \ref RAIL_BLE_AOX_OPTIONS_CONNLESS bit */
592 RAIL_BLE_AOX_OPTIONS_CONNLESS_SHIFT = 1,
593 /** Shift position of \ref RAIL_BLE_AOX_OPTIONS_CONN bit */
594 RAIL_BLE_AOX_OPTIONS_CONN_SHIFT = 2,
595 /** Shift position of \ref RAIL_BLE_AOX_OPTIONS_DISABLE_BUFFER_LOCK bit */
596 RAIL_BLE_AOX_OPTIONS_DISABLE_BUFFER_LOCK_SHIFT = 3,
597 };
598
599 /**
600 * @deprecated Obsolete AOX option
601 */
602 #define RAIL_BLE_AOX_OPTIONS_DO_SWITCH (0U)
603 /**
604 * @deprecated Obsolete AOX option
605 */
606 #define RAIL_BLE_AOX_OPTIONS_TX_ENABLED (0U)
607 /**
608 * @deprecated Obsolete AOX option
609 */
610 #define RAIL_BLE_AOX_OPTIONS_RX_ENABLED (0U)
611 /**
612 * @deprecated Please use \ref RAIL_BLE_AOX_OPTIONS_DISABLE_BUFFER_LOCK_SHIFT instead.
613 */
614 #define RAIL_BLE_AOX_OPTIONS_LOCK_CTE_BUFFER_SHIFT RAIL_BLE_AOX_OPTIONS_DISABLE_BUFFER_LOCK_SHIFT
615
616 /**
617 * Disable the AoX feature.
618 */
619 #define RAIL_BLE_AOX_OPTIONS_DISABLED (0U)
620 /**
621 * Sets one of the two AoX sampling/switching modes: 1 us or 2 us window.
622 */
623 #define RAIL_BLE_AOX_OPTIONS_SAMPLE_MODE (1U << RAIL_BLE_AOX_OPTIONS_SAMPLE_MODE_SHIFT)
624 /**
625 * Enables connectionless AoX Rx packets.
626 */
627 #define RAIL_BLE_AOX_OPTIONS_CONNLESS (1U << RAIL_BLE_AOX_OPTIONS_CONNLESS_SHIFT)
628 /**
629 * Enables connection based AoX Rx packets.
630 */
631 #define RAIL_BLE_AOX_OPTIONS_CONN (1U << RAIL_BLE_AOX_OPTIONS_CONN_SHIFT)
632 /**
633 * Disables CTE buffer lock.
634 */
635 #define RAIL_BLE_AOX_OPTIONS_DISABLE_BUFFER_LOCK (1U << RAIL_BLE_AOX_OPTIONS_DISABLE_BUFFER_LOCK_SHIFT)
636 /**
637 * Enables connection based or connectionless AoX Rx packets.
638 */
639 #define RAIL_BLE_AOX_OPTIONS_ENABLED (RAIL_BLE_AOX_OPTIONS_CONN | RAIL_BLE_AOX_OPTIONS_CONNLESS)
640
641 /**
642 * @struct RAIL_BLE_AoxConfig_t
643 * @brief Contains arguments for \ref RAIL_BLE_ConfigAox function.
644 */
645 typedef struct RAIL_BLE_AoxConfig {
646 /**
647 * See RAIL_BLE_AOX_OPTIONS_* for bitfield defines for different AoX features.
648 */
649 RAIL_BLE_AoxOptions_t aoxOptions;
650 /**
651 * Size of the raw AoX CTE (continuous tone extension) data capture buffer in
652 * bytes.
653 */
654 uint16_t cteBuffSize;
655 /**
656 * Address to where the received CTE is written.
657 */
658 uint32_t * cteBuffAddr;
659 /**
660 * Address to first element of antenna pattern array. Array must be in RAM.
661 * Each element of the array contains an antenna number. The switching pattern
662 * is defined by the order of antennas in this array.
663 */
664 uint8_t * antArrayAddr;
665 /**
666 * Size of the antenna pattern array.
667 */
668 uint8_t antArraySize;
669 } RAIL_BLE_AoxConfig_t;
670
671 /**
672 * @struct RAIL_BLE_AoxAntennaPortPins_t
673 * @brief Contains elements of \ref RAIL_BLE_AoxAntennaConfig_t struct.
674 */
675 typedef struct RAIL_BLE_AoxAntennaPortPins {
676 /**
677 * The port which is used for AoX antenna switching
678 */
679 uint8_t antPort;
680 /**
681 * The pin which is used for AoX antenna switching
682 */
683 uint8_t antPin;
684 } RAIL_BLE_AoxAntennaPortPins_t;
685
686 /**
687 * @struct RAIL_BLE_AoxAntennaConfig_t
688 * @brief Contains arguments for \ref RAIL_BLE_ConfigAoxAntenna function for
689 * EFR32XG22.
690 */
691 typedef struct RAIL_BLE_AoxAntennaConfig {
692 /**
693 * A pointer to an array containing struct of port and pin used for
694 * AoX antenna switching
695 */
696 RAIL_BLE_AoxAntennaPortPins_t *antPortPin;
697 /**
698 * Number of antenna pins to be configured.
699 */
700 uint8_t antCount;
701 } RAIL_BLE_AoxAntennaConfig_t;
702
703 /**
704 * Lock/unlock the CTE buffer from the application's perspective. The radio
705 * will write to the buffer only if the bit is NOT set at the beginning of the
706 * sampling period. The radio will set the bit once the sampling period starts
707 * to indicate that some CTE data has been collected, which will not be
708 * overwritten during the next sampling period, unless the buffer is unlocked by
709 * the application.
710 *
711 * @param[in] railHandle A RAIL instance handle.
712 * @param[in] lock Lock the CTE buffer if true and unlock it if false.
713 * @return True if the CTE buffer is locked after the call, otherwise false.
714 */
715 bool RAIL_BLE_LockCteBuffer(RAIL_Handle_t railHandle, bool lock);
716
717 /**
718 * Determine whether the CTE buffer is currently locked or not.
719 *
720 * @param[in] railHandle A handle for RAIL instance.
721 * @return True if CTE buffer is locked and false otherwise.
722 */
723 bool RAIL_BLE_CteBufferIsLocked(RAIL_Handle_t railHandle);
724
725 /**
726 * Get the offset into CTE sample of CTE data.
727 *
728 * @param[in] railHandle A handle for RAIL instance.
729 * @return The offset of CTE data in a CTE sample in bytes.
730 * On unsupported platforms this returns 0.
731 */
732 uint8_t RAIL_BLE_GetCteSampleOffset(RAIL_Handle_t railHandle);
733
734 /**
735 * Get the effective sample rate used by the ADC to capture the CTE samples.
736 *
737 * @param[in] railHandle A handle for RAIL instance.
738 * @return The actual sample rate used to capture the CTE in samples per second.
739 * On unsupported platforms this returns 0.
740 */
741 uint32_t RAIL_BLE_GetCteSampleRate(RAIL_Handle_t railHandle);
742
743 /**
744 * Configure Angle of Arrival/Departure (AoX) functionality. AoX is a method
745 * of radio localization which infers angle of arrival/departure of the signal
746 * based on different phases of the raw I/Q signal from different antennas by
747 * controlling external RF switch during the continuous tone extension (CTE).
748 * Connection based AoX packets are different than normal BLE packets in that
749 * they have 3 header bytes instead of 2 and they have CTE appended after the
750 * payload's CRC. 3rd byte or CTE info contains CTE length. Connectionless AoX
751 * packets have 2 header bytes and CTE info is part of the payload. AoX is
752 * supported on EFR32XG12/13/14 only on legacy 1Mbps BLE PHY.
753 * Note that calling \ref RAIL_GetRadioEntropy during AoX reception may break
754 * receiving packets.
755 *
756 * @param[in] railHandle A RAIL instance handle.
757 * @param[in] aoxConfig Configuration options for AoX
758 * @return RAIL_Status_t indicating success or failure of the call.
759 */
760 RAIL_Status_t RAIL_BLE_ConfigAox(RAIL_Handle_t railHandle,
761 const RAIL_BLE_AoxConfig_t *aoxConfig);
762 /**
763 * Perform one time initialization of AoX registers.
764 * This function must be called before \ref RAIL_BLE_ConfigAox
765 * and before configuring the BLE PHY.
766 *
767 * @param[in] railHandle A RAIL instance handle.
768 * @return RAIL_Status_t indicating success or failure of the call.
769 */
770 RAIL_Status_t RAIL_BLE_InitCte(RAIL_Handle_t railHandle);
771
772 /**
773 * Perform initialization of AoX antenna GPIO pins.
774 * This function must be called before calls to \ref RAIL_BLE_InitCte
775 * and \ref RAIL_BLE_ConfigAox, and before configuring the BLE PHY,
776 * else a \ref RAIL_STATUS_INVALID_CALL is returned.
777 *
778 * If user configures more pins, i.e., antCount in
779 * \ref RAIL_BLE_AoxAntennaConfig_t, than allowed
780 * \ref RAIL_BLE_AOX_ANTENNA_PIN_COUNT, then the API returns
781 * \ref RAIL_STATUS_INVALID_PARAMETER.
782 *
783 * If user configures lesser than or equal to number of pins allowed by
784 * \ref RAIL_BLE_AOX_ANTENNA_PIN_COUNT, then the requested number of pins
785 * are configured and \ref RAIL_STATUS_NO_ERROR is returned.
786 *
787 * If AoX antenna switching is inactive, non-AoX transmits and receives
788 * will occur on the first antenna specified by the antenna pattern or
789 * on the default antenna if no antenna pattern is provided.
790 *
791 * @param[in] railHandle A RAIL instance handle.
792 * @param[in] antennaConfig structure to hold the set of ports and pins to
793 * configure Antenna pins for AoX Antenna switching.
794 * @return RAIL_Status_t indicating success or failure of the call.
795 */
796 RAIL_Status_t RAIL_BLE_ConfigAoxAntenna(RAIL_Handle_t railHandle,
797 RAIL_BLE_AoxAntennaConfig_t *antennaConfig);
798
799 /** @} */ // end of group AoX
800
801 /// @addtogroup BLETX2TX BLE TX Channel Hopping
802 /// @{
803 /// @code{.c}
804 ///
805 /// // Configuration to send one additional packet
806 /// static RAIL_BLE_TxChannelHoppingConfigEntry_t entry[1];
807 /// static uint32_t buffer[BUFFER_SIZE];
808 /// static RAIL_BLE_TxRepeatConfig_t repeat = {
809 /// .iterations = 1,
810 /// .repeatOptions = RAIL_TX_REPEAT_OPTION_HOP,
811 /// .delayOrHop.channelHopping = {
812 /// .buffer = buffer,
813 /// .bufferLength = BUFFER_SIZE,
814 /// .numberOfChannels = 1,
815 /// .entries = &entry[0],
816 /// },
817 /// };
818 ///
819 /// // Send a normal packet on the current channel, then a packet on a new channel
820 /// int bleSendThenAdvertise(uint8_t *firstPacket, uint8_t *secondPacket)
821 /// {
822 /// // Load both packets into the FIFO
823 /// RAIL_WriteTxFifo(railHandle, firstPacket, FIRST_PACKET_LEN, true);
824 /// RAIL_WriteTxFifo(railHandle, secondPacket, SECOND_PACKET_LEN, false);
825 ///
826 /// // Configure a 300 us turnaround between transmits
827 /// entry[0].delayMode = RAIL_CHANNEL_HOPPING_DELAY_MODE_STATIC;
828 /// entry[0].delay = 300; // microseconds
829 ///
830 /// // Use default advertising parameters
831 /// entry[0].disableWhitening = false;
832 /// entry[0].crcInit = 0x00555555;
833 /// entry[0].accessAddress = 0x8E89BED6;
834 ///
835 /// // Transmit the repeated packet on the first advertising channel
836 /// entry[0].phy = RAIL_BLE_1Mbps;
837 /// entry[0].railChannel = 0;
838 /// entry[0].logicalChannel = 37;
839 ///
840 /// // Configure repeated transmit in RAIL, then transmit, sending both packets
841 /// RAIL_BLE_SetNextTxRepeat(railHandle, &repeat);
842 /// RAIL_StartTx(railHandle, currentChannel, RAIL_TX_OPTIONS_DEFAULT, NULL);
843 /// }
844 /// @endcode
845
846 /**
847 * @struct RAIL_BLE_TxChannelHoppingConfigEntry_t
848 * @brief Structure that represents one of the channels that is part of a
849 * \ref RAIL_BLE_TxChannelHoppingConfig_t sequence of channels used in
850 * channel hopping.
851 */
852 typedef struct RAIL_BLE_TxChannelHoppingConfigEntry {
853 /**
854 * Idle time in microseconds to wait before hopping into the
855 * channel indicated by this entry.
856 */
857 uint32_t delay;
858 /**
859 * The BLE PHY to use for this hop's transmit.
860 */
861 RAIL_BLE_Phy_t phy;
862 /**
863 * The logical channel to use for this hop's transmit. The whitener will
864 * be reinitialized if used.
865 */
866 uint8_t logicalChannel;
867 /**
868 * The channel number to be used for this hop's transmit. If this is an
869 * invalid channel for the chosen PHY, the call to \ref RAIL_SetNextTxRepeat()
870 * will fail.
871 */
872 uint8_t railChannel;
873 /**
874 * This can turn off the whitening engine and is useful for sending BLE test
875 * mode packets that don't have this turned on.
876 */
877 bool disableWhitening;
878 /**
879 * The value to use for CRC initialization.
880 */
881 uint32_t crcInit;
882 /**
883 * The access address to use for the connection.
884 */
885 uint32_t accessAddress;
886 } RAIL_BLE_TxChannelHoppingConfigEntry_t;
887
888 /**
889 * @struct RAIL_BLE_TxChannelHoppingConfig_t
890 * @brief Wrapper struct that will contain the sequence of
891 * \ref RAIL_BLE_TxChannelHoppingConfigEntry_t that represents the channel
892 * sequence to use during TX Channel Hopping.
893 */
894 typedef struct RAIL_BLE_TxChannelHoppingConfig {
895 /**
896 * Pointer to contiguous global read-write memory that will be used
897 * by RAIL to store channel hopping information throughout its operation.
898 * It need not be initialized and applications should never write
899 * data anywhere in this buffer.
900 */
901 uint32_t *buffer;
902 /**
903 * This parameter must be set to the length of the buffer array. This way,
904 * during configuration, the software can confirm it's writing within the
905 * range of the buffer. The configuration API will return an error
906 * if bufferLength is insufficient.
907 */
908 uint16_t bufferLength;
909 /** The number of channels that is in the channel hopping sequence. */
910 uint8_t numberOfChannels;
911 /**
912 * Pad bytes reserved for future use and currently ignored.
913 */
914 uint8_t reserved;
915 /**
916 * A pointer to the first element of an array of \ref
917 * RAIL_BLE_TxChannelHoppingConfigEntry_t that represents the channels
918 * used during channel hopping. The length of this array must be
919 * numberOfChannels.
920 */
921 RAIL_BLE_TxChannelHoppingConfigEntry_t *entries;
922 } RAIL_BLE_TxChannelHoppingConfig_t;
923
924 /// @struct RAIL_BLE_TxRepeatConfig_t
925 /// @brief A configuration structure for repeated transmits
926 ///
927 typedef struct RAIL_BLE_TxRepeatConfig {
928 /**
929 * The number of repeated transmits to run. A total of (iterations + 1)
930 * transmits will go on-air in the absence of errors.
931 */
932 uint16_t iterations;
933 /**
934 * Repeat option(s) to apply.
935 */
936 RAIL_TxRepeatOptions_t repeatOptions;
937 /**
938 * Per-repeat delay or hopping configuration, depending on repeatOptions.
939 */
940 union {
941 /**
942 * When \ref RAIL_TX_REPEAT_OPTION_HOP is not set, this specifies
943 * the delay time between each repeated transmit. Specify \ref
944 * RAIL_TRANSITION_TIME_KEEP to use the current \ref
945 * RAIL_StateTiming_t::txToTx transition time setting.
946 */
947 RAIL_TransitionTime_t delay;
948 /**
949 * When \ref RAIL_TX_REPEAT_OPTION_HOP is set, this specifies
950 * the channel hopping configuration to use when hopping between
951 * repeated transmits. Per-hop delays are configured within each
952 * \ref RAIL_BLE_TxChannelHoppingConfigEntry_t::delay rather than
953 * this union's delay field.
954 */
955 RAIL_BLE_TxChannelHoppingConfig_t channelHopping;
956 } delayOrHop;
957 } RAIL_BLE_TxRepeatConfig_t;
958
959 /**
960 * Set up automatic repeated transmits after the next transmit.
961 *
962 * @param[in] railHandle A RAIL instance handle.
963 * @param[in] repeatConfig The configuration structure for repeated transmits.
964 * @return Status code indicating a success of the function call.
965 *
966 * Repeated transmits will occur after an application-initiated transmit caused
967 * by calling one of the \ref Packet_TX APIs. The repetition will only occur
968 * after the first application-initiated transmit after this function is
969 * called. Future repeated transmits must be requested by calling this function
970 * again.
971 *
972 * Each repeated transmit that occurs will have full \ref PTI information and
973 * will receive events such as \ref RAIL_EVENT_TX_PACKET_SENT as normal.
974 *
975 * If a TX error occurs during the repetition, the process will abort and the
976 * TX error transition from \ref RAIL_SetTxTransitions will be used. If the
977 * repetition completes successfully, the TX success transition from
978 * \ref RAIL_SetTxTransitions will be used.
979 *
980 * Any call to \ref RAIL_Idle or \ref RAIL_StopTx will clear the pending
981 * repeated transmits. The state will also be cleared by another call to this
982 * function. To clear the repeated transmits before they've started without
983 * stopping other radio actions, call this function with a \ref
984 * RAIL_BLE_TxRepeatConfig_t::iterations count of 0. A DMP switch will clear this
985 * state only if the initial transmit triggering the repeated transmits has
986 * started.
987 *
988 * The application is responsible for populating the transmit data to be used
989 * by the repeated transmits via \ref RAIL_SetTxFifo or \ref RAIL_WriteTxFifo.
990 * Data will be transmitted from the TX FIFO. If the TX FIFO does not have
991 * sufficient data to transmit, a TX error and a \ref
992 * RAIL_EVENT_TX_UNDERFLOW will occur. To avoid an underflow, the
993 * application should queue data to be transmitted as early as possible.
994 *
995 * This function will fail to configure the repetition if a transmit of any
996 * kind is ongoing, including during the time between an initial transmit and
997 * the end of a previously-configured repetition.
998 *
999 * @note This feature/API is not supported on the EFR32XG1 family of chips.
1000 * Use the compile time symbol \ref RAIL_SUPPORTS_TX_TO_TX or the runtime
1001 * call \ref RAIL_SupportsTxToTx() to check whether the platform supports
1002 * this feature.
1003 */
1004 RAIL_Status_t RAIL_BLE_SetNextTxRepeat(RAIL_Handle_t railHandle,
1005 const RAIL_BLE_TxRepeatConfig_t *repeatConfig);
1006
1007 /** @} */ // end of group BLETX2TX
1008
1009 /** @} */ // end of BLE
1010
1011 #ifdef __cplusplus
1012 }
1013 #endif
1014
1015 #endif // __RAIL_BLE_H__
1016
