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.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 |
142:4eea097334d6 | 2 | * @file rail.h |
Anna Bridge |
142:4eea097334d6 | 3 | * @brief The main header file for the RAIL library. It describes the external |
Anna Bridge |
142:4eea097334d6 | 4 | * APIs available to a RAIL user |
AnnaBridge | 167:84c0a372a020 | 5 | * @copyright Copyright 2015 Silicon Laboratories, Inc. www.silabs.com |
Anna Bridge |
160:5571c4ff569f | 6 | *****************************************************************************/ |
Anna Bridge |
142:4eea097334d6 | 7 | |
Anna Bridge |
142:4eea097334d6 | 8 | #ifndef __RAIL_H__ |
Anna Bridge |
142:4eea097334d6 | 9 | #define __RAIL_H__ |
Anna Bridge |
142:4eea097334d6 | 10 | |
Anna Bridge |
142:4eea097334d6 | 11 | // Get the standard include types |
Anna Bridge |
142:4eea097334d6 | 12 | #include <stdint.h> |
Anna Bridge |
142:4eea097334d6 | 13 | #include <stdbool.h> |
AnnaBridge | 167:84c0a372a020 | 14 | #include <string.h> // For memcpy() |
Anna Bridge |
142:4eea097334d6 | 15 | |
Anna Bridge |
160:5571c4ff569f | 16 | // Get the RAIL-specific structures and types |
Anna Bridge |
160:5571c4ff569f | 17 | #include "rail_chip_specific.h" |
Anna Bridge |
142:4eea097334d6 | 18 | #include "rail_types.h" |
AnnaBridge | 167:84c0a372a020 | 19 | #include "rail_assert_error_codes.h" |
AnnaBridge | 167:84c0a372a020 | 20 | |
AnnaBridge | 167:84c0a372a020 | 21 | #ifdef __cplusplus |
AnnaBridge | 167:84c0a372a020 | 22 | extern "C" { |
AnnaBridge | 167:84c0a372a020 | 23 | #endif |
Anna Bridge |
142:4eea097334d6 | 24 | |
Anna Bridge |
142:4eea097334d6 | 25 | /** |
Anna Bridge |
160:5571c4ff569f | 26 | * @addtogroup RAIL_API RAIL API |
Anna Bridge |
142:4eea097334d6 | 27 | * @brief This is the primary API layer for the Radio Abstraction Interface |
Anna Bridge |
160:5571c4ff569f | 28 | * Layer (RAIL) |
Anna Bridge |
142:4eea097334d6 | 29 | * @{ |
Anna Bridge |
142:4eea097334d6 | 30 | */ |
Anna Bridge |
142:4eea097334d6 | 31 | |
Anna Bridge |
160:5571c4ff569f | 32 | /** |
Anna Bridge |
160:5571c4ff569f | 33 | * @defgroup Protocol_Specific Protocol Specific |
Anna Bridge |
160:5571c4ff569f | 34 | * @brief Protocol specific RAIL APIs |
Anna Bridge |
160:5571c4ff569f | 35 | */ |
Anna Bridge |
160:5571c4ff569f | 36 | |
Anna Bridge |
142:4eea097334d6 | 37 | /****************************************************************************** |
Anna Bridge |
142:4eea097334d6 | 38 | * General Radio Operation |
Anna Bridge |
142:4eea097334d6 | 39 | *****************************************************************************/ |
Anna Bridge |
142:4eea097334d6 | 40 | /** |
Anna Bridge |
142:4eea097334d6 | 41 | * @addtogroup General |
Anna Bridge |
160:5571c4ff569f | 42 | * @brief Basic APIs to set up and interact with the RAIL library |
Anna Bridge |
160:5571c4ff569f | 43 | * @{ |
Anna Bridge |
160:5571c4ff569f | 44 | */ |
Anna Bridge |
160:5571c4ff569f | 45 | |
Anna Bridge |
160:5571c4ff569f | 46 | /** |
Anna Bridge |
160:5571c4ff569f | 47 | * Gets the version information for the compiled RAIL library. |
Anna Bridge |
160:5571c4ff569f | 48 | * |
Anna Bridge |
160:5571c4ff569f | 49 | * @param[out] version A pointer to \ref RAIL_Version_t structure to |
Anna Bridge |
160:5571c4ff569f | 50 | * populate with version information. |
Anna Bridge |
160:5571c4ff569f | 51 | * @param[in] verbose Populate \ref RAIL_Version_t struct with verbose |
Anna Bridge |
160:5571c4ff569f | 52 | * information. |
Anna Bridge |
160:5571c4ff569f | 53 | * @return void. |
Anna Bridge |
160:5571c4ff569f | 54 | * |
Anna Bridge |
160:5571c4ff569f | 55 | * The version information contains a major version number, a minor version |
Anna Bridge |
160:5571c4ff569f | 56 | * number, and a rev (revision) number. |
Anna Bridge |
160:5571c4ff569f | 57 | */ |
Anna Bridge |
160:5571c4ff569f | 58 | void RAIL_GetVersion(RAIL_Version_t *version, bool verbose); |
Anna Bridge |
160:5571c4ff569f | 59 | |
Anna Bridge |
160:5571c4ff569f | 60 | /** |
Anna Bridge |
160:5571c4ff569f | 61 | * Initializes RAIL. |
Anna Bridge |
160:5571c4ff569f | 62 | * |
Anna Bridge |
160:5571c4ff569f | 63 | * @param[in,out] railCfg The configuration and state structure for setting up |
Anna Bridge |
160:5571c4ff569f | 64 | * the library, which contains memory and other options needed by RAIL. |
Anna Bridge |
160:5571c4ff569f | 65 | * This structure must be allocated in application global read-write |
Anna Bridge |
160:5571c4ff569f | 66 | * memory. RAIL may modify fields within or referenced by this structure |
Anna Bridge |
160:5571c4ff569f | 67 | * during its operation. |
Anna Bridge |
160:5571c4ff569f | 68 | * @param[in] cb A callback that notifies the application when the radio is |
Anna Bridge |
160:5571c4ff569f | 69 | * finished initializing and is ready for further configuration. This |
Anna Bridge |
160:5571c4ff569f | 70 | * callback is useful for potential transceiver products that require a |
Anna Bridge |
160:5571c4ff569f | 71 | * power up sequence before further configuration is available. After the |
Anna Bridge |
160:5571c4ff569f | 72 | * callback fires, the radio is ready for additional configuration before |
Anna Bridge |
160:5571c4ff569f | 73 | * transmit and receive operations. |
Anna Bridge |
160:5571c4ff569f | 74 | * @return Handle for initialized rail instance or NULL if an |
Anna Bridge |
160:5571c4ff569f | 75 | * invalid value was passed in the railCfg. |
Anna Bridge |
160:5571c4ff569f | 76 | */ |
Anna Bridge |
160:5571c4ff569f | 77 | RAIL_Handle_t RAIL_Init(RAIL_Config_t *railCfg, |
Anna Bridge |
160:5571c4ff569f | 78 | RAIL_InitCompleteCallbackPtr_t cb); |
Anna Bridge |
160:5571c4ff569f | 79 | |
Anna Bridge |
160:5571c4ff569f | 80 | /** |
Anna Bridge |
160:5571c4ff569f | 81 | * Collects entropy from the radio if available. |
Anna Bridge |
160:5571c4ff569f | 82 | * |
Anna Bridge |
160:5571c4ff569f | 83 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 84 | * @param[out] buffer The buffer to write the collected entropy. |
Anna Bridge |
160:5571c4ff569f | 85 | * @param[in] bytes The number of bytes to fill in in the input buffer. |
Anna Bridge |
160:5571c4ff569f | 86 | * @return Returns the number of bytes of entropy collected. For |
Anna Bridge |
160:5571c4ff569f | 87 | * chips that don't support entropy collection, the function returns 0. |
Anna Bridge |
160:5571c4ff569f | 88 | * Values less than the requested amount may also be returned on platforms |
Anna Bridge |
160:5571c4ff569f | 89 | * that use entropy pools to collect random data periodically. |
Anna Bridge |
160:5571c4ff569f | 90 | * |
Anna Bridge |
160:5571c4ff569f | 91 | * Attempts to fill the provided buffer with the requested number of bytes of |
Anna Bridge |
160:5571c4ff569f | 92 | * entropy. If the requested number of bytes can't be provided, as many |
Anna Bridge |
160:5571c4ff569f | 93 | * bytes as possible will be filled and returned. For chips |
Anna Bridge |
160:5571c4ff569f | 94 | * that do not support this function, 0 bytes will always be returned. For |
Anna Bridge |
160:5571c4ff569f | 95 | * information about the specific mechanism for gathering entropy, see |
Anna Bridge |
160:5571c4ff569f | 96 | * documentation for the chip family. |
Anna Bridge |
160:5571c4ff569f | 97 | */ |
Anna Bridge |
160:5571c4ff569f | 98 | uint16_t RAIL_GetRadioEntropy(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 99 | uint8_t *buffer, |
Anna Bridge |
160:5571c4ff569f | 100 | uint16_t bytes); |
Anna Bridge |
160:5571c4ff569f | 101 | |
Anna Bridge |
160:5571c4ff569f | 102 | /** @} */ // end of group General |
Anna Bridge |
160:5571c4ff569f | 103 | |
Anna Bridge |
160:5571c4ff569f | 104 | /****************************************************************************** |
Anna Bridge |
160:5571c4ff569f | 105 | * PTI |
Anna Bridge |
160:5571c4ff569f | 106 | *****************************************************************************/ |
Anna Bridge |
160:5571c4ff569f | 107 | /** |
Anna Bridge |
160:5571c4ff569f | 108 | * @addtogroup PTI Packet Trace (PTI) |
Anna Bridge |
160:5571c4ff569f | 109 | * @brief Basic APIs to set up and interact with PTI settings |
Anna Bridge |
142:4eea097334d6 | 110 | * @{ |
Anna Bridge |
142:4eea097334d6 | 111 | */ |
Anna Bridge |
142:4eea097334d6 | 112 | |
Anna Bridge |
142:4eea097334d6 | 113 | /** |
Anna Bridge |
160:5571c4ff569f | 114 | * Configures PTI pin locations, serial protocols, and baud rates. |
Anna Bridge |
160:5571c4ff569f | 115 | * |
Anna Bridge |
160:5571c4ff569f | 116 | * @param[in] railHandle A RAIL instance handle (currently not used). |
AnnaBridge | 167:84c0a372a020 | 117 | * @param[in] ptiConfig A configuration structure applied to the |
Anna Bridge |
160:5571c4ff569f | 118 | * relevant PTI registers. |
Anna Bridge |
160:5571c4ff569f | 119 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 120 | * |
Anna Bridge |
160:5571c4ff569f | 121 | * This method must be called before RAIL_EnablePti() is called. |
Anna Bridge |
160:5571c4ff569f | 122 | * Although we do take a RAIL handle for potential future |
Anna Bridge |
160:5571c4ff569f | 123 | * expansion of this function, it is currently not used. That is, |
Anna Bridge |
160:5571c4ff569f | 124 | * there is only one PTI configuration that can be active on a |
Anna Bridge |
160:5571c4ff569f | 125 | * chip, regardless of the number of protocols (unless the application |
Anna Bridge |
160:5571c4ff569f | 126 | * takes responsibility to update the configuration upon a protocol switch), |
Anna Bridge |
160:5571c4ff569f | 127 | * and the configuration is not saved in your RAIL instance. For optimal |
Anna Bridge |
160:5571c4ff569f | 128 | * future compatibility, pass in a chip specific handle, such as |
Anna Bridge |
160:5571c4ff569f | 129 | * \ref RAIL_EFR32_HANDLE for now. |
Anna Bridge |
142:4eea097334d6 | 130 | */ |
Anna Bridge |
160:5571c4ff569f | 131 | RAIL_Status_t RAIL_ConfigPti(RAIL_Handle_t railHandle, |
AnnaBridge | 167:84c0a372a020 | 132 | const RAIL_PtiConfig_t *ptiConfig); |
Anna Bridge |
142:4eea097334d6 | 133 | |
Anna Bridge |
142:4eea097334d6 | 134 | /** |
Anna Bridge |
160:5571c4ff569f | 135 | * Gets the currently active PTI configuration. |
Anna Bridge |
160:5571c4ff569f | 136 | * |
Anna Bridge |
160:5571c4ff569f | 137 | * @param[in] railHandle A RAIL instance handle (currently not used). |
Anna Bridge |
160:5571c4ff569f | 138 | * @param[out] ptiConfig A configuration structure filled with the active |
Anna Bridge |
160:5571c4ff569f | 139 | * PTI configuration. |
Anna Bridge |
160:5571c4ff569f | 140 | * @return RAIL status indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 141 | * |
Anna Bridge |
160:5571c4ff569f | 142 | * Although most combinations of configurations can be set, it is safest |
Anna Bridge |
160:5571c4ff569f | 143 | * to call this method after configuration to confirm which values were |
Anna Bridge |
160:5571c4ff569f | 144 | * actually set. As in RAIL_ConfigPti, railHandle is not used. This function |
Anna Bridge |
160:5571c4ff569f | 145 | * will always return the single active PTI configuration regardless of the |
Anna Bridge |
160:5571c4ff569f | 146 | * active protocol. For optimal future compatibility, pass in a chip |
Anna Bridge |
160:5571c4ff569f | 147 | * specific handle, such as \ref RAIL_EFR32_HANDLE for now. |
Anna Bridge |
142:4eea097334d6 | 148 | */ |
Anna Bridge |
160:5571c4ff569f | 149 | RAIL_Status_t RAIL_GetPtiConfig(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 150 | RAIL_PtiConfig_t *ptiConfig); |
Anna Bridge |
142:4eea097334d6 | 151 | |
Anna Bridge |
142:4eea097334d6 | 152 | /** |
Anna Bridge |
160:5571c4ff569f | 153 | * Enables the PTI output of the packet data. |
Anna Bridge |
160:5571c4ff569f | 154 | * |
Anna Bridge |
160:5571c4ff569f | 155 | * @param[in] railHandle A RAIL instance handle (currently not used). |
Anna Bridge |
160:5571c4ff569f | 156 | * @param[in] enable PTI is enabled if true; disable if false. |
Anna Bridge |
160:5571c4ff569f | 157 | * @return RAIL status indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 158 | * |
Anna Bridge |
160:5571c4ff569f | 159 | * Similarly to how there is only one PTI configuration per chip, |
Anna Bridge |
160:5571c4ff569f | 160 | * PTI can only be enabled or disabled for all protocols. It cannot |
Anna Bridge |
160:5571c4ff569f | 161 | * be individually set to enabled and disabled per protocol |
Anna Bridge |
160:5571c4ff569f | 162 | * (unless the application takes the responsibility of switching it when |
Anna Bridge |
160:5571c4ff569f | 163 | * the protocol switches), and enable/disable is not saved as part of your |
Anna Bridge |
160:5571c4ff569f | 164 | * RAIL instance. For optimal future compatibility, pass in a chip |
Anna Bridge |
160:5571c4ff569f | 165 | * specific handle, such as \ref RAIL_EFR32_HANDLE for now. |
Anna Bridge |
160:5571c4ff569f | 166 | */ |
Anna Bridge |
160:5571c4ff569f | 167 | RAIL_Status_t RAIL_EnablePti(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 168 | bool enable); |
Anna Bridge |
160:5571c4ff569f | 169 | |
Anna Bridge |
160:5571c4ff569f | 170 | /** |
Anna Bridge |
160:5571c4ff569f | 171 | * Sets a protocol that RAIL outputs on PTI. |
Anna Bridge |
160:5571c4ff569f | 172 | * |
Anna Bridge |
160:5571c4ff569f | 173 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 174 | * @param[in] protocol The enum representing which protocol the node is using. |
Anna Bridge |
160:5571c4ff569f | 175 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 176 | * |
Anna Bridge |
142:4eea097334d6 | 177 | * The protocol is output via the Packet Trace Interface (PTI) for each packet. |
Anna Bridge |
142:4eea097334d6 | 178 | * Before any protocol is set, the default value is \ref |
Anna Bridge |
160:5571c4ff569f | 179 | * RAIL_PTI_PROTOCOL_CUSTOM. One of the enum values should be used so that |
Anna Bridge |
160:5571c4ff569f | 180 | * the Network Analyzer can decode the packet. |
Anna Bridge |
142:4eea097334d6 | 181 | */ |
Anna Bridge |
160:5571c4ff569f | 182 | RAIL_Status_t RAIL_SetPtiProtocol(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 183 | RAIL_PtiProtocol_t protocol); |
Anna Bridge |
142:4eea097334d6 | 184 | |
Anna Bridge |
160:5571c4ff569f | 185 | /** @} */ // end of group PTI |
Anna Bridge |
142:4eea097334d6 | 186 | |
Anna Bridge |
160:5571c4ff569f | 187 | /****************************************************************************** |
AnnaBridge | 167:84c0a372a020 | 188 | * Antenna Control |
Anna Bridge |
160:5571c4ff569f | 189 | *****************************************************************************/ |
Anna Bridge |
142:4eea097334d6 | 190 | /** |
AnnaBridge | 167:84c0a372a020 | 191 | * @addtogroup Antenna_Control |
AnnaBridge | 167:84c0a372a020 | 192 | * @brief Basic APIs to control the Antenna functionality |
Anna Bridge |
142:4eea097334d6 | 193 | * @{ |
Anna Bridge |
142:4eea097334d6 | 194 | */ |
Anna Bridge |
142:4eea097334d6 | 195 | |
Anna Bridge |
142:4eea097334d6 | 196 | /** |
AnnaBridge | 167:84c0a372a020 | 197 | * Configures Antenna pin locations |
AnnaBridge | 167:84c0a372a020 | 198 | * @param[in] railHandle a RAIL instance handle. |
AnnaBridge | 167:84c0a372a020 | 199 | * @param[in] config A configuration structure applied to the relevant Antenna |
AnnaBridge | 167:84c0a372a020 | 200 | * Configuration registers. |
AnnaBridge | 167:84c0a372a020 | 201 | * @return Status code indicating success of the function call. |
AnnaBridge | 167:84c0a372a020 | 202 | * |
AnnaBridge | 167:84c0a372a020 | 203 | * Although we do take a RAIL handle for potential future expansion, it is |
AnnaBridge | 167:84c0a372a020 | 204 | * currently not used. |
AnnaBridge | 167:84c0a372a020 | 205 | * |
AnnaBridge | 167:84c0a372a020 | 206 | */ |
AnnaBridge | 167:84c0a372a020 | 207 | RAIL_Status_t RAIL_ConfigAntenna(RAIL_Handle_t railHandle, |
AnnaBridge | 167:84c0a372a020 | 208 | const RAIL_AntennaConfig_t *config); |
AnnaBridge | 167:84c0a372a020 | 209 | |
AnnaBridge | 167:84c0a372a020 | 210 | /** @} */ // end of group Antenna_Control |
AnnaBridge | 167:84c0a372a020 | 211 | |
AnnaBridge | 167:84c0a372a020 | 212 | /****************************************************************************** |
AnnaBridge | 167:84c0a372a020 | 213 | * Radio Configuration |
AnnaBridge | 167:84c0a372a020 | 214 | *****************************************************************************/ |
AnnaBridge | 167:84c0a372a020 | 215 | /// @addtogroup Radio_Configuration Radio Configuration |
AnnaBridge | 167:84c0a372a020 | 216 | /// @brief Routines for setting up and querying radio configuration information. |
AnnaBridge | 167:84c0a372a020 | 217 | /// |
AnnaBridge | 167:84c0a372a020 | 218 | /// These routines allow for runtime flexibility in the radio |
AnnaBridge | 167:84c0a372a020 | 219 | /// configuration. Some of the parameters, however, are meant to be generated |
AnnaBridge | 167:84c0a372a020 | 220 | /// from the radio calculator in Simplicity Studio. The basic code to configure |
AnnaBridge | 167:84c0a372a020 | 221 | /// the radio from this calculator output looks like the example below. |
AnnaBridge | 167:84c0a372a020 | 222 | /// |
AnnaBridge | 167:84c0a372a020 | 223 | /// @code{.c} |
AnnaBridge | 167:84c0a372a020 | 224 | /// // Associate a specific channel config with a particular RAIL instance, and |
AnnaBridge | 167:84c0a372a020 | 225 | /// // load the settings that correspond to the first usable channel. |
AnnaBridge | 167:84c0a372a020 | 226 | /// RAIL_ConfigChannels(railHandle, channelConfigs[0]); |
AnnaBridge | 167:84c0a372a020 | 227 | /// @endcode |
AnnaBridge | 167:84c0a372a020 | 228 | /// |
AnnaBridge | 167:84c0a372a020 | 229 | /// For more information about the types of parameters that can be changed in |
AnnaBridge | 167:84c0a372a020 | 230 | /// the other functions and how to use them, see their individual documentation. |
AnnaBridge | 167:84c0a372a020 | 231 | /// |
AnnaBridge | 167:84c0a372a020 | 232 | /// @{ |
AnnaBridge | 167:84c0a372a020 | 233 | |
AnnaBridge | 167:84c0a372a020 | 234 | /** |
Anna Bridge |
160:5571c4ff569f | 235 | * Loads a static radio configuration. |
Anna Bridge |
160:5571c4ff569f | 236 | * |
Anna Bridge |
160:5571c4ff569f | 237 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 238 | * @param[in] config A pointer to a radio configuration. |
Anna Bridge |
160:5571c4ff569f | 239 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 240 | * |
Anna Bridge |
160:5571c4ff569f | 241 | * The configuration passed into this function should be generated for you |
Anna Bridge |
160:5571c4ff569f | 242 | * and not manually created or edited. By default this function should not be |
Anna Bridge |
160:5571c4ff569f | 243 | * called in RAIL 2.x and later unless a non-default radio configuration needs |
Anna Bridge |
160:5571c4ff569f | 244 | * to be applied. In RAIL 2.x and later, the RAIL_ConfigChannels function |
Anna Bridge |
160:5571c4ff569f | 245 | * applies the default radio configuration automatically. |
Anna Bridge |
160:5571c4ff569f | 246 | */ |
Anna Bridge |
160:5571c4ff569f | 247 | RAIL_Status_t RAIL_ConfigRadio(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 248 | RAIL_RadioConfig_t config); |
Anna Bridge |
160:5571c4ff569f | 249 | |
Anna Bridge |
160:5571c4ff569f | 250 | /** |
Anna Bridge |
160:5571c4ff569f | 251 | * Modifies the currently configured fixed frame length in bytes. |
Anna Bridge |
160:5571c4ff569f | 252 | * |
Anna Bridge |
160:5571c4ff569f | 253 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 254 | * @param[in] length The expected fixed frame length. A value of 0 is infinite. |
Anna Bridge |
160:5571c4ff569f | 255 | * A value of RAIL_SETFIXEDLENGTH_INVALID restores the frame's length back to |
Anna Bridge |
160:5571c4ff569f | 256 | * that length specified by the default frame type configuration. |
Anna Bridge |
160:5571c4ff569f | 257 | * @return Length configured; The new frame length configured into the hardware |
AnnaBridge | 167:84c0a372a020 | 258 | * for use. 0 if in infinite mode, or RAIL_SETFIXEDLENGTH_INVALID if the frame |
AnnaBridge | 167:84c0a372a020 | 259 | * length has not yet been overridden by a valid value. |
Anna Bridge |
142:4eea097334d6 | 260 | * |
Anna Bridge |
160:5571c4ff569f | 261 | * Sets the fixed-length configuration for transmit and receive. |
Anna Bridge |
160:5571c4ff569f | 262 | * Be careful when using this function in receive and transmit as this |
Anna Bridge |
160:5571c4ff569f | 263 | * function changes the default frame configuration and remains in force until |
AnnaBridge | 167:84c0a372a020 | 264 | * it is called again with an input value of RAIL_SETFIXEDLENGTH_INVALID. This |
AnnaBridge | 167:84c0a372a020 | 265 | * function will override any fixed or variable length settings from a radio |
AnnaBridge | 167:84c0a372a020 | 266 | * configuration. |
Anna Bridge |
142:4eea097334d6 | 267 | */ |
Anna Bridge |
160:5571c4ff569f | 268 | uint16_t RAIL_SetFixedLength(RAIL_Handle_t railHandle, uint16_t length); |
Anna Bridge |
160:5571c4ff569f | 269 | |
Anna Bridge |
160:5571c4ff569f | 270 | /** |
Anna Bridge |
160:5571c4ff569f | 271 | * Configures the channels supported by this device. |
Anna Bridge |
160:5571c4ff569f | 272 | * |
Anna Bridge |
160:5571c4ff569f | 273 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 274 | * @param[in] config A pointer to the channel configuration for your device. |
Anna Bridge |
160:5571c4ff569f | 275 | * This pointer will be cached in the library so it must be something that |
Anna Bridge |
160:5571c4ff569f | 276 | * will exist for the runtime of the application. Typically, this should be |
Anna Bridge |
160:5571c4ff569f | 277 | * what is stored in Flash by the configuration tool. |
Anna Bridge |
160:5571c4ff569f | 278 | * @param[in] cb Function called whenever a radio configuration change occurs. |
Anna Bridge |
160:5571c4ff569f | 279 | * @return Returns the first available channel in the configuration. |
Anna Bridge |
160:5571c4ff569f | 280 | * |
Anna Bridge |
160:5571c4ff569f | 281 | * When configuring channels on the EFR32, the radio tuner is reconfigured |
Anna Bridge |
160:5571c4ff569f | 282 | * based on the frequency and channel spacing in the channel configuration. |
Anna Bridge |
160:5571c4ff569f | 283 | */ |
Anna Bridge |
160:5571c4ff569f | 284 | uint16_t RAIL_ConfigChannels(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 285 | const RAIL_ChannelConfig_t *config, |
Anna Bridge |
160:5571c4ff569f | 286 | RAIL_RadioConfigChangedCallback_t cb); |
Anna Bridge |
160:5571c4ff569f | 287 | |
Anna Bridge |
160:5571c4ff569f | 288 | /** |
Anna Bridge |
160:5571c4ff569f | 289 | * Checks to see if the channel exists in RAIL. |
Anna Bridge |
160:5571c4ff569f | 290 | * |
Anna Bridge |
160:5571c4ff569f | 291 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 292 | * @param[in] channel A channel number to check. |
Anna Bridge |
160:5571c4ff569f | 293 | * @return Returns RAIL_STATUS_NO_ERROR if channel exists |
Anna Bridge |
160:5571c4ff569f | 294 | * |
Anna Bridge |
160:5571c4ff569f | 295 | * Returns RAIL_STATUS_INVALID_PARAMETER if the given channel does not exist |
Anna Bridge |
160:5571c4ff569f | 296 | * in the channel configuration currently used, and RAIL_STATUS_NO_ERROR if the |
Anna Bridge |
160:5571c4ff569f | 297 | * channel is valid. |
Anna Bridge |
160:5571c4ff569f | 298 | */ |
Anna Bridge |
160:5571c4ff569f | 299 | RAIL_Status_t RAIL_IsValidChannel(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 300 | uint16_t channel); |
Anna Bridge |
160:5571c4ff569f | 301 | |
Anna Bridge |
160:5571c4ff569f | 302 | /** |
Anna Bridge |
160:5571c4ff569f | 303 | * Returns the symbol rate for the current PHY. |
Anna Bridge |
160:5571c4ff569f | 304 | * |
Anna Bridge |
160:5571c4ff569f | 305 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 306 | * @return The symbol rate in symbols per second or 0. |
Anna Bridge |
142:4eea097334d6 | 307 | * |
Anna Bridge |
160:5571c4ff569f | 308 | * The symbol rate is the rate of symbol changes over the air. For non-DSSS |
Anna Bridge |
160:5571c4ff569f | 309 | * PHYs, this is the same as the baudrate. For DSSS PHYs, it is the baudrate |
Anna Bridge |
160:5571c4ff569f | 310 | * divided by the length of a chipping sequence. For more information, |
Anna Bridge |
160:5571c4ff569f | 311 | * see the modem calculator documentation. If the rate is unable to be |
Anna Bridge |
160:5571c4ff569f | 312 | * calculated, this function will return 0. |
Anna Bridge |
160:5571c4ff569f | 313 | */ |
Anna Bridge |
160:5571c4ff569f | 314 | uint32_t RAIL_GetSymbolRate(RAIL_Handle_t railHandle); |
Anna Bridge |
160:5571c4ff569f | 315 | |
Anna Bridge |
160:5571c4ff569f | 316 | /** |
Anna Bridge |
160:5571c4ff569f | 317 | * Returns the bit rate for the current PHY. |
Anna Bridge |
160:5571c4ff569f | 318 | * |
Anna Bridge |
160:5571c4ff569f | 319 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 320 | * @return The bit rate in bits per second or 0. |
Anna Bridge |
160:5571c4ff569f | 321 | * |
Anna Bridge |
160:5571c4ff569f | 322 | * The bit rate is the effective over-the-air data rate. It does not account |
Anna Bridge |
160:5571c4ff569f | 323 | * for extra spreading for forward error correction, and so on, but |
Anna Bridge |
160:5571c4ff569f | 324 | * accounts for modulation schemes, DSSS, and other configurations. For more |
Anna Bridge |
160:5571c4ff569f | 325 | * information, see the modem calculator documentation. If the rate is unable |
Anna Bridge |
160:5571c4ff569f | 326 | * to be calculated, this function will return 0. |
Anna Bridge |
160:5571c4ff569f | 327 | */ |
Anna Bridge |
160:5571c4ff569f | 328 | uint32_t RAIL_GetBitRate(RAIL_Handle_t railHandle); |
Anna Bridge |
160:5571c4ff569f | 329 | |
Anna Bridge |
160:5571c4ff569f | 330 | /** |
Anna Bridge |
160:5571c4ff569f | 331 | * Sets the PA capacitor tune value for transmit and receive. |
Anna Bridge |
142:4eea097334d6 | 332 | * |
Anna Bridge |
160:5571c4ff569f | 333 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 334 | * @param[in] txPaCtuneValue PA Ctune value for TX mode. |
Anna Bridge |
160:5571c4ff569f | 335 | * @param[in] rxPaCtuneValue PA Ctune value for RX mode. |
Anna Bridge |
160:5571c4ff569f | 336 | * @return Status code indicating success of the function call. |
Anna Bridge |
160:5571c4ff569f | 337 | * |
Anna Bridge |
160:5571c4ff569f | 338 | * Provides the ability to tune the impedance of the transmit |
Anna Bridge |
160:5571c4ff569f | 339 | * and receive modes by changing the amount of capacitance at |
Anna Bridge |
160:5571c4ff569f | 340 | * the PA output. |
Anna Bridge |
142:4eea097334d6 | 341 | */ |
Anna Bridge |
160:5571c4ff569f | 342 | RAIL_Status_t RAIL_SetPaCTune(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 343 | uint8_t txPaCtuneValue, |
Anna Bridge |
160:5571c4ff569f | 344 | uint8_t rxPaCtuneValue); |
Anna Bridge |
160:5571c4ff569f | 345 | |
Anna Bridge |
160:5571c4ff569f | 346 | /** @} */ // end of group Radio_Configuration |
Anna Bridge |
160:5571c4ff569f | 347 | |
Anna Bridge |
160:5571c4ff569f | 348 | /****************************************************************************** |
Anna Bridge |
160:5571c4ff569f | 349 | * Timing Information |
Anna Bridge |
160:5571c4ff569f | 350 | *****************************************************************************/ |
Anna Bridge |
160:5571c4ff569f | 351 | /** |
Anna Bridge |
160:5571c4ff569f | 352 | * @addtogroup System_Timing System Timing |
Anna Bridge |
160:5571c4ff569f | 353 | * @brief Functionality related to the RAIL timer and general system time. |
Anna Bridge |
160:5571c4ff569f | 354 | * |
Anna Bridge |
160:5571c4ff569f | 355 | * These functions can be used to get information about the current system time |
Anna Bridge |
160:5571c4ff569f | 356 | * or to manipulate the RAIL timer. |
Anna Bridge |
160:5571c4ff569f | 357 | * |
Anna Bridge |
160:5571c4ff569f | 358 | * The system time returned by RAIL_GetTime() is in the same timebase that is |
Anna Bridge |
160:5571c4ff569f | 359 | * used throughout RAIL. Any callbacks that return a timestamp, such as |
Anna Bridge |
160:5571c4ff569f | 360 | * rxPacketReceived() callback, will use this same timebase as will any APIs |
Anna Bridge |
160:5571c4ff569f | 361 | * that accept an absolute time for scheduling their action. Throughout this |
Anna Bridge |
160:5571c4ff569f | 362 | * documentation the timebase used for this will be referred to as the RAIL |
Anna Bridge |
160:5571c4ff569f | 363 | * timebase. This is currently a value in microseconds from chip boot time. |
Anna Bridge |
160:5571c4ff569f | 364 | * This means that it will wrap every 1.19 hours. |
Anna Bridge |
160:5571c4ff569f | 365 | * (`(2^32 - 1) / (3600 sec/hr * 1000000 us/sec)`). |
Anna Bridge |
160:5571c4ff569f | 366 | * |
Anna Bridge |
160:5571c4ff569f | 367 | * The provided timer is hardware backed and interrupt driven. It can be used |
Anna Bridge |
160:5571c4ff569f | 368 | * for timing any event in your system, but will be especially helpful for |
Anna Bridge |
160:5571c4ff569f | 369 | * timing protocol based state machines and other systems that interact with |
Anna Bridge |
160:5571c4ff569f | 370 | * the radio. If you do not want to process the expiration in interrupt |
Anna Bridge |
160:5571c4ff569f | 371 | * context, leave the timerExpired() callback empty and poll for expiration |
Anna Bridge |
160:5571c4ff569f | 372 | * with the RAIL_IsTimerExpired() function. |
Anna Bridge |
160:5571c4ff569f | 373 | * |
Anna Bridge |
160:5571c4ff569f | 374 | * @{ |
Anna Bridge |
160:5571c4ff569f | 375 | */ |
Anna Bridge |
142:4eea097334d6 | 376 | |
Anna Bridge |
142:4eea097334d6 | 377 | /** |
AnnaBridge | 167:84c0a372a020 | 378 | * Configure the RAIL timer plugin. |
AnnaBridge | 167:84c0a372a020 | 379 | * |
AnnaBridge | 167:84c0a372a020 | 380 | * @param[in] enable Enables/Disables the RAIL multitimer. |
AnnaBridge | 167:84c0a372a020 | 381 | * @return True if the multitimer was successfully enabled/disabled, false |
AnnaBridge | 167:84c0a372a020 | 382 | * otherwise. |
AnnaBridge | 167:84c0a372a020 | 383 | * |
AnnaBridge | 167:84c0a372a020 | 384 | * @note This function must be called before calling \ref RAIL_SetMultiTimer. |
AnnaBridge | 167:84c0a372a020 | 385 | * This function must be called to use the timer driver plugin |
AnnaBridge | 167:84c0a372a020 | 386 | * with the RAIL single protocol library. |
AnnaBridge | 167:84c0a372a020 | 387 | * This function should not be called while the RAIL timer is running. |
AnnaBridge | 167:84c0a372a020 | 388 | * Call \ref RAIL_IsTimerRunning before enabling/disabling the multitimer. |
AnnaBridge | 167:84c0a372a020 | 389 | * If the multitimer is not needed, do not call this function. |
AnnaBridge | 167:84c0a372a020 | 390 | * This will allow the multitimer code to be dead stripped. |
AnnaBridge | 167:84c0a372a020 | 391 | */ |
AnnaBridge | 167:84c0a372a020 | 392 | bool RAIL_ConfigMultiTimer(bool enable); |
AnnaBridge | 167:84c0a372a020 | 393 | |
AnnaBridge | 167:84c0a372a020 | 394 | /** |
Anna Bridge |
160:5571c4ff569f | 395 | * Gets the current RAIL time. |
Anna Bridge |
160:5571c4ff569f | 396 | * |
Anna Bridge |
160:5571c4ff569f | 397 | * @return Returns the RAIL timebase in microseconds. Note that this wraps |
Anna Bridge |
160:5571c4ff569f | 398 | * after around 1.19 hours since it's stored in a 32bit value. |
Anna Bridge |
160:5571c4ff569f | 399 | * |
Anna Bridge |
160:5571c4ff569f | 400 | * Returns the current time in the RAIL timebase (microseconds). It can be |
Anna Bridge |
160:5571c4ff569f | 401 | * used to compare with packet timestamps or to schedule transmits. |
Anna Bridge |
160:5571c4ff569f | 402 | */ |
AnnaBridge | 167:84c0a372a020 | 403 | RAIL_Time_t RAIL_GetTime(void); |
Anna Bridge |
160:5571c4ff569f | 404 | |
Anna Bridge |
160:5571c4ff569f | 405 | /** |
Anna Bridge |
160:5571c4ff569f | 406 | * Sets the current RAIL time. |
Anna Bridge |
160:5571c4ff569f | 407 | * |
Anna Bridge |
160:5571c4ff569f | 408 | * @param[in] time Set the RAIL timebase to this value in microseconds. |
Anna Bridge |
160:5571c4ff569f | 409 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 410 | * |
Anna Bridge |
160:5571c4ff569f | 411 | * Sets the current time in the RAIL timebase in microseconds. |
Anna Bridge |
160:5571c4ff569f | 412 | */ |
AnnaBridge | 167:84c0a372a020 | 413 | RAIL_Status_t RAIL_SetTime(RAIL_Time_t time); |
Anna Bridge |
160:5571c4ff569f | 414 | |
Anna Bridge |
160:5571c4ff569f | 415 | /** |
Anna Bridge |
160:5571c4ff569f | 416 | * Schedules a timer to expire using the RAIL timebase. |
Anna Bridge |
160:5571c4ff569f | 417 | * |
Anna Bridge |
160:5571c4ff569f | 418 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 419 | * @param[in] time The timer's expiration time in the RAIL timebase. |
Anna Bridge |
160:5571c4ff569f | 420 | * @param[in] mode Indicates whether the time argument is an absolute |
Anna Bridge |
160:5571c4ff569f | 421 | * RAIL time or relative to the current RAIL time. Specifying mode |
Anna Bridge |
160:5571c4ff569f | 422 | * \ref RAIL_TIME_DISABLED is the same as calling RAIL_CancelTimer(). |
Anna Bridge |
160:5571c4ff569f | 423 | * @param[in] cb The callback for RAIL to call when the timer expires. |
Anna Bridge |
160:5571c4ff569f | 424 | * @return RAIL_STATUS_NO_ERROR on success and |
Anna Bridge |
160:5571c4ff569f | 425 | * RAIL_STATUS_INVALID_PARAMETER if the timer could not be scheduled. |
Anna Bridge |
160:5571c4ff569f | 426 | * |
Anna Bridge |
160:5571c4ff569f | 427 | * Configures a timer to expire after some period in the RAIL timebase. |
Anna Bridge |
160:5571c4ff569f | 428 | * This timer can be used to implement low level protocol features. |
Anna Bridge |
142:4eea097334d6 | 429 | * |
Anna Bridge |
160:5571c4ff569f | 430 | * @warning It is an error to attempt to schedule the timer when it is |
Anna Bridge |
160:5571c4ff569f | 431 | * still running from a previous request -- unless the cb callback is |
Anna Bridge |
160:5571c4ff569f | 432 | * identical to that used in the previous request, in which case the |
Anna Bridge |
160:5571c4ff569f | 433 | * timer is rescheduled to the new time. Note that in this case if |
Anna Bridge |
160:5571c4ff569f | 434 | * the original timer expires as it is being rescheduled, the callback |
Anna Bridge |
160:5571c4ff569f | 435 | * may or may not occur. It is generally good practice to cancel a |
Anna Bridge |
160:5571c4ff569f | 436 | * running timer before rescheduling it to minimize such ambiguity. |
Anna Bridge |
160:5571c4ff569f | 437 | */ |
Anna Bridge |
160:5571c4ff569f | 438 | RAIL_Status_t RAIL_SetTimer(RAIL_Handle_t railHandle, |
AnnaBridge | 167:84c0a372a020 | 439 | RAIL_Time_t time, |
Anna Bridge |
160:5571c4ff569f | 440 | RAIL_TimeMode_t mode, |
Anna Bridge |
160:5571c4ff569f | 441 | RAIL_TimerCallback_t cb); |
Anna Bridge |
160:5571c4ff569f | 442 | |
Anna Bridge |
160:5571c4ff569f | 443 | /** |
Anna Bridge |
160:5571c4ff569f | 444 | * Returns the absolute time that the RAIL timer was configured to expire. |
Anna Bridge |
160:5571c4ff569f | 445 | * |
Anna Bridge |
160:5571c4ff569f | 446 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 447 | * @return The absolute time that this timer was set to expire. |
Anna Bridge |
142:4eea097334d6 | 448 | * |
Anna Bridge |
160:5571c4ff569f | 449 | * It will give the absolute time regardless of the \ref RAIL_TimeMode_t that |
Anna Bridge |
160:5571c4ff569f | 450 | * was passed into \ref RAIL_SetTimer. Note that this time might be in the |
Anna Bridge |
160:5571c4ff569f | 451 | * past if the timer already expired. The return value is undefined if the |
Anna Bridge |
160:5571c4ff569f | 452 | * timer was never set. |
Anna Bridge |
142:4eea097334d6 | 453 | */ |
AnnaBridge | 167:84c0a372a020 | 454 | RAIL_Time_t RAIL_GetTimer(RAIL_Handle_t railHandle); |
Anna Bridge |
160:5571c4ff569f | 455 | |
Anna Bridge |
160:5571c4ff569f | 456 | /** |
Anna Bridge |
160:5571c4ff569f | 457 | * Stops the currently scheduled RAIL timer. |
Anna Bridge |
160:5571c4ff569f | 458 | * |
Anna Bridge |
160:5571c4ff569f | 459 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 460 | * @return void. |
Anna Bridge |
160:5571c4ff569f | 461 | * |
Anna Bridge |
160:5571c4ff569f | 462 | * Cancels the timer. If this function is called before the timer expires, |
Anna Bridge |
160:5571c4ff569f | 463 | * the cb callback specified in the earlier RAIL_SetTimer() call will never |
Anna Bridge |
160:5571c4ff569f | 464 | * be called. |
Anna Bridge |
160:5571c4ff569f | 465 | */ |
Anna Bridge |
160:5571c4ff569f | 466 | void RAIL_CancelTimer(RAIL_Handle_t railHandle); |
Anna Bridge |
142:4eea097334d6 | 467 | |
Anna Bridge |
142:4eea097334d6 | 468 | /** |
Anna Bridge |
160:5571c4ff569f | 469 | * Checks whether the RAIL timer has expired. |
Anna Bridge |
160:5571c4ff569f | 470 | * |
Anna Bridge |
160:5571c4ff569f | 471 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 472 | * @return True if the previously scheduled timer has expired and false |
Anna Bridge |
160:5571c4ff569f | 473 | * otherwise. |
Anna Bridge |
142:4eea097334d6 | 474 | * |
Anna Bridge |
160:5571c4ff569f | 475 | * Polling via this function can be used as an alternative to the callback. |
Anna Bridge |
160:5571c4ff569f | 476 | */ |
Anna Bridge |
160:5571c4ff569f | 477 | bool RAIL_IsTimerExpired(RAIL_Handle_t railHandle); |
Anna Bridge |
160:5571c4ff569f | 478 | |
Anna Bridge |
160:5571c4ff569f | 479 | /** |
Anna Bridge |
160:5571c4ff569f | 480 | * Checks whether the RAIL timer is currently running. |
Anna Bridge |
142:4eea097334d6 | 481 | * |
Anna Bridge |
160:5571c4ff569f | 482 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 483 | * @return Returns true if the timer is running and false if |
Anna Bridge |
160:5571c4ff569f | 484 | * the timer has expired or was never set. |
Anna Bridge |
142:4eea097334d6 | 485 | */ |
Anna Bridge |
160:5571c4ff569f | 486 | bool RAIL_IsTimerRunning(RAIL_Handle_t railHandle); |
Anna Bridge |
160:5571c4ff569f | 487 | |
Anna Bridge |
160:5571c4ff569f | 488 | /** |
AnnaBridge | 167:84c0a372a020 | 489 | * Starts a multitimer instance. |
AnnaBridge | 167:84c0a372a020 | 490 | * |
AnnaBridge | 167:84c0a372a020 | 491 | * @note |
AnnaBridge | 167:84c0a372a020 | 492 | * It is legal to start an already running timer. If this is done, the timer |
AnnaBridge | 167:84c0a372a020 | 493 | * will first be stopped before the new configurations are applied. |
AnnaBridge | 167:84c0a372a020 | 494 | * If expirationTime is 0, the callback will be called |
AnnaBridge | 167:84c0a372a020 | 495 | * immediately. |
AnnaBridge | 167:84c0a372a020 | 496 | * |
AnnaBridge | 167:84c0a372a020 | 497 | * @param[in,out] tmr A pointer to the timer instance to start. |
AnnaBridge | 167:84c0a372a020 | 498 | * @param[in] expirationTime When the timer is to expire. |
AnnaBridge | 167:84c0a372a020 | 499 | * @param[in] expirationMode Select mode of expirationTime. See \ref |
AnnaBridge | 167:84c0a372a020 | 500 | * RAIL_TimeMode_t. |
AnnaBridge | 167:84c0a372a020 | 501 | * @param[in] callback Function to call on timer expiry. See \ref |
AnnaBridge | 167:84c0a372a020 | 502 | * RAIL_MultiTimerCallback_t. NULL is a legal value. |
AnnaBridge | 167:84c0a372a020 | 503 | * @param[in] cbArg Extra callback function parameter for user application. |
AnnaBridge | 167:84c0a372a020 | 504 | * |
AnnaBridge | 167:84c0a372a020 | 505 | * @return |
AnnaBridge | 167:84c0a372a020 | 506 | * \ref RAIL_STATUS_NO_ERROR on success.@n |
AnnaBridge | 167:84c0a372a020 | 507 | * \ref RAIL_STATUS_INVALID_PARAMETER if tmr has an illegal value or if |
AnnaBridge | 167:84c0a372a020 | 508 | * timeout is in the past. |
AnnaBridge | 167:84c0a372a020 | 509 | */ |
AnnaBridge | 167:84c0a372a020 | 510 | RAIL_Status_t RAIL_SetMultiTimer(RAIL_MultiTimer_t *tmr, |
AnnaBridge | 167:84c0a372a020 | 511 | RAIL_Time_t expirationTime, |
AnnaBridge | 167:84c0a372a020 | 512 | RAIL_TimeMode_t expirationMode, |
AnnaBridge | 167:84c0a372a020 | 513 | RAIL_MultiTimerCallback_t callback, |
AnnaBridge | 167:84c0a372a020 | 514 | void *cbArg); |
AnnaBridge | 167:84c0a372a020 | 515 | |
AnnaBridge | 167:84c0a372a020 | 516 | /** |
AnnaBridge | 167:84c0a372a020 | 517 | * Stops the currently scheduled RAIL multi timer. |
AnnaBridge | 167:84c0a372a020 | 518 | * |
AnnaBridge | 167:84c0a372a020 | 519 | * @param[in,out] tmr A RAIL timer instance handle. |
AnnaBridge | 167:84c0a372a020 | 520 | * |
AnnaBridge | 167:84c0a372a020 | 521 | * @return |
AnnaBridge | 167:84c0a372a020 | 522 | * true if timer was successfully cancelled. |
AnnaBridge | 167:84c0a372a020 | 523 | * false if timer was not running. |
AnnaBridge | 167:84c0a372a020 | 524 | * |
AnnaBridge | 167:84c0a372a020 | 525 | * Cancels the timer. If this function is called before the timer expires, |
AnnaBridge | 167:84c0a372a020 | 526 | * the cb callback specified in the earlier RAIL_SetTimer() call will never |
AnnaBridge | 167:84c0a372a020 | 527 | * be called. |
AnnaBridge | 167:84c0a372a020 | 528 | */ |
AnnaBridge | 167:84c0a372a020 | 529 | bool RAIL_CancelMultiTimer(RAIL_MultiTimer_t *tmr); |
AnnaBridge | 167:84c0a372a020 | 530 | |
AnnaBridge | 167:84c0a372a020 | 531 | /** |
AnnaBridge | 167:84c0a372a020 | 532 | * Check if a given timer is running. |
AnnaBridge | 167:84c0a372a020 | 533 | * |
AnnaBridge | 167:84c0a372a020 | 534 | * @param[in] tmr A pointer to the timer structure to query. |
AnnaBridge | 167:84c0a372a020 | 535 | * |
AnnaBridge | 167:84c0a372a020 | 536 | * @return |
AnnaBridge | 167:84c0a372a020 | 537 | * true if timer is running. |
AnnaBridge | 167:84c0a372a020 | 538 | * false if timer is not running. |
AnnaBridge | 167:84c0a372a020 | 539 | */ |
AnnaBridge | 167:84c0a372a020 | 540 | bool RAIL_IsMultiTimerRunning(RAIL_MultiTimer_t *tmr); |
AnnaBridge | 167:84c0a372a020 | 541 | |
AnnaBridge | 167:84c0a372a020 | 542 | /** |
AnnaBridge | 167:84c0a372a020 | 543 | * Check if a given timer has expired. |
AnnaBridge | 167:84c0a372a020 | 544 | * |
AnnaBridge | 167:84c0a372a020 | 545 | * @param[in] tmr A pointer to the timer structure to query. |
AnnaBridge | 167:84c0a372a020 | 546 | * |
AnnaBridge | 167:84c0a372a020 | 547 | * @return |
AnnaBridge | 167:84c0a372a020 | 548 | * true if timer is expired. |
AnnaBridge | 167:84c0a372a020 | 549 | * false if timer is running. |
AnnaBridge | 167:84c0a372a020 | 550 | */ |
AnnaBridge | 167:84c0a372a020 | 551 | bool RAIL_IsMultiTimerExpired(RAIL_MultiTimer_t *tmr); |
AnnaBridge | 167:84c0a372a020 | 552 | |
AnnaBridge | 167:84c0a372a020 | 553 | /** |
AnnaBridge | 167:84c0a372a020 | 554 | * Get time left before a given timer instance expires. |
AnnaBridge | 167:84c0a372a020 | 555 | * |
AnnaBridge | 167:84c0a372a020 | 556 | * @param[in] tmr A pointer to the timer structure to query. |
AnnaBridge | 167:84c0a372a020 | 557 | * @param[in] timeMode An indication as to how the function provides the time |
AnnaBridge | 167:84c0a372a020 | 558 | * remaining. By choosing \ref |
AnnaBridge | 167:84c0a372a020 | 559 | * RAIL_TimeMode_t::RAIL_TIME_ABSOLUTE, the function returns the |
AnnaBridge | 167:84c0a372a020 | 560 | * absolute expiration time, and by choosing \ref |
AnnaBridge | 167:84c0a372a020 | 561 | * RAIL_TimeMode_t::RAIL_TIME_DELAY, the function returns the |
AnnaBridge | 167:84c0a372a020 | 562 | * amount of time remaining before the timer's expiration. |
AnnaBridge | 167:84c0a372a020 | 563 | * |
AnnaBridge | 167:84c0a372a020 | 564 | * @return |
AnnaBridge | 167:84c0a372a020 | 565 | * Time left expressed in RAIL's time units. |
AnnaBridge | 167:84c0a372a020 | 566 | * 0 if the soft timer is not running or has already expired. |
AnnaBridge | 167:84c0a372a020 | 567 | */ |
AnnaBridge | 167:84c0a372a020 | 568 | RAIL_Time_t RAIL_GetMultiTimer(RAIL_MultiTimer_t *tmr, |
AnnaBridge | 167:84c0a372a020 | 569 | RAIL_TimeMode_t timeMode); |
AnnaBridge | 167:84c0a372a020 | 570 | |
AnnaBridge | 167:84c0a372a020 | 571 | /** |
Anna Bridge |
160:5571c4ff569f | 572 | * Initialize RAIL timer synchronization. |
Anna Bridge |
160:5571c4ff569f | 573 | * |
Anna Bridge |
160:5571c4ff569f | 574 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 575 | * @param[in] sleepConfig A sleep configuration. |
Anna Bridge |
160:5571c4ff569f | 576 | * |
Anna Bridge |
160:5571c4ff569f | 577 | * @return Status code indicating success of the function call. |
Anna Bridge |
160:5571c4ff569f | 578 | */ |
Anna Bridge |
160:5571c4ff569f | 579 | RAIL_Status_t RAIL_ConfigSleep(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 580 | RAIL_SleepConfig_t sleepConfig); |
Anna Bridge |
142:4eea097334d6 | 581 | |
Anna Bridge |
142:4eea097334d6 | 582 | /** |
Anna Bridge |
160:5571c4ff569f | 583 | * Stop the RAIL timer and prepare RAIL for sleep. |
Anna Bridge |
160:5571c4ff569f | 584 | * |
Anna Bridge |
160:5571c4ff569f | 585 | * @param[in] wakeupProcessTime Time in microseconds that the application and |
Anna Bridge |
160:5571c4ff569f | 586 | * hardware need to recover from sleep state. |
Anna Bridge |
160:5571c4ff569f | 587 | * @param[out] deepSleepAllowed |
Anna Bridge |
160:5571c4ff569f | 588 | * true - system can go to deep sleep. |
Anna Bridge |
160:5571c4ff569f | 589 | * false - system should not go to deep sleep. Deep sleep should be blocked |
Anna Bridge |
160:5571c4ff569f | 590 | * in this case. |
Anna Bridge |
160:5571c4ff569f | 591 | * |
Anna Bridge |
160:5571c4ff569f | 592 | * @return Status code indicating success of the function call. |
Anna Bridge |
160:5571c4ff569f | 593 | * |
Anna Bridge |
160:5571c4ff569f | 594 | * @warning The active RAIL configuration must be idle for enabling sleep. |
Anna Bridge |
160:5571c4ff569f | 595 | */ |
Anna Bridge |
160:5571c4ff569f | 596 | RAIL_Status_t RAIL_Sleep(uint16_t wakeupProcessTime, bool *deepSleepAllowed); |
Anna Bridge |
160:5571c4ff569f | 597 | |
Anna Bridge |
160:5571c4ff569f | 598 | /** |
Anna Bridge |
160:5571c4ff569f | 599 | * Wake RAIL from sleep and restart the RAIL timer. |
Anna Bridge |
160:5571c4ff569f | 600 | * |
Anna Bridge |
160:5571c4ff569f | 601 | * @param[in] elapsedTime Add the sleep duration to the RAIL timer |
Anna Bridge |
160:5571c4ff569f | 602 | * before restarting the RAIL timer. |
Anna Bridge |
160:5571c4ff569f | 603 | * |
Anna Bridge |
160:5571c4ff569f | 604 | * @return Status code indicating success of the function call. |
Anna Bridge |
160:5571c4ff569f | 605 | * |
Anna Bridge |
160:5571c4ff569f | 606 | * If timer sync was enabled by \ref RAIL_ConfigSleep, synchronize the RAIL |
Anna Bridge |
160:5571c4ff569f | 607 | * timer using an alternate timer. Otherwise, add elapsedTime to the RAIL |
Anna Bridge |
160:5571c4ff569f | 608 | * timer. |
Anna Bridge |
142:4eea097334d6 | 609 | */ |
AnnaBridge | 167:84c0a372a020 | 610 | RAIL_Status_t RAIL_Wake(RAIL_Time_t elapsedTime); |
Anna Bridge |
160:5571c4ff569f | 611 | |
Anna Bridge |
160:5571c4ff569f | 612 | /** @} */ // end of group System_Timing |
Anna Bridge |
160:5571c4ff569f | 613 | |
Anna Bridge |
160:5571c4ff569f | 614 | /****************************************************************************** |
Anna Bridge |
160:5571c4ff569f | 615 | * Events |
Anna Bridge |
160:5571c4ff569f | 616 | *****************************************************************************/ |
Anna Bridge |
160:5571c4ff569f | 617 | /** |
Anna Bridge |
160:5571c4ff569f | 618 | * @addtogroup Events |
Anna Bridge |
160:5571c4ff569f | 619 | * @brief APIs related to events |
Anna Bridge |
160:5571c4ff569f | 620 | * @{ |
Anna Bridge |
160:5571c4ff569f | 621 | */ |
Anna Bridge |
160:5571c4ff569f | 622 | |
Anna Bridge |
160:5571c4ff569f | 623 | /** |
Anna Bridge |
160:5571c4ff569f | 624 | * Configures radio events. |
Anna Bridge |
160:5571c4ff569f | 625 | * |
Anna Bridge |
160:5571c4ff569f | 626 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 627 | * @param[in] mask Bitmask containing which events should be modified. |
Anna Bridge |
160:5571c4ff569f | 628 | * @param[in] events Define which events should trigger \ref RAIL_Config_t::eventsCallback |
Anna Bridge |
160:5571c4ff569f | 629 | * The full list of available callbacks can be found by looking at the |
Anna Bridge |
160:5571c4ff569f | 630 | * RAIL_EVENT_* set of defines. |
Anna Bridge |
160:5571c4ff569f | 631 | * @return Status code indicating success of the function call. |
Anna Bridge |
160:5571c4ff569f | 632 | * |
Anna Bridge |
160:5571c4ff569f | 633 | * Sets up which radio interrupts generate a RAIL event. The full list of |
Anna Bridge |
160:5571c4ff569f | 634 | * options is in \ref RAIL_Events_t. |
Anna Bridge |
160:5571c4ff569f | 635 | */ |
Anna Bridge |
160:5571c4ff569f | 636 | RAIL_Status_t RAIL_ConfigEvents(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 637 | RAIL_Events_t mask, |
Anna Bridge |
160:5571c4ff569f | 638 | RAIL_Events_t events); |
Anna Bridge |
160:5571c4ff569f | 639 | |
Anna Bridge |
160:5571c4ff569f | 640 | /** @} */ // end of group Events |
Anna Bridge |
142:4eea097334d6 | 641 | |
Anna Bridge |
142:4eea097334d6 | 642 | /****************************************************************************** |
Anna Bridge |
142:4eea097334d6 | 643 | * Data Management |
Anna Bridge |
142:4eea097334d6 | 644 | *****************************************************************************/ |
AnnaBridge | 167:84c0a372a020 | 645 | /// @addtogroup Data_Management Data Management |
AnnaBridge | 167:84c0a372a020 | 646 | /// @brief Data management functions |
AnnaBridge | 167:84c0a372a020 | 647 | /// |
AnnaBridge | 167:84c0a372a020 | 648 | /// These functions allow the application to choose how data is presented to the |
AnnaBridge | 167:84c0a372a020 | 649 | /// application. RAIL provides data in a packet-based method or in a FIFO-based |
AnnaBridge | 167:84c0a372a020 | 650 | /// method which gives the application more granularity and responsibility in |
AnnaBridge | 167:84c0a372a020 | 651 | /// managing transmit and receive data, and allows packet sizes larger than |
AnnaBridge | 167:84c0a372a020 | 652 | /// the RX or TX FIFO buffers. |
AnnaBridge | 167:84c0a372a020 | 653 | /// |
AnnaBridge | 167:84c0a372a020 | 654 | /// The application can configure RAIL data management through |
AnnaBridge | 167:84c0a372a020 | 655 | /// RAIL_ConfigData(). |
AnnaBridge | 167:84c0a372a020 | 656 | /// This function allows the application to specify the type of radio data |
AnnaBridge | 167:84c0a372a020 | 657 | /// (\ref RAIL_TxDataSource_t and \ref RAIL_RxDataSource_t) and the method of |
AnnaBridge | 167:84c0a372a020 | 658 | /// interacting with data (\ref RAIL_DataMethod_t). By default, RAIL |
AnnaBridge | 167:84c0a372a020 | 659 | /// configures TX and RX both with packet data source and packet mode. |
AnnaBridge | 167:84c0a372a020 | 660 | /// |
AnnaBridge | 167:84c0a372a020 | 661 | /// In packet based data management: |
AnnaBridge | 167:84c0a372a020 | 662 | /// - Packet lengths are determined from the Radio Configurator configuration |
AnnaBridge | 167:84c0a372a020 | 663 | /// or after receive packet completion using RAIL_GetRxPacketInfo(). |
AnnaBridge | 167:84c0a372a020 | 664 | /// - Load transmit data with RAIL_WriteTxFifo(). |
AnnaBridge | 167:84c0a372a020 | 665 | /// - Received packet data is made available on successful packet completion |
AnnaBridge | 167:84c0a372a020 | 666 | /// via \ref RAIL_Config_t::eventsCallback with \ref RAIL_EVENT_RX_PACKET_RECEIVED |
AnnaBridge | 167:84c0a372a020 | 667 | /// which can then use RAIL_GetRxPacketInfo() and RAIL_GetRxPacketDetails() to |
AnnaBridge | 167:84c0a372a020 | 668 | /// access packet information, and RAIL_PeekRxPacket() to access packet |
AnnaBridge | 167:84c0a372a020 | 669 | /// data. |
AnnaBridge | 167:84c0a372a020 | 670 | /// - Filtered, Aborted, or FrameError received packet data is automatically |
AnnaBridge | 167:84c0a372a020 | 671 | /// dropped without the application needing to worry about consuming it. |
AnnaBridge | 167:84c0a372a020 | 672 | /// The application can choose to not even be bothered with the events |
AnnaBridge | 167:84c0a372a020 | 673 | /// related to such packets: \ref RAIL_EVENT_RX_ADDRESS_FILTERED, |
AnnaBridge | 167:84c0a372a020 | 674 | /// \ref RAIL_EVENT_RX_PACKET_ABORTED, or \ref RAIL_EVENT_RX_FRAME_ERROR. |
AnnaBridge | 167:84c0a372a020 | 675 | /// |
AnnaBridge | 167:84c0a372a020 | 676 | /// In FIFO based data management: |
AnnaBridge | 167:84c0a372a020 | 677 | /// - Packet Lengths are determined from the Radio Configurator configuration |
AnnaBridge | 167:84c0a372a020 | 678 | /// or by application knowledge of packet payload structure. |
AnnaBridge | 167:84c0a372a020 | 679 | /// - Load transmit data with RAIL_WriteTxFifo() with reset set to false. |
AnnaBridge | 167:84c0a372a020 | 680 | /// - Received data can be retrieved prior to packet completion through |
AnnaBridge | 167:84c0a372a020 | 681 | /// RAIL_ReadRxFifo(), and is never dropped on Filtered, Aborted, or |
AnnaBridge | 167:84c0a372a020 | 682 | /// FrameError packets. The application should enable and handle these |
AnnaBridge | 167:84c0a372a020 | 683 | /// events so it can flush any packet data it's already retrieved. |
AnnaBridge | 167:84c0a372a020 | 684 | /// - After packet completion, remaining packet data for Filtered, Aborted, |
AnnaBridge | 167:84c0a372a020 | 685 | /// or FrameError packets can be either flushed automatically by RAIL |
AnnaBridge | 167:84c0a372a020 | 686 | /// or consumed by the application just like a successfully received packet, |
AnnaBridge | 167:84c0a372a020 | 687 | /// as determined from RAIL_GetRxPacketInfo(). RAIL_GetRxPacketDetails() |
AnnaBridge | 167:84c0a372a020 | 688 | /// provides packet detailed information only for successfully received |
AnnaBridge | 167:84c0a372a020 | 689 | /// packets. |
AnnaBridge | 167:84c0a372a020 | 690 | /// - Set the TX FIFO threshold through RAIL_SetTxFifoThreshold(). The |
AnnaBridge | 167:84c0a372a020 | 691 | /// \ref RAIL_Config_t::eventsCallback with \ref RAIL_EVENT_TX_FIFO_ALMOST_EMPTY |
AnnaBridge | 167:84c0a372a020 | 692 | /// will occur telling the application to load more TX packet data, if needed |
AnnaBridge | 167:84c0a372a020 | 693 | /// lest a \ref RAIL_EVENT_TX_UNDERFLOW event occurs. |
AnnaBridge | 167:84c0a372a020 | 694 | /// - Set the RX FIFO threshold through RAIL_SetRxFifoThreshold(). The |
AnnaBridge | 167:84c0a372a020 | 695 | /// \ref RAIL_Config_t::eventsCallback with \ref RAIL_EVENT_RX_FIFO_ALMOST_FULL |
AnnaBridge | 167:84c0a372a020 | 696 | /// will occur telling the application to consume some RX packet data lest a |
AnnaBridge | 167:84c0a372a020 | 697 | /// \ref RAIL_EVENT_RX_FIFO_OVERFLOW event occurs. |
AnnaBridge | 167:84c0a372a020 | 698 | /// - Get RX FIFO count information through |
AnnaBridge | 167:84c0a372a020 | 699 | /// RAIL_GetRxPacketInfo(\ref RAIL_RX_PACKET_HANDLE_NEWEST) |
AnnaBridge | 167:84c0a372a020 | 700 | /// (or RAIL_GetRxFifoBytesAvailable()). |
AnnaBridge | 167:84c0a372a020 | 701 | /// - Get TX FIFO count information through RAIL_GetTxFifoSpaceAvailable(). |
AnnaBridge | 167:84c0a372a020 | 702 | /// - Reset RX and/or TX FIFOs with RAIL_ResetFifo(). |
AnnaBridge | 167:84c0a372a020 | 703 | /// |
AnnaBridge | 167:84c0a372a020 | 704 | /// When trying to determine an appropriate threshold, the application needs |
AnnaBridge | 167:84c0a372a020 | 705 | /// to know each FIFO's size. The receive FIFO is internal to RAIL and its |
AnnaBridge | 167:84c0a372a020 | 706 | /// size is 512 bytes. The receive FIFO is level-based in that the \ref |
AnnaBridge | 167:84c0a372a020 | 707 | /// RAIL_EVENT_RX_FIFO_ALMOST_FULL event will constantly pend if the threshold |
AnnaBridge | 167:84c0a372a020 | 708 | /// is exceeded. This normally means that inside this event's callback, the |
AnnaBridge | 167:84c0a372a020 | 709 | /// application should |
AnnaBridge | 167:84c0a372a020 | 710 | /// empty enough of the FIFO to go under the threshold. To defer reading the |
AnnaBridge | 167:84c0a372a020 | 711 | /// FIFO to main context, the application can disable or re-enable the receive |
AnnaBridge | 167:84c0a372a020 | 712 | /// FIFO threshold event using RAIL_ConfigEvents() with the mask |
AnnaBridge | 167:84c0a372a020 | 713 | /// \ref RAIL_EVENT_RX_FIFO_ALMOST_FULL. |
AnnaBridge | 167:84c0a372a020 | 714 | /// |
AnnaBridge | 167:84c0a372a020 | 715 | /// The transmit FIFO is specified by the application and its actual size is |
AnnaBridge | 167:84c0a372a020 | 716 | /// the value returned from the most recent call to RAIL_SetTxFifo(), |
AnnaBridge | 167:84c0a372a020 | 717 | /// The transmit FIFO is edge-based in that it only provides the \ref |
AnnaBridge | 167:84c0a372a020 | 718 | /// RAIL_EVENT_TX_FIFO_ALMOST_EMPTY event once when the threshold is crossed |
AnnaBridge | 167:84c0a372a020 | 719 | /// in the emptying direction. |
AnnaBridge | 167:84c0a372a020 | 720 | /// |
AnnaBridge | 167:84c0a372a020 | 721 | /// In FIFO mode, the FIFOs can store multiple packets. Depending on the |
AnnaBridge | 167:84c0a372a020 | 722 | /// traffic, RAIL can receive multiple packets into the receive FIFO before the |
AnnaBridge | 167:84c0a372a020 | 723 | /// application gets around to reading out the received data from the FIFO. |
AnnaBridge | 167:84c0a372a020 | 724 | /// RAIL_ReadRxFifo() won't allow reading beyond a packet boundary so |
AnnaBridge | 167:84c0a372a020 | 725 | /// process packet completion events promptly. Keep in mind that in FIFO mode, |
AnnaBridge | 167:84c0a372a020 | 726 | /// packet data already read from packets that are subsequently aborted, |
AnnaBridge | 167:84c0a372a020 | 727 | /// frameerror, or filtered should be flushed. |
AnnaBridge | 167:84c0a372a020 | 728 | /// |
AnnaBridge | 167:84c0a372a020 | 729 | /// While RAIL defaults to packet mode, the application can explicitly |
AnnaBridge | 167:84c0a372a020 | 730 | /// initialize RAIL for packet mode in the following manner: |
AnnaBridge | 167:84c0a372a020 | 731 | /// @code{.c} |
AnnaBridge | 167:84c0a372a020 | 732 | /// static const RAIL_DataConfig_t railDataConfig = { |
AnnaBridge | 167:84c0a372a020 | 733 | /// .txSource = TX_PACKET_DATA, |
AnnaBridge | 167:84c0a372a020 | 734 | /// .rxSource = RX_PACKET_DATA, |
AnnaBridge | 167:84c0a372a020 | 735 | /// .txMethod = PACKET_MODE, |
AnnaBridge | 167:84c0a372a020 | 736 | /// .rxMethod = PACKET_MODE, |
AnnaBridge | 167:84c0a372a020 | 737 | /// }; |
AnnaBridge | 167:84c0a372a020 | 738 | /// |
AnnaBridge | 167:84c0a372a020 | 739 | /// status = RAIL_ConfigData(&railDataConfig); |
AnnaBridge | 167:84c0a372a020 | 740 | /// |
AnnaBridge | 167:84c0a372a020 | 741 | /// // Events that can occur in Packet Mode: |
AnnaBridge | 167:84c0a372a020 | 742 | /// RAIL_EVENT_TX_PACKET_SENT |
AnnaBridge | 167:84c0a372a020 | 743 | /// RAIL_EVENT_RX_PACKET_RECEIVED |
AnnaBridge | 167:84c0a372a020 | 744 | /// and optionally (packet data automatically dropped): |
AnnaBridge | 167:84c0a372a020 | 745 | /// RAIL_EVENT_RX_ADDRESS_FILTERED |
AnnaBridge | 167:84c0a372a020 | 746 | /// RAIL_EVENT_RX_PACKET_ABORTED |
AnnaBridge | 167:84c0a372a020 | 747 | /// RAIL_EVENT_RX_FRAME_ERROR |
AnnaBridge | 167:84c0a372a020 | 748 | /// @endcode |
AnnaBridge | 167:84c0a372a020 | 749 | /// |
AnnaBridge | 167:84c0a372a020 | 750 | /// Initializing RAIL for FIFO Mode requires a few more function calls: |
AnnaBridge | 167:84c0a372a020 | 751 | /// @code{.c} |
AnnaBridge | 167:84c0a372a020 | 752 | /// static const RAIL_DataConfig_t railDataConfig = { |
AnnaBridge | 167:84c0a372a020 | 753 | /// .txSource = TX_PACKET_DATA, |
AnnaBridge | 167:84c0a372a020 | 754 | /// .rxSource = RX_PACKET_DATA, |
AnnaBridge | 167:84c0a372a020 | 755 | /// .txMethod = FIFO_MODE, |
AnnaBridge | 167:84c0a372a020 | 756 | /// .rxMethod = FIFO_MODE, |
AnnaBridge | 167:84c0a372a020 | 757 | /// }; |
AnnaBridge | 167:84c0a372a020 | 758 | /// |
AnnaBridge | 167:84c0a372a020 | 759 | /// status = RAIL_ConfigData(&railDataConfig); |
AnnaBridge | 167:84c0a372a020 | 760 | /// |
AnnaBridge | 167:84c0a372a020 | 761 | /// // Gets the size of the FIFOs. |
AnnaBridge | 167:84c0a372a020 | 762 | /// // The transmit and receive FIFOs are the same size |
AnnaBridge | 167:84c0a372a020 | 763 | /// uint16_t fifoSize = RAIL_GetTxFifoSpaceAvailable(); |
AnnaBridge | 167:84c0a372a020 | 764 | /// |
AnnaBridge | 167:84c0a372a020 | 765 | /// // Sets the transmit and receive FIFO thresholds. |
AnnaBridge | 167:84c0a372a020 | 766 | /// // For this example, set the threshold in the middle of each FIFO |
AnnaBridge | 167:84c0a372a020 | 767 | /// RAIL_SetRxFifoThreshold(fifoSize / 2); |
AnnaBridge | 167:84c0a372a020 | 768 | /// RAIL_SetTxFifoThreshold(fifoSize / 2); |
AnnaBridge | 167:84c0a372a020 | 769 | /// |
AnnaBridge | 167:84c0a372a020 | 770 | /// // Events that can occur in FIFO mode: |
AnnaBridge | 167:84c0a372a020 | 771 | /// RAIL_EVENT_TX_FIFO_ALMOST_EMPTY |
AnnaBridge | 167:84c0a372a020 | 772 | /// RAIL_EVENT_TX_UNDERFLOW |
AnnaBridge | 167:84c0a372a020 | 773 | /// RAIL_EVENT_TXACK_UNDERFLOW |
AnnaBridge | 167:84c0a372a020 | 774 | /// RAIL_EVENT_TX_PACKET_SENT |
AnnaBridge | 167:84c0a372a020 | 775 | /// RAIL_EVENT_RX_FIFO_ALMOST_FULL |
AnnaBridge | 167:84c0a372a020 | 776 | /// RAIL_EVENT_RX_FIFO_OVERFLOW |
AnnaBridge | 167:84c0a372a020 | 777 | /// RAIL_EVENT_RX_ADDRESS_FILTERED |
AnnaBridge | 167:84c0a372a020 | 778 | /// RAIL_EVENT_RX_PACKET_ABORTED |
AnnaBridge | 167:84c0a372a020 | 779 | /// RAIL_EVENT_RX_FRAME_ERROR |
AnnaBridge | 167:84c0a372a020 | 780 | /// RAIL_EVENT_RX_PACKET_RECEIVED |
AnnaBridge | 167:84c0a372a020 | 781 | /// @endcode |
AnnaBridge | 167:84c0a372a020 | 782 | /// |
AnnaBridge | 167:84c0a372a020 | 783 | /// On receive, an application can use multiple data sources that |
AnnaBridge | 167:84c0a372a020 | 784 | /// are only compatible with the FIFO method of data delivery. All that differs |
AnnaBridge | 167:84c0a372a020 | 785 | /// from the FIFO mode example above is the RAIL_DataConfig_t::rxSource setting. |
AnnaBridge | 167:84c0a372a020 | 786 | /// IQ data samples are taken at the hardware's oversample rate and the amount |
AnnaBridge | 167:84c0a372a020 | 787 | /// of data can easily overwhelm the CPU processing time. The sample rate |
AnnaBridge | 167:84c0a372a020 | 788 | /// depends on the chosen PHY, as determined by the data rate and the decimation |
AnnaBridge | 167:84c0a372a020 | 789 | /// chain. It is <b>not</b> recommended to use the IQ data source with sample |
AnnaBridge | 167:84c0a372a020 | 790 | /// rates above 300 k samples/second as the CPU might not be able to keep up |
AnnaBridge | 167:84c0a372a020 | 791 | /// with the data. Depending on the application and needed CPU bandwidth, slower |
AnnaBridge | 167:84c0a372a020 | 792 | /// data rates may be required. |
AnnaBridge | 167:84c0a372a020 | 793 | /// @code{.c} |
AnnaBridge | 167:84c0a372a020 | 794 | /// // IQ data is provided into the receive FIFO |
AnnaBridge | 167:84c0a372a020 | 795 | /// static const RAIL_DataConfig_t railDataConfig = { |
AnnaBridge | 167:84c0a372a020 | 796 | /// .txSource = TX_PACKET_DATA, |
AnnaBridge | 167:84c0a372a020 | 797 | /// .rxSource = RX_IQDATA_FILTLSB, |
AnnaBridge | 167:84c0a372a020 | 798 | /// .txMethod = FIFO_MODE, |
AnnaBridge | 167:84c0a372a020 | 799 | /// .rxMethod = FIFO_MODE, |
AnnaBridge | 167:84c0a372a020 | 800 | /// }; |
AnnaBridge | 167:84c0a372a020 | 801 | /// |
AnnaBridge | 167:84c0a372a020 | 802 | /// // When reading IQ data out of the FIFO, it comes in the following format: |
AnnaBridge | 167:84c0a372a020 | 803 | /// //------------------------------------ |
AnnaBridge | 167:84c0a372a020 | 804 | /// // I[LSB] | I[MSB] | Q[LSB] | Q[MSB] | |
AnnaBridge | 167:84c0a372a020 | 805 | /// //------------------------------------ |
AnnaBridge | 167:84c0a372a020 | 806 | /// @endcode |
AnnaBridge | 167:84c0a372a020 | 807 | /// |
AnnaBridge | 167:84c0a372a020 | 808 | /// @note \ref RAIL_DataConfig_t.txMethod and \ref RAIL_DataConfig_t.rxMethod |
AnnaBridge | 167:84c0a372a020 | 809 | /// must have the same \ref RAIL_DataMethod_t configuration. |
AnnaBridge | 167:84c0a372a020 | 810 | /// |
AnnaBridge | 167:84c0a372a020 | 811 | /// @warning Do not call RAIL_ReadRxFifo() function while in |
AnnaBridge | 167:84c0a372a020 | 812 | /// \ref RAIL_DataMethod_t::PACKET_MODE. |
AnnaBridge | 167:84c0a372a020 | 813 | /// @{ |
Anna Bridge |
142:4eea097334d6 | 814 | |
Anna Bridge |
142:4eea097334d6 | 815 | /** |
Anna Bridge |
142:4eea097334d6 | 816 | * RAIL data management configuration |
Anna Bridge |
142:4eea097334d6 | 817 | * |
Anna Bridge |
160:5571c4ff569f | 818 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 819 | * @param[in] dataConfig RAIL data configuration structure. |
Anna Bridge |
160:5571c4ff569f | 820 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 821 | * |
Anna Bridge |
142:4eea097334d6 | 822 | * This function configures how RAIL manages data. The application can |
Anna Bridge |
160:5571c4ff569f | 823 | * configure RAIL to receive data in a packet-based or FIFO-based format. |
Anna Bridge |
160:5571c4ff569f | 824 | * FIFO mode is necessary to support packets larger than the radio's |
Anna Bridge |
160:5571c4ff569f | 825 | * FIFO buffers. |
Anna Bridge |
142:4eea097334d6 | 826 | * |
Anna Bridge |
160:5571c4ff569f | 827 | * With FIFO mode, the application sets appropriate FIFO thresholds via |
Anna Bridge |
160:5571c4ff569f | 828 | * RAIL_SetTxFifoThreshold() and RAIL_SetRxFifoThreshold(), and then |
Anna Bridge |
160:5571c4ff569f | 829 | * enables and handles the \ref RAIL_EVENT_TX_FIFO_ALMOST_EMPTY event |
Anna Bridge |
160:5571c4ff569f | 830 | * callback (to feed more packet data via RAIL_WriteTxFifo() before the |
Anna Bridge |
160:5571c4ff569f | 831 | * FIFO underflows), and the \ref RAIL_EVENT_RX_FIFO_ALMOST_FULL event |
Anna Bridge |
160:5571c4ff569f | 832 | * callback (to consume packet data via RAIL_ReadRxFifo() before the |
Anna Bridge |
160:5571c4ff569f | 833 | * RX FIFO overflows). |
Anna Bridge |
160:5571c4ff569f | 834 | * |
Anna Bridge |
160:5571c4ff569f | 835 | * When configuring TX or RX for FIFO mode, this function resets the configured |
Anna Bridge |
160:5571c4ff569f | 836 | * FIFOs. When configuring TX or RX for Packet mode, this function will reset |
Anna Bridge |
160:5571c4ff569f | 837 | * the corresponding FIFO thresholds such that they won't trigger the |
Anna Bridge |
160:5571c4ff569f | 838 | * \ref RAIL_EVENT_RX_FIFO_ALMOST_FULL or \ref RAIL_EVENT_TX_FIFO_ALMOST_EMPTY |
Anna Bridge |
160:5571c4ff569f | 839 | * events. |
Anna Bridge |
142:4eea097334d6 | 840 | * |
Anna Bridge |
160:5571c4ff569f | 841 | * When \ref RAIL_DataConfig_t.rxMethod is set to \ref |
Anna Bridge |
160:5571c4ff569f | 842 | * RAIL_DataMethod_t.FIFO_MODE, the radio won't drop packet data of |
Anna Bridge |
160:5571c4ff569f | 843 | * aborted or CRC error packets, but will present it to the application |
Anna Bridge |
160:5571c4ff569f | 844 | * to deal with accordingly. On completion of such erroneous packets, the |
Anna Bridge |
160:5571c4ff569f | 845 | * \ref RAIL_Config_t::eventsCallback with \ref RAIL_EVENT_RX_PACKET_ABORTED, |
Anna Bridge |
160:5571c4ff569f | 846 | * \ref RAIL_EVENT_RX_FRAME_ERROR, or \ref RAIL_EVENT_RX_ADDRESS_FILTERED will |
Anna Bridge |
160:5571c4ff569f | 847 | * tell the application it can drop any data it read via RAIL_ReadRxFifo() during reception. |
Anna Bridge |
160:5571c4ff569f | 848 | * For CRC error packets when the \ref RAIL_RX_OPTION_IGNORE_CRC_ERRORS |
Anna Bridge |
160:5571c4ff569f | 849 | * RX option is in effect, the application would check for that from the |
Anna Bridge |
160:5571c4ff569f | 850 | * \ref RAIL_RxPacketStatus_t obtained by calling RAIL_GetRxPacketInfo(). |
Anna Bridge |
160:5571c4ff569f | 851 | * RAIL will automatically flush any remaining packet data after reporting |
Anna Bridge |
160:5571c4ff569f | 852 | * one of these packet completion events, or the application can explicitly |
Anna Bridge |
160:5571c4ff569f | 853 | * flush it by calling RAIL_ReleaseRxPacket(). |
Anna Bridge |
142:4eea097334d6 | 854 | * |
Anna Bridge |
160:5571c4ff569f | 855 | * When \ref RAIL_DataConfig_t.rxMethod is set to \ref |
Anna Bridge |
160:5571c4ff569f | 856 | * RAIL_DataMethod_t.PACKET_MODE, the radio will drop all packet data |
Anna Bridge |
160:5571c4ff569f | 857 | * associated with aborted packets including those with CRC errors (unless |
Anna Bridge |
160:5571c4ff569f | 858 | * configured to ignore CRC errors via the |
Anna Bridge |
160:5571c4ff569f | 859 | * \ref RAIL_RX_OPTION_IGNORE_CRC_ERRORS RX option). The application will |
Anna Bridge |
160:5571c4ff569f | 860 | * never be bothered to deal with packet data from such packets. |
Anna Bridge |
160:5571c4ff569f | 861 | * |
Anna Bridge |
160:5571c4ff569f | 862 | * In either mode, the application can set RX options as needed, and |
Anna Bridge |
160:5571c4ff569f | 863 | * packet details are not available for aborted packets. |
Anna Bridge |
142:4eea097334d6 | 864 | */ |
Anna Bridge |
160:5571c4ff569f | 865 | RAIL_Status_t RAIL_ConfigData(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 866 | const RAIL_DataConfig_t *dataConfig); |
Anna Bridge |
142:4eea097334d6 | 867 | |
Anna Bridge |
142:4eea097334d6 | 868 | /** |
Anna Bridge |
160:5571c4ff569f | 869 | * Writes data to the transmit FIFO. |
Anna Bridge |
142:4eea097334d6 | 870 | * |
Anna Bridge |
160:5571c4ff569f | 871 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 872 | * @param[in] dataPtr Application provided pointer to transmit data |
Anna Bridge |
160:5571c4ff569f | 873 | * @param[in] writeLength Number of bytes to write to the transmit FIFO |
Anna Bridge |
160:5571c4ff569f | 874 | * @param[in] reset If true resets TX FIFO before writing the data. |
Anna Bridge |
160:5571c4ff569f | 875 | * @return The number of bytes written to the transmit FIFO. |
Anna Bridge |
142:4eea097334d6 | 876 | * |
Anna Bridge |
160:5571c4ff569f | 877 | * This function reads data from the provided dataPtr and writes it to the TX |
Anna Bridge |
160:5571c4ff569f | 878 | * FIFO. If the requested writeLength exceeds the current number of bytes open |
Anna Bridge |
160:5571c4ff569f | 879 | * in the transmit FIFO, the function only writes until the transmit FIFO |
Anna Bridge |
160:5571c4ff569f | 880 | * is full. The function returns the number of bytes written to the transmit |
Anna Bridge |
160:5571c4ff569f | 881 | * FIFO, and returns zero if railHandle is NULL or if the TX FIFO is full. |
Anna Bridge |
142:4eea097334d6 | 882 | * |
Anna Bridge |
160:5571c4ff569f | 883 | * @note It is the protocol's packet configuration, as set up by the radio |
Anna Bridge |
160:5571c4ff569f | 884 | * configurator or via RAIL_SetFixedLength(), that determines how many |
Anna Bridge |
160:5571c4ff569f | 885 | * bytes of data are consumed from the TX FIFO for a successful transmit |
Anna Bridge |
160:5571c4ff569f | 886 | * operation, not the writeLength value passed in. If not enough data has |
Anna Bridge |
160:5571c4ff569f | 887 | * been put into the TX FIFO, a \ref RAIL_EVENT_TX_UNDERFLOW event will |
Anna Bridge |
160:5571c4ff569f | 888 | * occur. If too much data, the extra data will either become the first bytes |
Anna Bridge |
160:5571c4ff569f | 889 | * sent in a subsequent packet, or will be thrown away if the FIFO gets |
Anna Bridge |
160:5571c4ff569f | 890 | * reset prior to the next transmit. In general, the proper number of |
Anna Bridge |
160:5571c4ff569f | 891 | * packet bytes to put into the TX FIFO are all payload bytes except for |
Anna Bridge |
160:5571c4ff569f | 892 | * any CRC bytes which the packet configuration would cause to be sent |
Anna Bridge |
160:5571c4ff569f | 893 | * automatically. |
Anna Bridge |
142:4eea097334d6 | 894 | * |
Anna Bridge |
160:5571c4ff569f | 895 | * @note This function does not create a critical section but, depending on the |
Anna Bridge |
160:5571c4ff569f | 896 | * application, a critical section could be appropriate. |
Anna Bridge |
142:4eea097334d6 | 897 | */ |
Anna Bridge |
160:5571c4ff569f | 898 | uint16_t RAIL_WriteTxFifo(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 899 | const uint8_t *dataPtr, |
Anna Bridge |
160:5571c4ff569f | 900 | uint16_t writeLength, |
Anna Bridge |
160:5571c4ff569f | 901 | bool reset); |
Anna Bridge |
142:4eea097334d6 | 902 | |
Anna Bridge |
142:4eea097334d6 | 903 | /** |
Anna Bridge |
160:5571c4ff569f | 904 | * Set the address of the TX FIFO, a circular buffer used for TX data |
Anna Bridge |
142:4eea097334d6 | 905 | * |
Anna Bridge |
160:5571c4ff569f | 906 | * @param[in] railHandle A RAIL instance handle. |
AnnaBridge | 167:84c0a372a020 | 907 | * @param[in,out] addr Pointer to a read-write memory location in RAM |
Anna Bridge |
160:5571c4ff569f | 908 | * used as the TX FIFO. This memory must persist until the next call to |
Anna Bridge |
160:5571c4ff569f | 909 | * this function. |
Anna Bridge |
160:5571c4ff569f | 910 | * @param[in] initLength Number of initial bytes already in the TX FIFO. |
Anna Bridge |
160:5571c4ff569f | 911 | * @param[in] size Desired size of the TX FIFO in bytes. |
Anna Bridge |
160:5571c4ff569f | 912 | * @return Returns the FIFO size in bytes that has been set. |
Anna Bridge |
142:4eea097334d6 | 913 | * |
Anna Bridge |
160:5571c4ff569f | 914 | * This function is used to set the memory location for the TX FIFO. This |
Anna Bridge |
160:5571c4ff569f | 915 | * function must be called at least once before any transmit operations occur. |
Anna Bridge |
142:4eea097334d6 | 916 | * |
Anna Bridge |
160:5571c4ff569f | 917 | * The FIFO size can be determined by the return value of this function. The |
Anna Bridge |
160:5571c4ff569f | 918 | * chosen size is determined based on the available FIFO sizes supported by |
Anna Bridge |
160:5571c4ff569f | 919 | * the hardware. For more on supported FIFO sizes see chip-specific |
Anna Bridge |
160:5571c4ff569f | 920 | * documentation, such as \ref efr32_main. The returned FIFO size will be the |
Anna Bridge |
160:5571c4ff569f | 921 | * closest allowed size less than or equal to the passed in size parameter, |
Anna Bridge |
160:5571c4ff569f | 922 | * unless the size parameter is smaller than the minimum FIFO size. If the |
Anna Bridge |
160:5571c4ff569f | 923 | * initLength parameter is larger than the returned size, than the FIFO will be |
Anna Bridge |
160:5571c4ff569f | 924 | * full up to its size. |
Anna Bridge |
142:4eea097334d6 | 925 | * |
Anna Bridge |
160:5571c4ff569f | 926 | * User may write to the custom memory location directly before calling this |
Anna Bridge |
160:5571c4ff569f | 927 | * function, or use \ref RAIL_WriteTxFifo to write to the memory location after |
Anna Bridge |
160:5571c4ff569f | 928 | * calling this function. For previously-written memory to be set in the TX |
Anna Bridge |
160:5571c4ff569f | 929 | * FIFO, user must specify its initLength. |
Anna Bridge |
160:5571c4ff569f | 930 | * |
Anna Bridge |
160:5571c4ff569f | 931 | * This function reserves the block of RAM starting at txBufPtr with a length |
Anna Bridge |
160:5571c4ff569f | 932 | * of the returned FIFO size. That RAM block is used internally as a circular |
Anna Bridge |
160:5571c4ff569f | 933 | * buffer for the transmit FIFO. The FIFO must be able to hold the entire FIFO |
Anna Bridge |
160:5571c4ff569f | 934 | * size. The caller must guarantee the custom FIFO remains intact and unchanged |
Anna Bridge |
160:5571c4ff569f | 935 | * (except via calls to \ref RAIL_WriteTxFifo) until the next call to this |
Anna Bridge |
160:5571c4ff569f | 936 | * function. |
Anna Bridge |
160:5571c4ff569f | 937 | * |
Anna Bridge |
160:5571c4ff569f | 938 | * @note It is the protocol's packet configuration, as set up by the radio |
Anna Bridge |
160:5571c4ff569f | 939 | * configurator or via RAIL_SetFixedLength(), that determines how many |
Anna Bridge |
160:5571c4ff569f | 940 | * bytes of data are consumed from the TX FIFO for a successful transmit |
Anna Bridge |
160:5571c4ff569f | 941 | * operation, not the initLength value passed in. If not enough data has |
Anna Bridge |
160:5571c4ff569f | 942 | * been put into the TX FIFO, a \ref RAIL_EVENT_TX_UNDERFLOW event will |
Anna Bridge |
160:5571c4ff569f | 943 | * occur. If too much data, the extra data will either become the first bytes |
Anna Bridge |
160:5571c4ff569f | 944 | * sent in a subsequent packet, or will be thrown away if the FIFO gets |
Anna Bridge |
160:5571c4ff569f | 945 | * reset prior to the next transmit. In general, the proper number of |
Anna Bridge |
160:5571c4ff569f | 946 | * packet bytes to put into the TX FIFO are all payload bytes except for |
Anna Bridge |
160:5571c4ff569f | 947 | * any CRC bytes which the packet configuration would cause to be sent |
Anna Bridge |
160:5571c4ff569f | 948 | * automatically. |
Anna Bridge |
142:4eea097334d6 | 949 | */ |
Anna Bridge |
160:5571c4ff569f | 950 | uint16_t RAIL_SetTxFifo(RAIL_Handle_t railHandle, |
AnnaBridge | 167:84c0a372a020 | 951 | uint8_t *addr, |
Anna Bridge |
160:5571c4ff569f | 952 | uint16_t initLength, |
Anna Bridge |
160:5571c4ff569f | 953 | uint16_t size); |
Anna Bridge |
142:4eea097334d6 | 954 | |
Anna Bridge |
142:4eea097334d6 | 955 | /** |
Anna Bridge |
160:5571c4ff569f | 956 | * Reads packet data from RAIL's internal receive FIFO buffer. |
Anna Bridge |
160:5571c4ff569f | 957 | * This function can be used in any RX mode, though in Packet |
Anna Bridge |
160:5571c4ff569f | 958 | * mode it can only be used on the oldest unreleased packet whose |
Anna Bridge |
160:5571c4ff569f | 959 | * RAIL_RxPacketStatus_t is among the RAIL_RX_PACKET_READY_ set. |
Anna Bridge |
142:4eea097334d6 | 960 | * |
Anna Bridge |
160:5571c4ff569f | 961 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 962 | * @param[out] dataPtr An application-provided pointer to store data. |
Anna Bridge |
160:5571c4ff569f | 963 | * If NULL, the data is thrown away rather than copied out. |
Anna Bridge |
160:5571c4ff569f | 964 | * @param[in] readLength A number of packet bytes to read from the FIFO. |
Anna Bridge |
160:5571c4ff569f | 965 | * @return The number of packet bytes read from the receive FIFO. |
Anna Bridge |
142:4eea097334d6 | 966 | * |
Anna Bridge |
160:5571c4ff569f | 967 | * This function reads packet data from the head of receive FIFO and |
Anna Bridge |
160:5571c4ff569f | 968 | * writes it to the provided dataPtr. It does not permit reading more |
Anna Bridge |
160:5571c4ff569f | 969 | * data than is available in the FIFO, nor does it permit reading more |
Anna Bridge |
160:5571c4ff569f | 970 | * data than remains in the oldest unreleased packet. |
Anna Bridge |
142:4eea097334d6 | 971 | * |
Anna Bridge |
160:5571c4ff569f | 972 | * Because this function does not have a critical section, either use it |
Anna Bridge |
160:5571c4ff569f | 973 | * only in one context or make sure function calls are protected to prevent |
Anna Bridge |
160:5571c4ff569f | 974 | * buffer corruption. |
AnnaBridge | 167:84c0a372a020 | 975 | * |
AnnaBridge | 167:84c0a372a020 | 976 | * @note When reading data from an arriving packet that is not yet complete |
AnnaBridge | 167:84c0a372a020 | 977 | * keep in mind its data is highly suspect because it has not yet passed |
AnnaBridge | 167:84c0a372a020 | 978 | * any CRC integrity checking. Also note the packet could be aborted, |
AnnaBridge | 167:84c0a372a020 | 979 | * cancelled, or fail momentarily, invalidating its data in Packet mode. |
AnnaBridge | 167:84c0a372a020 | 980 | * Furthermore, there is a small chance towards the end of packet reception |
AnnaBridge | 167:84c0a372a020 | 981 | * that the RX FIFO could include not only packet data received so far, |
AnnaBridge | 167:84c0a372a020 | 982 | * but also some raw radio-appended info detail bytes that RAIL's |
AnnaBridge | 167:84c0a372a020 | 983 | * packet-completion processing will subsequently deal with. It's up to the |
AnnaBridge | 167:84c0a372a020 | 984 | * application to know its packet format well enough to avoid reading this |
AnnaBridge | 167:84c0a372a020 | 985 | * info as it will corrupt the packet's details and possibly corrupt the |
AnnaBridge | 167:84c0a372a020 | 986 | * RX FIFO buffer. |
Anna Bridge |
142:4eea097334d6 | 987 | */ |
Anna Bridge |
160:5571c4ff569f | 988 | uint16_t RAIL_ReadRxFifo(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 989 | uint8_t *dataPtr, |
Anna Bridge |
160:5571c4ff569f | 990 | uint16_t readLength); |
Anna Bridge |
142:4eea097334d6 | 991 | |
Anna Bridge |
142:4eea097334d6 | 992 | /** |
Anna Bridge |
160:5571c4ff569f | 993 | * Configures the RAIL transmit FIFO almost empty threshold. |
Anna Bridge |
142:4eea097334d6 | 994 | * |
Anna Bridge |
160:5571c4ff569f | 995 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 996 | * @param[in] txThreshold The threshold once fallen under will fire \ref RAIL_Config_t::eventsCallback |
Anna Bridge |
160:5571c4ff569f | 997 | * with \ref RAIL_EVENT_TX_FIFO_ALMOST_EMPTY set. |
Anna Bridge |
160:5571c4ff569f | 998 | * @return Configured transmit FIFO threshold value. |
Anna Bridge |
142:4eea097334d6 | 999 | * |
Anna Bridge |
160:5571c4ff569f | 1000 | * This function configures the threshold for the transmit FIFO. When the count |
Anna Bridge |
160:5571c4ff569f | 1001 | * of the transmit FIFO is less than the configured threshold, \ref RAIL_Config_t::eventsCallback |
Anna Bridge |
160:5571c4ff569f | 1002 | * will fire with \ref RAIL_EVENT_TX_FIFO_ALMOST_EMPTY set. A value of |
Anna Bridge |
160:5571c4ff569f | 1003 | * 0 is invalid and will not change the current configuration. |
Anna Bridge |
142:4eea097334d6 | 1004 | */ |
Anna Bridge |
160:5571c4ff569f | 1005 | uint16_t RAIL_SetTxFifoThreshold(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1006 | uint16_t txThreshold); |
Anna Bridge |
142:4eea097334d6 | 1007 | |
Anna Bridge |
142:4eea097334d6 | 1008 | /** |
Anna Bridge |
160:5571c4ff569f | 1009 | * Configures the RAIL receive FIFO almost full threshold. |
Anna Bridge |
142:4eea097334d6 | 1010 | * |
Anna Bridge |
160:5571c4ff569f | 1011 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1012 | * @param[in] rxThreshold The threshold once exceeded will fire \ref RAIL_Config_t::eventsCallback |
Anna Bridge |
160:5571c4ff569f | 1013 | * with \ref RAIL_EVENT_RX_FIFO_ALMOST_FULL set. |
Anna Bridge |
160:5571c4ff569f | 1014 | * @return Configured receive FIFO threshold value. |
Anna Bridge |
142:4eea097334d6 | 1015 | * |
Anna Bridge |
160:5571c4ff569f | 1016 | * This function configures the threshold for the receive FIFO. When the count |
Anna Bridge |
160:5571c4ff569f | 1017 | * of the receive FIFO is greater than the configured threshold, |
AnnaBridge | 167:84c0a372a020 | 1018 | * \ref RAIL_Config_t::eventsCallback will fire with |
AnnaBridge | 167:84c0a372a020 | 1019 | * \ref RAIL_EVENT_RX_FIFO_ALMOST_FULL set. A value of 0xFFFF is invalid and |
AnnaBridge | 167:84c0a372a020 | 1020 | * will not change the current configuration. Depending on the size of the |
AnnaBridge | 167:84c0a372a020 | 1021 | * receive FIFO hardware, the maximum value can vary. If the rxThreshold value |
AnnaBridge | 167:84c0a372a020 | 1022 | * exceeds the capability of the hardware, the RX threshold will be configured |
AnnaBridge | 167:84c0a372a020 | 1023 | * so that it fires only when the FIFO is one byte away from being full. |
Anna Bridge |
160:5571c4ff569f | 1024 | */ |
Anna Bridge |
160:5571c4ff569f | 1025 | uint16_t RAIL_SetRxFifoThreshold(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1026 | uint16_t rxThreshold); |
Anna Bridge |
160:5571c4ff569f | 1027 | |
Anna Bridge |
160:5571c4ff569f | 1028 | /** |
Anna Bridge |
160:5571c4ff569f | 1029 | * Gets the RAIL transmit FIFO almost empty threshold value. |
Anna Bridge |
142:4eea097334d6 | 1030 | * |
Anna Bridge |
160:5571c4ff569f | 1031 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1032 | * @return Configured TX Threshold value. |
Anna Bridge |
160:5571c4ff569f | 1033 | * |
Anna Bridge |
160:5571c4ff569f | 1034 | * Retrieves the configured TX threshold value. |
Anna Bridge |
142:4eea097334d6 | 1035 | */ |
Anna Bridge |
160:5571c4ff569f | 1036 | uint16_t RAIL_GetTxFifoThreshold(RAIL_Handle_t railHandle); |
Anna Bridge |
142:4eea097334d6 | 1037 | |
Anna Bridge |
142:4eea097334d6 | 1038 | /** |
Anna Bridge |
160:5571c4ff569f | 1039 | * Gets the RAIL receive FIFO almost full threshold value. |
Anna Bridge |
160:5571c4ff569f | 1040 | * |
Anna Bridge |
160:5571c4ff569f | 1041 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1042 | * @return Configured RX Threshold value. |
Anna Bridge |
142:4eea097334d6 | 1043 | * |
Anna Bridge |
160:5571c4ff569f | 1044 | * Retrieves the configured RX threshold value. |
Anna Bridge |
160:5571c4ff569f | 1045 | */ |
Anna Bridge |
160:5571c4ff569f | 1046 | uint16_t RAIL_GetRxFifoThreshold(RAIL_Handle_t railHandle); |
Anna Bridge |
160:5571c4ff569f | 1047 | |
Anna Bridge |
160:5571c4ff569f | 1048 | /** |
Anna Bridge |
160:5571c4ff569f | 1049 | * Resets the RAIL FIFOs. |
Anna Bridge |
142:4eea097334d6 | 1050 | * |
Anna Bridge |
160:5571c4ff569f | 1051 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1052 | * @param[in] txFifo If true, reset the transmit FIFO. |
Anna Bridge |
160:5571c4ff569f | 1053 | * @param[in] rxFifo If true, reset the receive FIFO. |
Anna Bridge |
160:5571c4ff569f | 1054 | * @return void. |
Anna Bridge |
142:4eea097334d6 | 1055 | * |
Anna Bridge |
160:5571c4ff569f | 1056 | * This function can reset each FIFO. The application should not reset the RX |
Anna Bridge |
160:5571c4ff569f | 1057 | * FIFO while receiving a frame. |
Anna Bridge |
160:5571c4ff569f | 1058 | */ |
Anna Bridge |
160:5571c4ff569f | 1059 | void RAIL_ResetFifo(RAIL_Handle_t railHandle, bool txFifo, bool rxFifo); |
Anna Bridge |
160:5571c4ff569f | 1060 | |
Anna Bridge |
160:5571c4ff569f | 1061 | /** |
Anna Bridge |
160:5571c4ff569f | 1062 | * Get the number of bytes available in the receive FIFO. |
Anna Bridge |
160:5571c4ff569f | 1063 | * This function should only be used in RX FIFO mode; apps should |
Anna Bridge |
160:5571c4ff569f | 1064 | * probably be using RAIL_GetRxPacketInfo() instead. |
Anna Bridge |
160:5571c4ff569f | 1065 | * |
Anna Bridge |
160:5571c4ff569f | 1066 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1067 | * @return Number of raw bytes in the receive FIFO. |
Anna Bridge |
142:4eea097334d6 | 1068 | * |
Anna Bridge |
160:5571c4ff569f | 1069 | * @note The number of bytes returned may not just reflect the current |
Anna Bridge |
160:5571c4ff569f | 1070 | * packet's data but could also include raw appended info bytes added |
Anna Bridge |
160:5571c4ff569f | 1071 | * after successful packet reception and bytes from subsequently received |
AnnaBridge | 167:84c0a372a020 | 1072 | * packets. It is up to the app to never try to consume more than the |
AnnaBridge | 167:84c0a372a020 | 1073 | * packet's actual data when using the value returned here in a subsequent |
AnnaBridge | 167:84c0a372a020 | 1074 | * call to RAIL_ReadRxFifo(), otherwise the Rx buffer will be corrupted. |
Anna Bridge |
142:4eea097334d6 | 1075 | */ |
Anna Bridge |
160:5571c4ff569f | 1076 | uint16_t RAIL_GetRxFifoBytesAvailable(RAIL_Handle_t railHandle); |
Anna Bridge |
160:5571c4ff569f | 1077 | |
Anna Bridge |
142:4eea097334d6 | 1078 | /** |
Anna Bridge |
160:5571c4ff569f | 1079 | * Gets the number of bytes open in the transmit FIFO. |
Anna Bridge |
160:5571c4ff569f | 1080 | * |
Anna Bridge |
160:5571c4ff569f | 1081 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1082 | * @return Number of bytes open in the transmit FIFO. |
Anna Bridge |
160:5571c4ff569f | 1083 | * |
Anna Bridge |
160:5571c4ff569f | 1084 | * Gets the number of bytes open in the transmit FIFO. |
Anna Bridge |
142:4eea097334d6 | 1085 | */ |
Anna Bridge |
160:5571c4ff569f | 1086 | uint16_t RAIL_GetTxFifoSpaceAvailable(RAIL_Handle_t railHandle); |
Anna Bridge |
160:5571c4ff569f | 1087 | |
Anna Bridge |
160:5571c4ff569f | 1088 | /** @} */ // end of group Data_Management |
Anna Bridge |
142:4eea097334d6 | 1089 | |
Anna Bridge |
142:4eea097334d6 | 1090 | /****************************************************************************** |
Anna Bridge |
160:5571c4ff569f | 1091 | * State Transitions |
Anna Bridge |
142:4eea097334d6 | 1092 | *****************************************************************************/ |
Anna Bridge |
142:4eea097334d6 | 1093 | /** |
Anna Bridge |
160:5571c4ff569f | 1094 | * @addtogroup State_Transitions State Transitions |
Anna Bridge |
142:4eea097334d6 | 1095 | * @{ |
Anna Bridge |
142:4eea097334d6 | 1096 | */ |
Anna Bridge |
142:4eea097334d6 | 1097 | |
Anna Bridge |
142:4eea097334d6 | 1098 | /** |
Anna Bridge |
160:5571c4ff569f | 1099 | * Configures RAIL automatic state transitions after RX. |
Anna Bridge |
142:4eea097334d6 | 1100 | * |
Anna Bridge |
160:5571c4ff569f | 1101 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1102 | * @param[in] transitions The state transitions to apply after reception. |
Anna Bridge |
160:5571c4ff569f | 1103 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 1104 | * |
Anna Bridge |
160:5571c4ff569f | 1105 | * This function fails if unsupported transitions are passed in or if the |
Anna Bridge |
160:5571c4ff569f | 1106 | * radio is currently in the RX state. Success can transition to TX, RX, or |
Anna Bridge |
160:5571c4ff569f | 1107 | * IDLE, while error can transition to RX or IDLE. |
Anna Bridge |
142:4eea097334d6 | 1108 | */ |
Anna Bridge |
160:5571c4ff569f | 1109 | RAIL_Status_t RAIL_SetRxTransitions(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1110 | const RAIL_StateTransitions_t *transitions); |
Anna Bridge |
142:4eea097334d6 | 1111 | |
Anna Bridge |
142:4eea097334d6 | 1112 | /** |
Anna Bridge |
160:5571c4ff569f | 1113 | * Configures RAIL automatic state transitions after TX. |
Anna Bridge |
142:4eea097334d6 | 1114 | * |
Anna Bridge |
160:5571c4ff569f | 1115 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1116 | * @param[in] transitions The state transitions to apply after transmission. |
Anna Bridge |
160:5571c4ff569f | 1117 | * @return Status code indicating a success of the function call. |
Anna Bridge |
142:4eea097334d6 | 1118 | * |
Anna Bridge |
160:5571c4ff569f | 1119 | * This function fails if unsupported transitions are passed in or if the |
Anna Bridge |
160:5571c4ff569f | 1120 | * radio is currently in the TX state. Success and error can each transition |
Anna Bridge |
160:5571c4ff569f | 1121 | * to RX or IDLE. |
Anna Bridge |
142:4eea097334d6 | 1122 | */ |
Anna Bridge |
160:5571c4ff569f | 1123 | RAIL_Status_t RAIL_SetTxTransitions(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1124 | const RAIL_StateTransitions_t *transitions); |
Anna Bridge |
142:4eea097334d6 | 1125 | |
Anna Bridge |
142:4eea097334d6 | 1126 | /** |
Anna Bridge |
160:5571c4ff569f | 1127 | * Configures RAIL automatic state transition timing. |
Anna Bridge |
142:4eea097334d6 | 1128 | * |
Anna Bridge |
160:5571c4ff569f | 1129 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1130 | * @param[in,out] timings The timings used to configure the RAIL state |
Anna Bridge |
160:5571c4ff569f | 1131 | * machine. This structure is overwritten with the actual times that were |
Anna Bridge |
160:5571c4ff569f | 1132 | * set, if an input timing is invalid. |
Anna Bridge |
160:5571c4ff569f | 1133 | * @return Status code indicating a success of the function call. |
Anna Bridge |
142:4eea097334d6 | 1134 | * |
Anna Bridge |
160:5571c4ff569f | 1135 | * The timings given are close to the actual transition time. However, |
Anna Bridge |
160:5571c4ff569f | 1136 | * a still uncharacterized software overhead occurs. Also, timings are not |
Anna Bridge |
160:5571c4ff569f | 1137 | * always adhered to when using an automatic transition after an error, due to |
Anna Bridge |
160:5571c4ff569f | 1138 | * the cleanup required to recover from the error. |
Anna Bridge |
142:4eea097334d6 | 1139 | */ |
Anna Bridge |
160:5571c4ff569f | 1140 | RAIL_Status_t RAIL_SetStateTiming(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1141 | RAIL_StateTiming_t *timings); |
Anna Bridge |
142:4eea097334d6 | 1142 | |
Anna Bridge |
142:4eea097334d6 | 1143 | /** |
Anna Bridge |
160:5571c4ff569f | 1144 | * Places the radio into an idle state. |
Anna Bridge |
142:4eea097334d6 | 1145 | * |
Anna Bridge |
160:5571c4ff569f | 1146 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1147 | * @param[in] mode The method for shutting down the radio. |
Anna Bridge |
160:5571c4ff569f | 1148 | * @param[in] wait Whether this function should wait for the radio to reach |
Anna Bridge |
160:5571c4ff569f | 1149 | * idle before returning. |
Anna Bridge |
160:5571c4ff569f | 1150 | * @return void. |
Anna Bridge |
142:4eea097334d6 | 1151 | * |
AnnaBridge | 167:84c0a372a020 | 1152 | * This function is used to remove the radio from TX and RX states. How these |
AnnaBridge | 167:84c0a372a020 | 1153 | * states are left is defined by the mode parameter. |
AnnaBridge | 167:84c0a372a020 | 1154 | * |
AnnaBridge | 167:84c0a372a020 | 1155 | * In multiprotocol, this API will also cause the radio to be yielded so that |
AnnaBridge | 167:84c0a372a020 | 1156 | * other tasks can be run. See \ref rail_radio_scheduler_yield for more details. |
Anna Bridge |
142:4eea097334d6 | 1157 | */ |
Anna Bridge |
160:5571c4ff569f | 1158 | void RAIL_Idle(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1159 | RAIL_IdleMode_t mode, |
Anna Bridge |
160:5571c4ff569f | 1160 | bool wait); |
Anna Bridge |
142:4eea097334d6 | 1161 | |
Anna Bridge |
142:4eea097334d6 | 1162 | /** |
Anna Bridge |
160:5571c4ff569f | 1163 | * Gets the current radio state. |
Anna Bridge |
142:4eea097334d6 | 1164 | * |
Anna Bridge |
160:5571c4ff569f | 1165 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1166 | * @return An enumeration for the current radio state. |
Anna Bridge |
142:4eea097334d6 | 1167 | * |
Anna Bridge |
160:5571c4ff569f | 1168 | * Returns the state of the radio as a bitmask containing: |
Anna Bridge |
160:5571c4ff569f | 1169 | * \ref RAIL_RF_STATE_IDLE, \ref RAIL_RF_STATE_RX, \ref RAIL_RF_STATE_TX, |
Anna Bridge |
160:5571c4ff569f | 1170 | * and \ref RAIL_RF_STATE_ACTIVE. \ref RAIL_RF_STATE_IDLE, \ref |
Anna Bridge |
160:5571c4ff569f | 1171 | * RAIL_RF_STATE_RX, and \ref RAIL_RF_STATE_TX bits are mutually exclusive. |
Anna Bridge |
160:5571c4ff569f | 1172 | * The radio can transition through intermediate states, |
Anna Bridge |
160:5571c4ff569f | 1173 | * which are not reported but are instead bucketed into the state |
Anna Bridge |
160:5571c4ff569f | 1174 | * being transitioned into. For example, when the transmitter is in the |
Anna Bridge |
160:5571c4ff569f | 1175 | * process of shutting down, this function will return TX, as if the |
Anna Bridge |
160:5571c4ff569f | 1176 | * shutdown process hadn't started yet. |
Anna Bridge |
142:4eea097334d6 | 1177 | */ |
Anna Bridge |
160:5571c4ff569f | 1178 | RAIL_RadioState_t RAIL_GetRadioState(RAIL_Handle_t railHandle); |
Anna Bridge |
142:4eea097334d6 | 1179 | |
Anna Bridge |
160:5571c4ff569f | 1180 | /** @} */ // end of group State_Transitions |
Anna Bridge |
142:4eea097334d6 | 1181 | |
Anna Bridge |
142:4eea097334d6 | 1182 | /****************************************************************************** |
Anna Bridge |
142:4eea097334d6 | 1183 | * Transmit |
Anna Bridge |
142:4eea097334d6 | 1184 | *****************************************************************************/ |
Anna Bridge |
142:4eea097334d6 | 1185 | /** |
Anna Bridge |
142:4eea097334d6 | 1186 | * @addtogroup Transmit |
Anna Bridge |
142:4eea097334d6 | 1187 | * @brief APIs related to transmitting data packets |
Anna Bridge |
142:4eea097334d6 | 1188 | * @{ |
Anna Bridge |
142:4eea097334d6 | 1189 | */ |
Anna Bridge |
142:4eea097334d6 | 1190 | |
AnnaBridge | 167:84c0a372a020 | 1191 | /// @addtogroup PA Power Amplifier (PA) |
AnnaBridge | 167:84c0a372a020 | 1192 | /// @brief APIs for interacting with one of the on chip PAs. |
AnnaBridge | 167:84c0a372a020 | 1193 | /// |
AnnaBridge | 167:84c0a372a020 | 1194 | /// These APIs let you configure the on chip PA to get the appropriate output |
AnnaBridge | 167:84c0a372a020 | 1195 | /// power. |
AnnaBridge | 167:84c0a372a020 | 1196 | /// |
AnnaBridge | 167:84c0a372a020 | 1197 | /// There a few types of functions that are found here |
AnnaBridge | 167:84c0a372a020 | 1198 | /// 1) Configuration functions: These functions set and get configuration |
AnnaBridge | 167:84c0a372a020 | 1199 | /// for the PA. In this case, "configuration" refers to a) indicating |
AnnaBridge | 167:84c0a372a020 | 1200 | /// which PA to use, b) the voltage supplied by your board to the PA, |
AnnaBridge | 167:84c0a372a020 | 1201 | /// and c) the ramp time over which to ramp the PA up to its full |
AnnaBridge | 167:84c0a372a020 | 1202 | /// power. |
AnnaBridge | 167:84c0a372a020 | 1203 | /// 2) Power-setting functions: These functions consume the actual |
AnnaBridge | 167:84c0a372a020 | 1204 | /// values written to the PA registers, and write them appropriately. |
AnnaBridge | 167:84c0a372a020 | 1205 | /// These values are referred to as "(raw) power levels". The range of |
AnnaBridge | 167:84c0a372a020 | 1206 | /// acceptable values for these functions depends on which PA is |
AnnaBridge | 167:84c0a372a020 | 1207 | /// currently active. The higher the power level set, the higher |
AnnaBridge | 167:84c0a372a020 | 1208 | /// the dBm power actually output by the chip. However, the mapping |
AnnaBridge | 167:84c0a372a020 | 1209 | /// between dBm and these power levels can vary greatly between |
AnnaBridge | 167:84c0a372a020 | 1210 | /// modules/boards. |
AnnaBridge | 167:84c0a372a020 | 1211 | /// 3) Conversion functions: These functions do the work of converting |
AnnaBridge | 167:84c0a372a020 | 1212 | /// between the "power levels" discussed previously and the actual |
AnnaBridge | 167:84c0a372a020 | 1213 | /// dBm values output by the chip. Continue reading for more details |
AnnaBridge | 167:84c0a372a020 | 1214 | /// on how to handle unit conversion. |
AnnaBridge | 167:84c0a372a020 | 1215 | /// |
AnnaBridge | 167:84c0a372a020 | 1216 | /// The accuracy of the chip output power in dBm will vary from application to |
AnnaBridge | 167:84c0a372a020 | 1217 | /// to application. For some protocols or channels the protocol itself or |
AnnaBridge | 167:84c0a372a020 | 1218 | /// legal limitations will require applications to know exactly what power |
AnnaBridge | 167:84c0a372a020 | 1219 | /// they're transmitting at, in dBm. Other applications will not have |
AnnaBridge | 167:84c0a372a020 | 1220 | /// these restrictions, and users will simply find some power level(s) |
AnnaBridge | 167:84c0a372a020 | 1221 | /// that fit their criteria for the trade-off between radio range and |
AnnaBridge | 167:84c0a372a020 | 1222 | /// power savings, regardless of what dBm power that maps to. |
AnnaBridge | 167:84c0a372a020 | 1223 | /// |
AnnaBridge | 167:84c0a372a020 | 1224 | /// In order to provide a solution that fits all these applications, |
AnnaBridge | 167:84c0a372a020 | 1225 | /// Silicon Labs has provided a great deal of flexibility in |
AnnaBridge | 167:84c0a372a020 | 1226 | /// \ref RAIL_ConvertRawToDbm and \ref RAIL_ConvertDbmToRaw, the two functions |
AnnaBridge | 167:84c0a372a020 | 1227 | /// that do the conversion between the dBm power and the raw power levels. |
AnnaBridge | 167:84c0a372a020 | 1228 | /// Those levels of customizability are outlined below |
AnnaBridge | 167:84c0a372a020 | 1229 | /// 1) No customizability needed: for a given dBm value, the result |
AnnaBridge | 167:84c0a372a020 | 1230 | /// of RAIL_ConvertDbmToRaw provides an appropriate |
AnnaBridge | 167:84c0a372a020 | 1231 | /// raw power level that, when written to the registers via |
AnnaBridge | 167:84c0a372a020 | 1232 | /// RAIL_SetPowerLevel, causes the chip to actually output at that |
AnnaBridge | 167:84c0a372a020 | 1233 | /// dBm power. In this case, no action is needed by the user, |
AnnaBridge | 167:84c0a372a020 | 1234 | /// the WEAK versions of the conversion functions can be used, |
AnnaBridge | 167:84c0a372a020 | 1235 | /// and the default include paths in pa_conversions_efr32.h can |
AnnaBridge | 167:84c0a372a020 | 1236 | /// be used. |
AnnaBridge | 167:84c0a372a020 | 1237 | /// 2) The mapping of power level to dBm is not good, but the |
AnnaBridge | 167:84c0a372a020 | 1238 | /// level of precision is sufficient: In pa_conversions_efr32.c |
AnnaBridge | 167:84c0a372a020 | 1239 | /// the WEAK versions of the conversion functions work by using |
AnnaBridge | 167:84c0a372a020 | 1240 | /// 8-segment piecewise linear curves to convert between dBm |
AnnaBridge | 167:84c0a372a020 | 1241 | /// and power levels for PA's with hundreds of power levels |
AnnaBridge | 167:84c0a372a020 | 1242 | /// and simple mapping tables for use with PA's with only a few |
AnnaBridge | 167:84c0a372a020 | 1243 | /// levels. If this method is sufficiently precise, but the mapping |
AnnaBridge | 167:84c0a372a020 | 1244 | /// between power levels and dBm is wrong, Silicon Labs recommends |
AnnaBridge | 167:84c0a372a020 | 1245 | /// copying pa_curves_efr32.h into a new file, updating the segments |
AnnaBridge | 167:84c0a372a020 | 1246 | /// to form a better fit (_DCDC_CURVES or _VBAT_CURVES defines), and |
AnnaBridge | 167:84c0a372a020 | 1247 | /// then adding the RAIL_PA_CURVES define to your build with the path |
AnnaBridge | 167:84c0a372a020 | 1248 | /// to the new file. |
AnnaBridge | 167:84c0a372a020 | 1249 | /// 3) A different level of precision is needed and the fit is bad: |
AnnaBridge | 167:84c0a372a020 | 1250 | /// If the piecewise-linear line segment fit is not appropriate for |
AnnaBridge | 167:84c0a372a020 | 1251 | /// your solution, the functions in pa_conversions_efr32.c can be |
AnnaBridge | 167:84c0a372a020 | 1252 | /// totally rewritten, as long as RAIL_ConvertDbmToRaw and |
AnnaBridge | 167:84c0a372a020 | 1253 | /// RAIL_ConvertRawToDbm have the same signatures. It is completely |
AnnaBridge | 167:84c0a372a020 | 1254 | /// acceptable to re-write these in a way that makes the |
AnnaBridge | 167:84c0a372a020 | 1255 | /// pa_curves_efr32.h and pa_curve_types_efr32.h files referenced in |
AnnaBridge | 167:84c0a372a020 | 1256 | /// pa_conversions_efr32.h unnecessary. Those files are needed solely |
AnnaBridge | 167:84c0a372a020 | 1257 | /// for the conversion methods that Silicon Labs provides. |
AnnaBridge | 167:84c0a372a020 | 1258 | /// 4) dBm values are not necessary: If your application does not require |
AnnaBridge | 167:84c0a372a020 | 1259 | /// dBm values at all, Silicon Labs recommends overwriting |
AnnaBridge | 167:84c0a372a020 | 1260 | /// RAIL_ConvertDbmToRaw and RAIL_ConvertRawToDbm with smaller functions |
AnnaBridge | 167:84c0a372a020 | 1261 | /// (i.e. return 0 or whatever was input). These functions are called |
AnnaBridge | 167:84c0a372a020 | 1262 | /// from within the RAIL library, so they can never be deadstripped, |
AnnaBridge | 167:84c0a372a020 | 1263 | /// but making them as small as possible is the best way to reduce code |
AnnaBridge | 167:84c0a372a020 | 1264 | /// size. From there, you can simply call RAIL_SetTxPower, without |
AnnaBridge | 167:84c0a372a020 | 1265 | /// converting from a dBm value. If you never want the library to coerce the |
AnnaBridge | 167:84c0a372a020 | 1266 | /// power based on channels, RAIL_ConvertRawToDbm should be overwritten |
AnnaBridge | 167:84c0a372a020 | 1267 | /// to always return 0 and RAIL_ConvertDbmToRaw should be overwritten to |
AnnaBridge | 167:84c0a372a020 | 1268 | /// always return 255. |
AnnaBridge | 167:84c0a372a020 | 1269 | /// |
AnnaBridge | 167:84c0a372a020 | 1270 | /// The following is example code on how to initialize your PA |
AnnaBridge | 167:84c0a372a020 | 1271 | /// @code{.c} |
AnnaBridge | 167:84c0a372a020 | 1272 | /// |
AnnaBridge | 167:84c0a372a020 | 1273 | /// #include "pa_conversions_efr32.h" |
AnnaBridge | 167:84c0a372a020 | 1274 | /// |
AnnaBridge | 167:84c0a372a020 | 1275 | /// // Helper macro to declare all the curve structures used by the Silicon Labs-provided |
AnnaBridge | 167:84c0a372a020 | 1276 | /// // conversion functions |
AnnaBridge | 167:84c0a372a020 | 1277 | /// RAIL_DECLARE_TX_POWER_VBAT_CURVES(piecewiseSegments, curvesSg, curves24Hp, curves24Lp); |
AnnaBridge | 167:84c0a372a020 | 1278 | /// |
AnnaBridge | 167:84c0a372a020 | 1279 | /// // Put the variables declared above into the appropriate structure |
AnnaBridge | 167:84c0a372a020 | 1280 | /// RAIL_TxPowerCurvesConfig_t txPowerCurvesConfig = { curves24Hp, curvesSg, curves24Lp, piecewiseSegments }; |
AnnaBridge | 167:84c0a372a020 | 1281 | /// |
AnnaBridge | 167:84c0a372a020 | 1282 | /// // In the Silicon Labs implementation, the user is required to save those curves into |
AnnaBridge | 167:84c0a372a020 | 1283 | /// // to be referenced when the conversion functions are called |
AnnaBridge | 167:84c0a372a020 | 1284 | /// RAIL_InitTxPowerCurves(&txPowerCurvesConfig); |
AnnaBridge | 167:84c0a372a020 | 1285 | /// |
AnnaBridge | 167:84c0a372a020 | 1286 | /// // Declare the structure used to configure the PA |
AnnaBridge | 167:84c0a372a020 | 1287 | /// RAIL_TxPowerConfig_t txPowerConfig = { RAIL_TX_POWER_MODE_2P4_HP, 3300, 10 }; |
AnnaBridge | 167:84c0a372a020 | 1288 | /// |
AnnaBridge | 167:84c0a372a020 | 1289 | /// // And then init the PA. Here, it is assumed that 'railHandle' is a valid RAIL_Handle_t |
AnnaBridge | 167:84c0a372a020 | 1290 | /// // that has already been initialized. |
AnnaBridge | 167:84c0a372a020 | 1291 | /// RAIL_ConfigTxPower(railHandle, &txPowerConfig); |
AnnaBridge | 167:84c0a372a020 | 1292 | /// |
AnnaBridge | 167:84c0a372a020 | 1293 | /// // Pick a dBm power to use: 100 deci-dBm = 10 dBm. See docs on RAIL_TxPower_t |
AnnaBridge | 167:84c0a372a020 | 1294 | /// RAIL_TxPower_t power = 100; |
AnnaBridge | 167:84c0a372a020 | 1295 | /// |
AnnaBridge | 167:84c0a372a020 | 1296 | /// // Get the config written by RAIL_ConfigTxPower to confirm what was actually set |
AnnaBridge | 167:84c0a372a020 | 1297 | /// RAIL_GetTxPowerConfig(railHandle, &txPowerConfig); |
AnnaBridge | 167:84c0a372a020 | 1298 | /// |
AnnaBridge | 167:84c0a372a020 | 1299 | /// // RAIL_ConvertDbmToRaw will be the weak version provided by Silicon Labs |
AnnaBridge | 167:84c0a372a020 | 1300 | /// // by default, or the customer version, if overwritten. |
AnnaBridge | 167:84c0a372a020 | 1301 | /// RAIL_TxPowerLevel_t powerLevel = RAIL_ConvertDbmToRaw(railHandle, |
AnnaBridge | 167:84c0a372a020 | 1302 | /// txPowerConfig.mode, |
AnnaBridge | 167:84c0a372a020 | 1303 | /// power); |
AnnaBridge | 167:84c0a372a020 | 1304 | /// |
AnnaBridge | 167:84c0a372a020 | 1305 | /// // Write the result of the conversion to the PA power registers in terms |
AnnaBridge | 167:84c0a372a020 | 1306 | /// // of raw power levels |
AnnaBridge | 167:84c0a372a020 | 1307 | /// RAIL_SetTxPower(railHandle, powerLevel); |
AnnaBridge | 167:84c0a372a020 | 1308 | /// @endcode |
AnnaBridge | 167:84c0a372a020 | 1309 | /// |
AnnaBridge | 167:84c0a372a020 | 1310 | /// @note: all the lines following "RAIL_TxPower_t power = 100;" can be |
AnnaBridge | 167:84c0a372a020 | 1311 | /// replaced with the provided utility function, \ref RAIL_SetTxPowerDbm. |
AnnaBridge | 167:84c0a372a020 | 1312 | /// However, the full example here was provided for clarity. See the |
AnnaBridge | 167:84c0a372a020 | 1313 | /// documentation on \ref RAIL_SetTxPowerDbm for more details. |
AnnaBridge | 167:84c0a372a020 | 1314 | /// |
AnnaBridge | 167:84c0a372a020 | 1315 | /// @{ |
Anna Bridge |
142:4eea097334d6 | 1316 | |
Anna Bridge |
142:4eea097334d6 | 1317 | /** |
Anna Bridge |
160:5571c4ff569f | 1318 | * Initialize TxPower Settings |
Anna Bridge |
160:5571c4ff569f | 1319 | * |
Anna Bridge |
160:5571c4ff569f | 1320 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1321 | * @param[in] config Instance which contains desired initial settings |
Anna Bridge |
160:5571c4ff569f | 1322 | * for the TX amplifier. |
Anna Bridge |
160:5571c4ff569f | 1323 | * @return RAIL_Status_t indicating success or an error. |
Anna Bridge |
160:5571c4ff569f | 1324 | * |
Anna Bridge |
160:5571c4ff569f | 1325 | * These settings include the selection between the multiple TX amplifiers, |
Anna Bridge |
160:5571c4ff569f | 1326 | * voltage supplied to the TX power amplifier, and ramp times. This must |
Anna Bridge |
160:5571c4ff569f | 1327 | * be called before any transmit occurs, or \ref RAIL_SetTxPower is called. |
Anna Bridge |
160:5571c4ff569f | 1328 | * While we recommend always calling this function during initialization, |
Anna Bridge |
160:5571c4ff569f | 1329 | * it can also be called anytime if these settings need to change to adapt |
Anna Bridge |
160:5571c4ff569f | 1330 | * to a different application/protocol. This API will also reset TX Power to |
Anna Bridge |
160:5571c4ff569f | 1331 | * its minimum value, so \ref RAIL_SetTxPower must be called after calling this. |
Anna Bridge |
160:5571c4ff569f | 1332 | * |
Anna Bridge |
160:5571c4ff569f | 1333 | * At times, certain combinations of configurations cannot be achieved. |
Anna Bridge |
160:5571c4ff569f | 1334 | * This API attempts to get as close as possible to the requested settings. The |
Anna Bridge |
160:5571c4ff569f | 1335 | * following "RAIL_Get..." API can be used to determine what values were set. |
Anna Bridge |
160:5571c4ff569f | 1336 | */ |
Anna Bridge |
160:5571c4ff569f | 1337 | RAIL_Status_t RAIL_ConfigTxPower(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1338 | const RAIL_TxPowerConfig_t *config); |
Anna Bridge |
160:5571c4ff569f | 1339 | |
Anna Bridge |
160:5571c4ff569f | 1340 | /** |
Anna Bridge |
160:5571c4ff569f | 1341 | * Get the TX power settings currently used in the amplifier |
Anna Bridge |
160:5571c4ff569f | 1342 | * |
Anna Bridge |
160:5571c4ff569f | 1343 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1344 | * @param[out] config Pointer to memory allocated to hold current TxPower |
Anna Bridge |
160:5571c4ff569f | 1345 | * configuration structure. |
Anna Bridge |
160:5571c4ff569f | 1346 | * @return RAIL_TxPowerConfig_t RAIL status variable indicating whether |
Anna Bridge |
160:5571c4ff569f | 1347 | * or not the get was successful. |
Anna Bridge |
142:4eea097334d6 | 1348 | * |
Anna Bridge |
160:5571c4ff569f | 1349 | * Note, this API does not return the current TX power - that is separately |
Anna Bridge |
160:5571c4ff569f | 1350 | * managed by the \ref RAIL_GetTxPower/\ref RAIL_SetTxPower API's. This API |
Anna Bridge |
160:5571c4ff569f | 1351 | * should be used to know exactly which values were set as a result of |
Anna Bridge |
160:5571c4ff569f | 1352 | * \ref RAIL_ConfigTxPower. |
Anna Bridge |
160:5571c4ff569f | 1353 | */ |
Anna Bridge |
160:5571c4ff569f | 1354 | RAIL_Status_t RAIL_GetTxPowerConfig(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1355 | RAIL_TxPowerConfig_t *config); |
Anna Bridge |
160:5571c4ff569f | 1356 | |
Anna Bridge |
160:5571c4ff569f | 1357 | /** |
Anna Bridge |
160:5571c4ff569f | 1358 | * Set the TX power in units of raw units (see \ref rail_chip_specific.h for |
Anna Bridge |
160:5571c4ff569f | 1359 | * value ranges). |
Anna Bridge |
160:5571c4ff569f | 1360 | * |
Anna Bridge |
160:5571c4ff569f | 1361 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1362 | * @param[in] powerLevel Power in chip specific \ref RAIL_TxPowerLevel_t units. |
Anna Bridge |
160:5571c4ff569f | 1363 | * @return RAIL_Status_t indicating success or an error. |
Anna Bridge |
160:5571c4ff569f | 1364 | * |
Anna Bridge |
160:5571c4ff569f | 1365 | * In order to convert between decibels and the integer values that the |
Anna Bridge |
160:5571c4ff569f | 1366 | * registers take, call \ref RAIL_ConvertDbmToRaw. Silicon Labs provides |
Anna Bridge |
160:5571c4ff569f | 1367 | * a weak version of this function which works well with our boards. However |
Anna Bridge |
160:5571c4ff569f | 1368 | * a customer using his/her own custom board will want to characterize |
Anna Bridge |
160:5571c4ff569f | 1369 | * chip operation on that board and override the function to do the conversion |
Anna Bridge |
160:5571c4ff569f | 1370 | * appropriately from the desired dB values to raw integer values. |
Anna Bridge |
160:5571c4ff569f | 1371 | * |
Anna Bridge |
160:5571c4ff569f | 1372 | * Depending on the configuration used in \ref RAIL_ConfigTxPower, not all |
Anna Bridge |
160:5571c4ff569f | 1373 | * power levels are achievable. This API will get as close as possible to |
Anna Bridge |
160:5571c4ff569f | 1374 | * the desired power without exceeding it, and calling \ref RAIL_GetTxPower is |
Anna Bridge |
160:5571c4ff569f | 1375 | * the only way to know the exact value written. |
Anna Bridge |
160:5571c4ff569f | 1376 | * |
Anna Bridge |
160:5571c4ff569f | 1377 | * Calling this function before configuring the PA (i.e. before a successful |
Anna Bridge |
160:5571c4ff569f | 1378 | * call to \ref RAIL_ConfigTxPower) will cause an error to be returned. |
Anna Bridge |
160:5571c4ff569f | 1379 | */ |
Anna Bridge |
160:5571c4ff569f | 1380 | RAIL_Status_t RAIL_SetTxPower(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1381 | RAIL_TxPowerLevel_t powerLevel); |
Anna Bridge |
160:5571c4ff569f | 1382 | |
Anna Bridge |
160:5571c4ff569f | 1383 | /** |
Anna Bridge |
160:5571c4ff569f | 1384 | * Returns the current power setting of the PA. |
Anna Bridge |
160:5571c4ff569f | 1385 | * |
Anna Bridge |
160:5571c4ff569f | 1386 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1387 | * @return The chip specific \ref RAIL_TxPowerLevel_t value of the current |
Anna Bridge |
160:5571c4ff569f | 1388 | * transmit power. |
Anna Bridge |
142:4eea097334d6 | 1389 | * |
Anna Bridge |
160:5571c4ff569f | 1390 | * This API returns the raw value that was actually set by \ref RAIL_SetTxPower. |
Anna Bridge |
160:5571c4ff569f | 1391 | * Silicon Labs provides a weak version of \ref RAIL_ConvertRawToDbm that works |
Anna Bridge |
160:5571c4ff569f | 1392 | * with our boards to convert these raw values into actual output dBm values. |
Anna Bridge |
160:5571c4ff569f | 1393 | * However, if a customer is using a custom board, we recommend that he/she re- |
Anna Bridge |
160:5571c4ff569f | 1394 | * characterizes the relationship between raw and decibel values, and overrides |
Anna Bridge |
160:5571c4ff569f | 1395 | * the provided function with one more that more accurately reflects the actual |
Anna Bridge |
160:5571c4ff569f | 1396 | * relationship. |
Anna Bridge |
160:5571c4ff569f | 1397 | * |
Anna Bridge |
160:5571c4ff569f | 1398 | * Calling this function before configuring the PA (i.e. before a successful |
Anna Bridge |
160:5571c4ff569f | 1399 | * call to \ref RAIL_ConfigTxPower) will cause an error to be returned |
Anna Bridge |
160:5571c4ff569f | 1400 | * (RAIL_TX_POWER_LEVEL_INVALID). |
Anna Bridge |
160:5571c4ff569f | 1401 | */ |
Anna Bridge |
160:5571c4ff569f | 1402 | RAIL_TxPowerLevel_t RAIL_GetTxPower(RAIL_Handle_t railHandle); |
Anna Bridge |
160:5571c4ff569f | 1403 | |
Anna Bridge |
160:5571c4ff569f | 1404 | /** |
Anna Bridge |
160:5571c4ff569f | 1405 | * Converts raw values written to registers to decibel value (in units of |
Anna Bridge |
160:5571c4ff569f | 1406 | * deci-dBm). |
Anna Bridge |
160:5571c4ff569f | 1407 | * |
Anna Bridge |
160:5571c4ff569f | 1408 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1409 | * @param[in] mode PA mode for which to do the conversion. |
Anna Bridge |
160:5571c4ff569f | 1410 | * @param[in] powerLevel Raw amplifier register value to be converted to |
Anna Bridge |
160:5571c4ff569f | 1411 | * deci-dBm. |
Anna Bridge |
160:5571c4ff569f | 1412 | * @return raw amplifier values converted to units of deci-dBm. |
Anna Bridge |
160:5571c4ff569f | 1413 | * |
Anna Bridge |
160:5571c4ff569f | 1414 | * A weak version of this function is provided by Silicon Labs that is tuned |
Anna Bridge |
160:5571c4ff569f | 1415 | * to provide accurate values for our boards. If the customer intends to use |
Anna Bridge |
160:5571c4ff569f | 1416 | * a custom board, the relationship between what is written to the Tx amplifier |
Anna Bridge |
160:5571c4ff569f | 1417 | * and the actual output power should be re-characterized and implemented in an |
Anna Bridge |
160:5571c4ff569f | 1418 | * overriding version of \ref RAIL_ConvertRawToDbm. For minimum code size and |
Anna Bridge |
160:5571c4ff569f | 1419 | * best speed use only raw values with the TxPower API and override this |
Anna Bridge |
160:5571c4ff569f | 1420 | * function with a smaller function. In the weak version provided with the RAIL |
Anna Bridge |
160:5571c4ff569f | 1421 | * library, railHandle is only used to indicate to the user from where the |
Anna Bridge |
160:5571c4ff569f | 1422 | * function was called, so it is OK to use either a real protocol handle, or one |
Anna Bridge |
160:5571c4ff569f | 1423 | * of the chip specific ones, such as \ref RAIL_EFR32_HANDLE. |
Anna Bridge |
160:5571c4ff569f | 1424 | * |
Anna Bridge |
160:5571c4ff569f | 1425 | * Although the definitions of this function may change, the signature |
Anna Bridge |
160:5571c4ff569f | 1426 | * must be as declared here. |
Anna Bridge |
142:4eea097334d6 | 1427 | */ |
Anna Bridge |
160:5571c4ff569f | 1428 | RAIL_TxPower_t RAIL_ConvertRawToDbm(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1429 | RAIL_TxPowerMode_t mode, |
Anna Bridge |
160:5571c4ff569f | 1430 | RAIL_TxPowerLevel_t powerLevel); |
Anna Bridge |
160:5571c4ff569f | 1431 | |
Anna Bridge |
160:5571c4ff569f | 1432 | /** |
Anna Bridge |
160:5571c4ff569f | 1433 | * Converts the desired decibel value (in units of deci-dBm) |
Anna Bridge |
160:5571c4ff569f | 1434 | * to raw integer values used by the TX amplifier registers. |
Anna Bridge |
160:5571c4ff569f | 1435 | * |
Anna Bridge |
160:5571c4ff569f | 1436 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1437 | * @param[in] mode PA mode for which to do the conversion. |
Anna Bridge |
160:5571c4ff569f | 1438 | * @param[in] power Desired dBm values in units of deci-dBm. |
Anna Bridge |
160:5571c4ff569f | 1439 | * @return deci-dBm value converted to a raw |
Anna Bridge |
160:5571c4ff569f | 1440 | * integer value that can be used directly with \ref RAIL_SetTxPower. |
Anna Bridge |
160:5571c4ff569f | 1441 | * |
Anna Bridge |
160:5571c4ff569f | 1442 | * A weak version of this function is provided by Silicon Labs that is tuned |
Anna Bridge |
160:5571c4ff569f | 1443 | * to provide accurate values for our boards. If the customer intends to use |
Anna Bridge |
160:5571c4ff569f | 1444 | * a custom board, the relationship between what is written to the TX amplifier |
Anna Bridge |
160:5571c4ff569f | 1445 | * and the actual output power should be characterized and implemented in an |
Anna Bridge |
160:5571c4ff569f | 1446 | * overriding version of \ref RAIL_ConvertDbmToRaw. For minimum code size and |
Anna Bridge |
160:5571c4ff569f | 1447 | * best speed use only raw values with the TxPower API and override this |
Anna Bridge |
160:5571c4ff569f | 1448 | * function with a smaller function. In the weak version provided with the RAIL |
Anna Bridge |
160:5571c4ff569f | 1449 | * library, railHandle is only used to indicate to the user from where the |
Anna Bridge |
160:5571c4ff569f | 1450 | * function was called, so it is OK to use either a real protocol handle, or one |
Anna Bridge |
160:5571c4ff569f | 1451 | * of the chip specific ones, such as \ref RAIL_EFR32_HANDLE. |
Anna Bridge |
160:5571c4ff569f | 1452 | * |
Anna Bridge |
160:5571c4ff569f | 1453 | * Although the definitions of this function may change, the signature |
Anna Bridge |
160:5571c4ff569f | 1454 | * must be as declared here. |
Anna Bridge |
160:5571c4ff569f | 1455 | * |
Anna Bridge |
160:5571c4ff569f | 1456 | * @note This function is called from within the RAIL library for |
Anna Bridge |
160:5571c4ff569f | 1457 | * comparison between channel limitations and current power. It will |
Anna Bridge |
160:5571c4ff569f | 1458 | * throw an assert if you haven't called RAIL_InitTxPowerCurves |
Anna Bridge |
160:5571c4ff569f | 1459 | * which initializes the mappings between raw power levels and |
Anna Bridge |
160:5571c4ff569f | 1460 | * actual dBm powers. To avoid this assert, ensure that the |
Anna Bridge |
160:5571c4ff569f | 1461 | * maxPower of all channel config entries is \ref RAIL_TX_POWER_MAX |
Anna Bridge |
160:5571c4ff569f | 1462 | * or above, or override this function to always return 255. |
Anna Bridge |
160:5571c4ff569f | 1463 | */ |
Anna Bridge |
160:5571c4ff569f | 1464 | RAIL_TxPowerLevel_t RAIL_ConvertDbmToRaw(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1465 | RAIL_TxPowerMode_t mode, |
Anna Bridge |
160:5571c4ff569f | 1466 | RAIL_TxPower_t power); |
Anna Bridge |
160:5571c4ff569f | 1467 | |
Anna Bridge |
160:5571c4ff569f | 1468 | /** @} */ // end of group PA |
Anna Bridge |
142:4eea097334d6 | 1469 | |
AnnaBridge | 167:84c0a372a020 | 1470 | /// Sets the TX power in terms of deci-dBm instead of raw power level. |
AnnaBridge | 167:84c0a372a020 | 1471 | /// |
AnnaBridge | 167:84c0a372a020 | 1472 | /// @param[in] railHandle A RAIL instance handle. |
AnnaBridge | 167:84c0a372a020 | 1473 | /// @param[in] power Desired deci-dBm power to be set. |
AnnaBridge | 167:84c0a372a020 | 1474 | /// @return RAIL Status variable indicate whether setting the |
AnnaBridge | 167:84c0a372a020 | 1475 | /// power was successful. |
AnnaBridge | 167:84c0a372a020 | 1476 | /// |
AnnaBridge | 167:84c0a372a020 | 1477 | /// This is a utility function crafted for user convenience. Normally, to set TX |
AnnaBridge | 167:84c0a372a020 | 1478 | /// power in dBm, the user would have to do the following: |
AnnaBridge | 167:84c0a372a020 | 1479 | /// |
AnnaBridge | 167:84c0a372a020 | 1480 | /// @code{.c} |
AnnaBridge | 167:84c0a372a020 | 1481 | /// RAIL_TxPower_t power = 100; // 100 deci-dBm, 10 dBm |
AnnaBridge | 167:84c0a372a020 | 1482 | /// RAIL_TxPowerConfig_t txPowerConfig; |
AnnaBridge | 167:84c0a372a020 | 1483 | /// RAIL_GetTxPowerConfig(railHandle, &txPowerConfig); |
AnnaBridge | 167:84c0a372a020 | 1484 | /// // RAIL_ConvertDbmToRaw will be the weak version provided by Silicon Labs |
AnnaBridge | 167:84c0a372a020 | 1485 | /// // by default, or the customer version, if overwritten. |
AnnaBridge | 167:84c0a372a020 | 1486 | /// RAIL_TxPowerLevel_t powerLevel = RAIL_ConvertDbmToRaw(railHandle, |
AnnaBridge | 167:84c0a372a020 | 1487 | /// txPowerConfig.mode, |
AnnaBridge | 167:84c0a372a020 | 1488 | /// power); |
AnnaBridge | 167:84c0a372a020 | 1489 | /// RAIL_SetTxPower(railHandle, powerLevel); |
AnnaBridge | 167:84c0a372a020 | 1490 | /// @endcode |
AnnaBridge | 167:84c0a372a020 | 1491 | /// |
AnnaBridge | 167:84c0a372a020 | 1492 | /// This function wraps all those calls in a single function with power passed in |
AnnaBridge | 167:84c0a372a020 | 1493 | /// as a parameter. |
AnnaBridge | 167:84c0a372a020 | 1494 | /// |
Anna Bridge |
160:5571c4ff569f | 1495 | RAIL_Status_t RAIL_SetTxPowerDbm(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1496 | RAIL_TxPower_t power); |
Anna Bridge |
160:5571c4ff569f | 1497 | |
AnnaBridge | 167:84c0a372a020 | 1498 | /// Gets the TX power in terms of deci-dBm instead of raw power level. |
AnnaBridge | 167:84c0a372a020 | 1499 | /// |
AnnaBridge | 167:84c0a372a020 | 1500 | /// @param[in] railHandle A RAIL instance handle. |
AnnaBridge | 167:84c0a372a020 | 1501 | /// @return The current output power in deci-dBm |
AnnaBridge | 167:84c0a372a020 | 1502 | /// |
AnnaBridge | 167:84c0a372a020 | 1503 | /// This is a utility function crafted for user convenience. Normally, to get TX |
AnnaBridge | 167:84c0a372a020 | 1504 | /// power in dBm, the user would have to do the following: |
AnnaBridge | 167:84c0a372a020 | 1505 | /// |
AnnaBridge | 167:84c0a372a020 | 1506 | /// @code{.c} |
AnnaBridge | 167:84c0a372a020 | 1507 | /// RAIL_TxPowerLevel_t powerLevel = RAIL_GetTxPower(railHandle); |
AnnaBridge | 167:84c0a372a020 | 1508 | /// RAIL_TxPowerConfig_t txPowerConfig; |
AnnaBridge | 167:84c0a372a020 | 1509 | /// RAIL_GetTxPowerConfig(railHandle, &txPowerConfig); |
AnnaBridge | 167:84c0a372a020 | 1510 | /// // RAIL_ConvertRawToDbm will be the weak version provided by Silicon Labs |
AnnaBridge | 167:84c0a372a020 | 1511 | /// // by default, or the customer version, if overwritten. |
AnnaBridge | 167:84c0a372a020 | 1512 | /// RAIL_TxPower_t power = RAIL_ConvertRawToDbm(railHandle, |
AnnaBridge | 167:84c0a372a020 | 1513 | /// txPowerConfig.mode, |
AnnaBridge | 167:84c0a372a020 | 1514 | /// power); |
AnnaBridge | 167:84c0a372a020 | 1515 | /// return power; |
AnnaBridge | 167:84c0a372a020 | 1516 | /// @endcode |
AnnaBridge | 167:84c0a372a020 | 1517 | /// |
AnnaBridge | 167:84c0a372a020 | 1518 | /// This function wraps all those calls in a single function with power returned |
AnnaBridge | 167:84c0a372a020 | 1519 | /// as the result. |
AnnaBridge | 167:84c0a372a020 | 1520 | /// |
Anna Bridge |
160:5571c4ff569f | 1521 | RAIL_TxPower_t RAIL_GetTxPowerDbm(RAIL_Handle_t railHandle); |
Anna Bridge |
142:4eea097334d6 | 1522 | |
Anna Bridge |
160:5571c4ff569f | 1523 | /** |
Anna Bridge |
160:5571c4ff569f | 1524 | * Start a non-blocking transmit |
Anna Bridge |
160:5571c4ff569f | 1525 | * |
Anna Bridge |
160:5571c4ff569f | 1526 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1527 | * @param[in] channel Define the channel to transmit on. |
Anna Bridge |
160:5571c4ff569f | 1528 | * @param[in] options TX options to be applied to this transmit only. |
Anna Bridge |
160:5571c4ff569f | 1529 | * @param[in] schedulerInfo Information to allow the radio scheduler to place |
Anna Bridge |
160:5571c4ff569f | 1530 | * this transmit appropriately. This is only used in multiprotocol version of |
Anna Bridge |
160:5571c4ff569f | 1531 | * RAIL and may be set to NULL in all other versions. |
Anna Bridge |
160:5571c4ff569f | 1532 | * @return Status code indicating success of the function call. If successfully |
Anna Bridge |
160:5571c4ff569f | 1533 | * initiated, transmit completion or failure will be reported by a later |
Anna Bridge |
160:5571c4ff569f | 1534 | * \ref RAIL_Config_t::eventsCallback with the appropriate \ref RAIL_Events_t. |
Anna Bridge |
160:5571c4ff569f | 1535 | * |
Anna Bridge |
160:5571c4ff569f | 1536 | * Will begin transmission of the payload previously loaded via |
Anna Bridge |
160:5571c4ff569f | 1537 | * \ref RAIL_WriteTxFifo() immediately, or right after a packet currently being |
Anna Bridge |
160:5571c4ff569f | 1538 | * received is completed. |
Anna Bridge |
160:5571c4ff569f | 1539 | * |
Anna Bridge |
160:5571c4ff569f | 1540 | * Returns an error if a previous transmit is still in progress. |
Anna Bridge |
160:5571c4ff569f | 1541 | * If changing channels, any ongoing packet reception is aborted. |
Anna Bridge |
160:5571c4ff569f | 1542 | * |
Anna Bridge |
160:5571c4ff569f | 1543 | * In multiprotocol you must ensure that you properly yield the radio after this |
Anna Bridge |
160:5571c4ff569f | 1544 | * operation completes. See \ref rail_radio_scheduler_yield for more details. |
Anna Bridge |
160:5571c4ff569f | 1545 | */ |
Anna Bridge |
160:5571c4ff569f | 1546 | RAIL_Status_t RAIL_StartTx(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1547 | uint16_t channel, |
Anna Bridge |
160:5571c4ff569f | 1548 | RAIL_TxOptions_t options, |
Anna Bridge |
160:5571c4ff569f | 1549 | const RAIL_SchedulerInfo_t *schedulerInfo); |
Anna Bridge |
142:4eea097334d6 | 1550 | |
Anna Bridge |
142:4eea097334d6 | 1551 | /** |
Anna Bridge |
160:5571c4ff569f | 1552 | * Send a packet on a schedule, instead of immediately |
Anna Bridge |
160:5571c4ff569f | 1553 | * |
Anna Bridge |
160:5571c4ff569f | 1554 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1555 | * @param[in] channel Define the channel to transmit on. |
Anna Bridge |
160:5571c4ff569f | 1556 | * @param[in] options TX options to be applied to this transmit only. |
Anna Bridge |
160:5571c4ff569f | 1557 | * @param[in] config A pointer to the \ref RAIL_ScheduleTxConfig_t |
Anna Bridge |
160:5571c4ff569f | 1558 | * structure containing when the transmit should occur. |
Anna Bridge |
160:5571c4ff569f | 1559 | * @param[in] schedulerInfo Information to allow the radio scheduler to place |
Anna Bridge |
160:5571c4ff569f | 1560 | * this transmit appropriately. This is only used in multiprotocol version of |
Anna Bridge |
160:5571c4ff569f | 1561 | * RAIL and may be set to NULL in all other versions. |
Anna Bridge |
160:5571c4ff569f | 1562 | * @return Status code indicating success of the function call. If successfully |
Anna Bridge |
160:5571c4ff569f | 1563 | * initiated, a transmit completion or failure will be reported by a later |
Anna Bridge |
160:5571c4ff569f | 1564 | * \ref RAIL_Config_t::eventsCallback with the appropriate \ref RAIL_Events_t. |
Anna Bridge |
160:5571c4ff569f | 1565 | * |
Anna Bridge |
160:5571c4ff569f | 1566 | * Will begin transmission of the payload previously loaded via |
Anna Bridge |
160:5571c4ff569f | 1567 | * \ref RAIL_WriteTxFifo() at the scheduled time. |
Anna Bridge |
160:5571c4ff569f | 1568 | * The time (in microseconds) as well as whether that time is absolute or |
Anna Bridge |
160:5571c4ff569f | 1569 | * relative, is specified using the \ref RAIL_ScheduleTxConfig_t structure. |
Anna Bridge |
160:5571c4ff569f | 1570 | * Also specified in this structure is what to do if a scheduled transmit |
Anna Bridge |
160:5571c4ff569f | 1571 | * fires in the midst of receiving a packet. |
Anna Bridge |
160:5571c4ff569f | 1572 | * |
Anna Bridge |
160:5571c4ff569f | 1573 | * Returns an error if a previous transmit is still in progress. |
Anna Bridge |
160:5571c4ff569f | 1574 | * If changing channels, any ongoing packet reception is aborted. |
Anna Bridge |
142:4eea097334d6 | 1575 | * |
Anna Bridge |
160:5571c4ff569f | 1576 | * In multiprotocol you must ensure that you properly yield the radio after this |
Anna Bridge |
160:5571c4ff569f | 1577 | * operation completes. See \ref rail_radio_scheduler_yield for more details. |
Anna Bridge |
160:5571c4ff569f | 1578 | */ |
Anna Bridge |
160:5571c4ff569f | 1579 | RAIL_Status_t RAIL_StartScheduledTx(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1580 | uint16_t channel, |
Anna Bridge |
160:5571c4ff569f | 1581 | RAIL_TxOptions_t options, |
Anna Bridge |
160:5571c4ff569f | 1582 | const RAIL_ScheduleTxConfig_t *config, |
Anna Bridge |
160:5571c4ff569f | 1583 | const RAIL_SchedulerInfo_t *schedulerInfo); |
Anna Bridge |
160:5571c4ff569f | 1584 | |
Anna Bridge |
160:5571c4ff569f | 1585 | /** |
Anna Bridge |
160:5571c4ff569f | 1586 | * Start a non-blocking Transmit using CSMA |
Anna Bridge |
160:5571c4ff569f | 1587 | * |
Anna Bridge |
160:5571c4ff569f | 1588 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1589 | * @param[in] channel Define the channel to transmit on. |
Anna Bridge |
160:5571c4ff569f | 1590 | * @param[in] options TX options to be applied to this transmit only. |
Anna Bridge |
160:5571c4ff569f | 1591 | * @param[in] csmaConfig A pointer to the RAIL_CsmaConfig_t structure |
Anna Bridge |
160:5571c4ff569f | 1592 | * describing the CSMA parameters to use for this transmit. |
Anna Bridge |
160:5571c4ff569f | 1593 | * @param[in] schedulerInfo Information to allow the radio scheduler to place |
Anna Bridge |
160:5571c4ff569f | 1594 | * this transmit appropriately. This is only used in multiprotocol version of |
Anna Bridge |
160:5571c4ff569f | 1595 | * RAIL and may be set to NULL in all other versions. |
Anna Bridge |
160:5571c4ff569f | 1596 | * @return Status code indicating success of the function call. If successfully |
Anna Bridge |
160:5571c4ff569f | 1597 | * initiated, a transmit completion or failure will be reported by a later |
Anna Bridge |
160:5571c4ff569f | 1598 | * \ref RAIL_Config_t::eventsCallback with the appropriate \ref RAIL_Events_t. |
Anna Bridge |
142:4eea097334d6 | 1599 | * |
Anna Bridge |
160:5571c4ff569f | 1600 | * First performs the Carrier Sense Multiple Access (CSMA) algorithm and if |
Anna Bridge |
160:5571c4ff569f | 1601 | * the channel is deemed clear (RSSI below the specified threshold) it will |
Anna Bridge |
160:5571c4ff569f | 1602 | * commence transmission of the payload previously loaded via |
Anna Bridge |
160:5571c4ff569f | 1603 | * RAIL_WriteTxFifo(). |
Anna Bridge |
160:5571c4ff569f | 1604 | * Packets can be received during CSMA backoff periods if receive is active |
Anna Bridge |
160:5571c4ff569f | 1605 | * throughout the CSMA process. This will happen either by starting the CSMA |
Anna Bridge |
160:5571c4ff569f | 1606 | * process while receive is already active, or if the csmaBackoff time in |
Anna Bridge |
160:5571c4ff569f | 1607 | * the \ref RAIL_CsmaConfig_t is less than the idleToRx time (set by |
Anna Bridge |
160:5571c4ff569f | 1608 | * RAIL_SetStateTiming()). If the csmaBackoff time is greater than the |
Anna Bridge |
160:5571c4ff569f | 1609 | * idleToRx time, then receive will only be active during CSMA's clear channel |
Anna Bridge |
160:5571c4ff569f | 1610 | * assessments. |
Anna Bridge |
160:5571c4ff569f | 1611 | * |
Anna Bridge |
160:5571c4ff569f | 1612 | * If the CSMA algorithm deems the channel busy, the \ref RAIL_Config_t::eventsCallback |
Anna Bridge |
160:5571c4ff569f | 1613 | * occurs with \ref RAIL_EVENT_TX_CHANNEL_BUSY, and the contents |
Anna Bridge |
160:5571c4ff569f | 1614 | * of the TX FIFO remain intact, untouched. |
Anna Bridge |
160:5571c4ff569f | 1615 | * |
Anna Bridge |
160:5571c4ff569f | 1616 | * Returns an error if a previous transmit is still in progress. |
Anna Bridge |
160:5571c4ff569f | 1617 | * If changing channels, any ongoing packet reception is aborted. |
Anna Bridge |
160:5571c4ff569f | 1618 | * |
Anna Bridge |
160:5571c4ff569f | 1619 | * In multiprotocol you must ensure that you properly yield the radio after this |
Anna Bridge |
160:5571c4ff569f | 1620 | * operation completes. See \ref rail_radio_scheduler_yield for more details. |
Anna Bridge |
142:4eea097334d6 | 1621 | */ |
Anna Bridge |
160:5571c4ff569f | 1622 | RAIL_Status_t RAIL_StartCcaCsmaTx(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1623 | uint16_t channel, |
Anna Bridge |
160:5571c4ff569f | 1624 | RAIL_TxOptions_t options, |
Anna Bridge |
160:5571c4ff569f | 1625 | const RAIL_CsmaConfig_t *csmaConfig, |
Anna Bridge |
160:5571c4ff569f | 1626 | const RAIL_SchedulerInfo_t *schedulerInfo); |
Anna Bridge |
160:5571c4ff569f | 1627 | |
Anna Bridge |
160:5571c4ff569f | 1628 | /** |
Anna Bridge |
160:5571c4ff569f | 1629 | * Start a non-blocking Transmit using LBT |
Anna Bridge |
160:5571c4ff569f | 1630 | * |
Anna Bridge |
160:5571c4ff569f | 1631 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1632 | * @param[in] channel Define the channel to transmit on. |
Anna Bridge |
160:5571c4ff569f | 1633 | * @param[in] options TX options to be applied to this transmit only. |
Anna Bridge |
160:5571c4ff569f | 1634 | * @param[in] lbtConfig A pointer to the RAIL_LbtConfig_t structure |
Anna Bridge |
160:5571c4ff569f | 1635 | * describing the LBT parameters to use for this transmit. |
Anna Bridge |
160:5571c4ff569f | 1636 | * @param[in] schedulerInfo Information to allow the radio scheduler to place |
Anna Bridge |
160:5571c4ff569f | 1637 | * this transmit appropriately. This is only used in multiprotocol version of |
Anna Bridge |
160:5571c4ff569f | 1638 | * RAIL and may be set to NULL in all other versions. |
Anna Bridge |
160:5571c4ff569f | 1639 | * @return Status code indicating success of the function call. If successfully |
Anna Bridge |
160:5571c4ff569f | 1640 | * initiated, a transmit completion or failure will be reported by a later |
Anna Bridge |
160:5571c4ff569f | 1641 | * \ref RAIL_Config_t::eventsCallback with the appropriate \ref RAIL_Events_t. |
Anna Bridge |
160:5571c4ff569f | 1642 | * |
Anna Bridge |
160:5571c4ff569f | 1643 | * First performs the Listen Before Talk (LBT) algorithm and if the channel |
Anna Bridge |
160:5571c4ff569f | 1644 | * is deemed clear (RSSI below the specified threshold) it will commence |
Anna Bridge |
160:5571c4ff569f | 1645 | * transmission of the payload previously loaded via RAIL_WriteTxFifo(). |
Anna Bridge |
160:5571c4ff569f | 1646 | * Packets can be received during LBT backoff periods if receive is active |
Anna Bridge |
160:5571c4ff569f | 1647 | * throughout the LBT process. This will happen either by starting the LBT |
Anna Bridge |
160:5571c4ff569f | 1648 | * process while receive is already active, or if the lbtBackoff time in |
Anna Bridge |
160:5571c4ff569f | 1649 | * the \ref RAIL_LbtConfig_t is less than the idleToRx time (set by |
Anna Bridge |
160:5571c4ff569f | 1650 | * RAIL_SetStateTiming()). If the lbtBackoff time is greater than the |
Anna Bridge |
160:5571c4ff569f | 1651 | * idleToRx time, then receive will only be active during LBT's clear channel |
Anna Bridge |
160:5571c4ff569f | 1652 | * assessments. |
Anna Bridge |
160:5571c4ff569f | 1653 | * |
Anna Bridge |
160:5571c4ff569f | 1654 | * If the LBT algorithm deems the channel busy, the \ref RAIL_Config_t::eventsCallback occurs with |
Anna Bridge |
160:5571c4ff569f | 1655 | * \ref RAIL_EVENT_TX_CHANNEL_BUSY, and the contents |
Anna Bridge |
160:5571c4ff569f | 1656 | * of the TX FIFO remain intact, untouched. |
Anna Bridge |
160:5571c4ff569f | 1657 | * |
Anna Bridge |
160:5571c4ff569f | 1658 | * Returns an error if a previous transmit is still in progress. |
Anna Bridge |
160:5571c4ff569f | 1659 | * If changing channels, any ongoing packet reception is aborted. |
Anna Bridge |
160:5571c4ff569f | 1660 | * |
Anna Bridge |
160:5571c4ff569f | 1661 | * In multiprotocol you must ensure that you properly yield the radio after this |
Anna Bridge |
160:5571c4ff569f | 1662 | * operation completes. See \ref rail_radio_scheduler_yield for more details. |
Anna Bridge |
160:5571c4ff569f | 1663 | */ |
Anna Bridge |
160:5571c4ff569f | 1664 | RAIL_Status_t RAIL_StartCcaLbtTx(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1665 | uint16_t channel, |
Anna Bridge |
160:5571c4ff569f | 1666 | RAIL_TxOptions_t options, |
Anna Bridge |
160:5571c4ff569f | 1667 | const RAIL_LbtConfig_t *lbtConfig, |
Anna Bridge |
160:5571c4ff569f | 1668 | const RAIL_SchedulerInfo_t *schedulerInfo); |
Anna Bridge |
142:4eea097334d6 | 1669 | |
Anna Bridge |
142:4eea097334d6 | 1670 | /** |
Anna Bridge |
142:4eea097334d6 | 1671 | * Sets the CCA threshold in dBm |
Anna Bridge |
142:4eea097334d6 | 1672 | * |
Anna Bridge |
160:5571c4ff569f | 1673 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1674 | * @param[in] ccaThresholdDbm The CCA threshold in dBm. |
Anna Bridge |
160:5571c4ff569f | 1675 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 1676 | * |
Anna Bridge |
160:5571c4ff569f | 1677 | * Unlike RAIL_StartCcaCsmaTx() or RAIL_StartCcaLbtTx(), which can cause a |
Anna Bridge |
160:5571c4ff569f | 1678 | * transmit, this function only modifies the CCA threshold. A possible |
Anna Bridge |
160:5571c4ff569f | 1679 | * use case for this function is to set the CCA threshold to invalid RSSI |
Anna Bridge |
160:5571c4ff569f | 1680 | * of -128 which blocks transmission by preventing clear channel assessments |
Anna Bridge |
160:5571c4ff569f | 1681 | * from succeeding. |
Anna Bridge |
142:4eea097334d6 | 1682 | */ |
Anna Bridge |
160:5571c4ff569f | 1683 | RAIL_Status_t RAIL_SetCcaThreshold(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1684 | int8_t ccaThresholdDbm); |
Anna Bridge |
142:4eea097334d6 | 1685 | |
Anna Bridge |
142:4eea097334d6 | 1686 | /** |
Anna Bridge |
160:5571c4ff569f | 1687 | * Gets detailed information about the last packet transmitted. |
Anna Bridge |
160:5571c4ff569f | 1688 | * |
Anna Bridge |
160:5571c4ff569f | 1689 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1690 | * @param[in,out] pPacketDetails An application-provided pointer to store |
Anna Bridge |
160:5571c4ff569f | 1691 | * RAIL_TxPacketDetails_t corresponding to the transmit event. |
Anna Bridge |
160:5571c4ff569f | 1692 | * The isAck and timeSent fields totalPacketBytes and timePosition |
Anna Bridge |
160:5571c4ff569f | 1693 | * must be initialized prior to each call: |
Anna Bridge |
160:5571c4ff569f | 1694 | * - isAck true to obtain details about the most recent ACK transmit, |
Anna Bridge |
160:5571c4ff569f | 1695 | * false to obtain details about the most recent app-initiated transmit. |
Anna Bridge |
160:5571c4ff569f | 1696 | * - totalPacketBytes with the total number of bytes of the transmitted |
Anna Bridge |
160:5571c4ff569f | 1697 | * packet for RAIL to use when calculating the specified timestamp. |
Anna Bridge |
160:5571c4ff569f | 1698 | * This should account for all bytes sent over the air after the |
Anna Bridge |
160:5571c4ff569f | 1699 | * Preamble and Sync word(s), including CRC bytes. |
Anna Bridge |
160:5571c4ff569f | 1700 | * - timePosition with a \ref RAIL_PacketTimePosition_t value specifying |
Anna Bridge |
160:5571c4ff569f | 1701 | * the packet position to put in the timeSent field on return. |
Anna Bridge |
160:5571c4ff569f | 1702 | * This field will also be updated with the actual position corresponding |
Anna Bridge |
160:5571c4ff569f | 1703 | * to the timeSent value filled in. |
Anna Bridge |
160:5571c4ff569f | 1704 | * @return \ref RAIL_STATUS_NO_ERROR if pPacketDetails was filled in, |
Anna Bridge |
160:5571c4ff569f | 1705 | * or an appropriate error code otherwise. |
Anna Bridge |
160:5571c4ff569f | 1706 | * |
Anna Bridge |
160:5571c4ff569f | 1707 | * This function can only be called from callback context for either |
Anna Bridge |
160:5571c4ff569f | 1708 | * \ref RAIL_EVENT_TX_PACKET_SENT or \ref RAIL_EVENT_TXACK_PACKET_SENT |
Anna Bridge |
160:5571c4ff569f | 1709 | * events. |
Anna Bridge |
142:4eea097334d6 | 1710 | */ |
Anna Bridge |
160:5571c4ff569f | 1711 | RAIL_Status_t RAIL_GetTxPacketDetails(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1712 | RAIL_TxPacketDetails_t *pPacketDetails); |
Anna Bridge |
160:5571c4ff569f | 1713 | /** |
Anna Bridge |
160:5571c4ff569f | 1714 | * Prevent the radio from starting a transmit. |
Anna Bridge |
160:5571c4ff569f | 1715 | * |
Anna Bridge |
160:5571c4ff569f | 1716 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1717 | * @param[in] enable Enable/Disable TX hold off. |
Anna Bridge |
160:5571c4ff569f | 1718 | * @return void. |
Anna Bridge |
160:5571c4ff569f | 1719 | * |
Anna Bridge |
160:5571c4ff569f | 1720 | * Enable TX hold off to prevent the radio from starting any transmits. |
Anna Bridge |
160:5571c4ff569f | 1721 | * Disable TX hold off to allow the radio to transmit again. |
Anna Bridge |
160:5571c4ff569f | 1722 | * Attempting to transmit with the TX hold off enabled will result in |
Anna Bridge |
160:5571c4ff569f | 1723 | * \ref RAIL_EVENT_TX_BLOCKED and/or \ref RAIL_EVENT_TXACK_BLOCKED |
Anna Bridge |
160:5571c4ff569f | 1724 | * events. |
Anna Bridge |
160:5571c4ff569f | 1725 | * |
Anna Bridge |
160:5571c4ff569f | 1726 | * @note This function does not affect a transmit that has already started. |
Anna Bridge |
160:5571c4ff569f | 1727 | * To stop an already-started transmission, use RAIL_Idle() with |
Anna Bridge |
160:5571c4ff569f | 1728 | * \ref RAIL_IDLE_ABORT. |
Anna Bridge |
160:5571c4ff569f | 1729 | */ |
Anna Bridge |
160:5571c4ff569f | 1730 | void RAIL_EnableTxHoldOff(RAIL_Handle_t railHandle, bool enable); |
Anna Bridge |
142:4eea097334d6 | 1731 | |
Anna Bridge |
142:4eea097334d6 | 1732 | /** |
Anna Bridge |
160:5571c4ff569f | 1733 | * Check whether or not TX hold off is enabled. |
Anna Bridge |
160:5571c4ff569f | 1734 | * |
Anna Bridge |
160:5571c4ff569f | 1735 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1736 | * @return Returns true if TX hold off is enabled, false otherwise. |
Anna Bridge |
160:5571c4ff569f | 1737 | * |
Anna Bridge |
160:5571c4ff569f | 1738 | * TX hold off can be enabled/disabled using \ref RAIL_EnableTxHoldOff. |
Anna Bridge |
160:5571c4ff569f | 1739 | * Attempting to transmit with the TX hold off enabled will block the |
Anna Bridge |
160:5571c4ff569f | 1740 | * transmission and result in \ref RAIL_EVENT_TX_BLOCKED |
Anna Bridge |
160:5571c4ff569f | 1741 | * and/or \ref RAIL_EVENT_TXACK_BLOCKED events. |
Anna Bridge |
142:4eea097334d6 | 1742 | */ |
Anna Bridge |
160:5571c4ff569f | 1743 | bool RAIL_IsTxHoldOffEnabled(RAIL_Handle_t railHandle); |
Anna Bridge |
160:5571c4ff569f | 1744 | |
Anna Bridge |
160:5571c4ff569f | 1745 | /** @} */ // end of group Transmit |
Anna Bridge |
142:4eea097334d6 | 1746 | |
Anna Bridge |
142:4eea097334d6 | 1747 | /****************************************************************************** |
Anna Bridge |
142:4eea097334d6 | 1748 | * Receive |
Anna Bridge |
142:4eea097334d6 | 1749 | *****************************************************************************/ |
Anna Bridge |
142:4eea097334d6 | 1750 | /** |
Anna Bridge |
142:4eea097334d6 | 1751 | * @addtogroup Receive |
Anna Bridge |
142:4eea097334d6 | 1752 | * @brief APIs related to packet receive |
Anna Bridge |
142:4eea097334d6 | 1753 | * @{ |
Anna Bridge |
142:4eea097334d6 | 1754 | */ |
Anna Bridge |
142:4eea097334d6 | 1755 | |
Anna Bridge |
142:4eea097334d6 | 1756 | /** |
Anna Bridge |
160:5571c4ff569f | 1757 | * Configures receive options. |
Anna Bridge |
160:5571c4ff569f | 1758 | * |
Anna Bridge |
160:5571c4ff569f | 1759 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1760 | * @param[in] mask A bitmask containing which options should be modified. |
Anna Bridge |
160:5571c4ff569f | 1761 | * @param[in] options A bitmask containing desired configuration settings. |
Anna Bridge |
160:5571c4ff569f | 1762 | * Bit positions for each option are found in the \ref RAIL_RxOptions_t. |
Anna Bridge |
160:5571c4ff569f | 1763 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 1764 | * |
Anna Bridge |
160:5571c4ff569f | 1765 | * Configures the radio receive flow based on the list of available options. |
Anna Bridge |
160:5571c4ff569f | 1766 | * Only the options indicated by the mask parameter will be affected. Pass |
Anna Bridge |
160:5571c4ff569f | 1767 | * \ref RAIL_RX_OPTIONS_ALL to set all parameters. |
Anna Bridge |
160:5571c4ff569f | 1768 | * The previous settings may affect the current frame if a packet is |
Anna Bridge |
160:5571c4ff569f | 1769 | * received during this configuration. |
Anna Bridge |
160:5571c4ff569f | 1770 | */ |
Anna Bridge |
160:5571c4ff569f | 1771 | RAIL_Status_t RAIL_ConfigRxOptions(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1772 | RAIL_RxOptions_t mask, |
Anna Bridge |
160:5571c4ff569f | 1773 | RAIL_RxOptions_t options); |
Anna Bridge |
160:5571c4ff569f | 1774 | |
Anna Bridge |
160:5571c4ff569f | 1775 | /** |
Anna Bridge |
160:5571c4ff569f | 1776 | * Start the receiver on a specific channel. |
Anna Bridge |
142:4eea097334d6 | 1777 | * |
Anna Bridge |
160:5571c4ff569f | 1778 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1779 | * @param[in] channel The channel to listen on. |
Anna Bridge |
160:5571c4ff569f | 1780 | * @param[in] schedulerInfo Information to allow the radio scheduler to place |
Anna Bridge |
160:5571c4ff569f | 1781 | * this receive appropriately. This is only used in multiprotocol version of |
Anna Bridge |
160:5571c4ff569f | 1782 | * RAIL and may be set to NULL in all other versions. |
Anna Bridge |
160:5571c4ff569f | 1783 | * @return Status code indicating success of the function call. |
Anna Bridge |
160:5571c4ff569f | 1784 | * |
Anna Bridge |
160:5571c4ff569f | 1785 | * This is a non-blocking function. Whenever a packet is received \ref RAIL_Config_t::eventsCallback |
Anna Bridge |
160:5571c4ff569f | 1786 | * will fire with \ref RAIL_EVENT_RX_PACKET_RECEIVED set. If you call |
Anna Bridge |
160:5571c4ff569f | 1787 | * this while not idle but with a different channel we will abort any ongoing |
Anna Bridge |
160:5571c4ff569f | 1788 | * receive or transmit operation. |
Anna Bridge |
142:4eea097334d6 | 1789 | */ |
Anna Bridge |
160:5571c4ff569f | 1790 | RAIL_Status_t RAIL_StartRx(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1791 | uint16_t channel, |
Anna Bridge |
160:5571c4ff569f | 1792 | const RAIL_SchedulerInfo_t *schedulerInfo); |
Anna Bridge |
142:4eea097334d6 | 1793 | |
Anna Bridge |
142:4eea097334d6 | 1794 | /** |
Anna Bridge |
160:5571c4ff569f | 1795 | * Schedules a receive window for some future time. |
Anna Bridge |
142:4eea097334d6 | 1796 | * |
Anna Bridge |
160:5571c4ff569f | 1797 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1798 | * @param[in] channel A channel to listen on. |
Anna Bridge |
160:5571c4ff569f | 1799 | * @param[in] cfg The configuration structure to define the receive window. |
Anna Bridge |
160:5571c4ff569f | 1800 | * @param[in] schedulerInfo Information to allow the radio scheduler to place |
Anna Bridge |
160:5571c4ff569f | 1801 | * this receive appropriately. This is only used in multiprotocol version of |
Anna Bridge |
160:5571c4ff569f | 1802 | * RAIL and may be set to NULL in all other versions. |
Anna Bridge |
160:5571c4ff569f | 1803 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 1804 | * |
Anna Bridge |
160:5571c4ff569f | 1805 | * This API immediately changes the channel and schedules receive to start |
Anna Bridge |
160:5571c4ff569f | 1806 | * at the specified time and end at the given end time. If you do not specify |
Anna Bridge |
160:5571c4ff569f | 1807 | * an end time, you may call this API later with an end time as long as you set |
Anna Bridge |
160:5571c4ff569f | 1808 | * the start time to disabled. You can also terminate the receive |
Anna Bridge |
160:5571c4ff569f | 1809 | * operation immediately using the RAIL_Idle() function. Note that relative |
Anna Bridge |
160:5571c4ff569f | 1810 | * end times are always relative to the start unless no start time is |
Anna Bridge |
160:5571c4ff569f | 1811 | * specified. If changing channels, aborts any ongoing packet transmission or |
Anna Bridge |
160:5571c4ff569f | 1812 | * reception. |
Anna Bridge |
160:5571c4ff569f | 1813 | * |
Anna Bridge |
160:5571c4ff569f | 1814 | * In multiprotocol you must ensure that you properly yield the radio after this |
Anna Bridge |
160:5571c4ff569f | 1815 | * call. See \ref rail_radio_scheduler_yield for more details. |
Anna Bridge |
142:4eea097334d6 | 1816 | */ |
Anna Bridge |
160:5571c4ff569f | 1817 | RAIL_Status_t RAIL_ScheduleRx(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1818 | uint16_t channel, |
Anna Bridge |
160:5571c4ff569f | 1819 | const RAIL_ScheduleRxConfig_t *cfg, |
Anna Bridge |
160:5571c4ff569f | 1820 | const RAIL_SchedulerInfo_t *schedulerInfo); |
Anna Bridge |
142:4eea097334d6 | 1821 | |
Anna Bridge |
142:4eea097334d6 | 1822 | /** |
Anna Bridge |
160:5571c4ff569f | 1823 | * Get basic information about a pending or received packet. |
Anna Bridge |
160:5571c4ff569f | 1824 | * This function can be used in any RX mode; it does not free up any |
Anna Bridge |
160:5571c4ff569f | 1825 | * internal resources. |
Anna Bridge |
142:4eea097334d6 | 1826 | * |
Anna Bridge |
160:5571c4ff569f | 1827 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1828 | * @param[in] packetHandle A packet handle for the unreleased packet as |
Anna Bridge |
160:5571c4ff569f | 1829 | * returned from a previous call, or sentinel values |
Anna Bridge |
160:5571c4ff569f | 1830 | * \ref RAIL_RX_PACKET_HANDLE_OLDEST or \ref RAIL_RX_PACKET_HANDLE_NEWEST. |
Anna Bridge |
160:5571c4ff569f | 1831 | * @param[out] pPacketInfo An application-provided pointer to store |
Anna Bridge |
160:5571c4ff569f | 1832 | * \ref RAIL_RxPacketInfo_t for the requested packet. |
Anna Bridge |
160:5571c4ff569f | 1833 | * @return The packet handle for the requested packet: |
Anna Bridge |
160:5571c4ff569f | 1834 | * if packetHandle was one of the sentinel values, returns the actual |
Anna Bridge |
160:5571c4ff569f | 1835 | * packet handle for that packet, otherwise returns packetHandle. |
Anna Bridge |
160:5571c4ff569f | 1836 | * It may return \ref RAIL_RX_PACKET_HANDLE_INVALID to indicate an error. |
AnnaBridge | 167:84c0a372a020 | 1837 | * |
AnnaBridge | 167:84c0a372a020 | 1838 | * @note When getting info about an arriving packet that is not yet complete |
AnnaBridge | 167:84c0a372a020 | 1839 | * (i.e. pPacketInfo->packetStatus == \ref RAIL_RX_PACKET_RECEIVING), keep |
AnnaBridge | 167:84c0a372a020 | 1840 | * in mind its data is highly suspect because it has not yet passed any CRC |
AnnaBridge | 167:84c0a372a020 | 1841 | * integrity checking. Also note the packet could be aborted, cancelled, or |
AnnaBridge | 167:84c0a372a020 | 1842 | * fail momentarily, invalidating its data in Packet mode. Furthermore, there |
AnnaBridge | 167:84c0a372a020 | 1843 | * is a small chance towards the end of packet reception that the filled-in |
AnnaBridge | 167:84c0a372a020 | 1844 | * RAIL_RxPacketInfo_t could include not only packet data received so far, |
AnnaBridge | 167:84c0a372a020 | 1845 | * but also some raw radio-appended info detail bytes that RAIL's |
AnnaBridge | 167:84c0a372a020 | 1846 | * packet-completion processing will subsequently deal with. It's up to the |
AnnaBridge | 167:84c0a372a020 | 1847 | * application to know its packet format well enough to avoid confusing such |
AnnaBridge | 167:84c0a372a020 | 1848 | * info as packet data. |
Anna Bridge |
142:4eea097334d6 | 1849 | */ |
Anna Bridge |
160:5571c4ff569f | 1850 | RAIL_RxPacketHandle_t RAIL_GetRxPacketInfo(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1851 | RAIL_RxPacketHandle_t packetHandle, |
Anna Bridge |
160:5571c4ff569f | 1852 | RAIL_RxPacketInfo_t *pPacketInfo); |
Anna Bridge |
160:5571c4ff569f | 1853 | |
Anna Bridge |
160:5571c4ff569f | 1854 | /** |
AnnaBridge | 167:84c0a372a020 | 1855 | * Convenience helper function to copy a full packet to a user-specified |
AnnaBridge | 167:84c0a372a020 | 1856 | * contiguous buffer. |
AnnaBridge | 167:84c0a372a020 | 1857 | * |
AnnaBridge | 167:84c0a372a020 | 1858 | * @param[out] pDest An application-provided pointer to a buffer of at |
AnnaBridge | 167:84c0a372a020 | 1859 | * least pPacketInfo->packetBytes in size to store the packet data |
AnnaBridge | 167:84c0a372a020 | 1860 | * contiguously. This buffer must never overlay RAIL's Rx FIFO buffer. |
AnnaBridge | 167:84c0a372a020 | 1861 | * Exactly pPacketInfo->packetBytes of packet data will be written into it. |
AnnaBridge | 167:84c0a372a020 | 1862 | * @param[out] pPacketInfo |
AnnaBridge | 167:84c0a372a020 | 1863 | * \ref RAIL_RxPacketInfo_t for the requested packet. |
AnnaBridge | 167:84c0a372a020 | 1864 | * @return void. |
AnnaBridge | 167:84c0a372a020 | 1865 | * |
AnnaBridge | 167:84c0a372a020 | 1866 | * @note This helper is intended to be expedient -- it does not check the |
AnnaBridge | 167:84c0a372a020 | 1867 | * validity of its arguments, so don't pass either as NULL, and don't |
AnnaBridge | 167:84c0a372a020 | 1868 | * pass a pDest pointer to a buffer that's too small for the packet's data. |
AnnaBridge | 167:84c0a372a020 | 1869 | * @note If only a portion of the packet is needed, use RAIL_PeekRxPacket() |
AnnaBridge | 167:84c0a372a020 | 1870 | * instead. |
AnnaBridge | 167:84c0a372a020 | 1871 | */ |
AnnaBridge | 167:84c0a372a020 | 1872 | static inline |
AnnaBridge | 167:84c0a372a020 | 1873 | void RAIL_CopyRxPacket(uint8_t *pDest, |
AnnaBridge | 167:84c0a372a020 | 1874 | const RAIL_RxPacketInfo_t *pPacketInfo) |
AnnaBridge | 167:84c0a372a020 | 1875 | { |
AnnaBridge | 167:84c0a372a020 | 1876 | memcpy(pDest, pPacketInfo->firstPortionData, pPacketInfo->firstPortionBytes); |
AnnaBridge | 167:84c0a372a020 | 1877 | if (pPacketInfo->lastPortionData != NULL) { |
AnnaBridge | 167:84c0a372a020 | 1878 | memcpy(pDest + pPacketInfo->firstPortionBytes, |
AnnaBridge | 167:84c0a372a020 | 1879 | pPacketInfo->lastPortionData, |
AnnaBridge | 167:84c0a372a020 | 1880 | pPacketInfo->packetBytes - pPacketInfo->firstPortionBytes); |
AnnaBridge | 167:84c0a372a020 | 1881 | } |
AnnaBridge | 167:84c0a372a020 | 1882 | } |
AnnaBridge | 167:84c0a372a020 | 1883 | |
AnnaBridge | 167:84c0a372a020 | 1884 | /** |
Anna Bridge |
160:5571c4ff569f | 1885 | * Get detailed information about a ready packet received (one whose |
Anna Bridge |
160:5571c4ff569f | 1886 | * \ref RAIL_RxPacketStatus_t is among the RAIL_RX_PACKET_READY_ set). |
Anna Bridge |
160:5571c4ff569f | 1887 | * This function can be used in any RX mode; it does not free up any |
Anna Bridge |
160:5571c4ff569f | 1888 | * internal resources. |
Anna Bridge |
160:5571c4ff569f | 1889 | * |
Anna Bridge |
160:5571c4ff569f | 1890 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1891 | * @param[in] packetHandle A packet handle for the unreleased packet as |
Anna Bridge |
160:5571c4ff569f | 1892 | * returned from a previous call to RAIL_GetRxPacketInfo() or |
Anna Bridge |
160:5571c4ff569f | 1893 | * RAIL_HoldRxPacket(), or sentinel values \ref RAIL_RX_PACKET_HANDLE_OLDEST |
Anna Bridge |
160:5571c4ff569f | 1894 | * or \ref RAIL_RX_PACKET_HANDLE_NEWEST. |
Anna Bridge |
160:5571c4ff569f | 1895 | * @param[in,out] pPacketDetails An application-provided pointer to store |
Anna Bridge |
160:5571c4ff569f | 1896 | * \ref RAIL_RxPacketDetails_t for the requested packet. |
Anna Bridge |
160:5571c4ff569f | 1897 | * The timeReceived fields totalPacketBytes and timePosition must be |
Anna Bridge |
160:5571c4ff569f | 1898 | * initialized prior to each call: |
Anna Bridge |
160:5571c4ff569f | 1899 | * - totalPacketBytes with the total number of bytes of the received |
Anna Bridge |
160:5571c4ff569f | 1900 | * packet for RAIL to use when calculating the specified timestamp. |
Anna Bridge |
160:5571c4ff569f | 1901 | * This should account for all bytes received over the air after the |
Anna Bridge |
160:5571c4ff569f | 1902 | * Preamble and Sync word(s), including CRC bytes. |
Anna Bridge |
160:5571c4ff569f | 1903 | * - timePosition with a \ref RAIL_PacketTimePosition_t value specifying |
Anna Bridge |
160:5571c4ff569f | 1904 | * the packet position to put in the timeReceived field on return. |
Anna Bridge |
160:5571c4ff569f | 1905 | * This field will also be updated with the actual position corresponding |
Anna Bridge |
160:5571c4ff569f | 1906 | * to the timeReceived value filled in. |
Anna Bridge |
160:5571c4ff569f | 1907 | * @return \ref RAIL_STATUS_NO_ERROR if pPacketDetails was filled in, |
Anna Bridge |
160:5571c4ff569f | 1908 | * or an appropriate error code otherwise. |
Anna Bridge |
160:5571c4ff569f | 1909 | */ |
Anna Bridge |
160:5571c4ff569f | 1910 | RAIL_Status_t RAIL_GetRxPacketDetails(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1911 | RAIL_RxPacketHandle_t packetHandle, |
Anna Bridge |
160:5571c4ff569f | 1912 | RAIL_RxPacketDetails_t *pPacketDetails); |
Anna Bridge |
142:4eea097334d6 | 1913 | |
Anna Bridge |
142:4eea097334d6 | 1914 | /** |
Anna Bridge |
160:5571c4ff569f | 1915 | * Place a temporary hold on this packet's data and information resources |
Anna Bridge |
160:5571c4ff569f | 1916 | * within RAIL. |
Anna Bridge |
160:5571c4ff569f | 1917 | * This shall only be called from within RAIL callback context. |
Anna Bridge |
160:5571c4ff569f | 1918 | * This function can be used in any RX mode. |
Anna Bridge |
142:4eea097334d6 | 1919 | * |
Anna Bridge |
160:5571c4ff569f | 1920 | * Normally when RAIL issues its callback indicating a packet is ready |
Anna Bridge |
160:5571c4ff569f | 1921 | * or aborted, it expects the application's callback to retrieve and |
Anna Bridge |
160:5571c4ff569f | 1922 | * copy (or discard) the packet's information and data, and will free up |
Anna Bridge |
160:5571c4ff569f | 1923 | * its internal packet data after the callback returns. This function |
Anna Bridge |
160:5571c4ff569f | 1924 | * tells RAIL to hold onto those resources after the callback returns in |
Anna Bridge |
160:5571c4ff569f | 1925 | * case the application wants to defer processing the packet to a later |
Anna Bridge |
160:5571c4ff569f | 1926 | * time, e.g. outside of callback context. |
Anna Bridge |
160:5571c4ff569f | 1927 | * |
Anna Bridge |
160:5571c4ff569f | 1928 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1929 | * @return The packet handle for the packet associated with the callback, |
Anna Bridge |
160:5571c4ff569f | 1930 | * or \ref RAIL_RX_PACKET_HANDLE_INVALID if no such packet yet exists. |
Anna Bridge |
142:4eea097334d6 | 1931 | */ |
Anna Bridge |
160:5571c4ff569f | 1932 | RAIL_RxPacketHandle_t RAIL_HoldRxPacket(RAIL_Handle_t railHandle); |
Anna Bridge |
142:4eea097334d6 | 1933 | |
Anna Bridge |
142:4eea097334d6 | 1934 | /** |
Anna Bridge |
160:5571c4ff569f | 1935 | * Copies 'len' bytes of packet data starting from 'offset' from the |
Anna Bridge |
160:5571c4ff569f | 1936 | * receive FIFO. Those bytes remain valid for re-peeking. |
Anna Bridge |
142:4eea097334d6 | 1937 | * |
Anna Bridge |
160:5571c4ff569f | 1938 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1939 | * @param[in] packetHandle A packet handle as returned from a previous |
Anna Bridge |
160:5571c4ff569f | 1940 | * RAIL_GetRxPacketInfo() or RAIL_HoldRxPacket() call, or |
Anna Bridge |
160:5571c4ff569f | 1941 | * sentinel values \ref RAIL_RX_PACKET_HANDLE_OLDEST |
Anna Bridge |
160:5571c4ff569f | 1942 | * or \ref RAIL_RX_PACKET_HANDLE_NEWEST. |
Anna Bridge |
160:5571c4ff569f | 1943 | * @param[out] pDst A pointer to the location where the received bytes will |
Anna Bridge |
160:5571c4ff569f | 1944 | * be copied. If NULL, no copying occurs. |
Anna Bridge |
160:5571c4ff569f | 1945 | * @param[in] len A number of packet data bytes to copy. |
Anna Bridge |
160:5571c4ff569f | 1946 | * @param[in] offset A byte offset within remaining packet data from which |
Anna Bridge |
160:5571c4ff569f | 1947 | * to copy. |
Anna Bridge |
160:5571c4ff569f | 1948 | * @return Number of packet bytes copied. |
Anna Bridge |
160:5571c4ff569f | 1949 | * |
Anna Bridge |
160:5571c4ff569f | 1950 | * @note Peek does not permit peeking beyond the requested packet's |
AnnaBridge | 167:84c0a372a020 | 1951 | * available packet data (though there is a small chance it might |
AnnaBridge | 167:84c0a372a020 | 1952 | * for a \ref RAIL_RX_PACKET_HANDLE_NEWEST packet at the very end of |
AnnaBridge | 167:84c0a372a020 | 1953 | * still being received). Nor can one peek into already-consumed data read |
AnnaBridge | 167:84c0a372a020 | 1954 | * by RAIL_ReadRxFifo(). len and offset are relative to the remaining data |
Anna Bridge |
160:5571c4ff569f | 1955 | * available in the packet, if any was already consumed by RAIL_ReadRxFifo(). |
Anna Bridge |
142:4eea097334d6 | 1956 | */ |
Anna Bridge |
160:5571c4ff569f | 1957 | uint16_t RAIL_PeekRxPacket(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1958 | RAIL_RxPacketHandle_t packetHandle, |
Anna Bridge |
160:5571c4ff569f | 1959 | uint8_t *pDst, |
Anna Bridge |
160:5571c4ff569f | 1960 | uint16_t len, |
Anna Bridge |
160:5571c4ff569f | 1961 | uint16_t offset); |
Anna Bridge |
142:4eea097334d6 | 1962 | |
Anna Bridge |
142:4eea097334d6 | 1963 | /** |
Anna Bridge |
160:5571c4ff569f | 1964 | * Release RAIL's internal resources for the packet. |
Anna Bridge |
160:5571c4ff569f | 1965 | * This must be called for any packet previously held via |
Anna Bridge |
160:5571c4ff569f | 1966 | * RAIL_HoldRxPacket(), and may optionally be called within |
Anna Bridge |
160:5571c4ff569f | 1967 | * callback context to release RAIL resources sooner than at |
Anna Bridge |
160:5571c4ff569f | 1968 | * callback completion time when not holding the packet. |
Anna Bridge |
160:5571c4ff569f | 1969 | * This function can be used in any RX mode. |
Anna Bridge |
142:4eea097334d6 | 1970 | * |
Anna Bridge |
160:5571c4ff569f | 1971 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1972 | * @param[in] packetHandle A packet handle as returned from a previous |
Anna Bridge |
160:5571c4ff569f | 1973 | * RAIL_HoldRxPacket() call, or sentinel values |
Anna Bridge |
160:5571c4ff569f | 1974 | * \ref RAIL_RX_PACKET_HANDLE_OLDEST or \ref RAIL_RX_PACKET_HANDLE_NEWEST. |
Anna Bridge |
160:5571c4ff569f | 1975 | * The latter might be used within RAIL callback context to explicitly |
Anna Bridge |
160:5571c4ff569f | 1976 | * release the packet associated with the callback early, before it would |
Anna Bridge |
160:5571c4ff569f | 1977 | * be released automatically by RAIL on callback return (unless explicitly |
Anna Bridge |
160:5571c4ff569f | 1978 | * held). |
Anna Bridge |
160:5571c4ff569f | 1979 | * @return \ref RAIL_STATUS_NO_ERROR if the held packet was released |
Anna Bridge |
160:5571c4ff569f | 1980 | * or an appropriate error code otherwise. |
Anna Bridge |
142:4eea097334d6 | 1981 | */ |
Anna Bridge |
160:5571c4ff569f | 1982 | RAIL_Status_t RAIL_ReleaseRxPacket(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 1983 | RAIL_RxPacketHandle_t packetHandle); |
Anna Bridge |
142:4eea097334d6 | 1984 | |
Anna Bridge |
142:4eea097334d6 | 1985 | /** |
Anna Bridge |
160:5571c4ff569f | 1986 | * Returns the current raw RSSI. |
Anna Bridge |
160:5571c4ff569f | 1987 | * |
Anna Bridge |
160:5571c4ff569f | 1988 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 1989 | * @param[in] wait if false returns instant RSSI with no checks. |
Anna Bridge |
160:5571c4ff569f | 1990 | * @return \ref RAIL_RSSI_INVALID if the receiver is disabled and an RSSI |
Anna Bridge |
160:5571c4ff569f | 1991 | * value can't be obtained. Otherwise, return the RSSI in quarter dBm, dbm*4. |
Anna Bridge |
142:4eea097334d6 | 1992 | * |
Anna Bridge |
160:5571c4ff569f | 1993 | * Gets the current RSSI value. This value represents the current energy of the |
Anna Bridge |
160:5571c4ff569f | 1994 | * channel, it can change rapidly, and will be low if no RF energy is |
Anna Bridge |
160:5571c4ff569f | 1995 | * in the current channel. The function from the value reported to dBm is an |
Anna Bridge |
160:5571c4ff569f | 1996 | * offset dependent on the PHY and the PCB layout. Users should characterize the |
Anna Bridge |
160:5571c4ff569f | 1997 | * RSSI received on their hardware and apply an offset in the application to |
Anna Bridge |
160:5571c4ff569f | 1998 | * account for board and PHY parameters. 'Wait' argument doesn't guarantee |
Anna Bridge |
160:5571c4ff569f | 1999 | * a valid RSSI reading.'Wait' being true gives assurance that that the RSSI is |
Anna Bridge |
160:5571c4ff569f | 2000 | * current and not stale value from previous radio state. If GetRssi is called |
Anna Bridge |
160:5571c4ff569f | 2001 | * during RX-to-RX, RX-to-IDLE or RX-to-TX transition the RSSI is considered |
Anna Bridge |
160:5571c4ff569f | 2002 | * stale and \ref RAIL_RSSI_INVALID is returned if wait=true. 'Wait' being false |
Anna Bridge |
160:5571c4ff569f | 2003 | * will return either current RSSI or stale RSSI measurement (if called during |
Anna Bridge |
160:5571c4ff569f | 2004 | * RX-to-RX, RX-to-IDLE or RX-to-TX transition). \ref RAIL_RSSI_INVALID is |
Anna Bridge |
160:5571c4ff569f | 2005 | * returned if radio hasn't been in RX longer than 'idleToRx' time |
Anna Bridge |
160:5571c4ff569f | 2006 | * (see \ref RAIL_StateTiming_t), regardless of wait argument. |
Anna Bridge |
160:5571c4ff569f | 2007 | * |
Anna Bridge |
160:5571c4ff569f | 2008 | * In multiprotocol, this function returns \ref RAIL_RSSI_INVALID |
Anna Bridge |
160:5571c4ff569f | 2009 | * immediately if railHandle is not the current active \ref RAIL_Handle_t. |
Anna Bridge |
160:5571c4ff569f | 2010 | * Additionally 'wait' should never be set 'true' in multiprotocol |
Anna Bridge |
160:5571c4ff569f | 2011 | * as the wait time is not consistent, so scheduling a scheduler |
Anna Bridge |
160:5571c4ff569f | 2012 | * slot cannot be done accurately. |
Anna Bridge |
160:5571c4ff569f | 2013 | */ |
Anna Bridge |
160:5571c4ff569f | 2014 | int16_t RAIL_GetRssi(RAIL_Handle_t railHandle, bool wait); |
Anna Bridge |
160:5571c4ff569f | 2015 | |
Anna Bridge |
160:5571c4ff569f | 2016 | /** |
Anna Bridge |
160:5571c4ff569f | 2017 | * Starts the RSSI averaging over a specified time in us. |
Anna Bridge |
160:5571c4ff569f | 2018 | * |
Anna Bridge |
160:5571c4ff569f | 2019 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2020 | * @param[in] channel The physical channel to set. |
Anna Bridge |
142:4eea097334d6 | 2021 | * @param[in] averagingTimeUs Averaging time in microseconds. |
Anna Bridge |
160:5571c4ff569f | 2022 | * @param[in] schedulerInfo Information to allow the radio scheduler to place |
Anna Bridge |
160:5571c4ff569f | 2023 | * this operation appropriately. This is only used in multiprotocol version of |
Anna Bridge |
160:5571c4ff569f | 2024 | * RAIL and may be set to NULL in all other versions. |
Anna Bridge |
160:5571c4ff569f | 2025 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 2026 | * |
Anna Bridge |
160:5571c4ff569f | 2027 | * Starts a non-blocking hardware-based RSSI averaging mechanism. Only a single |
Anna Bridge |
142:4eea097334d6 | 2028 | * instance of RSSI averaging can be run at any time and the radio must be idle |
Anna Bridge |
142:4eea097334d6 | 2029 | * to start. |
Anna Bridge |
160:5571c4ff569f | 2030 | * |
Anna Bridge |
160:5571c4ff569f | 2031 | * In multiprotocol, this is a scheduled event. It will start when railHandle |
Anna Bridge |
160:5571c4ff569f | 2032 | * becomes active, and railHandle will need to stay active until the averaging |
Anna Bridge |
160:5571c4ff569f | 2033 | * completes. If the averaging is interrupted, calls to |
Anna Bridge |
160:5571c4ff569f | 2034 | * \ref RAIL_GetAverageRssi will return \ref RAIL_RSSI_INVALID. |
Anna Bridge |
160:5571c4ff569f | 2035 | * |
Anna Bridge |
160:5571c4ff569f | 2036 | * Also in multiprotocol, the user is required to call \ref RAIL_YieldRadio |
Anna Bridge |
160:5571c4ff569f | 2037 | * after this event completes (i.e. when \ref RAIL_EVENT_RSSI_AVERAGE_DONE |
Anna Bridge |
160:5571c4ff569f | 2038 | * occurs). |
Anna Bridge |
142:4eea097334d6 | 2039 | */ |
Anna Bridge |
160:5571c4ff569f | 2040 | RAIL_Status_t RAIL_StartAverageRssi(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 2041 | uint16_t channel, |
AnnaBridge | 167:84c0a372a020 | 2042 | RAIL_Time_t averagingTimeUs, |
Anna Bridge |
160:5571c4ff569f | 2043 | const RAIL_SchedulerInfo_t *schedulerInfo); |
Anna Bridge |
142:4eea097334d6 | 2044 | |
Anna Bridge |
142:4eea097334d6 | 2045 | /** |
Anna Bridge |
160:5571c4ff569f | 2046 | * Queries whether the RSSI averaging is done. |
Anna Bridge |
142:4eea097334d6 | 2047 | * |
Anna Bridge |
160:5571c4ff569f | 2048 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
142:4eea097334d6 | 2049 | * @return Returns true if done and false otherwise. |
Anna Bridge |
142:4eea097334d6 | 2050 | * |
Anna Bridge |
160:5571c4ff569f | 2051 | * This function can be used to poll for completion of the RSSI averaging |
Anna Bridge |
160:5571c4ff569f | 2052 | * to avoid relying on an interrupt-based callback. |
Anna Bridge |
142:4eea097334d6 | 2053 | */ |
Anna Bridge |
160:5571c4ff569f | 2054 | bool RAIL_IsAverageRssiReady(RAIL_Handle_t railHandle); |
Anna Bridge |
142:4eea097334d6 | 2055 | |
Anna Bridge |
142:4eea097334d6 | 2056 | /** |
Anna Bridge |
160:5571c4ff569f | 2057 | * Gets the RSSI averaged over specified time in us. |
Anna Bridge |
142:4eea097334d6 | 2058 | * |
Anna Bridge |
160:5571c4ff569f | 2059 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2060 | * @return Return \ref RAIL_RSSI_INVALID if the receiver is disabled |
Anna Bridge |
160:5571c4ff569f | 2061 | * an RSSI value can't be obtained. Otherwise, return the RSSI in |
Anna Bridge |
160:5571c4ff569f | 2062 | * quarter dBm,dbm*4. |
Anna Bridge |
142:4eea097334d6 | 2063 | * |
Anna Bridge |
160:5571c4ff569f | 2064 | * Gets the hardware RSSI average after issuing RAIL_StartAverageRssi. |
Anna Bridge |
160:5571c4ff569f | 2065 | * It should be used after \ref RAIL_StartAverageRssi. |
Anna Bridge |
142:4eea097334d6 | 2066 | */ |
Anna Bridge |
160:5571c4ff569f | 2067 | int16_t RAIL_GetAverageRssi(RAIL_Handle_t railHandle); |
Anna Bridge |
142:4eea097334d6 | 2068 | |
Anna Bridge |
142:4eea097334d6 | 2069 | /****************************************************************************** |
Anna Bridge |
160:5571c4ff569f | 2070 | * Address Filtering (RX) |
Anna Bridge |
142:4eea097334d6 | 2071 | *****************************************************************************/ |
Anna Bridge |
142:4eea097334d6 | 2072 | /** |
Anna Bridge |
160:5571c4ff569f | 2073 | * @addtogroup Address_Filtering Address Filtering |
Anna Bridge |
142:4eea097334d6 | 2074 | * @brief Configuration APIs for receive packet address filtering. |
Anna Bridge |
142:4eea097334d6 | 2075 | * |
Anna Bridge |
142:4eea097334d6 | 2076 | * The address filtering code examines the packet as follows. |
Anna Bridge |
142:4eea097334d6 | 2077 | * |
Anna Bridge |
142:4eea097334d6 | 2078 | * | `Bytes: 0 - 255` | `0 - 8` | `0 - 255` | `0 - 8` | `Variable` | |
Anna Bridge |
142:4eea097334d6 | 2079 | * |:----------------:|---------:|----------:|---------:|:----------:| |
Anna Bridge |
142:4eea097334d6 | 2080 | * | `Data0` | `Field0` | `Data1` | `Field1` | `Data2` | |
Anna Bridge |
142:4eea097334d6 | 2081 | * |
Anna Bridge |
142:4eea097334d6 | 2082 | * In the above structure, anything listed as DataN is an optional section of |
Anna Bridge |
142:4eea097334d6 | 2083 | * bytes that RAIL will not process for address filtering. The FieldN segments |
Anna Bridge |
160:5571c4ff569f | 2084 | * reference-specific sections in the packet that will each be interpreted |
Anna Bridge |
160:5571c4ff569f | 2085 | * as an address during address filtering. The application may submit up to |
Anna Bridge |
160:5571c4ff569f | 2086 | * four addresses to attempt to match each field segment and each address may |
Anna Bridge |
160:5571c4ff569f | 2087 | * have a size of up to 8 bytes. To set up address filtering, first configure |
Anna Bridge |
160:5571c4ff569f | 2088 | * the locations and length of the addresses in the packet. Next, configure |
Anna Bridge |
160:5571c4ff569f | 2089 | * which combinations of matches in Field0 and Field1 should constitute an |
Anna Bridge |
160:5571c4ff569f | 2090 | * address match. Lastly, enter addresses into tables for each field and |
Anna Bridge |
160:5571c4ff569f | 2091 | * enable them. The first two of these are part of the \ref RAIL_AddrConfig_t |
Anna Bridge |
160:5571c4ff569f | 2092 | * structure while the second part is configured at runtime using the |
Anna Bridge |
160:5571c4ff569f | 2093 | * RAIL_SetAddressFilterAddress() API. A brief description of each |
Anna Bridge |
160:5571c4ff569f | 2094 | * configuration is listed below. |
Anna Bridge |
142:4eea097334d6 | 2095 | * |
Anna Bridge |
160:5571c4ff569f | 2096 | * For the first piece of configuration, the offsets and sizes of the fields |
Anna Bridge |
160:5571c4ff569f | 2097 | * are assumed fixed for the RAIL address filter. To set them, specify |
Anna Bridge |
142:4eea097334d6 | 2098 | * arrays for these values in the sizes and offsets entries in the |
Anna Bridge |
160:5571c4ff569f | 2099 | * \ref RAIL_AddrConfig_t structure. A size of zero indicates that a field is |
Anna Bridge |
160:5571c4ff569f | 2100 | * disabled. The start offset for a field is relative to the previous start |
Anna Bridge |
160:5571c4ff569f | 2101 | * offset and, if you're using FrameType decoding, the first start offset is |
Anna Bridge |
142:4eea097334d6 | 2102 | * relative to the end of the byte containing the frame type. |
Anna Bridge |
142:4eea097334d6 | 2103 | * |
Anna Bridge |
160:5571c4ff569f | 2104 | * Configuring which combinations of Field0 and Field1 constitute a match is |
Anna Bridge |
160:5571c4ff569f | 2105 | * the most complex portion of the address filter. The easiest way to think |
Anna Bridge |
160:5571c4ff569f | 2106 | * about this is with a truth table. If you consider each of the four possible |
Anna Bridge |
160:5571c4ff569f | 2107 | * address entries in a field, you can have a match on any one of those or a |
Anna Bridge |
160:5571c4ff569f | 2108 | * match for none of them. This can be represented as a 4-bit mask where 1 |
Anna Bridge |
160:5571c4ff569f | 2109 | * indicates a match and 0 indicates no match. Representing the Field0 match |
Anna Bridge |
160:5571c4ff569f | 2110 | * options as rows and the Field1 options as columns results in a truth table |
Anna Bridge |
160:5571c4ff569f | 2111 | * as shown below. |
Anna Bridge |
142:4eea097334d6 | 2112 | * |
Anna Bridge |
142:4eea097334d6 | 2113 | * | | 0000 | 0001 | 0010 | 0100 | 1000 | |
Anna Bridge |
142:4eea097334d6 | 2114 | * |----------|------|------|------|------|------| |
Anna Bridge |
142:4eea097334d6 | 2115 | * | __0000__ | bit0 | bit1 | bit2 | bit3 | bit4 | |
Anna Bridge |
142:4eea097334d6 | 2116 | * | __0001__ | bit5 | bit6 | bit7 | bit8 | bit9 | |
Anna Bridge |
142:4eea097334d6 | 2117 | * | __0010__ | bit10| bit11| bit12| bit13| bit14| |
Anna Bridge |
142:4eea097334d6 | 2118 | * | __0100__ | bit15| bit16| bit17| bit18| bit19| |
Anna Bridge |
142:4eea097334d6 | 2119 | * | __1000__ | bit20| bit21| bit22| bit23| bit24| |
Anna Bridge |
142:4eea097334d6 | 2120 | * |
Anna Bridge |
160:5571c4ff569f | 2121 | * Because this is only 25 bits, it can be represented in one 32-bit integer |
Anna Bridge |
160:5571c4ff569f | 2122 | * where 1 indicates a filter pass and 0 indicates a filter fail. This is the |
Anna Bridge |
160:5571c4ff569f | 2123 | * matchTable parameter in the configuration struct and is used during |
Anna Bridge |
160:5571c4ff569f | 2124 | * filtering. For common simple configurations two defines are provided with |
Anna Bridge |
160:5571c4ff569f | 2125 | * the truth tables as shown below. The first is \ref |
Anna Bridge |
160:5571c4ff569f | 2126 | * ADDRCONFIG_MATCH_TABLE_SINGLE_FIELD, which can be used if only using |
Anna Bridge |
160:5571c4ff569f | 2127 | * one address field (either field). If using two fields and want to |
Anna Bridge |
160:5571c4ff569f | 2128 | * force in the same address entry in each field, use the second define: \ref |
Anna Bridge |
160:5571c4ff569f | 2129 | * ADDRCONFIG_MATCH_TABLE_DOUBLE_FIELD. For more complex systems, |
Anna Bridge |
160:5571c4ff569f | 2130 | * create a valid custom table. |
Anna Bridge |
142:4eea097334d6 | 2131 | * |
Anna Bridge |
160:5571c4ff569f | 2132 | * @note Address filtering does not function reliably with PHYs that use a data |
Anna Bridge |
160:5571c4ff569f | 2133 | * rate greater than 500 kbps. If this is a requirement, filter in software |
Anna Bridge |
160:5571c4ff569f | 2134 | * for the time being. |
Anna Bridge |
142:4eea097334d6 | 2135 | * |
Anna Bridge |
142:4eea097334d6 | 2136 | * @{ |
Anna Bridge |
142:4eea097334d6 | 2137 | */ |
Anna Bridge |
142:4eea097334d6 | 2138 | |
Anna Bridge |
142:4eea097334d6 | 2139 | /** |
Anna Bridge |
160:5571c4ff569f | 2140 | * Configures address filtering. |
Anna Bridge |
142:4eea097334d6 | 2141 | * |
Anna Bridge |
160:5571c4ff569f | 2142 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2143 | * @param[in] addrConfig The configuration structure, which defines how |
Anna Bridge |
160:5571c4ff569f | 2144 | * addresses are setup in your packets. |
Anna Bridge |
160:5571c4ff569f | 2145 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 2146 | * |
Anna Bridge |
160:5571c4ff569f | 2147 | * This function must be called to set up address filtering. You may call it |
Anna Bridge |
160:5571c4ff569f | 2148 | * multiple times but all previous information is wiped out each time you call |
Anna Bridge |
160:5571c4ff569f | 2149 | * and any configured addresses must be reset. |
Anna Bridge |
142:4eea097334d6 | 2150 | */ |
Anna Bridge |
160:5571c4ff569f | 2151 | RAIL_Status_t RAIL_ConfigAddressFilter(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 2152 | const RAIL_AddrConfig_t *addrConfig); |
Anna Bridge |
142:4eea097334d6 | 2153 | |
Anna Bridge |
142:4eea097334d6 | 2154 | /** |
Anna Bridge |
160:5571c4ff569f | 2155 | * Enables address filtering. |
Anna Bridge |
142:4eea097334d6 | 2156 | * |
Anna Bridge |
160:5571c4ff569f | 2157 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2158 | * @param[in] enable An argument to indicate whether or not to enable address |
Anna Bridge |
160:5571c4ff569f | 2159 | * filtering. |
Anna Bridge |
160:5571c4ff569f | 2160 | * @return True if address filtering was enabled to start with and false |
Anna Bridge |
160:5571c4ff569f | 2161 | * otherwise. |
Anna Bridge |
160:5571c4ff569f | 2162 | * |
Anna Bridge |
160:5571c4ff569f | 2163 | * Only allow packets through that pass the current address filtering |
Anna Bridge |
160:5571c4ff569f | 2164 | * configuration. This does not reset or change the configuration so you can |
Anna Bridge |
160:5571c4ff569f | 2165 | * set that up before turning on this feature. |
Anna Bridge |
142:4eea097334d6 | 2166 | */ |
Anna Bridge |
160:5571c4ff569f | 2167 | bool RAIL_EnableAddressFilter(RAIL_Handle_t railHandle, bool enable); |
Anna Bridge |
142:4eea097334d6 | 2168 | |
Anna Bridge |
142:4eea097334d6 | 2169 | /** |
Anna Bridge |
160:5571c4ff569f | 2170 | * Returns whether address filtering is currently enabled. |
Anna Bridge |
142:4eea097334d6 | 2171 | * |
Anna Bridge |
160:5571c4ff569f | 2172 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2173 | * @return True if address filtering is enabled and false otherwise. |
Anna Bridge |
142:4eea097334d6 | 2174 | */ |
Anna Bridge |
160:5571c4ff569f | 2175 | bool RAIL_IsAddressFilterEnabled(RAIL_Handle_t railHandle); |
Anna Bridge |
142:4eea097334d6 | 2176 | |
Anna Bridge |
142:4eea097334d6 | 2177 | /** |
Anna Bridge |
160:5571c4ff569f | 2178 | * Resets the address filtering configuration. |
Anna Bridge |
142:4eea097334d6 | 2179 | * |
Anna Bridge |
160:5571c4ff569f | 2180 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2181 | * @return void. |
Anna Bridge |
142:4eea097334d6 | 2182 | * |
Anna Bridge |
160:5571c4ff569f | 2183 | * Resets all structures related to address filtering. This does not disable |
Anna Bridge |
160:5571c4ff569f | 2184 | * address filtering. It leaves the radio in a state where no packets |
Anna Bridge |
160:5571c4ff569f | 2185 | * pass filtering. |
Anna Bridge |
142:4eea097334d6 | 2186 | */ |
Anna Bridge |
160:5571c4ff569f | 2187 | void RAIL_ResetAddressFilter(RAIL_Handle_t railHandle); |
Anna Bridge |
142:4eea097334d6 | 2188 | |
Anna Bridge |
142:4eea097334d6 | 2189 | /** |
Anna Bridge |
160:5571c4ff569f | 2190 | * Sets an address for filtering in hardware. |
Anna Bridge |
142:4eea097334d6 | 2191 | * |
Anna Bridge |
160:5571c4ff569f | 2192 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2193 | * @param[in] field Which address field you want to use for this address. |
Anna Bridge |
160:5571c4ff569f | 2194 | * @param[in] index Which match entry you want to place this address in for a |
Anna Bridge |
160:5571c4ff569f | 2195 | * given field. |
Anna Bridge |
160:5571c4ff569f | 2196 | * @param[in] value A pointer to the address data. This must be at least as |
Anna Bridge |
160:5571c4ff569f | 2197 | * long as the size specified in RAIL_ConfigAddressFilter(). |
Anna Bridge |
160:5571c4ff569f | 2198 | * @param[in] enable A boolean to indicate whether this address should be |
Anna Bridge |
160:5571c4ff569f | 2199 | * enabled immediately. |
Anna Bridge |
160:5571c4ff569f | 2200 | * @return Status code indicating success of the function call. |
Anna Bridge |
160:5571c4ff569f | 2201 | * |
Anna Bridge |
160:5571c4ff569f | 2202 | * This function loads the given address into hardware for filtering and |
Anna Bridge |
160:5571c4ff569f | 2203 | * starts filtering if you set the enable parameter to true. Otherwise, |
Anna Bridge |
160:5571c4ff569f | 2204 | * call RAIL_EnableAddressFilterAddress() to turn it on later. |
Anna Bridge |
142:4eea097334d6 | 2205 | */ |
Anna Bridge |
160:5571c4ff569f | 2206 | RAIL_Status_t RAIL_SetAddressFilterAddress(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 2207 | uint8_t field, |
Anna Bridge |
160:5571c4ff569f | 2208 | uint8_t index, |
Anna Bridge |
160:5571c4ff569f | 2209 | const uint8_t *value, |
Anna Bridge |
160:5571c4ff569f | 2210 | bool enable); |
Anna Bridge |
142:4eea097334d6 | 2211 | |
Anna Bridge |
142:4eea097334d6 | 2212 | /** |
Anna Bridge |
160:5571c4ff569f | 2213 | * Enables address filtering for the specified address. |
Anna Bridge |
142:4eea097334d6 | 2214 | * |
Anna Bridge |
160:5571c4ff569f | 2215 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2216 | * @param[in] enable An argument to indicate whether or not to enable address |
Anna Bridge |
160:5571c4ff569f | 2217 | * filtering. |
Anna Bridge |
160:5571c4ff569f | 2218 | * @param[in] field Which address field you want to enable the address in. |
Anna Bridge |
160:5571c4ff569f | 2219 | * @param[in] index Which match entry in the given field you want to enable. |
Anna Bridge |
160:5571c4ff569f | 2220 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 2221 | */ |
Anna Bridge |
160:5571c4ff569f | 2222 | RAIL_Status_t RAIL_EnableAddressFilterAddress(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 2223 | bool enable, |
Anna Bridge |
160:5571c4ff569f | 2224 | uint8_t field, |
Anna Bridge |
160:5571c4ff569f | 2225 | uint8_t index); |
Anna Bridge |
142:4eea097334d6 | 2226 | |
Anna Bridge |
160:5571c4ff569f | 2227 | /** @} */ // end of group Address_Filtering |
Anna Bridge |
142:4eea097334d6 | 2228 | |
Anna Bridge |
160:5571c4ff569f | 2229 | /** @} */ // end of group Receive |
Anna Bridge |
142:4eea097334d6 | 2230 | |
Anna Bridge |
142:4eea097334d6 | 2231 | /****************************************************************************** |
Anna Bridge |
142:4eea097334d6 | 2232 | * Auto Acking |
Anna Bridge |
142:4eea097334d6 | 2233 | *****************************************************************************/ |
AnnaBridge | 167:84c0a372a020 | 2234 | /// @addtogroup Auto_Ack Auto ACK |
AnnaBridge | 167:84c0a372a020 | 2235 | /// @brief APIs for configuring auto ACK functionality |
AnnaBridge | 167:84c0a372a020 | 2236 | /// |
AnnaBridge | 167:84c0a372a020 | 2237 | /// These APIs are used to configure the radio for auto acknowledgment |
AnnaBridge | 167:84c0a372a020 | 2238 | /// features. Auto ACK inherently changes how the underlying state machine |
AnnaBridge | 167:84c0a372a020 | 2239 | /// behaves so users should not modify RAIL_SetRxTransitions() and |
AnnaBridge | 167:84c0a372a020 | 2240 | /// RAIL_SetTxTransitions() while using auto ACK features. |
AnnaBridge | 167:84c0a372a020 | 2241 | /// |
AnnaBridge | 167:84c0a372a020 | 2242 | /// @code{.c} |
AnnaBridge | 167:84c0a372a020 | 2243 | /// // Go to RX after ACK operation |
AnnaBridge | 167:84c0a372a020 | 2244 | /// RAIL_AutoAckConfig_t autoAckConfig = { |
AnnaBridge | 167:84c0a372a020 | 2245 | /// .enable = true, |
AnnaBridge | 167:84c0a372a020 | 2246 | /// .ackTimeout = 1000, |
AnnaBridge | 167:84c0a372a020 | 2247 | /// // "error" param ignored |
AnnaBridge | 167:84c0a372a020 | 2248 | /// .rxTransitions = { RAIL_RF_STATE_RX, RAIL_RF_STATE_RX}, |
AnnaBridge | 167:84c0a372a020 | 2249 | /// // "error" param ignored |
AnnaBridge | 167:84c0a372a020 | 2250 | /// .txTransitions = { RAIL_RF_STATE_RX, RAIL_RF_STATE_RX} |
AnnaBridge | 167:84c0a372a020 | 2251 | /// }; |
AnnaBridge | 167:84c0a372a020 | 2252 | /// |
AnnaBridge | 167:84c0a372a020 | 2253 | /// RAIL_Status_t status = RAIL_ConfigAutoAck(railHandle, &autoAckConfig); |
AnnaBridge | 167:84c0a372a020 | 2254 | /// |
AnnaBridge | 167:84c0a372a020 | 2255 | /// uint8_t ackData[] = {0x05, 0x02, 0x10, 0x00}; |
AnnaBridge | 167:84c0a372a020 | 2256 | /// |
AnnaBridge | 167:84c0a372a020 | 2257 | /// RAIL_Status_t status = RAIL_WriteAutoAckFifo(ackData, sizeof(ackData)); |
AnnaBridge | 167:84c0a372a020 | 2258 | /// @endcode |
AnnaBridge | 167:84c0a372a020 | 2259 | /// |
AnnaBridge | 167:84c0a372a020 | 2260 | /// The acknowledgment transmits based on the frame format configured via |
AnnaBridge | 167:84c0a372a020 | 2261 | /// the Radio Configurator. For example, if the frame format is using a variable |
AnnaBridge | 167:84c0a372a020 | 2262 | /// length scheme, the ACK will be sent according to that scheme. If a 10-byte |
AnnaBridge | 167:84c0a372a020 | 2263 | /// packet is loaded into the ACK, but the variable length field of the ACK |
AnnaBridge | 167:84c0a372a020 | 2264 | /// payload specifies a length of 5, only 5 bytes will transmit for the ACK. |
AnnaBridge | 167:84c0a372a020 | 2265 | /// The converse is also true, if the frame length is configured to be a fixed |
AnnaBridge | 167:84c0a372a020 | 2266 | /// 10-byte packet but only 5 bytes are loaded into the ACK buffer, a TX |
AnnaBridge | 167:84c0a372a020 | 2267 | /// underflow occurs during the ACK transmit. |
AnnaBridge | 167:84c0a372a020 | 2268 | /// |
AnnaBridge | 167:84c0a372a020 | 2269 | /// Unlike in non-ACK mode, ACK mode will always return to a single |
AnnaBridge | 167:84c0a372a020 | 2270 | /// state after all ACK sequences complete, regardless of whether |
AnnaBridge | 167:84c0a372a020 | 2271 | /// the ACK was successfully received/sent or not. Read the documentation |
AnnaBridge | 167:84c0a372a020 | 2272 | /// of RAIL_ConfigAutoAck for more detail on how that is configured. To |
AnnaBridge | 167:84c0a372a020 | 2273 | /// not auto acknowledge a series of packets after transmit |
AnnaBridge | 167:84c0a372a020 | 2274 | /// or receive, call RAIL_PauseTxAutoAck(true) or RAIL_PauseRxAutoAck(true). |
AnnaBridge | 167:84c0a372a020 | 2275 | /// When auto acking is paused, after receiving or transmitting (also |
AnnaBridge | 167:84c0a372a020 | 2276 | /// regardless of success) a packet, the radio transitions to the same single |
AnnaBridge | 167:84c0a372a020 | 2277 | /// state it always defaults to while acking. To return to |
AnnaBridge | 167:84c0a372a020 | 2278 | /// normal state transition logic outside of acking, you must call |
AnnaBridge | 167:84c0a372a020 | 2279 | /// RAIL_ConfigAutoAck with the "enable" field false, and specify the |
AnnaBridge | 167:84c0a372a020 | 2280 | /// desired transitions in the rxTransitions and txTransitions fields. |
AnnaBridge | 167:84c0a372a020 | 2281 | /// To simply get out of a paused state and resume auto acking, call |
AnnaBridge | 167:84c0a372a020 | 2282 | /// RAIL_PauseTxAutoAck(false) or RAIL_PauseRxAutoAck(false). |
AnnaBridge | 167:84c0a372a020 | 2283 | /// |
AnnaBridge | 167:84c0a372a020 | 2284 | /// Applications can cancel the transmission of an ACK with |
AnnaBridge | 167:84c0a372a020 | 2285 | /// RAIL_CancelAutoAck(). Conversely, applications can control if a transmit |
AnnaBridge | 167:84c0a372a020 | 2286 | /// operation should wait for an ACK after transmitting by using |
AnnaBridge | 167:84c0a372a020 | 2287 | /// the \ref RAIL_TX_OPTION_WAIT_FOR_ACK bit. |
AnnaBridge | 167:84c0a372a020 | 2288 | /// |
AnnaBridge | 167:84c0a372a020 | 2289 | /// If the ACK payload is dynamic, the application must call |
AnnaBridge | 167:84c0a372a020 | 2290 | /// RAIL_WriteAutoAckFifo() with the appropriate ACK payload after the |
AnnaBridge | 167:84c0a372a020 | 2291 | /// application processes the receive. RAIL can auto ACK from the normal |
AnnaBridge | 167:84c0a372a020 | 2292 | /// transmit buffer if RAIL_UseTxFifoForAutoAck() is called before the radio |
AnnaBridge | 167:84c0a372a020 | 2293 | /// transmits the ACK. Ensure the transmit buffer contains data loaded by |
AnnaBridge | 167:84c0a372a020 | 2294 | /// RAIL_WriteTxFifo(). |
AnnaBridge | 167:84c0a372a020 | 2295 | /// |
AnnaBridge | 167:84c0a372a020 | 2296 | /// Standard-based protocols that contain auto ACK functionality are normally |
AnnaBridge | 167:84c0a372a020 | 2297 | /// configured in the protocol-specific configuration function. For example, |
AnnaBridge | 167:84c0a372a020 | 2298 | /// RAIL_IEEE802154_Init() provides auto ACK configuration parameters in \ref |
AnnaBridge | 167:84c0a372a020 | 2299 | /// RAIL_IEEE802154_Config_t and should only be configured through that |
AnnaBridge | 167:84c0a372a020 | 2300 | /// function. It is not advisable to call both RAIL_IEEE802154_Init() and |
AnnaBridge | 167:84c0a372a020 | 2301 | /// RAIL_ConfigAutoAck(). However, ACK modification functions are still valid to |
AnnaBridge | 167:84c0a372a020 | 2302 | /// use with protocol-specific ACKs. To cancel a IEEE 802.15.4 ACK transmit, use |
AnnaBridge | 167:84c0a372a020 | 2303 | /// RAIL_CancelAutoAck(). |
AnnaBridge | 167:84c0a372a020 | 2304 | /// |
AnnaBridge | 167:84c0a372a020 | 2305 | /// @{ |
Anna Bridge |
142:4eea097334d6 | 2306 | |
AnnaBridge | 167:84c0a372a020 | 2307 | /// Configures and enable auto acknowledgment. |
AnnaBridge | 167:84c0a372a020 | 2308 | /// |
AnnaBridge | 167:84c0a372a020 | 2309 | /// @param[in] railHandle A RAIL instance handle. |
AnnaBridge | 167:84c0a372a020 | 2310 | /// @param[in] config Auto ACK configuration structure. |
AnnaBridge | 167:84c0a372a020 | 2311 | /// @return Status code indicating success of the function call. |
AnnaBridge | 167:84c0a372a020 | 2312 | /// |
AnnaBridge | 167:84c0a372a020 | 2313 | /// Configures the RAIL state machine to for hardware-accelerated auto |
AnnaBridge | 167:84c0a372a020 | 2314 | /// acknowledgment. ACK timing parameters are defined in the configuration |
AnnaBridge | 167:84c0a372a020 | 2315 | /// structure. |
AnnaBridge | 167:84c0a372a020 | 2316 | /// |
AnnaBridge | 167:84c0a372a020 | 2317 | /// While auto acking is enabled, do not call the following RAIL functions: |
AnnaBridge | 167:84c0a372a020 | 2318 | /// - RAIL_SetRxTransitions() |
AnnaBridge | 167:84c0a372a020 | 2319 | /// - RAIL_SetTxTransitions() |
AnnaBridge | 167:84c0a372a020 | 2320 | /// |
AnnaBridge | 167:84c0a372a020 | 2321 | /// Note, that if you are enabling auto ACK (i.e. "enable" field is true) |
AnnaBridge | 167:84c0a372a020 | 2322 | /// The "error" fields of rxTransitions and txTransitions are ignored. |
AnnaBridge | 167:84c0a372a020 | 2323 | /// After all ACK sequences, (success or fail) the state machine will return |
AnnaBridge | 167:84c0a372a020 | 2324 | /// the radio to the "success" state. If you need information about the |
AnnaBridge | 167:84c0a372a020 | 2325 | /// actual success of the ACK sequence, you can use RAIL events such as |
AnnaBridge | 167:84c0a372a020 | 2326 | /// \ref RAIL_EVENT_TXACK_PACKET_SENT to make sure an ACK was sent, or |
AnnaBridge | 167:84c0a372a020 | 2327 | /// \ref RAIL_EVENT_RX_ACK_TIMEOUT to make sure that an ACK was received |
AnnaBridge | 167:84c0a372a020 | 2328 | /// within the specified timeout. |
AnnaBridge | 167:84c0a372a020 | 2329 | /// |
AnnaBridge | 167:84c0a372a020 | 2330 | /// If you wish to set a certain turnaround time (i.e. txToRx and rxToTx |
AnnaBridge | 167:84c0a372a020 | 2331 | /// in \ref RAIL_StateTiming_t), we recommend that you make txToRx lower than |
AnnaBridge | 167:84c0a372a020 | 2332 | /// desired, in order to ensure you get to RX in time to receive the ACK. |
AnnaBridge | 167:84c0a372a020 | 2333 | /// Silicon Labs recommends setting 10us lower than desired: |
AnnaBridge | 167:84c0a372a020 | 2334 | /// |
AnnaBridge | 167:84c0a372a020 | 2335 | /// @code{.c} |
AnnaBridge | 167:84c0a372a020 | 2336 | /// void setAutoAckStateTimings() |
AnnaBridge | 167:84c0a372a020 | 2337 | /// { |
AnnaBridge | 167:84c0a372a020 | 2338 | /// RAIL_StateTiming_t timings; |
AnnaBridge | 167:84c0a372a020 | 2339 | /// |
AnnaBridge | 167:84c0a372a020 | 2340 | /// // User is already in auto ACK and wants a turnaround of 192us |
AnnaBridge | 167:84c0a372a020 | 2341 | /// timings.rxToTx = 192; |
AnnaBridge | 167:84c0a372a020 | 2342 | /// timings.txToRx = 192 - 10; |
AnnaBridge | 167:84c0a372a020 | 2343 | /// |
AnnaBridge | 167:84c0a372a020 | 2344 | /// // Set other fields of timings... |
AnnaBridge | 167:84c0a372a020 | 2345 | /// timings.idleToRx = 100; |
AnnaBridge | 167:84c0a372a020 | 2346 | /// timings.idleToTx = 100; |
AnnaBridge | 167:84c0a372a020 | 2347 | /// timings.rxSearchTimeout = 0; |
AnnaBridge | 167:84c0a372a020 | 2348 | /// timings.txToRxSearchTimeout = 0; |
AnnaBridge | 167:84c0a372a020 | 2349 | /// |
AnnaBridge | 167:84c0a372a020 | 2350 | /// RAIL_SetStateTiming(railHandle, &timings); |
AnnaBridge | 167:84c0a372a020 | 2351 | /// } |
AnnaBridge | 167:84c0a372a020 | 2352 | /// @endcode |
AnnaBridge | 167:84c0a372a020 | 2353 | /// |
AnnaBridge | 167:84c0a372a020 | 2354 | /// As opposed to an explicit "Disable" API, simply set the "enable" |
AnnaBridge | 167:84c0a372a020 | 2355 | /// field of the RAIL_AutoAckConfig_t to false. Then, auto ACK will be |
AnnaBridge | 167:84c0a372a020 | 2356 | /// disabled and state transitions will be returned to the values set |
AnnaBridge | 167:84c0a372a020 | 2357 | /// in \ref RAIL_AutoAckConfig_t. During this disable, the "ackTimeout" field |
AnnaBridge | 167:84c0a372a020 | 2358 | /// isn't used. |
AnnaBridge | 167:84c0a372a020 | 2359 | /// |
Anna Bridge |
160:5571c4ff569f | 2360 | RAIL_Status_t RAIL_ConfigAutoAck(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 2361 | const RAIL_AutoAckConfig_t *config); |
Anna Bridge |
142:4eea097334d6 | 2362 | |
Anna Bridge |
142:4eea097334d6 | 2363 | /** |
Anna Bridge |
160:5571c4ff569f | 2364 | * Returns the enable status of the auto ACK feature. |
Anna Bridge |
142:4eea097334d6 | 2365 | * |
Anna Bridge |
160:5571c4ff569f | 2366 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2367 | * @return true if auto ACK is enabled, false if disabled. |
Anna Bridge |
142:4eea097334d6 | 2368 | */ |
Anna Bridge |
160:5571c4ff569f | 2369 | bool RAIL_IsAutoAckEnabled(RAIL_Handle_t railHandle); |
Anna Bridge |
142:4eea097334d6 | 2370 | |
Anna Bridge |
142:4eea097334d6 | 2371 | /** |
Anna Bridge |
160:5571c4ff569f | 2372 | * Loads the auto ACK buffer with ACK data. |
Anna Bridge |
142:4eea097334d6 | 2373 | * |
Anna Bridge |
160:5571c4ff569f | 2374 | * @param[in] railHandle A RAIL instance handle. |
AnnaBridge | 167:84c0a372a020 | 2375 | * @param[in] ackData A pointer to ACK data to transmit. |
AnnaBridge | 167:84c0a372a020 | 2376 | * @param[in] ackDataLen Number of bytes of ACK data. |
Anna Bridge |
160:5571c4ff569f | 2377 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 2378 | * |
Anna Bridge |
160:5571c4ff569f | 2379 | * If the ACK buffer is available for updates, load the ACK buffer with data. |
Anna Bridge |
142:4eea097334d6 | 2380 | */ |
Anna Bridge |
160:5571c4ff569f | 2381 | RAIL_Status_t RAIL_WriteAutoAckFifo(RAIL_Handle_t railHandle, |
AnnaBridge | 167:84c0a372a020 | 2382 | const uint8_t *ackData, |
AnnaBridge | 167:84c0a372a020 | 2383 | uint8_t ackDataLen); |
Anna Bridge |
142:4eea097334d6 | 2384 | |
Anna Bridge |
142:4eea097334d6 | 2385 | /** |
Anna Bridge |
160:5571c4ff569f | 2386 | * Pauses/resumes RX auto ACK functionality. |
Anna Bridge |
142:4eea097334d6 | 2387 | * |
Anna Bridge |
160:5571c4ff569f | 2388 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2389 | * @param[in] pause Pause or resume RX auto acking. |
Anna Bridge |
160:5571c4ff569f | 2390 | * @return void. |
Anna Bridge |
142:4eea097334d6 | 2391 | * |
Anna Bridge |
160:5571c4ff569f | 2392 | * When RX auto acking is paused, the radio transitions to default |
Anna Bridge |
160:5571c4ff569f | 2393 | * state after receiving a packet and does not transmit an ACK. |
Anna Bridge |
160:5571c4ff569f | 2394 | * When RX auto ACK is resumed, the radio resumes automatically acking |
Anna Bridge |
160:5571c4ff569f | 2395 | * every successfully received packet. |
Anna Bridge |
142:4eea097334d6 | 2396 | */ |
Anna Bridge |
160:5571c4ff569f | 2397 | void RAIL_PauseRxAutoAck(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 2398 | bool pause); |
Anna Bridge |
160:5571c4ff569f | 2399 | |
Anna Bridge |
160:5571c4ff569f | 2400 | /** |
Anna Bridge |
160:5571c4ff569f | 2401 | * Returns whether the RX auto ACK is paused. |
Anna Bridge |
160:5571c4ff569f | 2402 | * |
Anna Bridge |
160:5571c4ff569f | 2403 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2404 | * @return true if RX auto ACK is paused, false if not paused. |
Anna Bridge |
160:5571c4ff569f | 2405 | */ |
Anna Bridge |
160:5571c4ff569f | 2406 | bool RAIL_IsRxAutoAckPaused(RAIL_Handle_t railHandle); |
Anna Bridge |
142:4eea097334d6 | 2407 | |
Anna Bridge |
142:4eea097334d6 | 2408 | /** |
Anna Bridge |
160:5571c4ff569f | 2409 | * Pauses/resumes TX auto ACK functionality. |
Anna Bridge |
142:4eea097334d6 | 2410 | * |
Anna Bridge |
160:5571c4ff569f | 2411 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2412 | * @param[in] pause Pause or resume TX auto acking. |
Anna Bridge |
160:5571c4ff569f | 2413 | * @return void. |
Anna Bridge |
142:4eea097334d6 | 2414 | * |
Anna Bridge |
160:5571c4ff569f | 2415 | * When TX auto acking is paused, the radio transitions to a default |
Anna Bridge |
160:5571c4ff569f | 2416 | * state after transmitting a packet and does not wait for an ACK. When TX |
Anna Bridge |
160:5571c4ff569f | 2417 | * auto ACK is resumed, the radio resumes automatically waiting for |
Anna Bridge |
160:5571c4ff569f | 2418 | * an ACK after a successful transmit. |
Anna Bridge |
142:4eea097334d6 | 2419 | */ |
Anna Bridge |
160:5571c4ff569f | 2420 | void RAIL_PauseTxAutoAck(RAIL_Handle_t railHandle, bool pause); |
Anna Bridge |
142:4eea097334d6 | 2421 | |
Anna Bridge |
142:4eea097334d6 | 2422 | /** |
Anna Bridge |
160:5571c4ff569f | 2423 | * Returns whether the TX auto ACK is paused. |
Anna Bridge |
142:4eea097334d6 | 2424 | * |
Anna Bridge |
160:5571c4ff569f | 2425 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2426 | * @return true if TX auto ACK is paused, false if not paused. |
Anna Bridge |
142:4eea097334d6 | 2427 | */ |
Anna Bridge |
160:5571c4ff569f | 2428 | bool RAIL_IsTxAutoAckPaused(RAIL_Handle_t railHandle); |
Anna Bridge |
142:4eea097334d6 | 2429 | |
Anna Bridge |
142:4eea097334d6 | 2430 | /** |
Anna Bridge |
160:5571c4ff569f | 2431 | * Modifies the upcoming ACK to use the TX Buffer. |
Anna Bridge |
142:4eea097334d6 | 2432 | * |
Anna Bridge |
160:5571c4ff569f | 2433 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2434 | * @return Status code indicating success of the function call. This call will |
Anna Bridge |
160:5571c4ff569f | 2435 | * fail if it is too late to modify the outgoing ACK. |
Anna Bridge |
142:4eea097334d6 | 2436 | * |
Anna Bridge |
142:4eea097334d6 | 2437 | * This function allows the application to use the normal TX buffer as the data |
Anna Bridge |
160:5571c4ff569f | 2438 | * source for the upcoming ACK. The ACK modification to use the TX buffer only |
Anna Bridge |
160:5571c4ff569f | 2439 | * applies to one ACK transmission. |
Anna Bridge |
142:4eea097334d6 | 2440 | * |
Anna Bridge |
160:5571c4ff569f | 2441 | * This function only returns true if the following conditions are met: |
Anna Bridge |
160:5571c4ff569f | 2442 | * - Radio has not already decided to use the ACK buffer AND |
Anna Bridge |
160:5571c4ff569f | 2443 | * - Radio is either looking for sync, receiving the packet after sync, or in |
Anna Bridge |
160:5571c4ff569f | 2444 | * the Rx2Tx turnaround before the ACK is sent. |
Anna Bridge |
142:4eea097334d6 | 2445 | */ |
Anna Bridge |
160:5571c4ff569f | 2446 | RAIL_Status_t RAIL_UseTxFifoForAutoAck(RAIL_Handle_t railHandle); |
Anna Bridge |
142:4eea097334d6 | 2447 | |
Anna Bridge |
142:4eea097334d6 | 2448 | /** |
Anna Bridge |
160:5571c4ff569f | 2449 | * Cancels the upcoming ACK. |
Anna Bridge |
142:4eea097334d6 | 2450 | * |
Anna Bridge |
160:5571c4ff569f | 2451 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2452 | * @return Status code indicating success of the function call. This call will |
Anna Bridge |
160:5571c4ff569f | 2453 | * fail if it is too late to modify the outgoing ACK. |
Anna Bridge |
142:4eea097334d6 | 2454 | * |
Anna Bridge |
160:5571c4ff569f | 2455 | * This function allows the application to cancel the upcoming automatic |
Anna Bridge |
160:5571c4ff569f | 2456 | * acknowledgment. |
Anna Bridge |
142:4eea097334d6 | 2457 | * |
Anna Bridge |
160:5571c4ff569f | 2458 | * This function only returns true if the following conditions are met: |
Anna Bridge |
160:5571c4ff569f | 2459 | * - Radio has not already decided to transmit the ACK AND |
Anna Bridge |
142:4eea097334d6 | 2460 | * - Radio is either looking for sync, receiving the packet after sync or in |
Anna Bridge |
160:5571c4ff569f | 2461 | * the Rx2Tx turnaround before the ACK is sent. |
Anna Bridge |
142:4eea097334d6 | 2462 | */ |
Anna Bridge |
160:5571c4ff569f | 2463 | RAIL_Status_t RAIL_CancelAutoAck(RAIL_Handle_t railHandle); |
Anna Bridge |
142:4eea097334d6 | 2464 | |
Anna Bridge |
142:4eea097334d6 | 2465 | /** |
Anna Bridge |
160:5571c4ff569f | 2466 | * Returns whether the radio is currently waiting for an ACK. |
Anna Bridge |
142:4eea097334d6 | 2467 | * |
Anna Bridge |
160:5571c4ff569f | 2468 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2469 | * @return True if radio is waiting for ACK, false if radio is not waiting for |
Anna Bridge |
160:5571c4ff569f | 2470 | * an ACK. |
Anna Bridge |
160:5571c4ff569f | 2471 | * |
Anna Bridge |
160:5571c4ff569f | 2472 | * This function allows the application to query whether the radio is currently |
Anna Bridge |
160:5571c4ff569f | 2473 | * waiting for an ACK after a transmit operation. |
Anna Bridge |
142:4eea097334d6 | 2474 | */ |
Anna Bridge |
160:5571c4ff569f | 2475 | bool RAIL_IsAutoAckWaitingForAck(RAIL_Handle_t railHandle); |
Anna Bridge |
142:4eea097334d6 | 2476 | |
Anna Bridge |
160:5571c4ff569f | 2477 | /** @} */ // end of group Auto_Ack |
Anna Bridge |
142:4eea097334d6 | 2478 | |
Anna Bridge |
142:4eea097334d6 | 2479 | /****************************************************************************** |
Anna Bridge |
142:4eea097334d6 | 2480 | * Calibration |
Anna Bridge |
142:4eea097334d6 | 2481 | *****************************************************************************/ |
AnnaBridge | 167:84c0a372a020 | 2482 | /// @addtogroup Calibration |
AnnaBridge | 167:84c0a372a020 | 2483 | /// @brief APIs for calibrating the radio |
AnnaBridge | 167:84c0a372a020 | 2484 | /// @{ |
AnnaBridge | 167:84c0a372a020 | 2485 | /// |
AnnaBridge | 167:84c0a372a020 | 2486 | /// These APIs can be used to calibrate the radio. The RAIL library |
AnnaBridge | 167:84c0a372a020 | 2487 | /// determines which calibrations are necessary. Calibrations can |
AnnaBridge | 167:84c0a372a020 | 2488 | /// be enabled/disabled with the RAIL_CalMask_t parameter. |
AnnaBridge | 167:84c0a372a020 | 2489 | /// |
AnnaBridge | 167:84c0a372a020 | 2490 | /// Some calibrations produce values that can be saved and reapplied to |
AnnaBridge | 167:84c0a372a020 | 2491 | /// save repetition of the calibration process. |
AnnaBridge | 167:84c0a372a020 | 2492 | /// |
AnnaBridge | 167:84c0a372a020 | 2493 | /// Calibrations can either be run with \ref RAIL_Calibrate, or with the |
AnnaBridge | 167:84c0a372a020 | 2494 | /// individual chip-specific calibration routines. An example for running code |
AnnaBridge | 167:84c0a372a020 | 2495 | /// with \ref RAIL_Calibrate looks like: |
AnnaBridge | 167:84c0a372a020 | 2496 | /// |
AnnaBridge | 167:84c0a372a020 | 2497 | /// @code{.c} |
AnnaBridge | 167:84c0a372a020 | 2498 | /// static RAIL_CalValues_t calValues = RAIL_CALVALUES_UNINIT; |
AnnaBridge | 167:84c0a372a020 | 2499 | /// |
AnnaBridge | 167:84c0a372a020 | 2500 | /// void RAILCb_Event(RAIL_Handle_t railHandle, RAIL_Events_t events) { |
AnnaBridge | 167:84c0a372a020 | 2501 | /// // Omitting other event handlers |
AnnaBridge | 167:84c0a372a020 | 2502 | /// if (events & RAIL_EVENT_CAL_NEEDED) { |
AnnaBridge | 167:84c0a372a020 | 2503 | /// // Run all pending calibrations, and save the results |
AnnaBridge | 167:84c0a372a020 | 2504 | /// RAIL_Calibrate(railHandle, &calValues, RAIL_CAL_ALL_PENDING); |
AnnaBridge | 167:84c0a372a020 | 2505 | /// } |
AnnaBridge | 167:84c0a372a020 | 2506 | /// } |
AnnaBridge | 167:84c0a372a020 | 2507 | /// @endcode |
AnnaBridge | 167:84c0a372a020 | 2508 | /// |
AnnaBridge | 167:84c0a372a020 | 2509 | /// Alternatively, if the image rejection calibration for your chip can be |
AnnaBridge | 167:84c0a372a020 | 2510 | /// determined ahead of time, such as by running the calibration on a separate |
AnnaBridge | 167:84c0a372a020 | 2511 | /// firmware image on each chip, then the following calibration process will |
AnnaBridge | 167:84c0a372a020 | 2512 | /// result in smaller code. |
AnnaBridge | 167:84c0a372a020 | 2513 | /// |
AnnaBridge | 167:84c0a372a020 | 2514 | /// @code{.c} |
AnnaBridge | 167:84c0a372a020 | 2515 | /// static uint32_t imageRejection = IRCAL_VALUE; |
AnnaBridge | 167:84c0a372a020 | 2516 | /// |
AnnaBridge | 167:84c0a372a020 | 2517 | /// void RAILCb_Event(RAIL_Handle_t railHandle, RAIL_Events_t events) { |
AnnaBridge | 167:84c0a372a020 | 2518 | /// // Omitting other event handlers |
AnnaBridge | 167:84c0a372a020 | 2519 | /// if (events & RAIL_EVENT_CAL_NEEDED) { |
AnnaBridge | 167:84c0a372a020 | 2520 | /// RAIL_CalMask_t pendingCals = RAIL_GetPendingCal(railHandle); |
AnnaBridge | 167:84c0a372a020 | 2521 | /// // Disable the radio if we have to do an offline calibration |
AnnaBridge | 167:84c0a372a020 | 2522 | /// if (pendingCals & RAIL_CAL_TEMP_VC0) { |
AnnaBridge | 167:84c0a372a020 | 2523 | /// RAIL_CalibrateTemp(railHandle); |
AnnaBridge | 167:84c0a372a020 | 2524 | /// } |
AnnaBridge | 167:84c0a372a020 | 2525 | /// if (pendingCals & RAIL_CAL_ONETIME_IRCAL) { |
AnnaBridge | 167:84c0a372a020 | 2526 | /// RAIL_ApplyIrCalibration(railHandle, imageRejection); |
AnnaBridge | 167:84c0a372a020 | 2527 | /// } |
AnnaBridge | 167:84c0a372a020 | 2528 | /// } |
AnnaBridge | 167:84c0a372a020 | 2529 | /// } |
AnnaBridge | 167:84c0a372a020 | 2530 | /// @endcode |
Anna Bridge |
142:4eea097334d6 | 2531 | |
Anna Bridge |
142:4eea097334d6 | 2532 | /** |
Anna Bridge |
142:4eea097334d6 | 2533 | * Initialize RAIL Calibration |
Anna Bridge |
142:4eea097334d6 | 2534 | * |
Anna Bridge |
160:5571c4ff569f | 2535 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2536 | * @param[in] calEnable A bitmask of which calibrations to enable for callback |
Anna Bridge |
160:5571c4ff569f | 2537 | * notification. The exact meaning of these bits is chip specific. |
Anna Bridge |
160:5571c4ff569f | 2538 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 2539 | * |
Anna Bridge |
142:4eea097334d6 | 2540 | * Calibration initialization provides the calibration settings that |
Anna Bridge |
142:4eea097334d6 | 2541 | * correspond to the current radio configuration. |
Anna Bridge |
142:4eea097334d6 | 2542 | */ |
Anna Bridge |
160:5571c4ff569f | 2543 | RAIL_Status_t RAIL_ConfigCal(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 2544 | RAIL_CalMask_t calEnable); |
Anna Bridge |
142:4eea097334d6 | 2545 | |
Anna Bridge |
142:4eea097334d6 | 2546 | /** |
Anna Bridge |
160:5571c4ff569f | 2547 | * Starts the calibration process. |
Anna Bridge |
142:4eea097334d6 | 2548 | * |
Anna Bridge |
160:5571c4ff569f | 2549 | * @param[in] railHandle A RAIL instance handle. |
AnnaBridge | 167:84c0a372a020 | 2550 | * @param[in,out] calValues A structure of calibration values to apply. |
AnnaBridge | 167:84c0a372a020 | 2551 | * If a valid calibration values structure is provided and the structure |
AnnaBridge | 167:84c0a372a020 | 2552 | * contains valid calibration values, those values will be applied to the |
AnnaBridge | 167:84c0a372a020 | 2553 | * hardware, and the RAIL library will cache those values for use again later. |
AnnaBridge | 167:84c0a372a020 | 2554 | * If a valid calibration values structure is provided and the structure |
AnnaBridge | 167:84c0a372a020 | 2555 | * contains a calibration value of \ref RAIL_CAL_INVALID_VALUE for the |
AnnaBridge | 167:84c0a372a020 | 2556 | * desired calibration, the desired calibration will run, the calibration |
AnnaBridge | 167:84c0a372a020 | 2557 | * values structure will be updated with a valid calibration value, and the |
AnnaBridge | 167:84c0a372a020 | 2558 | * RAIL library will cache that value for use again later. |
AnnaBridge | 167:84c0a372a020 | 2559 | * If a NULL pointer is provided, the desired calibration will run, |
AnnaBridge | 167:84c0a372a020 | 2560 | * and the RAIL library will cache that value for use again later; however, |
AnnaBridge | 167:84c0a372a020 | 2561 | * the valid calibration value will not be returned to the application. |
Anna Bridge |
160:5571c4ff569f | 2562 | * @param[in] calForce A mask to force specific calibration(s) to execute. |
Anna Bridge |
160:5571c4ff569f | 2563 | * To run all pending calibrations, use the value \ref RAIL_CAL_ALL_PENDING. |
Anna Bridge |
160:5571c4ff569f | 2564 | * Only the calibrations specified will run, even if not enabled during |
Anna Bridge |
160:5571c4ff569f | 2565 | * initialization. |
Anna Bridge |
160:5571c4ff569f | 2566 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 2567 | * |
AnnaBridge | 167:84c0a372a020 | 2568 | * If calibrations were performed previously and the application saves the |
AnnaBridge | 167:84c0a372a020 | 2569 | * calibration values (i.e. call this function with a calibration values |
AnnaBridge | 167:84c0a372a020 | 2570 | * structure containing calibration values of \ref RAIL_CAL_INVALID_VALUE |
AnnaBridge | 167:84c0a372a020 | 2571 | * before a reset), the application can later bypass the time it would normally |
AnnaBridge | 167:84c0a372a020 | 2572 | * take to recalibrate hardware by reusing previous calibration values (i.e. |
AnnaBridge | 167:84c0a372a020 | 2573 | * call this function with a calibration values structure containing valid |
AnnaBridge | 167:84c0a372a020 | 2574 | * calibration values after a reset). |
Anna Bridge |
160:5571c4ff569f | 2575 | * |
Anna Bridge |
160:5571c4ff569f | 2576 | * If multiple protocols are used, this function will return |
Anna Bridge |
160:5571c4ff569f | 2577 | * \ref RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is |
Anna Bridge |
160:5571c4ff569f | 2578 | * not active. The caller must attempt to re-call this function later, in that |
Anna Bridge |
160:5571c4ff569f | 2579 | * case. |
Anna Bridge |
142:4eea097334d6 | 2580 | * |
AnnaBridge | 167:84c0a372a020 | 2581 | * @note Instead of this function, consider using the individual chip-specific |
AnnaBridge | 167:84c0a372a020 | 2582 | * functions. Using the individual functions will allow for better |
AnnaBridge | 167:84c0a372a020 | 2583 | * dead-stripping if not all calibrations are run. |
Anna Bridge |
142:4eea097334d6 | 2584 | * @note Some calibrations should only be executed when the radio is IDLE. See |
Anna Bridge |
160:5571c4ff569f | 2585 | * chip-specific documentation for more details. |
Anna Bridge |
160:5571c4ff569f | 2586 | */ |
Anna Bridge |
160:5571c4ff569f | 2587 | RAIL_Status_t RAIL_Calibrate(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 2588 | RAIL_CalValues_t *calValues, |
Anna Bridge |
160:5571c4ff569f | 2589 | RAIL_CalMask_t calForce); |
Anna Bridge |
160:5571c4ff569f | 2590 | |
Anna Bridge |
160:5571c4ff569f | 2591 | /** |
Anna Bridge |
160:5571c4ff569f | 2592 | * Returns the current set of pending calibrations. |
Anna Bridge |
160:5571c4ff569f | 2593 | * |
Anna Bridge |
160:5571c4ff569f | 2594 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2595 | * @return A mask of all pending calibrations that the user has been asked to |
Anna Bridge |
160:5571c4ff569f | 2596 | * perform. |
Anna Bridge |
160:5571c4ff569f | 2597 | * |
Anna Bridge |
160:5571c4ff569f | 2598 | * This function returns a full set of pending calibrations. The only way |
Anna Bridge |
160:5571c4ff569f | 2599 | * to clear pending calibrations is to perform them using the \ref |
Anna Bridge |
160:5571c4ff569f | 2600 | * RAIL_Calibrate() API with the appropriate list of calibrations. |
Anna Bridge |
142:4eea097334d6 | 2601 | */ |
Anna Bridge |
160:5571c4ff569f | 2602 | RAIL_CalMask_t RAIL_GetPendingCal(RAIL_Handle_t railHandle); |
Anna Bridge |
160:5571c4ff569f | 2603 | |
Anna Bridge |
160:5571c4ff569f | 2604 | /** |
Anna Bridge |
160:5571c4ff569f | 2605 | * Enable/Disable PA calibration |
Anna Bridge |
160:5571c4ff569f | 2606 | * |
Anna Bridge |
160:5571c4ff569f | 2607 | * @param[in] enable Enables/Disables PA calibration |
Anna Bridge |
160:5571c4ff569f | 2608 | * @return void. |
Anna Bridge |
160:5571c4ff569f | 2609 | * |
Anna Bridge |
160:5571c4ff569f | 2610 | * Enabling this will ensure that the PA power remains constant chip to chip. |
Anna Bridge |
160:5571c4ff569f | 2611 | * By default this feature is disabled after reset. |
Anna Bridge |
160:5571c4ff569f | 2612 | * |
Anna Bridge |
160:5571c4ff569f | 2613 | * @note this function should be called before \ref RAIL_ConfigTxPower() if this |
Anna Bridge |
160:5571c4ff569f | 2614 | * feature is desired. |
Anna Bridge |
160:5571c4ff569f | 2615 | */ |
Anna Bridge |
160:5571c4ff569f | 2616 | void RAIL_EnablePaCal(bool enable); |
Anna Bridge |
160:5571c4ff569f | 2617 | |
Anna Bridge |
160:5571c4ff569f | 2618 | /** @} */ // end of group Calibration |
Anna Bridge |
160:5571c4ff569f | 2619 | |
Anna Bridge |
160:5571c4ff569f | 2620 | /****************************************************************************** |
Anna Bridge |
160:5571c4ff569f | 2621 | * RF Sense Structures |
Anna Bridge |
160:5571c4ff569f | 2622 | *****************************************************************************/ |
Anna Bridge |
160:5571c4ff569f | 2623 | /** |
Anna Bridge |
160:5571c4ff569f | 2624 | * @addtogroup Rf_Sense RF Sense |
Anna Bridge |
160:5571c4ff569f | 2625 | * @{ |
Anna Bridge |
160:5571c4ff569f | 2626 | */ |
Anna Bridge |
142:4eea097334d6 | 2627 | |
Anna Bridge |
142:4eea097334d6 | 2628 | /** |
Anna Bridge |
160:5571c4ff569f | 2629 | * Starts/stops RF Sense functionality for use during low-energy sleep modes. |
Anna Bridge |
142:4eea097334d6 | 2630 | * |
Anna Bridge |
160:5571c4ff569f | 2631 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2632 | * @param[in] band The frequency band(s) on which to sense the RF energy. |
Anna Bridge |
160:5571c4ff569f | 2633 | * To stop RF Sense, specify \ref RAIL_RFSENSE_OFF. |
Anna Bridge |
160:5571c4ff569f | 2634 | * @param[in] senseTime The time (in microseconds) the RF energy must be |
Anna Bridge |
160:5571c4ff569f | 2635 | * continually detected to be considered "sensed". |
Anna Bridge |
160:5571c4ff569f | 2636 | * @param[in] cb \ref RAIL_RfSense_CallbackPtr_t is called when the RF is |
Anna Bridge |
160:5571c4ff569f | 2637 | * sensed. Set null if polling via \ref RAIL_IsRfSensed(). |
Anna Bridge |
160:5571c4ff569f | 2638 | * @return The actual senseTime used, which may be different than |
Anna Bridge |
160:5571c4ff569f | 2639 | * requested due to limitations of the hardware. If 0, RF sense was |
Anna Bridge |
160:5571c4ff569f | 2640 | * disabled or could not be enabled (no callback will be issued). |
Anna Bridge |
142:4eea097334d6 | 2641 | * |
Anna Bridge |
160:5571c4ff569f | 2642 | * The EFR32 has the ability to sense the presence of RF Energy above -20 dBm |
Anna Bridge |
160:5571c4ff569f | 2643 | * within either or both the 2.4 GHz and Sub-GHz bands and trigger an event |
Anna Bridge |
160:5571c4ff569f | 2644 | * if that energy is continuously present for certain durations of time. |
Anna Bridge |
160:5571c4ff569f | 2645 | * |
Anna Bridge |
160:5571c4ff569f | 2646 | * @note After RF energy has been sensed, the RF Sense is automatically |
Anna Bridge |
160:5571c4ff569f | 2647 | * disabled. RAIL_StartRfSense() must be called again to reactivate it. |
Anna Bridge |
160:5571c4ff569f | 2648 | * |
AnnaBridge | 167:84c0a372a020 | 2649 | * @note Packet reception is not guaranteed to work correctly once RF Sense is |
AnnaBridge | 167:84c0a372a020 | 2650 | * enabled. To be safe, an application should turn this on only after idling |
AnnaBridge | 167:84c0a372a020 | 2651 | * the radio to stop receive and turn it off before attempting to restart |
AnnaBridge | 167:84c0a372a020 | 2652 | * receive. Since EM4 sleep causes the chip to come up through the reset |
AnnaBridge | 167:84c0a372a020 | 2653 | * vector any wake from EM4 must also shut off RF Sense to ensure proper |
AnnaBridge | 167:84c0a372a020 | 2654 | * receive functionality. |
AnnaBridge | 167:84c0a372a020 | 2655 | * |
Anna Bridge |
160:5571c4ff569f | 2656 | * @warning RF Sense functionality is only guaranteed from 0 to 85 degrees |
Anna Bridge |
160:5571c4ff569f | 2657 | * Celsius. RF Sense should be disabled outside of this temperature range. |
Anna Bridge |
142:4eea097334d6 | 2658 | */ |
AnnaBridge | 167:84c0a372a020 | 2659 | RAIL_Time_t RAIL_StartRfSense(RAIL_Handle_t railHandle, |
AnnaBridge | 167:84c0a372a020 | 2660 | RAIL_RfSenseBand_t band, |
AnnaBridge | 167:84c0a372a020 | 2661 | RAIL_Time_t senseTime, |
AnnaBridge | 167:84c0a372a020 | 2662 | RAIL_RfSense_CallbackPtr_t cb); |
Anna Bridge |
142:4eea097334d6 | 2663 | |
Anna Bridge |
142:4eea097334d6 | 2664 | /** |
Anna Bridge |
160:5571c4ff569f | 2665 | * Checks if the RF was sensed. |
Anna Bridge |
142:4eea097334d6 | 2666 | * |
Anna Bridge |
160:5571c4ff569f | 2667 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2668 | * @return true if RF was sensed since the last call to \ref RAIL_StartRfSense. |
Anna Bridge |
160:5571c4ff569f | 2669 | * False otherwise. |
Anna Bridge |
142:4eea097334d6 | 2670 | * |
Anna Bridge |
160:5571c4ff569f | 2671 | * This function is useful if \ref RAIL_StartRfSense is called with a null |
Anna Bridge |
160:5571c4ff569f | 2672 | * callback. It is generally used after EM4 reboot but can be used any time. |
Anna Bridge |
142:4eea097334d6 | 2673 | */ |
Anna Bridge |
160:5571c4ff569f | 2674 | bool RAIL_IsRfSensed(RAIL_Handle_t railHandle); |
Anna Bridge |
160:5571c4ff569f | 2675 | |
Anna Bridge |
160:5571c4ff569f | 2676 | /** @} */ // end of group Rf_Sense |
Anna Bridge |
160:5571c4ff569f | 2677 | |
Anna Bridge |
160:5571c4ff569f | 2678 | /****************************************************************************** |
Anna Bridge |
160:5571c4ff569f | 2679 | * Multiprotocol Structures |
Anna Bridge |
160:5571c4ff569f | 2680 | *****************************************************************************/ |
Anna Bridge |
160:5571c4ff569f | 2681 | /** |
Anna Bridge |
160:5571c4ff569f | 2682 | * @addtogroup Multiprotocol |
Anna Bridge |
160:5571c4ff569f | 2683 | * @brief Multiprotocol scheduler APIs to support multiple time-sliced PHYs. |
Anna Bridge |
160:5571c4ff569f | 2684 | * @{ |
Anna Bridge |
160:5571c4ff569f | 2685 | */ |
Anna Bridge |
142:4eea097334d6 | 2686 | |
Anna Bridge |
142:4eea097334d6 | 2687 | /** |
Anna Bridge |
160:5571c4ff569f | 2688 | * Yields the radio to other configurations |
Anna Bridge |
160:5571c4ff569f | 2689 | * |
Anna Bridge |
160:5571c4ff569f | 2690 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2691 | * @return void. |
Anna Bridge |
160:5571c4ff569f | 2692 | * |
Anna Bridge |
160:5571c4ff569f | 2693 | * This function is used to indicate that the previous transmit or scheduled |
Anna Bridge |
160:5571c4ff569f | 2694 | * receive operation has completed. It must be used in multiprotocol RAIL since |
Anna Bridge |
160:5571c4ff569f | 2695 | * the scheduler assumes that any transmit or receive operation that is started |
Anna Bridge |
160:5571c4ff569f | 2696 | * by you can go on infinitely based on state transitions and your protocol. |
AnnaBridge | 167:84c0a372a020 | 2697 | * RAIL will not allow a lower priority tasks to run until this is called so it |
AnnaBridge | 167:84c0a372a020 | 2698 | * can negatively impact performance of those protocols if this is omitted or |
AnnaBridge | 167:84c0a372a020 | 2699 | * delayed. It is also possible to simply call the \ref RAIL_Idle() API to |
AnnaBridge | 167:84c0a372a020 | 2700 | * to both terminate the operation and idle the radio. In single protocol RAIL |
AnnaBridge | 167:84c0a372a020 | 2701 | * this API does nothing. |
Anna Bridge |
160:5571c4ff569f | 2702 | * |
Anna Bridge |
160:5571c4ff569f | 2703 | * See \ref rail_radio_scheduler_yield for more details. |
Anna Bridge |
142:4eea097334d6 | 2704 | */ |
Anna Bridge |
160:5571c4ff569f | 2705 | void RAIL_YieldRadio(RAIL_Handle_t railHandle); |
Anna Bridge |
160:5571c4ff569f | 2706 | |
Anna Bridge |
160:5571c4ff569f | 2707 | /** |
Anna Bridge |
160:5571c4ff569f | 2708 | * Get the status of the RAIL scheduler. |
Anna Bridge |
160:5571c4ff569f | 2709 | * |
Anna Bridge |
160:5571c4ff569f | 2710 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2711 | * @return \ref RAIL_SchedulerStatus_t status. |
Anna Bridge |
160:5571c4ff569f | 2712 | * |
AnnaBridge | 167:84c0a372a020 | 2713 | * This function can only be called from callback context after the |
AnnaBridge | 167:84c0a372a020 | 2714 | * \ref RAIL_EVENT_SCHEDULER_STATUS event occurs. |
Anna Bridge |
160:5571c4ff569f | 2715 | */ |
Anna Bridge |
160:5571c4ff569f | 2716 | RAIL_SchedulerStatus_t RAIL_GetSchedulerStatus(RAIL_Handle_t railHandle); |
Anna Bridge |
160:5571c4ff569f | 2717 | |
Anna Bridge |
160:5571c4ff569f | 2718 | /** @} */ // end of group Multiprotocol |
Anna Bridge |
142:4eea097334d6 | 2719 | |
Anna Bridge |
142:4eea097334d6 | 2720 | /****************************************************************************** |
Anna Bridge |
142:4eea097334d6 | 2721 | * Diagnostic |
Anna Bridge |
142:4eea097334d6 | 2722 | *****************************************************************************/ |
Anna Bridge |
142:4eea097334d6 | 2723 | /** |
Anna Bridge |
142:4eea097334d6 | 2724 | * @addtogroup Diagnostic |
Anna Bridge |
142:4eea097334d6 | 2725 | * @brief APIs for diagnostic and test chip modes |
Anna Bridge |
142:4eea097334d6 | 2726 | * @{ |
Anna Bridge |
142:4eea097334d6 | 2727 | */ |
Anna Bridge |
142:4eea097334d6 | 2728 | |
Anna Bridge |
142:4eea097334d6 | 2729 | /** |
Anna Bridge |
160:5571c4ff569f | 2730 | * Enables or disables direct mode for RAIL. |
Anna Bridge |
160:5571c4ff569f | 2731 | * |
Anna Bridge |
160:5571c4ff569f | 2732 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2733 | * @param[in] enable Whether or not to enable direct mode. |
Anna Bridge |
160:5571c4ff569f | 2734 | * @return \ref RAIL_STATUS_NO_ERROR on success and an error code on failure. |
Anna Bridge |
142:4eea097334d6 | 2735 | * |
Anna Bridge |
160:5571c4ff569f | 2736 | * @warning This API configures fixed pins for TX data in, RX data out, |
Anna Bridge |
160:5571c4ff569f | 2737 | * RX clock out. There should be more control over these pins in the |
Anna Bridge |
160:5571c4ff569f | 2738 | * future but they are currently fixed. Also, this API is not safe to |
Anna Bridge |
160:5571c4ff569f | 2739 | * use in a true multiprotocol app. |
Anna Bridge |
142:4eea097334d6 | 2740 | * |
Anna Bridge |
160:5571c4ff569f | 2741 | * In this mode packets are output and input directly to the radio via GPIO |
Anna Bridge |
160:5571c4ff569f | 2742 | * and RAIL packet handling is ignored. On the EFR32, the DIN pin in TX is |
Anna Bridge |
142:4eea097334d6 | 2743 | * EFR32_PC10, which corresponds to EXP_HEADER15/WSTKP12, and the DOUT pin in |
Anna Bridge |
142:4eea097334d6 | 2744 | * RX is EFR32_PC11, which corresponds to EXP_HEADER16/WSTKP13. |
Anna Bridge |
142:4eea097334d6 | 2745 | */ |
Anna Bridge |
160:5571c4ff569f | 2746 | RAIL_Status_t RAIL_EnableDirectMode(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 2747 | bool enable); |
Anna Bridge |
142:4eea097334d6 | 2748 | |
Anna Bridge |
142:4eea097334d6 | 2749 | /** |
Anna Bridge |
160:5571c4ff569f | 2750 | * Sets the crystal tuning. |
Anna Bridge |
142:4eea097334d6 | 2751 | * |
Anna Bridge |
160:5571c4ff569f | 2752 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2753 | * @param[in] tune A chip-dependent crystal capacitor bank tuning parameter. |
Anna Bridge |
160:5571c4ff569f | 2754 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 2755 | * |
Anna Bridge |
160:5571c4ff569f | 2756 | * Tunes the crystal that the radio depends on to change the location of the |
Anna Bridge |
160:5571c4ff569f | 2757 | * center frequency for transmitting and receiving. This function will only |
Anna Bridge |
160:5571c4ff569f | 2758 | * succeed if the radio is idle at the time of the call. |
Anna Bridge |
160:5571c4ff569f | 2759 | * |
Anna Bridge |
160:5571c4ff569f | 2760 | * @note This function proportionally affects the entire chip's timing |
Anna Bridge |
160:5571c4ff569f | 2761 | * across all its peripherals, including radio tuning and channel spacing. |
Anna Bridge |
160:5571c4ff569f | 2762 | * A separate function, \ref RAIL_SetFreqOffset(), can be used to adjust |
Anna Bridge |
160:5571c4ff569f | 2763 | * just the radio tuner without disturbing channel spacing or other chip |
Anna Bridge |
160:5571c4ff569f | 2764 | * peripheral timing. |
Anna Bridge |
142:4eea097334d6 | 2765 | */ |
Anna Bridge |
160:5571c4ff569f | 2766 | RAIL_Status_t RAIL_SetTune(RAIL_Handle_t railHandle, uint32_t tune); |
Anna Bridge |
142:4eea097334d6 | 2767 | |
Anna Bridge |
142:4eea097334d6 | 2768 | /** |
Anna Bridge |
160:5571c4ff569f | 2769 | * Gets the crystal tuning. |
Anna Bridge |
142:4eea097334d6 | 2770 | * |
Anna Bridge |
160:5571c4ff569f | 2771 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2772 | * @return A chip-dependent crystal capacitor bank tuning parameter. |
Anna Bridge |
142:4eea097334d6 | 2773 | * |
Anna Bridge |
160:5571c4ff569f | 2774 | * Retrieves the current tuning value used by the crystal that the radio |
Anna Bridge |
160:5571c4ff569f | 2775 | * depends on. |
Anna Bridge |
142:4eea097334d6 | 2776 | */ |
Anna Bridge |
160:5571c4ff569f | 2777 | uint32_t RAIL_GetTune(RAIL_Handle_t railHandle); |
Anna Bridge |
142:4eea097334d6 | 2778 | |
Anna Bridge |
142:4eea097334d6 | 2779 | /** |
Anna Bridge |
160:5571c4ff569f | 2780 | * Gets the frequency offset. |
Anna Bridge |
142:4eea097334d6 | 2781 | * |
Anna Bridge |
160:5571c4ff569f | 2782 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2783 | * @return Returns the measured frequency offset on a received packet. |
Anna Bridge |
160:5571c4ff569f | 2784 | * The units are described in the \ref RAIL_FrequencyOffset_t |
Anna Bridge |
160:5571c4ff569f | 2785 | * documentation. If this returns \ref RAIL_FREQUENCY_OFFSET_INVALID |
Anna Bridge |
160:5571c4ff569f | 2786 | * it was called while the radio wasn't active and there is no way |
Anna Bridge |
160:5571c4ff569f | 2787 | * to get the frequency offset. |
Anna Bridge |
142:4eea097334d6 | 2788 | * |
Anna Bridge |
160:5571c4ff569f | 2789 | * Retrieves the measured frequency offset used during the previous |
Anna Bridge |
160:5571c4ff569f | 2790 | * received packet, which includes the current radio frequency offset |
AnnaBridge | 167:84c0a372a020 | 2791 | * (see \ref RAIL_SetFreqOffset()). If the chip has not been in RX, |
Anna Bridge |
160:5571c4ff569f | 2792 | * it returns the nominal radio frequency offset. |
Anna Bridge |
142:4eea097334d6 | 2793 | */ |
Anna Bridge |
160:5571c4ff569f | 2794 | RAIL_FrequencyOffset_t RAIL_GetRxFreqOffset(RAIL_Handle_t railHandle); |
Anna Bridge |
142:4eea097334d6 | 2795 | |
Anna Bridge |
142:4eea097334d6 | 2796 | /** |
Anna Bridge |
160:5571c4ff569f | 2797 | * Sets the nominal radio frequency offset. |
Anna Bridge |
142:4eea097334d6 | 2798 | * |
Anna Bridge |
160:5571c4ff569f | 2799 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2800 | * @param[in] freqOffset \ref RAIL_FrequencyOffset_t parameter (signed, 2's |
Anna Bridge |
160:5571c4ff569f | 2801 | * complement). |
Anna Bridge |
160:5571c4ff569f | 2802 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 2803 | * |
Anna Bridge |
160:5571c4ff569f | 2804 | * This is used to adjust the radio's tuning frequency slightly up or down. |
Anna Bridge |
160:5571c4ff569f | 2805 | * It might be used in conjunction with \ref RAIL_GetRxFreqOffset() after |
Anna Bridge |
160:5571c4ff569f | 2806 | * receiving a packet from a peer to adjust the tuner to better match the |
Anna Bridge |
160:5571c4ff569f | 2807 | * peer's tuned frequency. |
Anna Bridge |
160:5571c4ff569f | 2808 | * |
Anna Bridge |
160:5571c4ff569f | 2809 | * @note Unlike \ref RAIL_SetTune(), which affects the entire chip's |
Anna Bridge |
160:5571c4ff569f | 2810 | * timing including radio tuning and channel spacing, this function |
Anna Bridge |
160:5571c4ff569f | 2811 | * only affects radio tuning without disturbing channel spacing or |
Anna Bridge |
160:5571c4ff569f | 2812 | * other chip peripheral timing. |
Anna Bridge |
142:4eea097334d6 | 2813 | */ |
Anna Bridge |
160:5571c4ff569f | 2814 | RAIL_Status_t RAIL_SetFreqOffset(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 2815 | RAIL_FrequencyOffset_t freqOffset); |
Anna Bridge |
142:4eea097334d6 | 2816 | |
Anna Bridge |
142:4eea097334d6 | 2817 | /** |
Anna Bridge |
160:5571c4ff569f | 2818 | * Starts transmitting a stream on a certain channel. |
Anna Bridge |
142:4eea097334d6 | 2819 | * |
Anna Bridge |
160:5571c4ff569f | 2820 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2821 | * @param[in] channel A channel on which to emit a stream. |
Anna Bridge |
160:5571c4ff569f | 2822 | * @param[in] mode Choose the stream mode (PN9, and so on). |
Anna Bridge |
160:5571c4ff569f | 2823 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 2824 | * |
Anna Bridge |
160:5571c4ff569f | 2825 | * Begins streaming onto the given channel. The sources can either be an |
Anna Bridge |
160:5571c4ff569f | 2826 | * unmodulated carrier wave, or an encoded stream of bits from a PN9 source. |
Anna Bridge |
160:5571c4ff569f | 2827 | * All ongoing radio operations will be stopped before transmission begins. |
Anna Bridge |
142:4eea097334d6 | 2828 | */ |
Anna Bridge |
160:5571c4ff569f | 2829 | RAIL_Status_t RAIL_StartTxStream(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 2830 | uint16_t channel, |
Anna Bridge |
160:5571c4ff569f | 2831 | RAIL_StreamMode_t mode); |
Anna Bridge |
142:4eea097334d6 | 2832 | |
Anna Bridge |
142:4eea097334d6 | 2833 | /** |
Anna Bridge |
160:5571c4ff569f | 2834 | * Stops stream transmission. |
Anna Bridge |
142:4eea097334d6 | 2835 | * |
Anna Bridge |
160:5571c4ff569f | 2836 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2837 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 2838 | * |
Anna Bridge |
160:5571c4ff569f | 2839 | * Halts the transmission started by RAIL_StartTxStream(). |
Anna Bridge |
142:4eea097334d6 | 2840 | */ |
Anna Bridge |
160:5571c4ff569f | 2841 | RAIL_Status_t RAIL_StopTxStream(RAIL_Handle_t railHandle); |
Anna Bridge |
142:4eea097334d6 | 2842 | |
AnnaBridge | 167:84c0a372a020 | 2843 | /** |
AnnaBridge | 167:84c0a372a020 | 2844 | * Configures the verification of radio memory contents. |
AnnaBridge | 167:84c0a372a020 | 2845 | * |
AnnaBridge | 167:84c0a372a020 | 2846 | * @param[in] railHandle A RAIL instance handle. |
AnnaBridge | 167:84c0a372a020 | 2847 | * @param[in,out] configVerify A configuration structure made available to |
AnnaBridge | 167:84c0a372a020 | 2848 | * RAIL in order to perform radio state verification. This structure must be |
AnnaBridge | 167:84c0a372a020 | 2849 | * allocated in application global read-write memory. RAIL may modify |
AnnaBridge | 167:84c0a372a020 | 2850 | * fields within or referenced by this structure during its operation. |
AnnaBridge | 167:84c0a372a020 | 2851 | * @param[in] radioConfig A ptr to a radioConfig that is to be used as a |
AnnaBridge | 167:84c0a372a020 | 2852 | * white list for verifying memory contents. |
AnnaBridge | 167:84c0a372a020 | 2853 | * @param[in] cb A callback that notifies the application of a mismatch in |
AnnaBridge | 167:84c0a372a020 | 2854 | * expected vs actual memory contents. A NULL parameter may be passed in |
AnnaBridge | 167:84c0a372a020 | 2855 | * if a callback is not provided by the application. |
AnnaBridge | 167:84c0a372a020 | 2856 | * @return \ref RAIL_STATUS_NO_ERROR if setup of the verification feature |
AnnaBridge | 167:84c0a372a020 | 2857 | * successfully occurred. |
AnnaBridge | 167:84c0a372a020 | 2858 | * \ref RAIL_STATUS_INVALID_PARAMETER is returned if the provided railHandle |
AnnaBridge | 167:84c0a372a020 | 2859 | * or configVerify structures are invalid. |
AnnaBridge | 167:84c0a372a020 | 2860 | */ |
AnnaBridge | 167:84c0a372a020 | 2861 | RAIL_Status_t RAIL_ConfigVerification(RAIL_Handle_t railHandle, |
AnnaBridge | 167:84c0a372a020 | 2862 | RAIL_VerifyConfig_t *configVerify, |
AnnaBridge | 167:84c0a372a020 | 2863 | const uint32_t *radioConfig, |
AnnaBridge | 167:84c0a372a020 | 2864 | RAIL_VerifyCallbackPtr_t cb); |
AnnaBridge | 167:84c0a372a020 | 2865 | |
AnnaBridge | 167:84c0a372a020 | 2866 | /** |
AnnaBridge | 167:84c0a372a020 | 2867 | * Verifies radio memory contents. |
AnnaBridge | 167:84c0a372a020 | 2868 | * |
AnnaBridge | 167:84c0a372a020 | 2869 | * @param[in,out] configVerify A configuration structure made available to |
AnnaBridge | 167:84c0a372a020 | 2870 | * RAIL in order to perform radio state verification. This structure must be |
AnnaBridge | 167:84c0a372a020 | 2871 | * allocated in application global read-write memory. RAIL may modify |
AnnaBridge | 167:84c0a372a020 | 2872 | * fields within or referenced by this structure during its operation. |
AnnaBridge | 167:84c0a372a020 | 2873 | * @param[in] durationUs The duration (in microseconds) for how long memory |
AnnaBridge | 167:84c0a372a020 | 2874 | * verification should occur before returning to the application. A value of |
AnnaBridge | 167:84c0a372a020 | 2875 | * RAIL_VERIFY_DURATION_MAX indicates that all memory contents should be |
AnnaBridge | 167:84c0a372a020 | 2876 | * verified before returning to the application. |
AnnaBridge | 167:84c0a372a020 | 2877 | * @param[in] restart This flag only has meaning if a previous call of this |
AnnaBridge | 167:84c0a372a020 | 2878 | * function returned \ref RAIL_STATUS_SUSPENDED. By restarting (true), the |
AnnaBridge | 167:84c0a372a020 | 2879 | * verification process starts over from the beginning, or by resuming |
AnnaBridge | 167:84c0a372a020 | 2880 | * where verification left off after being suspended (false), verification |
AnnaBridge | 167:84c0a372a020 | 2881 | * can proceed towards completion. |
AnnaBridge | 167:84c0a372a020 | 2882 | * @return \ref RAIL_STATUS_NO_ERROR if the contents of all applicable |
AnnaBridge | 167:84c0a372a020 | 2883 | * memory locations have been verified. |
AnnaBridge | 167:84c0a372a020 | 2884 | * \ref RAIL_STATUS_SUSPENDED is returned if the provided test duration |
AnnaBridge | 167:84c0a372a020 | 2885 | * expired but the time was not sufficient to verify all memory contents. |
AnnaBridge | 167:84c0a372a020 | 2886 | * By calling \ref RAIL_Verify again, further verification will commence. |
AnnaBridge | 167:84c0a372a020 | 2887 | * \ref RAIL_STATUS_INVALID_PARAMETER is returned if the provided |
AnnaBridge | 167:84c0a372a020 | 2888 | * verifyConfig structure pointer is not configured for use by the active |
AnnaBridge | 167:84c0a372a020 | 2889 | * RAIL handle. |
AnnaBridge | 167:84c0a372a020 | 2890 | * \ref RAIL_STATUS_INVALID_STATE is returned if any of the verified |
AnnaBridge | 167:84c0a372a020 | 2891 | * memory contents are different from their reference values. |
AnnaBridge | 167:84c0a372a020 | 2892 | */ |
AnnaBridge | 167:84c0a372a020 | 2893 | RAIL_Status_t RAIL_Verify(RAIL_VerifyConfig_t *configVerify, |
AnnaBridge | 167:84c0a372a020 | 2894 | uint32_t durationUs, |
AnnaBridge | 167:84c0a372a020 | 2895 | bool restart); |
AnnaBridge | 167:84c0a372a020 | 2896 | |
Anna Bridge |
160:5571c4ff569f | 2897 | /** @} */ // end of group Diagnostic |
Anna Bridge |
142:4eea097334d6 | 2898 | |
Anna Bridge |
160:5571c4ff569f | 2899 | #ifndef DOXYGEN_SHOULD_SKIP_THIS |
Anna Bridge |
142:4eea097334d6 | 2900 | |
Anna Bridge |
142:4eea097334d6 | 2901 | /****************************************************************************** |
Anna Bridge |
142:4eea097334d6 | 2902 | * Debug |
Anna Bridge |
142:4eea097334d6 | 2903 | *****************************************************************************/ |
Anna Bridge |
142:4eea097334d6 | 2904 | /** |
Anna Bridge |
142:4eea097334d6 | 2905 | * @addtogroup Debug |
Anna Bridge |
142:4eea097334d6 | 2906 | * @brief APIs for debugging |
Anna Bridge |
142:4eea097334d6 | 2907 | * @{ |
Anna Bridge |
142:4eea097334d6 | 2908 | */ |
Anna Bridge |
142:4eea097334d6 | 2909 | |
Anna Bridge |
142:4eea097334d6 | 2910 | /** |
Anna Bridge |
160:5571c4ff569f | 2911 | * Configures the debug mode for the radio library. Do not use this function |
Anna Bridge |
160:5571c4ff569f | 2912 | * unless instructed by Silicon Labs. |
Anna Bridge |
160:5571c4ff569f | 2913 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2914 | * @param[in] debugMode Debug mode to enter. |
Anna Bridge |
160:5571c4ff569f | 2915 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 2916 | */ |
Anna Bridge |
160:5571c4ff569f | 2917 | RAIL_Status_t RAIL_SetDebugMode(RAIL_Handle_t railHandle, uint32_t debugMode); |
Anna Bridge |
142:4eea097334d6 | 2918 | |
Anna Bridge |
142:4eea097334d6 | 2919 | /** |
Anna Bridge |
160:5571c4ff569f | 2920 | * Returns the debug mode for the radio library. Do not use this function |
Anna Bridge |
160:5571c4ff569f | 2921 | * unless instructed by Silicon Labs. |
Anna Bridge |
160:5571c4ff569f | 2922 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2923 | * @return Debug mode for the radio library. |
Anna Bridge |
142:4eea097334d6 | 2924 | */ |
Anna Bridge |
160:5571c4ff569f | 2925 | uint32_t RAIL_GetDebugMode(RAIL_Handle_t railHandle); |
Anna Bridge |
142:4eea097334d6 | 2926 | |
Anna Bridge |
142:4eea097334d6 | 2927 | /** |
Anna Bridge |
160:5571c4ff569f | 2928 | * Overrides the radio base frequency. |
Anna Bridge |
142:4eea097334d6 | 2929 | * |
Anna Bridge |
160:5571c4ff569f | 2930 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2931 | * @param[in] freq A desired frequency in Hz. |
Anna Bridge |
160:5571c4ff569f | 2932 | * @return Status code indicating success of the function call. |
Anna Bridge |
142:4eea097334d6 | 2933 | * |
Anna Bridge |
142:4eea097334d6 | 2934 | * Sets the radio to transmit at the frequency given. This function can only |
Anna Bridge |
160:5571c4ff569f | 2935 | * be used while in \ref RAIL_DEBUG_MODE_FREQ_OVERRIDE. The given frequency |
Anna Bridge |
160:5571c4ff569f | 2936 | * needs to be close to the base frequency of the current PHY. |
Anna Bridge |
142:4eea097334d6 | 2937 | */ |
Anna Bridge |
160:5571c4ff569f | 2938 | RAIL_Status_t RAIL_OverrideDebugFrequency(RAIL_Handle_t railHandle, |
Anna Bridge |
160:5571c4ff569f | 2939 | uint32_t freq); |
Anna Bridge |
160:5571c4ff569f | 2940 | |
Anna Bridge |
160:5571c4ff569f | 2941 | /** @} */ // end of group Debug |
Anna Bridge |
142:4eea097334d6 | 2942 | |
Anna Bridge |
160:5571c4ff569f | 2943 | #endif//DOXYGEN_SHOULD_SKIP_THIS |
Anna Bridge |
160:5571c4ff569f | 2944 | |
Anna Bridge |
160:5571c4ff569f | 2945 | /****************************************************************************** |
Anna Bridge |
160:5571c4ff569f | 2946 | * Assertion Callback |
Anna Bridge |
160:5571c4ff569f | 2947 | *****************************************************************************/ |
Anna Bridge |
142:4eea097334d6 | 2948 | /** |
Anna Bridge |
160:5571c4ff569f | 2949 | * @addtogroup Assertions |
Anna Bridge |
160:5571c4ff569f | 2950 | * @brief Callbacks called by assertions |
Anna Bridge |
142:4eea097334d6 | 2951 | * |
Anna Bridge |
160:5571c4ff569f | 2952 | * This assertion framework was implemented for the purpose of not only being |
Anna Bridge |
160:5571c4ff569f | 2953 | * able to assert that certain conditions be true in a block of code, but also |
Anna Bridge |
160:5571c4ff569f | 2954 | * to be able to handle them more appropriately. In previous implementations, |
Anna Bridge |
160:5571c4ff569f | 2955 | * the behavior upon a failed assert would be to hang in a while(1) loop. |
Anna Bridge |
160:5571c4ff569f | 2956 | * However, with the callback, each assert is given a unique error code so that |
Anna Bridge |
160:5571c4ff569f | 2957 | * they can be handled on a more case-by-case basis. For documentation on each |
Anna Bridge |
160:5571c4ff569f | 2958 | * of the errors, please see the rail_assert_error_codes.h file. |
Anna Bridge |
160:5571c4ff569f | 2959 | * RAIL_ASSERT_ERROR_MESSAGES[errorCode] gives the explanation of the error. |
Anna Bridge |
160:5571c4ff569f | 2960 | * With asserts built into the library, customers can choose how to handle each |
Anna Bridge |
160:5571c4ff569f | 2961 | * error inside the callback. |
Anna Bridge |
142:4eea097334d6 | 2962 | * |
Anna Bridge |
160:5571c4ff569f | 2963 | * @{ |
Anna Bridge |
142:4eea097334d6 | 2964 | */ |
Anna Bridge |
142:4eea097334d6 | 2965 | |
Anna Bridge |
142:4eea097334d6 | 2966 | /** |
Anna Bridge |
160:5571c4ff569f | 2967 | * Callback called upon failed assertion. |
Anna Bridge |
160:5571c4ff569f | 2968 | * |
Anna Bridge |
160:5571c4ff569f | 2969 | * @param[in] railHandle A RAIL instance handle. |
Anna Bridge |
160:5571c4ff569f | 2970 | * @param[in] errorCode Value passed in by the calling assertion API indicating |
Anna Bridge |
160:5571c4ff569f | 2971 | * the RAIL error that is indicated by the failing assertion. |
Anna Bridge |
160:5571c4ff569f | 2972 | * @return void. |
Anna Bridge |
142:4eea097334d6 | 2973 | */ |
AnnaBridge | 167:84c0a372a020 | 2974 | void RAILCb_AssertFailed(RAIL_Handle_t railHandle, |
AnnaBridge | 167:84c0a372a020 | 2975 | RAIL_AssertErrorCodes_t errorCode); |
Anna Bridge |
160:5571c4ff569f | 2976 | |
Anna Bridge |
160:5571c4ff569f | 2977 | /** @} */ // end of group Assertions |
Anna Bridge |
160:5571c4ff569f | 2978 | |
Anna Bridge |
160:5571c4ff569f | 2979 | /** @} */ // end of group RAIL_API |
Anna Bridge |
142:4eea097334d6 | 2980 | |
AnnaBridge | 167:84c0a372a020 | 2981 | #ifdef __cplusplus |
AnnaBridge | 167:84c0a372a020 | 2982 | } |
AnnaBridge | 167:84c0a372a020 | 2983 | #endif |
AnnaBridge | 167:84c0a372a020 | 2984 | |
Anna Bridge |
142:4eea097334d6 | 2985 | #endif // __RAIL_H__ |