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.
TARGET_TB_SENSE_12/TOOLCHAIN_IAR/rail_ble.h@172:65be27845400, 2019-02-20 (annotated)
- Committer:
- AnnaBridge
- Date:
- Wed Feb 20 20:53:29 2019 +0000
- Revision:
- 172:65be27845400
- Parent:
- 171:3a7713b1edbc
mbed library release version 165
Who changed what in which revision?
User | Revision | Line number | New 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__ |