The official Mbed 2 C/C++ SDK provides the software platform and libraries to build your applications.

Dependents:   hello SerialTestv11 SerialTestv12 Sierpinski ... more

mbed 2

This is the mbed 2 library. If you'd like to learn about Mbed OS please see the mbed-os docs.

Committer:
AnnaBridge
Date:
Thu Nov 08 11:45:42 2018 +0000
Revision:
171:3a7713b1edbc
Parent:
TARGET_TB_SENSE_1/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/ble/rail_ble.h@167:84c0a372a020
mbed library. Release version 164

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Anna Bridge 160:5571c4ff569f 1 /***************************************************************************//**
Anna Bridge 160:5571c4ff569f 2 * @file rail_ble.h
Anna Bridge 160:5571c4ff569f 3 * @brief The BLE specific header file for the RAIL library.
AnnaBridge 167:84c0a372a020 4 * @copyright Copyright 2016 Silicon Laboratories, Inc. www.silabs.com
Anna Bridge 160:5571c4ff569f 5 ******************************************************************************/
Anna Bridge 160:5571c4ff569f 6
Anna Bridge 160:5571c4ff569f 7 #ifndef __RAIL_BLE_H__
Anna Bridge 160:5571c4ff569f 8 #define __RAIL_BLE_H__
Anna Bridge 160:5571c4ff569f 9
Anna Bridge 160:5571c4ff569f 10 // Get the standard include types
Anna Bridge 160:5571c4ff569f 11 #include <stdint.h>
Anna Bridge 160:5571c4ff569f 12 #include <stdbool.h>
Anna Bridge 160:5571c4ff569f 13
Anna Bridge 160:5571c4ff569f 14 // Get the RAIL specific structures and types
Anna Bridge 160:5571c4ff569f 15 #include "rail_types.h"
Anna Bridge 160:5571c4ff569f 16
AnnaBridge 167:84c0a372a020 17 #ifdef __cplusplus
AnnaBridge 167:84c0a372a020 18 extern "C" {
AnnaBridge 167:84c0a372a020 19 #endif
AnnaBridge 167:84c0a372a020 20
AnnaBridge 167:84c0a372a020 21 /// @addtogroup BLE
AnnaBridge 167:84c0a372a020 22 /// @ingroup Protocol_Specific
AnnaBridge 167:84c0a372a020 23 /// Accelerator routines for Bluetooth Low Energy (BLE).
AnnaBridge 167:84c0a372a020 24 ///
AnnaBridge 167:84c0a372a020 25 /// The APIs in this module help take care of configuring the radio for BLE
AnnaBridge 167:84c0a372a020 26 /// operation and provide some additional helper routines necessary for
AnnaBridge 167:84c0a372a020 27 /// normal BLE send/receive that aren't available directly in RAIL. All normal
AnnaBridge 167:84c0a372a020 28 /// RAIL APIs should be used to setup the application; however,
AnnaBridge 167:84c0a372a020 29 /// RAIL_ConfigChannels() and RAIL_ConfigRadio() should not be called to setup
AnnaBridge 167:84c0a372a020 30 /// the PHY. Instead, the RAIL_BLE_Config* APIs should be used to setup the
AnnaBridge 167:84c0a372a020 31 /// 1Mbps, 2Mbps, or Coded PHY configuration needed by the application. These
AnnaBridge 167:84c0a372a020 32 /// APIs will configure the hardware and also configure the set of valid BLE
AnnaBridge 167:84c0a372a020 33 /// channels.
AnnaBridge 167:84c0a372a020 34 ///
AnnaBridge 167:84c0a372a020 35 /// To implement a standard BLE link layer you will also need to handle tight
AnnaBridge 167:84c0a372a020 36 /// turnaround times and send packets at specific instants. This can all be
AnnaBridge 167:84c0a372a020 37 /// managed through general RAIL functions like RAIL_ScheduleTx(),
AnnaBridge 167:84c0a372a020 38 /// RAIL_ScheduleRx(), and RAIL_SetStateTiming(). See the full RAIL API for more
AnnaBridge 167:84c0a372a020 39 /// useful functions.
AnnaBridge 167:84c0a372a020 40 ///
AnnaBridge 167:84c0a372a020 41 /// A simple example of how to setup your application to be in BLE mode is shown
AnnaBridge 167:84c0a372a020 42 /// below. Note that this will put the radio on the first advertising channel
AnnaBridge 167:84c0a372a020 43 /// with the advertising Access Address. In any full featured BLE application you
AnnaBridge 167:84c0a372a020 44 /// will need to use the RAIL_BLE_ConfigChannelRadioParams() function to change
AnnaBridge 167:84c0a372a020 45 /// the sync word and other parameters as needed based on your connection.
AnnaBridge 167:84c0a372a020 46 ///
AnnaBridge 167:84c0a372a020 47 /// @code{.c}
AnnaBridge 167:84c0a372a020 48 ///
AnnaBridge 167:84c0a372a020 49 /// // RAIL Handle set at init time
AnnaBridge 167:84c0a372a020 50 /// static RAIL_Handle_t railHandle = NULL;
AnnaBridge 167:84c0a372a020 51 ///
AnnaBridge 167:84c0a372a020 52 /// // Put the radio into receive on the first BLE advertising channel
AnnaBridge 167:84c0a372a020 53 /// int bleAdvertiseEnable(void)
AnnaBridge 167:84c0a372a020 54 /// {
AnnaBridge 167:84c0a372a020 55 /// // Call the BLE initialization function to load the right radio config
AnnaBridge 167:84c0a372a020 56 /// RAIL_BLE_Init(railHandle);
AnnaBridge 167:84c0a372a020 57 ///
AnnaBridge 167:84c0a372a020 58 /// // Always choose the Viterbi PHY configuration if available on your chip
AnnaBridge 167:84c0a372a020 59 /// // for performance reasons.
AnnaBridge 167:84c0a372a020 60 /// RAIL_BLE_ConfigPhy1MbpsViterbi(railHandle);
AnnaBridge 167:84c0a372a020 61 ///
AnnaBridge 167:84c0a372a020 62 /// // Configure us for the first advertising channel (Physical: 0, Logical: 37)
AnnaBridge 167:84c0a372a020 63 /// // The CRC init value and Access Address come from the BLE specification.
AnnaBridge 167:84c0a372a020 64 /// RAIL_BLE_ConfigChannelRadioParams(railHandle,
AnnaBridge 167:84c0a372a020 65 /// 0x555555,
AnnaBridge 167:84c0a372a020 66 /// 0x8E89BED6,
AnnaBridge 167:84c0a372a020 67 /// 37,
AnnaBridge 167:84c0a372a020 68 /// false);
AnnaBridge 167:84c0a372a020 69 ///
AnnaBridge 167:84c0a372a020 70 /// // Start receiving on physical channel 0 (logical channel 37)
AnnaBridge 167:84c0a372a020 71 /// RAIL_StartRx(railHandle, 0, NULL);
AnnaBridge 167:84c0a372a020 72 /// }
AnnaBridge 167:84c0a372a020 73 /// @endcode
AnnaBridge 167:84c0a372a020 74 ///
AnnaBridge 167:84c0a372a020 75 /// @{
Anna Bridge 160:5571c4ff569f 76
Anna Bridge 160:5571c4ff569f 77 /**
Anna Bridge 160:5571c4ff569f 78 * @enum RAIL_BLE_Coding_t
Anna Bridge 160:5571c4ff569f 79 * @brief The variant of the BLE Coded PHY
Anna Bridge 160:5571c4ff569f 80 */
Anna Bridge 160:5571c4ff569f 81 RAIL_ENUM(RAIL_BLE_Coding_t) {
Anna Bridge 160:5571c4ff569f 82 RAIL_BLE_Coding_125kbps = 0,
Anna Bridge 160:5571c4ff569f 83 RAIL_BLE_Coding_125kbps_DSA = 1,
Anna Bridge 160:5571c4ff569f 84 RAIL_BLE_Coding_500kbps = 2,
Anna Bridge 160:5571c4ff569f 85 RAIL_BLE_Coding_500kbps_DSA = 3,
Anna Bridge 160:5571c4ff569f 86 };
Anna Bridge 160:5571c4ff569f 87
Anna Bridge 160:5571c4ff569f 88 /**
Anna Bridge 160:5571c4ff569f 89 * @struct RAIL_BLE_State_t
Anna Bridge 160:5571c4ff569f 90 * @brief State structure for BLE.
Anna Bridge 160:5571c4ff569f 91 *
Anna Bridge 160:5571c4ff569f 92 * This structure must be allocated in application global read-write memory
Anna Bridge 160:5571c4ff569f 93 * that persists for the duration of BLE usage. It cannot be allocated
Anna Bridge 160:5571c4ff569f 94 * in read-only memory or on the call stack.
Anna Bridge 160:5571c4ff569f 95 */
Anna Bridge 160:5571c4ff569f 96 typedef struct RAIL_BLE_State {
Anna Bridge 160:5571c4ff569f 97 uint32_t crcInit; /**< The value used for CRC initialization. */
Anna Bridge 160:5571c4ff569f 98 uint32_t accessAddress; /**< The access address used for the connection. */
Anna Bridge 160:5571c4ff569f 99 uint16_t channel; /**< The logical channel used. */
Anna Bridge 160:5571c4ff569f 100 bool disableWhitening; /**< Whether the whitening engine should be off. */
Anna Bridge 160:5571c4ff569f 101 } RAIL_BLE_State_t;
Anna Bridge 160:5571c4ff569f 102
Anna Bridge 160:5571c4ff569f 103 /**
Anna Bridge 160:5571c4ff569f 104 * Configure RAIL to run in BLE mode.
Anna Bridge 160:5571c4ff569f 105 *
Anna Bridge 160:5571c4ff569f 106 * @param[in] railHandle Handle for RAIL instance.
Anna Bridge 160:5571c4ff569f 107 * This function will change your radio and channel configuration and other
Anna Bridge 160:5571c4ff569f 108 * parameters to match what is needed for BLE. If you need to switch back to a
Anna Bridge 160:5571c4ff569f 109 * default RAIL mode then you must call RAIL_BLE_Deinit() first. This function
Anna Bridge 160:5571c4ff569f 110 * will configure the protocol output on PTI to \ref RAIL_PTI_PROTOCOL_BLE.
Anna Bridge 160:5571c4ff569f 111 */
Anna Bridge 160:5571c4ff569f 112 void RAIL_BLE_Init(RAIL_Handle_t railHandle);
Anna Bridge 160:5571c4ff569f 113
Anna Bridge 160:5571c4ff569f 114 /**
Anna Bridge 160:5571c4ff569f 115 * Take RAIL out of BLE mode.
Anna Bridge 160:5571c4ff569f 116 *
Anna Bridge 160:5571c4ff569f 117 * @param[in] railHandle Handle for RAIL instance.
Anna Bridge 160:5571c4ff569f 118 * This function will undo some of the configuration that happens when you call
Anna Bridge 160:5571c4ff569f 119 * RAIL_BLE_Init(). After this you can safely run your normal radio
Anna Bridge 160:5571c4ff569f 120 * initialization code to use a non-BLE configuration. This function will \b
Anna Bridge 160:5571c4ff569f 121 * not change back your radio or channel configurations so you must do this by
Anna Bridge 160:5571c4ff569f 122 * manually reinitializing. This also resets the protocol output on PTI to \ref
Anna Bridge 160:5571c4ff569f 123 * RAIL_PTI_PROTOCOL_CUSTOM.
Anna Bridge 160:5571c4ff569f 124 */
Anna Bridge 160:5571c4ff569f 125 void RAIL_BLE_Deinit(RAIL_Handle_t railHandle);
Anna Bridge 160:5571c4ff569f 126
Anna Bridge 160:5571c4ff569f 127 /**
Anna Bridge 160:5571c4ff569f 128 * Determine whether BLE mode is enabled or not.
Anna Bridge 160:5571c4ff569f 129 *
Anna Bridge 160:5571c4ff569f 130 * @param[in] railHandle Handle for RAIL instance.
Anna Bridge 160:5571c4ff569f 131 * @return True if BLE mode is enabled and false otherwise.
Anna Bridge 160:5571c4ff569f 132 * This function returns the current status of RAIL's BLE mode. It is enabled by
Anna Bridge 160:5571c4ff569f 133 * a call to RAIL_BLE_Init() and disabled by a call to RAIL_BLE_Deinit().
Anna Bridge 160:5571c4ff569f 134 */
Anna Bridge 160:5571c4ff569f 135 bool RAIL_BLE_IsEnabled(RAIL_Handle_t railHandle);
Anna Bridge 160:5571c4ff569f 136
Anna Bridge 160:5571c4ff569f 137 /**
Anna Bridge 160:5571c4ff569f 138 * Switch the Viterbi 1Mbps BLE PHY.
Anna Bridge 160:5571c4ff569f 139 *
Anna Bridge 160:5571c4ff569f 140 * @param[in] railHandle Handle for RAIL instance.
Anna Bridge 160:5571c4ff569f 141 * @return Status code indicating success of the function call.
Anna Bridge 160:5571c4ff569f 142 *
Anna Bridge 160:5571c4ff569f 143 * You can use this function to switch back to the defualt BLE 1Mbps PHY if you
Anna Bridge 160:5571c4ff569f 144 * have switched to the 2Mbps or another configuration. You may only call this
Anna Bridge 160:5571c4ff569f 145 * function after initializing BLE and while the radio is idle.
Anna Bridge 160:5571c4ff569f 146 */
Anna Bridge 160:5571c4ff569f 147 RAIL_Status_t RAIL_BLE_ConfigPhy1MbpsViterbi(RAIL_Handle_t railHandle);
Anna Bridge 160:5571c4ff569f 148
Anna Bridge 160:5571c4ff569f 149 /**
Anna Bridge 160:5571c4ff569f 150 * Switch the legacy non-Viterbi 1Mbps BLE PHY.
Anna Bridge 160:5571c4ff569f 151 *
Anna Bridge 160:5571c4ff569f 152 * @param[in] railHandle Handle for RAIL instance.
Anna Bridge 160:5571c4ff569f 153 * @return Status code indicating success of the function call.
Anna Bridge 160:5571c4ff569f 154 *
Anna Bridge 160:5571c4ff569f 155 * You can use this function to switch back to the legacy BLE 1Mbps PHY if you
Anna Bridge 160:5571c4ff569f 156 * have switched to the 2Mbps or another configuration. You may only call this
Anna Bridge 160:5571c4ff569f 157 * function after initializing BLE and while the radio is idle.
Anna Bridge 160:5571c4ff569f 158 */
Anna Bridge 160:5571c4ff569f 159 RAIL_Status_t RAIL_BLE_ConfigPhy1Mbps(RAIL_Handle_t railHandle);
Anna Bridge 160:5571c4ff569f 160
Anna Bridge 160:5571c4ff569f 161 /**
Anna Bridge 160:5571c4ff569f 162 * Switch the Viterbi 2Mbps BLE PHY.
Anna Bridge 160:5571c4ff569f 163 *
Anna Bridge 160:5571c4ff569f 164 * @param[in] railHandle Handle for RAIL instance.
Anna Bridge 160:5571c4ff569f 165 * @return Status code indicating success of the function call.
Anna Bridge 160:5571c4ff569f 166 *
Anna Bridge 160:5571c4ff569f 167 * You can use this function to switch back to the BLE 2Mbps PHY from the
Anna Bridge 160:5571c4ff569f 168 * default 1Mbps option. You may only call this function after initializing BLE
Anna Bridge 160:5571c4ff569f 169 * and while the radio is idle.
Anna Bridge 160:5571c4ff569f 170 *
Anna Bridge 160:5571c4ff569f 171 * @note Not all chips support the 2Mbps PHY. Consult your part's reference
Anna Bridge 160:5571c4ff569f 172 * manual to be sure that it does before trying this.
Anna Bridge 160:5571c4ff569f 173 */
Anna Bridge 160:5571c4ff569f 174 RAIL_Status_t RAIL_BLE_ConfigPhy2MbpsViterbi(RAIL_Handle_t railHandle);
Anna Bridge 160:5571c4ff569f 175
Anna Bridge 160:5571c4ff569f 176 /**
Anna Bridge 160:5571c4ff569f 177 * Switch the legacy non-Viterbi 2Mbps BLE PHY.
Anna Bridge 160:5571c4ff569f 178 *
Anna Bridge 160:5571c4ff569f 179 * @param[in] railHandle Handle for RAIL instance.
Anna Bridge 160:5571c4ff569f 180 * @return Status code indicating success of the function call.
Anna Bridge 160:5571c4ff569f 181 *
Anna Bridge 160:5571c4ff569f 182 * You can use this function to switch back to legacy BLE 2Mbps PHY from the
Anna Bridge 160:5571c4ff569f 183 * default 1Mbps option. You may only call this function after initializing BLE
Anna Bridge 160:5571c4ff569f 184 * and while the radio is idle.
Anna Bridge 160:5571c4ff569f 185 *
Anna Bridge 160:5571c4ff569f 186 * @note Not all chips support the 2Mbps PHY. Consult your part's reference
Anna Bridge 160:5571c4ff569f 187 * manual to be sure that it does before trying this.
Anna Bridge 160:5571c4ff569f 188 */
Anna Bridge 160:5571c4ff569f 189 RAIL_Status_t RAIL_BLE_ConfigPhy2Mbps(RAIL_Handle_t railHandle);
Anna Bridge 160:5571c4ff569f 190
Anna Bridge 160:5571c4ff569f 191 /**
Anna Bridge 160:5571c4ff569f 192 * Switch to the BLE Coded PHY.
Anna Bridge 160:5571c4ff569f 193 *
Anna Bridge 160:5571c4ff569f 194 * @param[in] railHandle Handle for RAIL instance.
AnnaBridge 167:84c0a372a020 195 * @param[in] bleCoding The RAIL_BLE_Coding_t to use
Anna Bridge 160:5571c4ff569f 196 * @return Status code indicating success of the function call.
Anna Bridge 160:5571c4ff569f 197 *
Anna Bridge 160:5571c4ff569f 198 * You can use this function to switch back to BLE Coded PHY from the default
Anna Bridge 160:5571c4ff569f 199 * 1Mbps option. You may only call this function after initializing BLE and
Anna Bridge 160:5571c4ff569f 200 * while the radio is idle. When using a BLE Coded PHY, the subPhy in
Anna Bridge 160:5571c4ff569f 201 * RAIL_AppendedInfo_t marks the coding of the received packet. A subPhy of 0
Anna Bridge 160:5571c4ff569f 202 * marks a 500kbps packet, and a subPhy of 1 marks a 125kbps packet.
Anna Bridge 160:5571c4ff569f 203 *
Anna Bridge 160:5571c4ff569f 204 * @note Not all chips support the BLE Coded PHY. Consult your part's reference
Anna Bridge 160:5571c4ff569f 205 * manual to be sure that it does before trying this.
Anna Bridge 160:5571c4ff569f 206 */
Anna Bridge 160:5571c4ff569f 207 RAIL_Status_t RAIL_BLE_ConfigPhyCoded(RAIL_Handle_t railHandle,
AnnaBridge 167:84c0a372a020 208 RAIL_BLE_Coding_t bleCoding);
Anna Bridge 160:5571c4ff569f 209
Anna Bridge 160:5571c4ff569f 210 /**
Anna Bridge 160:5571c4ff569f 211 * Helper function to change BLE radio parameters.
Anna Bridge 160:5571c4ff569f 212 *
Anna Bridge 160:5571c4ff569f 213 * @param[in] railHandle Handle for RAIL instance.
Anna Bridge 160:5571c4ff569f 214 * @param[in] crcInit The value to use for CRC initialization.
Anna Bridge 160:5571c4ff569f 215 * @param[in] accessAddress The access address to use for the connection.
Anna Bridge 160:5571c4ff569f 216 * @param[in] channel The logical channel that you're changing to. This is used to
Anna Bridge 160:5571c4ff569f 217 * initialize the whitener if you're using whitening.
Anna Bridge 160:5571c4ff569f 218 * @param[in] disableWhitening This can turn off the whitening engine and is useful
Anna Bridge 160:5571c4ff569f 219 * for sending BLE test mode packets that don't have this turned on.
Anna Bridge 160:5571c4ff569f 220 * @return Status code indicating success of the function call.
Anna Bridge 160:5571c4ff569f 221 *
Anna Bridge 160:5571c4ff569f 222 * This function can be used to switch radio parameters on every connection
Anna Bridge 160:5571c4ff569f 223 * and/or channel change. It is BLE-aware and will set the access address,
Anna Bridge 160:5571c4ff569f 224 * preamble, CRC initialization value, and whitening configuration without
Anna Bridge 160:5571c4ff569f 225 * requiring you to load a new radio config.
Anna Bridge 160:5571c4ff569f 226 */
Anna Bridge 160:5571c4ff569f 227 RAIL_Status_t RAIL_BLE_ConfigChannelRadioParams(RAIL_Handle_t railHandle,
Anna Bridge 160:5571c4ff569f 228 uint32_t crcInit,
Anna Bridge 160:5571c4ff569f 229 uint32_t accessAddress,
Anna Bridge 160:5571c4ff569f 230 uint16_t channel,
Anna Bridge 160:5571c4ff569f 231 bool disableWhitening);
Anna Bridge 160:5571c4ff569f 232
Anna Bridge 160:5571c4ff569f 233 /** @} */ // end of BLE
Anna Bridge 160:5571c4ff569f 234
AnnaBridge 167:84c0a372a020 235 #ifdef __cplusplus
AnnaBridge 167:84c0a372a020 236 }
AnnaBridge 167:84c0a372a020 237 #endif
AnnaBridge 167:84c0a372a020 238
Anna Bridge 160:5571c4ff569f 239 #endif // __RAIL_BLE_H__