mbed official / mbed

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

Dependents:   hello SerialTestv11 SerialTestv12 Sierpinski ... more

mbed 2

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

TARGET_TB_SENSE_1/TOOLCHAIN_IAR/rail.h@171:3a7713b1edbc, 2018-11-08 (annotated)

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

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Anna Bridge 160:5571c4ff569f 1 /**************************************************************************//**
Anna Bridge 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__