RAIL Library

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.

Introduction

The RAIL library is mostly standalone with a few external dependencies. Simplicity Studio application builder is not required but is recommended because it simplifies building applications using RAIL. 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 are described in hardware-specific documentation sections and valid implementations can be found as a part of the provided emlib/emdrv HAL layers. It is recommended that you use these versions for maximum support, but you're free to re-implement them if necessary.

Using RAIL

Features

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.
    • Enable and configure RX Channel Hopping for receiving packets across several channels.
  • Transmit
    • Configure the power amplifier ( 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.
  • Antenna Control
    • Configuring multi-antenna selection.
  • 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.
  • Assertions
    • Detecting and handling fatal runtime errors detected by RAIL.
  • 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 PHYs available for your device (1Mbps, 2Mbps, Coded PHY).
    • Preamble, sync word and whitening adjustment function for connections.
  • Z-Wave
    • Configure the Z-Wave PHY appropriate for your region.
    • Configure your NodeId and HomeId for receive filtering and wakeup beam filtering.

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, see Data Management .

Note: Before the radio can transmit, make sure the PA is initialized for your platform, which is described 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,
const RAIL_ChannelConfigEntry_t *entry)
{
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);
// The TX power must be reapplied 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
}
#if MULTIPROTOCOL
static RAILSched_Config_t schedCfg; // Must never be const
static RAIL_Config_t railCfg = { // Must never be const
. eventsCallback = &radioEventHandler,
.protocol = NULL, // For BLE, pointer to a RAIL_BLE_State_t
.scheduler = &schedCfg, // For MultiProtocol, additional scheduler memory
};
#else
static RAIL_Config_t railCfg = { // Must never be const
. eventsCallback = &radioEventHandler,
.protocol = NULL,
.scheduler = NULL,
};
#endif
// Initializes the radio out of startup so that it's ready to receive.
void radioInitialize( void )
{
// Initializes the RAIL library and any internal state it requires.
gRailHandle = RAIL_Init (&railCfg, NULL);
// Configures calibration settings.
RAIL_ConfigCal (gRailHandle, RAIL_CAL_ALL );
// Configures radio according to the generated radio settings.
RAIL_ConfigChannels (gRailHandle, channelConfigs[0], &radioConfigChangedHandler);
// Configures the most useful callbacks and catches a few errors.
RAIL_ConfigEvents (gRailHandle,
RAIL_EVENTS_ALL ,
RAIL_EVENT_TX_PACKET_SENT
| RAIL_EVENT_RX_PACKET_RECEIVED
| RAIL_EVENT_RX_FRAME_ERROR // invalid CRC
| RAIL_EVENT_RX_ADDRESS_FILTERED );
// Sets automatic transitions to always receive once started.
RAIL_StateTransitions_t railStateTransitions = {
. success = RAIL_RF_STATE_RX ,
.error = RAIL_RF_STATE_RX ,
};
RAIL_SetRxTransitions (gRailHandle, &railStateTransitions);
RAIL_SetTxTransitions (gRailHandle, &railStateTransitions);
// Sets up the transmit buffer.
RAIL_SetTxFifo (gRailHandle, txFifo, 0, TX_FIFO_SIZE);
}

Hardware-specific Configuration

For hardware-specific configuration and setup information, see subsequent sections.

EFR32