General
RAIL API

Basic APIs to set up and interact with the RAIL library.

Data Structures

struct  RAIL_Version_t
 Contains RAIL Library Version Information.

Macros

#define RAIL_DMA_INVALID   (0xFFU)
 A value to signal that RAIL should not use DMA.

Typedefs

typedef void * RAIL_Handle_t
 A handle of a RAIL instance, as returned from RAIL_Init().
 
typedef void(* RAIL_InitCompleteCallbackPtr_t) (RAIL_Handle_t railHandle)
 A pointer to init complete callback function.

Enumerations

enum  RAIL_Status_t {
  RAIL_STATUS_NO_ERROR,
  RAIL_STATUS_INVALID_PARAMETER,
  RAIL_STATUS_INVALID_STATE,
  RAIL_STATUS_INVALID_CALL,
  RAIL_STATUS_SUSPENDED
}
 A status returned by many RAIL API calls indicating their success or failure.

Functions

void RAIL_GetVersion (RAIL_Version_t *version, bool verbose)
 Get the version information for the compiled RAIL library.
 
RAIL_Status_t RAIL_UseDma (uint8_t channel)
 Allocate a DMA channel for RAIL to work with.
 
RAIL_Handle_t RAIL_Init (RAIL_Config_t *railCfg, RAIL_InitCompleteCallbackPtr_t cb)
 Initialize RAIL.
 
bool RAIL_IsInitialized (void)
 Get RAIL initialization status.
 
RAIL_Status_t RAIL_DelayUs (RAIL_Time_t microseconds)
 Blocking delay routine for a specified number of microseconds.
 
uint16_t RAIL_GetRadioEntropy (RAIL_Handle_t railHandle, uint8_t *buffer, uint16_t bytes)
 Collects entropy from the radio if available.

Detailed Description

Basic APIs to set up and interact with the RAIL library.

Macro Definition Documentation

◆ RAIL_DMA_INVALID

#define RAIL_DMA_INVALID   (0xFFU)

A value to signal that RAIL should not use DMA.

Definition at line 135 of file rail_types.h.

Typedef Documentation

◆ RAIL_InitCompleteCallbackPtr_t

typedef void(* RAIL_InitCompleteCallbackPtr_t) (RAIL_Handle_t railHandle)

A pointer to init complete callback function.

Parameters
[in]railHandleA handle for RAIL instance.
Returns
void.

Definition at line 132 of file rail_types.h.

Enumeration Type Documentation

◆ RAIL_Status_t

enum RAIL_Status_t

A status returned by many RAIL API calls indicating their success or failure.

Enumerator
RAIL_STATUS_NO_ERROR 

RAIL function reports no error.

RAIL_STATUS_INVALID_PARAMETER 

Call to RAIL function threw an error because of an invalid parameter.

RAIL_STATUS_INVALID_STATE 

Call to RAIL function threw an error because it was called during an invalid radio state.

RAIL_STATUS_INVALID_CALL 

RAIL function is called in an invalid order.

RAIL_STATUS_SUSPENDED 

RAIL function did not finish in the allotted time.

Definition at line 104 of file rail_types.h.

Function Documentation

◆ RAIL_DelayUs()

RAIL_Status_t RAIL_DelayUs ( RAIL_Time_t  microseconds)

Blocking delay routine for a specified number of microseconds.

Parameters
[in]microsecondsDelay duration in microseconds.
Returns
Status code indicating success of the function call.

This RAIL API should only be used for short blocking delays because it has less overhead than calling RAIL_GetTime() in a loop.

Note
Passing large delay values may give unpredictable results or trigger the Watchdog Reset.
Also, this function will start the clocks required for the RAIL timebase if they are not running, except between RAIL_Sleep() and RAIL_Wake() where the timer must remain stopped.
Interrupts are not disabled during the delay, so the delay may be longer if an interrupt extends beyond the delay duration.

◆ RAIL_GetRadioEntropy()

uint16_t RAIL_GetRadioEntropy ( RAIL_Handle_t  railHandle,
uint8_t *  buffer,
uint16_t  bytes 
)

Collects entropy from the radio if available.

Parameters
[in]railHandleA RAIL instance handle.
[out]bufferThe buffer to write the collected entropy.
[in]bytesThe number of bytes to fill in the input buffer.
Returns
Returns the number of bytes of entropy collected. For chips that don't support entropy collection, the function returns 0. Values less than the requested amount may also be returned on platforms that use entropy pools to collect random data periodically.

Attempts to fill the provided buffer with the requested number of bytes of entropy. If the requested number of bytes can't be provided, as many bytes as possible will be filled and returned. For chips that do not support this function, 0 bytes are always returned. For information about the specific mechanism for gathering entropy, see documentation for the chip family.

◆ RAIL_GetVersion()

void RAIL_GetVersion ( RAIL_Version_t *  version,
bool  verbose 
)

Get the version information for the compiled RAIL library.

Parameters
[out]versionA pointer to RAIL_Version_t structure to populate with version information.
[in]verbosePopulate RAIL_Version_t struct with verbose information.
Returns
void.

The version information contains a major version number, a minor version number, and a rev (revision) number.

◆ RAIL_Init()

RAIL_Handle_t RAIL_Init ( RAIL_Config_t *  railCfg,
RAIL_InitCompleteCallbackPtr_t  cb 
)

Initialize RAIL.

Parameters
[in,out]railCfgThe configuration and state structure for setting up the library, which contains memory and other options needed by RAIL. This structure must be allocated in application global read-write memory. RAIL may modify fields within or referenced by this structure during its operation.
[in]cbA callback that notifies the application when the radio is finished initializing and is ready for further configuration. This callback is useful for potential transceiver products that require a power up sequence before further configuration is available. After the callback fires, the radio is ready for additional configuration before transmit and receive operations.
Returns
Handle for initialized rail instance or NULL if an invalid value was passed in the railCfg.
Note
This function should be called only once per protocol. If called again, it will do nothing and return NULL.

◆ RAIL_IsInitialized()

bool RAIL_IsInitialized ( void  )

Get RAIL initialization status.

Returns
True if the radio has finished initializing and false otherwise.

RAIL APIs, e.g., RAIL_GetTime(), which work only if RAIL_Init() has been called, can use RAIL_IsInitialized() to determine whether RAIL has been initialized or not.

◆ RAIL_UseDma()

RAIL_Status_t RAIL_UseDma ( uint8_t  channel)

Allocate a DMA channel for RAIL to work with.

Parameters
[in]channelThe DMA channel to use when copying memory. If a value of RAIL_DMA_INVALID is passed, RAIL will stop using any DMA channel.
Returns
Status code indicating success of the function call.

To use this API, the application must initialize the DMA engine on the chip and allocate a DMA channel. This channel will be used periodically to copy memory more efficiently. This API should be called before RAIL_Init to have the most benefit. If the application needs to take back control of the DMA channel that RAIL is using, this API may be called with a channel of RAIL_DMA_INVALID to tell RAIL to stop using DMA.