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