RAIL Library

The Silicon Labs Radio Abstraction Interface Layer (RAIL) is a library that can be used as a generic interface for all Silicon Labs radio parts. By programming against this API you are able to write code that easily ports across different radio parts while having access to hardware acceleration wherever possible.


The RAIL library is as standalone as it can be with few external dependencies. To build applications using it we recommend using Simplicity Studio's application builder since it will simplify the process but that is not required. Depending on the hardware platform that you're using you may be required to provide certain HAL functionality for the library to work properly. These functions should be covered in the section of the guide for your hardware platform and valid implementations of them can be found as a part of the emlib/emdrv HAL layers that we provide. It is recommended that you use these versions for maximum support, but you're free to re-implement them if necessary.

Using RAIL


At a high level the functionality supported by RAIL is shown below. For more specifics on the APIs and how to use them see the module documentation.

  • General
    • Initialize the RAIL API layer.
    • Collect entropy from the radio (if available).
  • Radio Configuration
    • Configure the radio frequency, packet format, channel configuration and other PHY parameters.
    • Query current PHY data rates and parameters like current channel.
  • State Transitions
    • Configure automatic radio state transitions and transition timings.
  • Auto ACK
    • Configure the radio for automatic acknowledgments.
    • Load the auto ack payload.
  • System Timing
    • Get the current time in the RAIL timebase.
    • Configure a timer to trigger an event callback after an absolute or relative delay.
    • Specify where within a packet its timestamp is desired.
  • Events
    • Configure which radio or RAIL events the application wants to be told about via callback.
  • Data Management
    • Allows the application to choose the type of data and the method of data interaction through RAIL.
  • Receive
    • Configure receive options like CRC checking.
    • Start or schedule when to receive.
    • Enable and configure Address Filtering for each packet.
  • Transmit
    • Configure the power amplifier (PA) and set transmit power output.
    • Load and send packet data, either immediately, scheduled, or using CSMA or LBT.
    • Control per-transmit options like CRC generation, ACK waiting, etc.
  • Multiprotocol
    • Manage time-sharing of the radio among different protocols.
  • Calibration
    • APIs for handling various radio calibrations for optimal performance.
  • RF Sense
    • Enable RF energy sensing of specified duration across the 2.4 GHz and/or Sub-GHz bands (EFR32 only).
  • Packet Trace (PTI)
    • Configure Packet Trace pins and serial protocol.
    • Specify the stack protocol to aid network analyzer packet decoding.
  • Diagnostic
    • Output debug signals like an unmodulated tone and a continuously modulated stream of data.
    • Configure crystal tuning for your radio.
    • Fine-tune the radio tuner frequency.

Protocol specific hardware acceleration:

  • IEEE 802.15.4
    • Configure the IEEE802.15.4 2.4GHz PHY.
    • Configure node address and address filtering for IEEE 802.15.4.
    • Configure auto ack for IEEE 802.15.4.
  • BLE
    • Configure the Bluetooth Low Energy 1Mbit PHY.
    • Preamble, sync word and whitening adjustment function for connections.

Getting Started Example

Below is a simple example to show you how to initialize the RAIL library in your application. Notice that this requires the channel configurations which can be generated from the radio calculator in Simplicity Studio. By default RAIL interacts with data on a per-packet basis; for more information refer to Data Management.

Note: Before the radio can transmit, make sure the PA is initialized for your platform. This is covered in the Hardware Specific Configuration section below.

#include "rail.h"
#include "rail_config.h" // Generated by radio calculator
#define TX_FIFO_SIZE (128) // Any power of 2 from [64, 4096] on the EFR32
static RAIL_Handle_t gRailHandle = NULL;
static RAIL_TxPower_t txPower = 200; // Default to 20 dBm
static uint8_t txFifo[TX_FIFO_SIZE];
static const RAIL_TxPowerConfig_t railTxPowerConfig = { // May be const
// ... desired PA settings
static void radioConfigChangedHandler(RAIL_Handle_t railHandle,
bool isSubgig = (entry->baseFrequency < 1000000000UL);
// ... handle radio configuration change, e.g. select the desired PA possibly
// using isSubgig to handle multiple configurations
RAIL_ConfigTxPower(railHandle, &railTxPowerConfig);
// We must reapply the Tx power after changing the PA above
RAIL_SetTxPowerDbm(railHandle, txPower);
static void radioEventHandler(RAIL_Handle_t railHandle,
RAIL_Events_t events)
// ... handle RAIL events, e.g. receive and transmit completion
static RAIL_Config_t railCfg = { // Must never be const
.eventsCallback = &radioEventHandler,
.protocol = NULL, // For BLE, pointer to a RAIL_BLE_State_t
.scheduler = NULL, // For MultiProtocol, pointer to a RAIL_SchedConfig_t
// Initialize the radio out of startup so that it's ready to receive
void radioInitialize(void)
// Initialize the RAIL library and any internal state it requires
gRailHandle = RAIL_Init(&railCfg, NULL);
// Configure calibration settings
// Configure radio according to the generated radio settings
RAIL_ConfigChannels(gRailHandle, channelConfigs[0], &radioConfigChangedHandler);
// Configure the most useful callbacks plus catch a few errors
// Set automatic transitions to always receive once started
RAIL_StateTransitions_t railStateTransitions = {
.error = RAIL_RF_STATE_RX,
RAIL_SetRxTransitions(gRailHandle, &railStateTransitions);
RAIL_SetTxTransitions(gRailHandle, &railStateTransitions);
// Setup the transmit buffer
RAIL_SetTxFifo(gRailHandle, txFifo, 0, TX_FIFO_SIZE);

Hardware Specific Configuration

For information about configuration and setup that is specific to your hardware platform be sure to take a look at the pages below.