This tutorial builds upon the material covered in previous offerings:

• RAIL Tutorial 1: Introduction and init
• RAIL Tutorial 2: Transmitting a Packet
• RAIL Tutorial 3: Event Handling
• RAIL Tutorial 4: Combining Transmit and Receive
• (*) Introduction to Multi-PHY and Multiprotocol

(*) Make sure to read this one, as DMP is often misunderstood and used in applications that could be better served by multi-PHY. We recommend that you (at least) browse through the other tutorials before reading this (DMP) tutorial, since DMP affects most APIs in one way or another.

You can find additional RAIL tutorials on the table of contents page.

Note that this tutorial will not provide you with all of the knowledge required for DMP development. Rather, it will summarize what's already documented, and highlight differences between RAIL single protocol and multiprotocol operations.

Some chapters below are not important if you need RAIL-Bluetooth DMP, but even in that case most chapters are still relevant because they describe RAIL development in a DMP environment.

What is Dynamic Multiprotocol

Dynamic multiprotocol time-slices the radio and rapidly changes configurations to enable different wireless protocols to simultaneously operate reliably in the same application.

A typical usecase involves a RAIL-based proprietary protocol and the Silicon Labs Bluetooth stack running on the same chip at the same time. Since Bluetooth communication is periodic and therefore very predictable, other protocols can use the radio between Bluetooth communication bursts. However, it's also helpful to use DMP when all involved protocols are proprietary RAIL-based, to benefit from the code clarity provided by the separate RAIL instances.

From a firmware perspective, RAIL-DMP is similar to an object-oriented programming (OOP) class. It provides the radio driver, and multiple instances can be "created". Each instance can use the driver in the same way, and do so almost independently.

However, from a hardware perspective the chip has only a single instance of the radio. As such, RAIL-DMP is similar to multitasking: the same resource must be shared among multiple "tasks" demanding its time - this sharing is managed by the radio scheduler.

The Radio Scheduler

The radio scheduler's job is to give (or revoke) radio hardware access to (or from) the protocols running on it. To accomplish this it implements cooperative, preemptive multitasking.

• It's cooperative: Protocols should tell the scheduler when and for how long they need the radio, and protocols should yield the radio when not using it anymore
• It's preemptive: Protocols should define priority to each radio task, and the scheduler will abort tasks if a higher priority radio task must run

Note that the radio scheduler schedules only radio tasks. Although DMP is often used with an RTOS (like Micrium OS), RTOS tasks and Radio tasks - despite the common name - are very different terms. To make this less confusing, our documentation sometimes uses radio operation instead of radio task.

For the radio scheduler to calculate the time required for a given radio operation, it must know how much time it takes to change radio access from one protocol to another. Therefore, in DMP, a protocol change always takes 450us on EFR32xG1x, which accommodates the worst-case protocol change time. This makes DMP protocol change much slower than Multi-PHY PHY change.

Protocol change time in RAIL 2.5.x (Flex 2.4.x) and earlier was 750us (and it might change further in the future).

Setting up a project for RAIL-RAIL DMP

If you need RAIL+Bluetooth DMP, follow AN1134. This chapter describes how to set up DMP in a RAIL-only project.

To use DMP, you should first switch to the multiprotocol RAIL library, under plugins. Since DMP has a bigger memory footprint (both RAM and code), it's provided in a library which is not enabled in single protocol examples.

Next, you'll need PHY configurations for your protocols. You can either use Protocol Based Multi-PHY (see the Multi-PHY usecases and examples tutorial for details), or you can use embedded protocols, e.g. IEEE 802.15.4 2.4GHz 250kbps by calling RAIL_IEEE802154_Config2p4GHzRadio().

Micrium OS

Micrium OS is not technically required for RAIL DMP, although it's highly recommended to clearly separate protocols (and for RAIL+Bluetooth DMP, we actually only support Micrium-enabled projects.) Hence, Micrium OS will not be discussed in this article - it doesn't impact how you use RAIL APIs in RAIL-only DMP.

RAIL initialization

Let's see how one RAIL protocol should be initialized in DMP:

static void RAILCb_Generic(RAIL_Handle_t railHandle, RAIL_Events_t events);
static RAIL_Handle_t railHandle;
static RAILSched_Config_t railSchedState;
static RAIL_Config_t railCfg = {
  .eventsCallback = &RAILCb_Generic,
  .scheduler = &railSchedState,
  .protocol = NULL,
};

void initRadio1()
{
  railHandle = RAIL_Init(&railCfg, NULL);
}

static void RAILCb_Generic(RAIL_Handle_t railHandle, RAIL_Events_t events)
{
}

Let's compare it to the very first RAIL tutorial:

• railSchedState is a new static variable required for RAIL. This keeps the state of the protocol when it's not active (e.g. configured Rx options)
• railCfg.protocol is set to NULL. This is also a DMP specific field, but it's only used by the Silicon Labs Bluetooth stack.
• RAILCb_Generic is now static: Since all protocols will have their own callback functions, we should either make the function names unique, or put them in different C files as static. Although technically it's possible to use a common callback function for all protocols, it's not recommended as the readability of the code is much better with separate event handlers.
• halInit() is no longer called from initRadio1() - since we have multiple protocols to support, it makes more sense to set up RAIL requirements elsewhere in a protocol-independent init function

This code snippet initializes a single protocol. However, all remaining protocols can be initialized in the same way, noting that railHandle, railSchedState and RAILCb_Generic should be different for all protocols (probably by placing in separate C files).

From this point you can use RAIL almost the same way as in single protocol mode. Since almost all APIs have a railHandle argument, RAIL will know which protocol you want to access. However, you should be careful with:

• protocol independent APIs, i.e. the ones that don't have a railHandle argument
• APIs that affect the state of the radio scheduler, i.e. schedule or stop a radio task

Protocol independent APIs

There are a few APIs that always work the same way, regardless of which protocol they were called from:

• RAIL_SetTime()/RAIL_GetTime() - the timebase (which is also used for timestamping) is common for all protocols. It is not recommended to call RAIL_SetTime() in a DMP application (and calling it in a single protocol application can still be dangerous)
• RAIL_ConfigMultiTimer() - MultiTimer mode is a requirement in DMP, so it's enabled by default and cannot be disabled
• RAIL_Sleep()/RAIL_Wake() - Sleep management should be handled protocol-independently (e.g. in the idle task of the RTOS)

There are some other APIs that don't require railHandle, but they usually need a packet handler or timer handler, and so are still tied to a protocol.

Scheduling a finite radio task

The following APIs will trigger the radio scheduler to schedule a finite length new radio task:

• RAIL_ScheduleRx()
• RAIL_StartTx()
• RAIL_StartScheduledTx()
• RAIL_StartCcaCsmaTx()
• RAIL_StartCcaLbtTx()
• RAIL_StartAverageRssi()

(Note that RAIL_StartRx() and RAIL_StartTxStream() is not listed, as these as these are not finite length tasks.)

All the above APIs have the optional argument RAIL_SchedulerInfo_t. In single protocol mode, this argument is ignored, and can be NULL. In multiprotocol mode, this is the base of the scheduling, with its 3 member:

• priority - 0 to 255, 0 being the highest. Equal priority does not preempt
• slipTime - maximum time the task can be delayed due to other protocols, in us
• transactionTime - the time the task takes, in us

When the radio hardware is available, none of these scheduler info arguments are used. However, if two tasks are scheduled at the same time, the radio scheduler will try to stagger the operations using slipTime in order to satisfy both tasks. If that fails, the lower priority task will not get access to the radio.

It is also possible that an application schedules a high priority radio task when a conflicting lower priority task has already started. In that case, the lower priority task will be aborted (possibly in the middle of frame transmission).

If RAIL_SchedulerInfo_t is NULL, the scheduler will assume all parameters to be 0, i.e. highest priority, with no slipTime - it is highly recommended to not use this feature, and it's only mentioned here to simplify debugging.

Each protocol can schedule at most a single finite task.

For more details on the radio scheduler, see UG305 chapter 3 and the Multiprotocol description in the RAIL API doc.

Yielding

After each radio task the application must yield the radio. That can be achieved by calling RAIL_YieldRadio() or RAIL_Idle() - the latter also turns off the radio, which should have already occurred for finite tasks, so it's recommended to use RAIL_YieldRadio(). Manual yielding is required because the scheduler doesn't know about any automatic follow-up tasks (like ACKs) - you might want to yield immediately after receiving a packet, or you may instead want to wait for the auto ACK to go out.

Since yielding the radio will also call the radio scheduler to start/schedule the next radio task, you must first capture everything you need that might be overwritten by another protocol after yield, even in interrupt context. For example, timestamps of a transmitted packet must be accessed before yielding.

A Tx operation scheduled in the future can be cancelled using RAIL_Idle() or RAIL_StopTx(), where the latter doesn't yield the radio. An Rx operation scheduled in the future can only be cancelled using RAIL_Idle().

Background Rx

RAIL_StartRx() receives special handling in the radio scheduler, as it schedules an infinite task - namely, background Rx. The main difference when compared to finite tasks is that an infinite task sets the "default" state of the radio. It can be aborted by higher priority finite tasks, but it will be resumed automatically after the higher priority task is finished. For background Rx, this practically means that the radio will automatically return to Rx after Tx or packet reception, and you don't have to use auto state transitions like you do in single protocol mode. (Currently, the only infinite task supported by RAIL is background Rx).

Keep in mind that RAIL does not store the channel of background Rx: if you interrupt background Rx with a finite task on a different channel, the channel of the background Rx will change as well. E.g. if you're receiving in channel 0, then transmit on channel 1, the radio will "return" to receiving on channel 1. To change the background Rx channel back to 0, simply call RAIL_StartRx() again after you yield the radio.

RAIL_StartRx() has the same RAIL_SchedulerInfo_t configuration as the finite tasks, but depends only on the priority member - which, in general, should be the lowest priority used by the protocol.

Background Rx can be aborted using RAIL_Idle(), which also yields the radio. In DMP mode, it's recommended to only use RAIL_Idle() to stop background Rx.

It is also possible to change the priority of the background RX using RAIL_SetTaskPriority() - this is useful e.g. to increase the priority during packet reception, or after a particular packet.

TxStream

RAIL_StartTxStream() is called a debug task: A debug task must have the highest priority, because it can't be aborted. Otherwise, it works similarly to infinite tasks.

This API is different from all others as it doesn't use RAIL_SchedulerInfo_t. Since a stream can't really be aborted, the radio scheduler will handle this with the highest priority and no slip time.

Stream can be stopped with RAIL_StopTxStream(), RAIL_Idle() or RAIL_YieldRadio(), although it is recommended to use RAIL_StopTxStream() for clarity.

Auto state transitions

You might wonder, "what's the point of auto state transitions in DMP, if background Rx changes the default state to Rx?" The added value of auto state transitions is that the resulting state will inherit the original state's priority.

For example, you probably want the ACK reception on the same priority as the transmission itself, so you can set RAIL_SetTxTransition() to set up receive after the transmission for the ACK, and configure a timeout for it using RAIL_SetStateTiming().

If you have automatic state transition set up, you should only yield the radio after the whole operation (e.g. ACK reception or timeout) is finished. It's highly recommended to have automatic timeouts to prevent a high priority infinite task, but if you haven't set up timeouts, you can cancel the receive and yield the radio using RAIL_Idle().

To summarize:

• In RAIL single protocol, the default state is always idle, and auto state transitions should be used to always return the radio to Rx. In DMP, background Rx should be used for this.
• In single protocol mode, Rx state started by auto state transition is the same as Rx state started by StartRx. In DMP, auto state transitions are intended for ACK, as they inherit the (usually high) priority of the preceding task.

For more details, see UG305 chapter 6

MultiTimers

RAIL includes a timer virtualization service, called MultiTimer. Since its memory footprint is not negligible, this feature is disabled by default in single protocol mode. However, in multiprotocol mode, it is always enabled, since multiple timers are required for the multiple protocols. Therefore, using MultiTimers in your protocol implementations has no drawback in DMP.

Error handling

In single protocol RAIL, you generally need to places to handle errors:

• RAIL_StartXYZ()/RAIL_ScheduleXYZ() might return an error. If no error were returned, the operation was either finished, or an event will be triggered
• The event handler, where either a success or error event can be triggered, e.g. RAIL_EVENT_TX_PACKET_SENT or RAIL_EVENT_TX_CHANNEL_BUSY

In DMP, there's a third error case to handle above the previous two: You should always handle RAIL_EVENT_SCHEDULER_STATUS, where you might receive an error by calling RAIL_GetSchedulerStatus(). It's usually obvious which API call failed, e.g. RAIL_SCHEDULER_STATUS_SINGLE_TX_FAIL means a RAIL_StartTx() failed, but it might not be possible to know the original call resulted in error.

This was implemented because when you call e.g. RAIL_StartTx, the radio scheduler just creates task. When that task is running, it will actually call the single protocol RAIL_StartTx, and if that returns an error, it will trigger an RAIL_EVENT_SCHEDULER_STATUS event.

Debugging

When debugging DMP, Rx/Tx PRS channels are still very useful, see the tutorial about debugging for details.

For DMP based code, writing out to a GPIO when a protocol is scheduled/unscheduled is really useful. This can be easily done by setting a GPIO on RAIL_EVENT_CONFIG_SCHEDULED and clearing it on RAIL_EVENT_CONFIG_UNSCHEDULED.

Recommendations and practices

Although these practices are very important for DMP applications, you should consider applying them in single protocol applications as well, to simplify a potential future port to DMP:

• Only use RAIL_Idle() when it's necessary - In RAIL 1.x almost all APIs required that they be called from idle mode. This requirement was removed in RAIL 2.x, so it's very rarely needed, and since RAIL_Idle() also yields the radio, it should be very rarely used in DMP.
• Use the scheduling Rx/Tx features as much as possible - i.e. don't use timers and start Rx/Tx at timer interrupt, use the corresponding RAIL schedule API instead. This helps the radio scheduler to resolve conflicts with the configured slipTimes, or at least promptly let the application know about an unavoidable conflict.
• Set the slipTime/transactionTime correctly. Again, this helps the radio scheduler to resolve conflicts.

How not to use DMP

Using multiple DMP instances for multiple radio tasks (e.g. one protocol for advertising, one for connection, or one for Tx, one for Rx) is bad design: while it works, each protocol instance has a significant memory footprint, and switching time between protocols is much slower than switching Rx/Tx inside a protocol. At the moment, it is recommended to use DMP only for serving separate protocol stacks.

Using DMP to handle multiple PHYs for the same protocol stack is also not recommended: Multi-PHY is a much better solution for that, see the introduction to Multi-PHY and Multiprotocol tutorial for more details.

Related documentation

• UG305: Dynamic Multiprotocol User's Guide - You can skip the chapters that won't affect your design, e.g. if you don't plan to use zigbee, you can skip the zigbee chapters. This article somewhat overlaps with UG305 as we provide a short summary of the basics here.
• AN1134: Dynamic Multiprotocol Development with Bluetooth and Proprietary Protocols on RAIL - Read it if you plan to use Bluetooth - RAIL DMP, as it presents how to create Bluetooth - RAIL examples.
• The Multiprotocol description in the API doc - It is the concentrated (compared to UG305) description of the Radio Scheduler, and also overlaps with this article.

If you find any conflicts between this article and the above documents, give those documents priority as they will more quickly receive updates to track new RAIL DMP features and guidance.

Introduction

The goal of this tutorial series is to help you get started with RAIL, the C API for embedded software for Silicon Labs' EFR32 Wireless Geckos.

To read it, you should have some experience with embedded C - you should know how to handle interrupts, what volatile means, etc.

While we try to avoid using it, you might need some experience with radios as well. It definitely helps if you know what preamble or sync word is.

The tutorials should be read together with the RAIL API documentation.

If you find any contradiction between the tutorials and the API documentation, just always remember that the API documentation is more accurate.

This tutorial series focuses on the embedded code running on Wireless Geckos. Configuring the radio correctly is equally important, see AN971 for details on that.

Getting Started

You should start with these tutorials. All others are based on these, as these are the minimum to develop useful applications on RAIL.

1. Introduction and init
2. Transmitting a Packet
3. Event Handling
4. Combining Transmit and Receive

Basic Tutorials

These tutorials are common and basic features, you should read them before you start working on a project which uses RAIL.

• Time, Timestamping and Scheduling
• Calibrations
• Debugging

Advanced Tutorials

These tutorials describe features that are rarely needed - they are available and can be used when necessary, but you probably won't use them all in your application. Generally, you should read them only if you think you need them.

• Special Data Modes (FIFO, Direct, IQ)
• Understanding RAIL Config Files
• Tx/Rx Options
• Timer synchronization and sleep

Multi-PHY and Multi protocol Tutorials

These tutorials are about the Multi-PHY and multiprotocol capabilites of RAIL. If you plan to use that feature, we recommend to read the introduction then what you need, depending on your application.

• Introduction to Multi-PHY and Multiprotocol
• Multi-PHY usecases and examples
• Dynamic Multiprotocol (DMP)

This tutorial builds on the following tutorials:

• RAIL Tutorial 1: Introduction and init
• RAIL Tutorial 2: Transmitting a Packet
• RAIL Tutorial 3: Event Handling
• RAIL Tutorial 4: Combining Transmit and Receive

To get the most out of this tutorial, some familiarity with the radio configurator is required, and it's also recommended that you understand the basics of radio protocol stacks (i.e. the OSI model).

You can find these prerequisite tutorials on the table of contents site.

Introduction

With a customizable radio, the Wireless Gecko is a great option to support any radio configuration you need. You can set it up for standard IEEE 802.15.4, Bluetooth Low Energy, WMBus, or even the protocol (designed 30 years ago) used by your garage door opener. However, what if you need more than one of those standards? With single protocol radios, this requires a distinct 15.4 radio chip, a Bluetooth chip, and so on for each supported standard. Alternatively, with a single Wireless Gecko, you can store multiple "setups" in your device and switch between them. The only limitation is that it's still a single radio - you can't use multiple "setups" on the radio at the same time.

The best way to manage the sharing of this single radio resource depends on the particular usecase targeted by your application. We provide different solutions (discussed below) to help you identify an optimal approach for your design.

Channel-based Multi-PHY

The most common usecase in proprietary wireless is the need to support different PHY configurations. For example:

• You always handle received packets the same way, but you have to receive at multiple bitrates
• You have an asymmetric protocol, i.e. the Rx configuration is not the same as the Tx configuration
• You need wider bandwidth for CSMA/CA than your normal Rx mode to pass regulatory standards
• You have to handle different packet formats, but not at the same time: the upper layers of the stack decide which one to use
• Although the PHYs are technically the same, there is a power limitation on a given channel to pass regulatory standards
• The PHYs are technically the same, but the channel map is uneven - it's not possible to configure it using channel spacing

In these cases, Channel-based Multi-PHY is the best solution. It's called Channel-based, because in RAIL, you only need to change the channel to change the PHY.

You can find a setup guide for some of these usecases in the Multi-PHY usecases and examples tutorial.

Protocol-based Multi-PHY

This is not as widely used as Channel-based Multi-PHY, but it's the next logical step. The typical usecases:

• Your device will support multiple regions, and you choose one during configuration, but the device will rarely switch between those.
• Your device will support multiple protocols, but the device will rarely switch between those.

For this, we recommend Protocol-based Multi-PHY. In this case, you can switch between protocols by calling RAIL_ConfigChannels(), which will load the whole configuration.

Protocol based Multi-PHY is also useful if you want to test multiple configuration setups using RAILTest: You can change between protocols using the setConfigIndex RAILTest command.

You can find a setup guide for some of these usecases in the Multi-PHY usecases and examples tutorial.

Channel-based vs Protocol-based Multi-PHY

In general, you should consider your application requirements: If you want to have (for example) 20 channels, but those 20 channels are defined differently in some application configurations (typically by region), you should use Protocol-based Multi-PHY. A protocol change will be slower than a channel change, but the application doesn't even need to know which protocol is in use, since it still sees the same 20 channels through RAIL.

Otherwise, in almost all cases, Channel-based Multi-PHY is a better choice.

Dynamic Multiprotocol (DMP) between RAIL-based protocols

If you have full protocol stacks that are completely independent, it makes sense to develop the PHY and Link layer independently as well. These layers communicate with RAIL, and the cleanest solution to this problem is Dynamic Multiprotocol. Typical usecase:

• One protocol is used to communicate with key fobs, while another is used to communicate in a home automation network

In Dynamic Multiprotocol, the RAIL scheduler decides which protocol is active.

Dynamic Multiprotocol is more capable than Multi-PHY, but also more complex, so it has some drawbacks when compared to Multi-PHY:

• Protocol change takes 450us on EFR32xG1x. This is a fixed worst-case delay, because the RAIL scheduler must plan time-sharing of the radio resource using calculations on a known sufficient time span in order to accomodate protocol switches.
• It requires the multiprotocol version of the RAIL library, which has a bigger memory footprint (both RAM and code) than the single protocol version.

Writing RAIL application in DMP will be the subject of this tutorial.

Dynamic Multiprotocol between RAIL-based and other Silicon Labs stack protocols

The usecase for this is straight forward:

• If you need Bluetooth and a RAIL-based protocol in the same application

At the moment, Silicon Labs only provides such a DMP solution based on the Bluetooth stack and RAIL. You can access it by installing the Bluetooth SDK and starting one of the DMP applications. See AN1134 for more details, and an upcoming tutorial detailing DMP usage from a RAIL perspective.

Other multiprotocol solutions

You can find other types of multiprotocol mentioned in some Silicon Labs documents, but they are rarely used:

Programmable multiprotocol means multiple firmware images for each protocol, and the protocol is decided during the manufacturing process, i.e. a device is either programmed to be a Bluetooth or a Zigbee device.

Switched multiprotocol means two firmware images, one for each protocol. A bootloader loads the firmware needed for the protocol, and the two firmware can communicate with each other in a shared NVM storage. Protocol switching in switched multiprotocol is rather slow, and using DMP is almost always a better choice.

Concurrent multiprotocol means that the PHY and maybe the lower layers of the stacks are the same, but the upper layers are different. E.g. You can run two proprietary 15.4 protocol on the same channel at the same time, but you don't really need multiprotocol specific APIs to support it.

Related documentation

• AN971: EFR32 Radio Configurator Guide
• UG103.16: Multiprotocol fundamentals

Introduction

This article intends to show how to configure an On-off keying modulation profile in the Radio Configurator in Simplicity Studio. In this example we will be using two Wireless Starter Kit with BRD4257A radio boards (Flex Gecko, 19 dBm, 915 MHz). However, considering the following guidelines, the radio link can be set up for any base frequency and/or radio board.

The guide is not going into details about most of the controls found in the Radio Configurator and assumes basic radio technology and RAIL application creational knowledge. For more information on custom radio configurations, please see AN971.

OOK modulation

The On-off keying modulation method is a simple type of the amplitude-shift keying modulation. It codes the transmitted data at the presence or the absence of the carrier wave (binary one and zero respectively).

  

This type of modulation is quite popular due to its simplicity and rather low implementation costs. Its main advantage is that it can let the transmitter run in idle while transmitting zeros, which can preserve power. The biggest disadvantage of the technology is its sensitivity to noise. Since zero means nothing is transmitted, with a significant amount of background noise the ones and zeros can be a challenge to distinguish on the receiving end.

Radio configurator setup

Create a new RAILTEST example application to set up the radio link in the radio configurator. It is easier to start with a base profile, in our case we chose one of the 915 MHz profiles. Naturally, you can set the profile and the following settings based on your requirements.

General radio link parameters

After all the settings were loaded, switch to "Custom settings" to enable edit. Here choose OOK as the modulation type to switch to On-off Keying modulation.  In our case the data rate is set to 4.8 Kbps, as OOK transmissions are usually used with lower data rates. For this modulation, deviation is not relevant. 

Important: Make sure to uncheck all settings under the "Advanced tab" in the bottom, letting the configurator determine all the parameters.

If you are setting up a receiver, also make sure to define your RX and TX crystal accuracy under the "Crystal" tab. This will help the configurator determine a valid receive bandwidth. Alternatively, if you have a predefined receiver bandwidth, you can set it under the Advanced section, "Channel bandwidth" option. If neither the crystal accuracy nor the bandwidth is known, in general 200 kHz can be recommended.

BT parameter recommendations

At this point the modulation probably will not work yet, as the Shaping Filter Parameter (BT) is set for FSK2 (or any other which you used as a base profile) and not for OOK modulation. Set this parameter to 1.5 for the best results, see explanation below.

In yellow you can see the output and its spectrum generated with low BT parameter, in this case 0.5. It's visible how the signal is over-filtered, the edges are rounded down too much for the receiver to interpret this as an OOK modulation.

   

We can get an ideal OOK output signal by completely disabling the filtering, these outputs are marked with purple. You can see it on the time domain diagram how perfect it looks like, however significant background noise and regular side-bands appeared on its spectrum at the same time.

       

The output of the recommended configuration with the Gaussian filter on, using a BT of 1.5 is marked with teal on the figures. In time domain a lesser "rounding" effect came back, however by using this filter we can suppress the side-bands of the spectrum emission and less background noise is generated, while the receiver can interpret the signal without any issue.

Therefore, for the best results our recommended value is 1.5 for the BT parameter. See the final settings of the radio link below.

   

You can also find this configuration attached for the aforementioned base band and radio board.

Testing the radio link using railtest

With the settings above applied, it's time to generate the example code and build, flash it on the devices. After opening the console on both targets, or by just pushing the PB0 a few times shortly, we can check the functionality of the radio link.

See a test method with results in the following to get an approximate PER of the link created:

TX side

RAIL Test App - Built: Feb 12 2019 11:13:18
> settxdelay 10
{{(setTxDelay)}{txDelay:10}}
> tx 1000
> {{(tx)}{PacketTx:Enabled}{None:Disabled}{Time:47701122}}
{{(appMode)}{None:Enabled}{PacketTx:Disabled}{Time:84048987}}
{{(txEnd)}{txStatus:Complete}{transmitted:1000}{lastTxTime:84048937}{failed:0}
{lastTxStatus:0x0}{isAck:False}}

RX side

RAIL Test App - Built: Feb 12 2019 11:13:18
> setnotifications 0
{{(setNotifications)}{Peripherals:Enabled}{Notifications:Disabled}}
> status
{{(status)}{UserTxCount:0}{AckTxCount:0}{UserTxAborted:0}{AckTxAborted:0}{UserTxBlocked:0}
{AckTxBlocked:0}{UserTxUnderflow:0}{AckTxUnderflow:0}{RxCount:999}{SyncDetect:999}
{NoRxBuffer:0}{RfSensed:0}{ackTimeout:0}{ackTxFpSet:0}{ackTxFpFail:0}{RfState:Rx}
{RAIL_state_active:0}{RAIL_state_rx:1}{RAIL_state_tx:0}{Channel:0}{AppMode:None}
{TimingLost:0}{TimingDetect:0}{FrameErrors:0}{RxOverflow:0}{AddrFilt:0}{Aborted:0}
{Calibrations:1}{TxChannelBusy:0}{TxClear:0}{TxCca:0}{TxRetry:0}}

   

As you can see out of a 1000 packets sent with rather small delay, 999 arrived successfully, resulting a 0.1% error rate, which can be considered acceptable.

RSSI (Received Signal Strength Indicator) measurement is continuously running and the current result is stored in a HW register after the Rx is started. This register gets updated after each measurement window.

When the Rx is started the first RSSI result is not available immediately. The first RSSI acquisition time can be split into three parts:

1. State transition time to Rx – this depends on the starting state
2. Signal propagation through the Rx chain
3. RSSI measurement window length

As stated 1) depends on the starting state and also on a RAIL configuration that explicitly sets state transition times. More on this you can read here: RAIL Tutorial: Time, timestamping and Scheduling

Contribution 2) depends on the PHY configuration (and varies with PHY configuration). This time is mainly driven by the delay through the channel filter so as a rule of thumb it scales inversely proportionally with the configured channel bandwidth. For a typical FSK modulation where the channel filter roughly equals the signal bandwidth itself this time is ~ 3-4 Ts, where Ts is the symbol time.

RSSI measurement is held off for some amount of time to make sure no false RSSI readings are reported due to partial signal propagation. This time is configurable on the radio configurator advanced AGC section (AGC Settling Delay). Note that this parameters primarily adjusts the AGC (Automatic Gain Control) time schedule so it is recommended not to be tampered with as the AGC may go unstable or converge slowly.

Also note that this time period may be extended (by as much as 2x) for gain adjustments in the front end. It means that this time period depends on the signal level presented to the Rx. Typically you get the fastest response time around sensitivity level and may experience longer acquisition times above ~ sensitivity + 20 dB.

Contribution 3) is the RSSI measurement itself. Once the “blanking” period explained in point2) expires the first RSSI measurement commences. The measurement window through which the RSSI samples are averaged can be set on the configurator GUI with control RSSI Update Period. (Measurement and update period = 2^RSSI Update Period [Ts].) This control sets the length of the measurement window as well as the measurement update period. A result is reported after each back to back measurement window and stored in a HW register. Each result represents the average reading of the preceding measurement window. The HW register stores an invalid value until the 1st result gets written into it. (This is the invalid value RAIL also reports if a measurement results is not available, i.e., the device is not in Rx state or a valid result has not arrived yet in Rx state.)

As an example take a 100 kbps 2GFSK PHY with 50 kHz deviation and a 200 kHz channel filter with an RSSI Update Period of 1 meaning a 2Ts window. Suppose the starting state is idle. The time contributions will have the following values

1. 100 us  - the shortest programmable consistent** state transition time
2. ~ 3Ts = 30 us  - assuming close to sensitivity level signals
3. 2Ts = 20 us

** Note that the state transition time may also be configured to as fast as possible: from idle to Rx this typically means 60-80 us. In this mode the state transition time is not consistent. i.e., it varies from Rx start to Rx start. The shortest consistent state transition time from idle state to Rx state is 100 us.  Look for RAIL_StateTiming_t for more details.

The sum is ~ 150 us most of which is taken up by the state transition itself. If we take a much lower DR PHY as an example you may see that the RSSI acquisition time will mostly be driven by the symbol time.

If you are not happy with the RSSI acquisition time as the whole operation burns too much energy here is the tricks (and tradeoffs) you may apply to make it faster. As the state transition time is a given these will have the most benefits at low data rate PHYs.

1. Select the minimum measurement window of RSSI Update Period = 1 (measuring over 2Ts).
2. Open up the channel bandwidth. This will make the blanking time shorter at the expense of worse selectivity. In a channelized system you may not have much room here.
3. Increase the DR while keeping the same channel bandwidth. This will make the RSSI measurement time shorter at the price of less accurate readings. You must force the channel bandwidth to achieve this otherwise the calculator will make it automatically wider.
4. If your application can tolerate inconsistent state transition times opt for the as fast as possible option in RAIL_StateTiming_t.

Below are some explanations of the RAIL RSSI related APIs:

RAIL_GetRssi(): When this function is called it simply returns the current value stored in the HW RSSI register. It does not initiate a new measurement. It returns an invalid value if the HW register has an invalid value in it as explained above.

RAIL_StartAverageRssi() .This function can only be called from idle state. This function makes the radio transition to Rx state and measure one RSSI value with the exact measurement window given to it. This function reconfigures the radio to align the HW RSSI measurement window to the desired averaging time. This means that during the measurement packets cannot be received. To this end signal detection is disabled during the operation of this function. Once the RSSI measurement is acquired the configuration is restored and the radio returns to idle state. The HW supports a finer adjustment on the measurement window which is not exposed on the configurator GUI – this function makes use of this method to match the desired measurement window as accurate as possible from HW. The resolution of window adjustment is ~ Ts/10 – Ts/5. So taking the 100 kbps example the resolution will be between 1us – 2us. The exact resolution depends on the PHY configuration. Note that based on the operations of this API there will be a maximum time limit (dependent on the PHY) the API is capable of supporting. If a longer time period is requested RAIL_STATUS_INVALID_PARAMETER is returned.

RAIL Tutorial: Timer synchronization and sleep

This tutorial builds on the following tutorials:

• RAIL Tutorial 1: Introduction and init
• RAIL Tutorial 2: Transmitting a Packet
• RAIL Tutorial 3: Event Handling
• RAIL Tutorial 4: Combining Transmit and Receive
• RAIL Tutorial: Time, timestamping and Scheduling

Please read them first if you haven't.

You can find other tutorials on the table of contents site.

Why timer synchronization is needed

RAIL provides a timer which is used both for timestamping and for scheduled transmits/receives. However, since this timer runs from the main oscillator, it does not work in EM2 and deeper sleep modes. It's not possible to run the RAIL timer from one of the LF oscillators, they simply doesn't have the required resolution. However, that accuracy is only required in active communication, e.g. to schedule ACK messages. In inactive mode, LF clock accuracy is usually enough. Using two clocks for scheduling is complicated, and sometimes causes additional inaccuracy. EFR32 has a hardware level solution for that problem, which is a synchronization method between the radio timer and an RTC that can run in EM2.

The problem with the timer synchronization is that we cannot do it at any time: The typical frequency of the RTC is 32.768kHz, which means about 30us period (and it might be much worse if RTC is prescaled). If we save the value of both timers at the same time, we immediately have up to 30us error, and the same error again when we restore the radio timer. That's 60us worst case, which is catastrophic error for some protocols (including our BLE stack).

The solution to that problem is to save/restore the RAIL timer when the RTC timer ticks. This way, the worst case error is twice the RAIL timer resolution, which is 0.5us/2us, depending on the hardware (2us for EFR32xG1, 0.5us for all others). This is usually good enough for idle periods.

EFR32/RAIL implementation

RAIL does a bit more than that actually: It not only synchronizes the RAIL timer and RTC before sleep/after wakeup, it also uses RTC compare to set up an interrupt, which will wake the MCU up for the next radio operation. So, the flow of events is as follows:

1. Application schedules a radio operation (e.g. scheduled Tx)
2. Application requests RAIL to sleep (RAIL_Sleep())
3. RAIL synchronizes the timers
4. RAIL sets up an RTC timer interrupt to fire before the already set RAIL timer would fire
5. RAIL shuts down the RAIL timer
6. Application enters EM2 sleep
7. RTC wakes up the MCU
8. Application (usually em_emu.c) restarts the main oscillator, and other required clocks
9. Application requests RAIL to wake up (RAIL_Wake())
10. RAIL synchronizes the timers
11. RAIL timer fires, and starts the radio operation

Note that the RAIL timer is still needed to start the actual radio operation, so step 10 must be finished before the RAIL timer should fire. This means RAIL must know the time it takes to perform steps 7-10, and set the RTC timer earlier by this amount, to guarantee that the RAIL timer is running by the time the radio operation must start.

Bluetooth DMP Projects

If you're using RAIL in Bluetooth DMP projects, you don't have to worry about this: The Bluetooth side of the application handles it by calling the SleepAndSyncProtimer() function in the idle task.

Prerequisites

For the above operations, RAIL will need:

• A running RTC timer (for the synchronization)
• An RTC compare channel (for waking up the MCU)
• A PRS channel (so the synchronization can happen exactly when the RTC ticks)

Setting up the PRS Channel

RAIL always uses PRS channel 7, so it mustn't be used by the application, and only requires the PRS clock to be running:

CMU_ClockEnable(cmuClock_PRS, true);

Setting up the RTC: EFR32xG13, EFR32xG14

EFR32xG13 and EFR32xG14 have a specific radio RTC just for this, which is handled by RAIL. You only need an LF clock running, preferably LFXO (for higher accuracy). This is handled by the RAIL HAL plugin, but if you don't want to use that, you'll need the following to start the LFXO:

CMU_LFXOInit_TypeDef lfxoInit = BSP_CLK_LFXO_INIT;
lfxoInit.ctune = BSP_CLK_LFXO_CTUNE;
CMU_LFXOInit(&lfxoInit);
SystemLFXOClockSet(BSP_CLK_LFXO_FREQ);

Setting up the RTC: EFR32xG1, EFR32xG12

On EFR32xG1 and EFR32xG12, RAIL uses the RTCC and its compare channel 0. There's an easy way and a complex way to set this up.

RTCC for RAIL: The Easy Way

The easy way is to use RTCDRV: since it uses compare channel 1, it won't interfere with RAIL.

#include "rtcdriver.h"
RTCDRV_Init();

It doesn't matter if you don't use RTCDRV for anything, the important thing is that it sets up RTCC correctly, and clears its interrupt flag when needed.

RTCC for RAIL: The Complex Way

You might not want to use RTCDRV, in which case you have to manually initialize RTCC, compare channel 0, and enable its interrupt:

/* Set up LFXO for LFE. Normally handled automatically by the RAIL HAL plugin */
CMU_LFXOInit_TypeDef lfxoInit = BSP_CLK_LFXO_INIT;
lfxoInit.ctune = BSP_CLK_LFXO_CTUNE;
CMU_LFXOInit(&lfxoInit);
SystemLFXOClockSet(BSP_CLK_LFXO_FREQ);
CMU_ClockSelectSet(cmuClock_LFE, cmuSelect_LFXO);
/* init RTCC */
CMU_ClockEnable(cmuClock_CORELE, true);
CMU_ClockEnable(cmuClock_RTCC, true);
const RTCC_Init_TypeDef initRTCC =
{
  true,                 /* Start counting when init completed. */
  false,                /* Disable updating RTC during debug halt. */
  false,                /* Prescaler counts until max. before wrap around. */
  false,                /* Counter counts until max. before wrap around. */
  rtccCntPresc_1,       /* Set RTCC prescaler to 1 */
  rtccCntTickPresc,     /* Count according to prescaler configuration */
  #if defined(_RTCC_CTRL_BUMODETSEN_MASK)
  false,                /* Disable storing RTCC counter value in RTCC_CCV2 upon backup mode entry. */
  #endif
  false,                /* LFXO fail detection disabled */
  rtccCntModeNormal,    /* Use RTCC in normal mode and not in calender mode */
  false                 /* No leap year correction. */
};
RTCC_Init(&initRTCC);
/* Disable interrupt generation from RTC */
RTCC_IntDisable(_RTCC_IF_MASK);
/* Enable interrupt on NVIC - keep the default (empty) handler */
NVIC_ClearPendingIRQ(RTCC_IRQn);
NVIC_EnableIRQ(RTCC_IRQn);

You must also clear the interrupt flag RTCC_IF_CC0 in the interrupt handler, but it's simpler to clear all pending interrupts:

void RTCC_IRQHandler(void){
  CORE_DECLARE_IRQ_STATE;
  uint32_t flags;
  CORE_ENTER_ATOMIC();
  flags = RTCC_IntGetEnabled();
  RTCC_IntClear(flags);
  CORE_EXIT_ATOMIC();
}

Writing Platform Independent RTC Setup

You can use the following macro to detect your MCU at compile time:

#if _SILICON_LABS_32B_SERIES_1_CONFIG < 3
  //MCU is EFR32xG1 or EFR32xG12
#else
  //MCU is EFR32xG13 or EFR32xG14
#endif

Enabling Timer Synchronization

Finally, we let RAIL know that we want to use the timer synchronization feature:

RAIL_ConfigSleep(railHandle, RAIL_SLEEP_CONFIG_TIMERSYNC_ENABLED);

Entering and Leaving Sleep Mode

You can enter sleep mode by calling RAIL_Sleep(), which has 2 arguments.

deepSleepAllowed will return true if EM2 sleep is possible. If it returned true, the RAIL timer is stopped, and RAIL_Wake() must be called before calling any RAIL API. If it returned false, the RAIL timer isn't stopped, and RAIL_Wake() mustn't be called.

wakeupProcessTime sets the time required from the RTC interrupt to the actual timer synchronization, i.e. steps 7-10 on the list above. The easiest is to set it up based on testing, see the next chapter for details. A good starting value is 1000µs.

Once the HFXO is up and running again, you should call RAIL_Wake() to start and synchronize the RAIL timer. It has a single parameter, elapsedTime, which should be always 0 if you use the automatic synchronization.

So, in the end, the code should look something like this:

bool canDeepSleep = false;
while ( RAIL_Sleep(wakeupProcessTime, &canDeepSleep) != RAIL_STATUS_NO_ERROR )
  ;
if ( canDeepSleep ){
  EMU_EnterEM2(true);
  //after handling the RTC interrupt, and restoring clocks, we return here
  while ( RAIL_Wake(0) != RAIL_STATUS_NO_ERROR )
    ;
} else {
  EMU_EnterEM1();
}

Tuning wakeupProcessTime

The attached example code can be used to tune wakeupProcessTime. To use it, open a Simple RAIL with HAL application on your hardware, and replace its main.c with the attached one. It's designed to run on WSTK, but it shouldn't be too difficult to modify it to custom platforms. It uses UART, 2 buttons, and 2 GPIOS, one of which should be configurable as a PRS output (however, it should be possible to run this test with much less peripheral, it will be just less convenient).

Make sure you configure the hardware, especially the clock and energy manager (CMU and EMU) the way your application will use it: HFXO has some configurable delays, while EMU can configure EM2 sleep mode, which changes the wakeup time. The running peripheral clocks might also slightly change the wakeup time if you requested the EMU to restart the clocks. Also, make sure you set up the correct CTUNE values on both of the crystals.

Once you're done with that, enable the Virtual COM Port and Button modules on hwConf.

The application initializes RAIL, sets up timer synchronization, then enters the loop: It will schedule a 1ms RX window 50ms into the future, then enters EM2 sleep (Using the proper RAIL_Sleep()/RAIL_Wake() APIs). Once the radio returns to idle at the end of the RX window, it will schedule a new 1ms RX window 50ms into the future, and so on.

Connect an oscilloscope or logic analyzer to I2C_SDA/I2C_SCL pins of the WSTK: I2C_SDA will be pulled high if the radio is in RX, while I2C_SDA will be pulled high when the Rx window is scheduled, and pulled low when the MCU wakes up. You can decrease the wakeupProcessTime by pressing PB0, and increase it by pressing PB1. On a UART terminal, you'll see the currently configured wakeupProcessTime (in µs). If you decreased it too much, the MCU will wake up, but the radio will skip the RX window, i.e. I2C_SCL will toggle, but I2C_SDA won't:

The easiest way to catch those errors is to set an interval trigger, like on the screenshot above.

Note that if you set the wakeupProcessTime way too low, the application might crash.

Once you find the minimum wakeupProcessTime, you’ll want to add a safety margin to this value (to account for part-to-part and temperature-induced variation)

RAIL APIs Referenced in this Article

• RAIL_ConfigSleep()
• RAIL_Sleep()
• RAIL_Wake()

While this is a RAIL software tutorial, it could be useful for a hardware engineer who's working on a radio setup as well. It helps if you have some knowledge of RAIL, but only basic C knowledge is a requirement.

You can find other tutorials on the table of contents site.

Silicon Labs provides tools to generate RAIL config files, but it could be useful to understand how they work.

The generated files

The radio configurator is bundled with appbuilder, which generates a number of files, but only 3 is the result of the radio configurator:

• rail_config.c
• rail_config.h
• efr32_radio_configurator_log.txt

The log file has some information on calculated values, e.g. the bandwidth or the IF frequency.

The header

The configurator generates rail_config.h, with only two lines (apart from includes and header guards):

#define RADIO_CONFIG_XTAL_FREQUENCY 38400000UL
extern const RAIL_ChannelConfig_t *channelConfigs[];

The first one tells that the config was created for a 38.4MHz crystal, while the second one is the variable to access the configuration from the application.

The most important file is rail_config.c, and from this point, we analyze that. It's recommended to open a rail_config.c file for reference when reading this tutorial.

Callback functions

The configurator generates the following callback functions, with empty body:

uint32_t RAILCb_CalcSymbolRate(RAIL_Handle_t railHandle)
uint32_t RAILCb_CalcBitRate(RAIL_Handle_t railHandle)
void RAILCb_ConfigFrameTypeLength(RAIL_Handle_t railHandle, const RAIL_FrameType_t *frameType)

These callbacks are implemented in RAIL as a weak function, but only needed when RAIL is used with a config generated by an older configurator. Since they're not needed with the new configurator, these functions override the weak functions in RAIL saving the codespace used by them.

The config array(s)

Most of the config is encoded into a config array (in case of a multi-phy config, multiple config arrays), that looks like this:

const uint32_t generated[] = {
  0x01040FF0UL, (uint32_t) generated_phyInfo,
     /* 0FF4 */ 0x00000000UL,
     /* 0FF8 */ 0x0003C000UL,
  //more config
  0xFFFFFFFFUL,
};

These are essentially address-value pairs, that RAIL decodes and loads to the correct place. Keep in mind that these are EFR32 generation specific arrays, e.g. you cannot use an array on an xG13 device if it was generated for xG1. However, you can use the same config on a Mighty Gecko and a Flex Gecko, as long as the generation is the same.

Helper arrays

Some features, like the "3 out of 6" encoder needs helper arrays, that are referenced by a pointer in the main config array.

PHY info array

One of the values of the config array is a pointer to another array called generated_phyInfo. This holds information of the config for RAIL. For example, the function RAIL_GetBitrate() returns the bitrate for the config. While it can be calculated from the config values, it's faster and even takes less code space to store it in the phyInfo.

IR calibration helpers

For details on the IR calibration, refer to the Calibration tutorial.

The configurator generates an array and a struct that is connected to the IR calibration, and they look like this:

static const uint8_t generated_irCalConfig[] = {
  24, 69, 3, 6, 4, 16, 1, 1, 1, 3, 1, 6, 0, 16, 39, 0, 0, 10, 0, 0, 0, 0, 0, 0, 0
};

RAIL_ChannelConfigEntryAttr_t generated_entryAttr = {
  { 0xFFFFFFFFUL }
};

The first one, generated_irCalConfig tells RAIL how to run the IR calibration on this phy. This array is passed as part of the PHY info array. The second one, generated_entryAttr is used to cache the calibration result. When you run RAIL_CalibrateIr(), RAIL_ApplyIrCalibration() or RAIL_Calibrate, it will store the IR calibration result here. If you load a channel with the entryAttr value of 0xFFFFFFFFUL, it will trigger the event RAIL_EVENT_CAL_NEEDED. This is passed as part of the channel entry configuration.

Channel configuration

RAIL_ConfigChannels() takes a RAIL_ChannelConfig_t argument. In the config file, it usually looks something like this:

const RAIL_ChannelConfig_t generated_channelConfig = {
  generated,
  NULL,
  generated_channels,
  1
};

The first argument generated, is the base configuration: It is loaded immediately when you call RAIL_ConfigChannels(). The second parameter is part of RAIL 2.x multiphy features, we'll return to that later. The third parameter, generated_channels, is a pointer to and array of RAIL_ChannelConfigEntry_t, while the last parameter is the number of elements in the previous array.

The channel entry is an array of structs, looking like this (with a single element):

const RAIL_ChannelConfigEntry_t generated_channels[] = {
  {
    .phyConfigDeltaAdd = NULL,
    .baseFrequency = 868000000,
    .channelSpacing = 1000000,
    .physicalChannelOffset = 0,
    .channelNumberStart = 0,
    .channelNumberEnd = 20,
    .maxPower = RAIL_TX_POWER_MAX,
    .attr = &generated_entryAttr
  },
};

The first parameter (.phyConfigDeltaAdd) is again part of the multiphy features. maxPower can be used if you have to limit the transmit power on some channels to meet regulatory standards. Note that it's in deci-dBm, so unless it's set to RAIL_TX_POWER_MAX, you'll need the PA conversion plugin or the PA conversion functions implemented to use it. attr points to the entryAttr struct, which is part of the IR calibration system, see above.

The remaining parameters set the frequency and the channel numbers. The frequency of a given channelNumber is calculated with this formula:

channelFrequency = baseFrequency + channelSpacing * ( channelNumber - physicalChannelOffset )

Note that you cannot set the frequency beyond a limit without changes in the configuration. These limits depend on the part, so please rely on the configurator's help. If you set the frequency beyond the configuration's capability, you'll get a RAIL_ASSERT_FAILED_SYNTH_VCO_FREQUENCY assert.

channelNumberStart and channelNumberEnd sets the limits of the entry, i.e. the first and the last channel.

Creating channel configs for evenly spaced channels

The example above shows a 21 channel configuration from 868MHz (ch0) to 868+20*1=888MHz (ch20).

You might wonder what's the point of physicalChannelOffset. In simple, sequential configs, it can be useful if the standard doesn't start on channel 0. For example, IEEE 802.15.4 defines 16 channels on 2.4GHz, with the range 11-26. This can be set like this:

const RAIL_ChannelConfigEntry_t generated_channels[] = {
  {
    .phyConfigDeltaAdd = NULL,
    .baseFrequency = 2405000000,
    .channelSpacing = 5000000,
    .physicalChannelOffset = 11,
    .channelNumberStart = 11,
    .channelNumberEnd = 26,
    .maxPower = RAIL_TX_POWER_MAX,
    .attr = &generated_entryAttr
  },
};

const RAIL_ChannelConfig_t generated_channelConfig = {
  generated,
  NULL,
  generated_channels,
  1
};

Since physicalChannelOffset == channelNumberStart, the frequency for channel 11 will be 2405MHz, based on the formula above.

Creating channel configs with uneven channel spacing

Unfortunately, not all protocols define such even channel maps. E.g., imagine a scenario, where you have 3 channels, on 868.3MHz, 868.9MHz and 869.9MHz. That could be implemented with the following:

const RAIL_ChannelConfigEntry_t generated_channels[] = {
  {
    .phyConfigDeltaAdd = NULL,
    .baseFrequency = 868300000,
    .channelSpacing = 600000,
    .physicalChannelOffset = 0,
    .channelNumberStart = 0,
    .channelNumberEnd = 1,
    .maxPower = RAIL_TX_POWER_MAX,
    .attr = &generated_entryAttr
  },
  {
    .phyConfigDeltaAdd = NULL,
    .baseFrequency = 869900000,
    .channelSpacing = 0,
    .physicalChannelOffset = 2,
    .channelNumberStart = 2,
    .channelNumberEnd = 2,
    .maxPower = RAIL_TX_POWER_MAX,
    .attr = &generated_entryAttr
  },
};

const RAIL_ChannelConfig_t generated_channelConfig = {
  generated,
  NULL,
  generated_channels,
  2
};

As you can see, the array has two elements now. The first one creates channel 0 and 1 on 868.3MHz and 868.3+0.6=868.9MHz, while the second one creates channel 2 on 869.9MHz. To use it, don't forget to set the arrayLength to 2 in RAIL_ChannelConfig_t.

Channels with multiple definition

This channel description method does not restrict multiple definitions for the same channel number. RAIL will always use the first definition from the array. This can be used, if regulations restricts transmission power on one channel. E.g. let's say we have a 0 dBm restriction on channel 15 of the above 15.4 configuration. This can be coded like this:

const RAIL_ChannelConfigEntry_t generated_channels[] = {
  {
    .phyConfigDeltaAdd = NULL,
    .baseFrequency = 2405000000,
    .channelSpacing = 5000000,
    .physicalChannelOffset = 11,
    .channelNumberStart = 15,
    .channelNumberEnd = 15,
    .maxPower = 0,
    .attr = &generated_entryAttr
  },
  {
    .phyConfigDeltaAdd = NULL,
    .baseFrequency = 2405000000,
    .channelSpacing = 5000000,
    .physicalChannelOffset = 11,
    .channelNumberStart = 11,
    .channelNumberEnd = 26,
    .maxPower = RAIL_TX_POWER_MAX,
    .attr = &generated_entryAttr
  },
};

const RAIL_ChannelConfig_t generated_channelConfig = {
  generated,
  NULL,
  generated_channels,
  2
};

When RAIL tries to load channel 15, it will find the first config first, so it will use it with the power restriction of 0, set by maxPower. However, for all other channels RAIL will use the second, unrestricted config.

Multi-PHY capabilites

Config switch

You can create multi-phy configs without RAIL's help, by simply reconfiguring RAIL using RAIL_ConfigChannels(). You can find the structure for this in rail_config.c, in it's top level array:

const RAIL_ChannelConfig_t *channelConfigs[] = {
  &generated_channelConfig,
};

This is usually used like this:

RAIL_ConfigChannels(railHandle, channelConfigs[0], NULL);

However, it's an array, and there's nothing against adding multiple RAIL_ChannelConfig_t pointers into that array, and calling RAIL_ConfigChannels(railHandle, channelConfigs[1], NULL); when needed.

Channel based multi-PHY

You can partially reconfigure the radio with a simple channel change, e.g. channels 0-19 uses 100kbps bitrate, and channels 20-39 uses 200kbps bitrate on the same frequencies. That can be configured using the two struct members we skipped when discussing the channel configuration:

RAIL_ChannelConfig_t.phyConfigDeltaSubtract //second parameter of RAIL_ChannelConfig_t
RAIL_ChannelConfigEntry_t.phyConfigDeltaAdd //first parameter of RAIL_ChannelConfigEntry_t

These can both point to config arrays, similar (but usually smaller) than the base array. To understand how this works, let's see how RAIL loads a channel:

1. Checks if the desired channel is already configured (i.e. by a previous tx/rx operation or using RAIL_PrepareChannel()). If it is, exits
2. Goes through the array of RAIL_ChannelConfigEntry_t in the configuration, from array index 0 to the end, or until it finds the channel
3. Checks the value of phyConfigDeltaAdd (i.e. the memory address in the pointer). If it's the same as the loaded one, GOTO 6.
4. Loads phyConfigDeltaSubtract. This is used to return to a known base configuration.
5. Loads phyConfigDeltaAdd of the new configuration. Stores its address to avoid loading it for a different channel
6. Calculates, and sets the frequency
7. If power level is above the limit, it sets it to the limit
8. Calls a RAIL_RadioConfigChangedCallback_t, if it was given as third parameter of RAIL_ConfigChannels()

With the algorithm above, you can set up multiple config entries with the same phyConfigDeltaAdd, and it will still load the config when it changes the channel to one that uses different phyConfigDeltaAdd. Note that it never switches PA. If your config change requires PA switching (e.g. changing between 2.4GHz and sub-GHz PA), it should be handled in the callback called in step 8. It also doesn't increase the PA level, that could be also handled in this callback.

API introduced in this tutorial

Types and enums

• RAIL_ChannelConfig_t
• RAIL_ChannelConfigEntry_t

This tutorial builds on the following tutorials:

• RAIL Tutorial 1: Introduction and init
• RAIL Tutorial 2: Transmitting a packet
• RAIL Tutorial 3: Event handling
• RAIL Tutorial 4: Combining transmit and receive

Please read them first if you haven't. You should also have some experience with SWD based debugging in Simplicity Studio.

You can find other tutorials on the table of contents site.

Like most embedded radio platforms, EFR32 provides a way to download/upload packets during reception/transmission, respectively. So, for example, while you're sending the first couple of bytes of of your frame, you can still upload the end of the frame.

Since the radio is using ring buffers, this makes possible to handle longer frames than what fits into the buffer, and nowadays, this is pretty much the only reason to use it. A typical usecase for example is a protocol, where almost all of the frames fit into 128B buffer, but in rare cases, the protocol must handle 512B long frames. In this tutorial the examples will present how to do that.

Advanced packet mode features

If you have to look into the packet during reception (e.g. because you will use RAIL_SetFixedLength() to handle a frame length coding which is not supported by hardware), you shouldn't use FIFO mode. Instead, you can use RAIL_PeekRxPacket() to look into the packet, but still keeping it in the buffer, and only downloading it when you got the full frame.

If you want to have multiple frames in the buffer, there's also no reason to use FIFO mode: you can handle multiple frames without problems using packet mode. Before transmit, you can use the same APIs (RAIL_SetTxFifo() and RAIL_WriteTxFifo()) to write multiple packets, while you can store the packetHandles in Rx mode and keep them in buffer using RAIL_HoldRxPacket().

Differences in FIFO mode

Switching to FIFO mode doesn't actually do anything on the transmit side (since RAIL 2.0), but changing the receiver to FIFO mode slightly changes the behavior of the receive buffer: RAIL_GetRxPacketInfo() (the usual way to access the received packet) won't work, you must use RAIL_ReadRxFifo(). Also, RAIL won't provide information on the frame length, and you should be careful to read exactly as many bytes as your frame, otherwise you might corrupt the next packet: E.g. if you leave the end of the packet in the FIFO, you will probably download it as the beginning of the next packet, corrupting that frame as well.

Enabling FIFO mode

RAIL_ConfigData() can be used to switch to FIFO mode, probably at the end of your radio init function:

RAIL_SetTxFifo(railHandle, txBuffer, 0, TX_BUFFER_SIZE);
static const RAIL_DataConfig_t railDataConfig = {
  .txSource = TX_PACKET_DATA,
  .rxSource = RX_PACKET_DATA,
  .txMethod = FIFO_MODE, //doesn't do anything
  .rxMethod = FIFO_MODE,
};
status = RAIL_ConfigData(railHandle, &railDataConfig);
RAIL_SetTxFifoThreshold(railHandle, TX_BUFFER_SIZE - TX_BUFFER_SIZE / 10);
RAIL_SetRxFifoThreshold(railHandle, RX_BUFFER_SIZE - RX_BUFFER_SIZE / 10);
RAIL_ConfigEvents(railHandle, RAIL_EVENT_TX_FIFO_ALMOST_EMPTY|RAIL_EVENT_RX_FIFO_ALMOST_FULL,
                    RAIL_EVENT_TX_FIFO_ALMOST_EMPTY|RAIL_EVENT_RX_FIFO_ALMOST_FULL);

First, it sets up a tx buffer with RAIL_SetTxFifo, then configures RAIL to use FIFO mode. Then it sets up both rx and tx thresholds to 10%, which is usually a good value, although you might want to increase it at high data rates (RX_BUFFER_SIZE should be 512B, if you did not implement RAILCb_SetupRxFifo). Finally, it enables the two "threshold reached" event.

Using FIFO mode: transmit

On the transmit side, the idea is to fill the buffer completely, start the transmission, and fill the remaining when needed:

#define PACKET_LENGTH 1024
uint8_t packetToSend[PACKET_LENGTH];
volatile uint16_t txOffset;
void startTx(){
  txOffset = RAIL_WriteTxFifo(railHandle, packetToSend, PACKET_LENGTH, false);
  RAIL_StartTx(railHandle, 0, RAIL_TX_OPTIONS_DEFAULT, NULL);
}

void RAILCb_Generic(RAIL_Handle_t railHandle, RAIL_Events_t events){
  if ( (events & RAIL_EVENT_TX_FIFO_ALMOST_EMPTY) && ( txOffset < PACKET_LENGTH ) ){
    txOffset += RAIL_WriteTxFifo(railHandle, packetToSend + txOffset, PACKET_LENGTH - txOffset, false);
  }
}

This is just the related code, you probably have more events handled. If you look at the calls of RAIL_WriteTxFifo(), you can see that we always try to write the whole (remaining) packet, and do not check how much space we have in the FIFO. While we could do that, using RAIL_GetTxFifoSpaceAvailable(), it's not necessary: RAIL_WriteTxFifo() will automatically stop when the FIFO is full, and return with the number of bytes successfully written.

We do pretty much the same in the event, but we're adjusting both the source and the size with txOffset. The condition txOffset < PACKET_LENGTH is important, because the FIFO events do not check packet lengths: unless you have multiple packets in the buffer, you'll get an RAIL_EVENT_TX_FIFO_ALMOST_EMPTY every time when you have just threshold amount of bytes remaining of your packet (since it's normal to have an empty buffer if you don't want to send anything).

Using FIFO mode: receive

The receive side is basically the opposite of the transmit side:

#define PACKET_LENGTH 1024
uint8_t packetToReceive[PACKET_LENGTH];
volatile uint16_t rxOffset = 0;

void RAILCb_Generic(RAIL_Handle_t railHandle, RAIL_Events_t events){
  if ( events & RAIL_EVENT_TX_FIFO_ALMOST_FULL ){
    rxOffset += RAIL_ReadRxFifo(railHandle, packetToReceive + rxOffset, PACKET_LENGTH - rxOffset);
  }
  if ( events & RAIL_EVENTS_RX_COMPLETION ){
      if ( events & RAIL_EVENT_RX_PACKET_RECEIVED ){
        if ( rxOffset < PACKET_LENGTH ){
          rxOffset += RAIL_ReadRxFifo(railHandle, packetToReceive + rxOffset, PACKET_LENGTH - rxOffset);
        }
        RAIL_RxPacketDetails_t packetDetails = {
          .isAck = false,
          .timeReceived = {
            .timePosition = RAIL_PACKET_TIME_AT_SYNC_END,
            .totalPacketBytes = PACKET_LENGTH,
          },
        };
        RAIL_GetRxPacketDetails(railHandle, RAIL_RX_PACKET_HANDLE_NEWEST, &packetDetails);
      }
      rxOffset = 0;
    }
}

We start with an empty packetToReceive, and the first thing we receive will be a single or multiple RAIL_EVENT_TX_FIFO_ALMOST_FULL (alternatively, RAIL_EVENT_RX_SYNC1_DETECT/RAIL_EVENT_RX_SYNC2_DETECT could be handled to set up packetToReceive for reception). Each time we got that event, we download as much from the FIFO as we can, and adjust the offset (again, we could check the amount of data in the FIFO using RAIL_GetRxFifoBytesAvailable(), but it's not necessary). When we got the RAIL_EVENT_RX_PACKET_RECEIVED, we probably still have some data remaining in the FIFO, so we download that. Then we get the packetDetails, just like we do for a normal packet. We reset the offset to be ready for the next packet, both on successful receive and errors.

Since this was a fixed length setup, there was no need to figure out the length. In variable length mode, you probably want to download the length field only first, set up a global variable with the length, and continue just like the above sample.

Special data sources

For the RX buffer, you can set up special data modes:

• RX_PACKET_DATA: normal mode, default
• RX_DEMOD_DATA: demodulated, but not sliced data. 1B per sample
• RX_IQDATA_FILTLSB: IQ data, lower 16 bits of 19. 2x2B per sample
• RX_IQDATA_FILTMSB: IQ data, upper 16 bits of 19. 2x2B per sample

All of these modes have a higher sample rate than what you set up on the configurator, since the radio does about 5-10x oversampling (depending on the configuration), which is removed at the end of the demodulation chain. Keep in mind that this could result so high data rate that the MCU won't be able to move data that fast. In our tests, we could handle about 50kb/s in IQ modes. These are quite complex to use, because you basically disable parts of the demodulation chain, but sometimes it's the only possibility.

RX_DEMOD_DATA is useful if your frame format is impossible to detect with the hardware, e.g. it has no preamble. It can be also useful if you need baudrate/deviation tolerance not supported by the hardware. It's basically tapping the demodulation chain when the "analog" demodulation is done, but it's quantized to 8 bits - so if you have set up FSK2 modulation, the result will be basically an FM demodulated signal.

RX_IQDATA_FILTLSB and RX_IQDATA_FILTMSB is useful if the hardware does not support the modulation you need - you can write you're own demodulator which works from the IQ samples, but that's quite heavy task for the CPU, and usually a complicated problem to solve. When IQ mode is used, one sample includes 4B, in this sequence:
I[LSB], I[MSB], Q[LSB], Q[MSB].

If you enable any of these modes, they will start filling the FIFO immediately, as detection doesn't work without the end of the demodulator chain.

Direct mode

You can configure the radio to send the data it receives to a GPIO, and read data from a GPIO and send it through radio, making essentially a transceiver. You can enable it with RAIL_EnableDirectMode(), and it's currently fixed to portC10 and portC11 for DIN/DOUT. When you start rx, you'll see nothing on DOUT: It will only start outputting data after sync word detection. Length decoder works as well, and it will stop reception when reaches the configured length (either variable or fixed). Tx mode works similarly, but it's mostly for diagnostic purposes, as it's not possible to use a sync mode reliably without a clock signal.

There's an Asynchronous direct mode checkbox on the configurator. If it's enabled, the DOUT pin's behavior will change: It will output oversampled data whenever the radio is in rx mode. See this KBA for details on this mode.

API introduced in this tutorial

Functions

• RAIL_PeekRxPacket
• RAIL_ReadRxFifo
• RAIL_ConfigData
• RAIL_SetTxFifoThreshold
• RAIL_SetRxFifoThreshold
• RAIL_GetTxFifoSpaceAvailable
• RAIL_GetRxFifoBytesAvailable

Types and enums

• RAIL_DataConfig_t
• RAIL_DataMethod_t (FIFO_MODE/PACKET_MODE)
• RAIL_RxDataSource_t (RX_PACKET_DATA/RX_DEMOD_DATA/RX_IQDATA_FILTLSB/RX_IQDATA_FILTMSB)
• RAIL_EVENT_TX_FIFO_ALMOST_EMPTY
• RAIL_EVENT_TX_FIFO_ALMOST_FULL

This tutorial builds on basic RAIL knowledge and does not detail all its APIs in depth. For a better understanding, please go through the RAIL tutorials if you haven't already.

Introduction

This project combines the MCU-based examples with the RAIL examples using one, or preferably two wireless starter kits. The purpose of this tutorial is to show how to include various peripheral drivers into a RAIL example project. It utilizes the basic capabilities of the RAIL while taking advantage of the built-in peripherals on the WSTKs as well, such as the LCD screen (through SPI), the digital temperature and relative humidity sensor (via I2C) and basic GPIO features, such as flashing LEDs and using interrupts for the buttons.

Specification

The specification of our application is relatively simple:

• Make the application reusable, run the same code on all WSTKs.
• The user should be able to switch between transmit and receive mode with a push of a button.
• Receive mode should be default. In this mode, receive the packet and update the screen based on the packet’s contents.
• If transmit mode is selected, read data from the thermometer and send it out in a packet.

First steps and hardware configuration

Setting up the radio configuration and the RAIL from scratch is not recommended, as it is time consuming and by using an example project we can make sure to get everything right for the first try. Let’s start our project with a RAIL example project instead. For our case the “RAIL: Simple TRX” example seems ideal: transmit and receive already work in this project all we should do is to add the graphics and sensor functionality and include the sensor data in the packet.

AppBuilder setup

After creating the project, the App Builder opens. First thing we should do is to choose a radio profile. Custom profiles can also be configured; however, a base profile is a sure bet. In this example we’re using a Mighty Gecko 868 MHz board, therefore one of the 868 MHz profiles are chosen. Choose any of the base profiles supported by your board.

  

The last step before generating the code is to disable some of the macros turned on by default in this example. Make sure the only macro enabled on the “Other” tab is the “HAL_MICRO” as we won’t need the VCOM retarget or any other debug functions in this project.

    

Press “Generate” to create the basic TRX application using RAIL.

Configuring DefaultMode Peripherals

This project is now set up to be used for RAIL, however the LCD and sensor drivers are not included yet. First, we will have to enable these peripherals ­– and disable anything unnecessary for the project – in the Hardware Configurator.

Make sure to enable the following:

• I2C Sensor (also enables I2C0)
• SPI Display (also enables USART1)

We won’t need:

• Serial
• Virtual COM port
• USART0 (can only be disabled after the first two)

Also delete the retargetserial.c file from the hal-efr32 folder as we won’t need this source anymore since we don't want to retarget the serial port in this example.

    

Including necessary drivers

To use the two extra drivers, we will need to also include them and a few other dependencies to our project's include paths.

     

Add the following lines to the include paths:

• "${StudioSdkPath}/platform/middleware/glib/dmd"
• "${StudioSdkPath}/platform/middleware/glib/glib"

And copy the following folders/files to your project.

From ${StudioSdkPath}\hardware\kit\common\drivers

To [project folder]\spidisplay\

• display.c
• displayls013b7dh03.c
• displaypalemlib.c
• retargettextdisplay.c
• textdisplay.c

To [project folder]\sensor\

• si7013.c

From ${StudioSdkPath}\hardware\kit\[your kit's folder]\config

To [project folder]\hal-config\

• retargettextdisplayconfig.h
• textdisplayconfig.h

If you did everything right, the project source tree should look something like this:

     

At this point the code won’t compile however, as some macros still need to be enabled. Add TEXTDISPLAY_FONT_8x8=1 and INCLUDE_TEXTDISPLAY_SUPPORT=1 to your Symbols under the Project properties. These two defines will let our project know that we have a screen in our design which supports text display, and we need the font size to be 8x8 pixel big.

     

Also, there’re two macros still undefined (as they are not defined for this board in the retargettextdisplayconfig.h). Modify your copy of this header file, so it’s base content will look like below. If your retargeted text display configuration file has these lines, you're good to go.

/* Display number to retarget stdout to. */
#define RETARGETTEXTDISPLAY_DISPLAY_NO   (0)

// ADDED MANUALLY
#define RETARGETTEXTDISPLAY_SCROLL_MODE (0)
#define RETARGETTEXTDISPLAY_LINE_FEED_MODE (0)

With this modification the project should compile and you should have all the necessary drivers included in it. There’s only one setting left to change and we can start writing the main functionality. We will use printf to write lines of data to the LCD which data will also contain floating point numbers (temperature, humidity). To be able to do that, make sure “Printf float” is enabled under the General Linker settings.

    

Driver initialization

RAIL and radio setup

As our initial design is already set up for transmit and receive, all the necessary RAIL configuration is done. However, as it is recommended in the RAIL tutorial: Calibrations, in this example the calibrations are also enabled. The other modification to the RAIL setup is handling the RAIL_EVENT_TX_COMPLETION event. This event combines all transmit related events – even the errors –, therefore this way we have a better opportunity to handle them. In the example code provided, all RAIL and radio related calls are grouped together into the radioInit() function provided by the original RAIL TRX example.

Initializing the LCD

With the drivers set up, we can retarget the printf function to the screen on the starter kit. This way we have an easy and convenient way to write lines of text on the screen, without having an in-depth knowledge of the graphics drivers. To initialize and retarget the screen, we need the following few lines:

// Initialize the display module
DISPLAY_Init();
// Retarget stdio to a text display
if (RETARGET_TextDisplayInit() != TEXTDISPLAY_EMSTATUS_OK) {
    while (1)
        ;
}

You can find out more of the graphical driver and using the LCD screen in the emlcd and textdisplay MCU examples for the EFM32PG kit.

Setting up the sensor

The sensor uses I²C to send the measured data. To use the sensor, we will need to initialize the I²C peripheral and enable the sensor itself through its enable pin. The I²C driver has a predefined structure for use with the sensor and the configuration files of our board should contain all the necessary locations for the data and enable pins. Do the following to setup the sensor:

// i2c init
I2CSPM_Init_TypeDef i2cInit = I2CSPM_INIT_SENSOR;
I2CSPM_Init(&i2cInit);
// Enable Si7021 sensor isolation switch
GPIO_PinModeSet(BSP_I2CSENSOR_ENABLE_PORT, BSP_I2CSENSOR_ENABLE_PIN, gpioModePushPull, 1);

Please refer to the humitemp and inttemp MCU examples for the EFM32PG kit to learn more about using the sensor. 

GPIO Callback for the buttons

The callback is already written in the Simple TRX example, the only thing we will have to do is to modify it a little. The functionality we should have is to toggle the RX and TX whenever a button is pressed.

RAIL Callback

As it was discussed in the RAIL tutorials, the way of using the RAIL is through the event handler. We can configure all kind of events and catch them in the main callback function of the RAIL. The calibration event was enabled earlier, the callback function should be modified accordingly as well. It’s not the only thing we need to modify here however. Since the simple TRX example doesn’t need the packet it receives, as default it just drops it. We would like to keep the packet and hold it for future use by calling RAIL_HoldRxPacket() after RX completion. We also would like to write a confirmation message on the screen if the packet was sent successfully and set a packet pending flag false after – any kind of – transmit completion. This flag will be necessary to monitor the scheduled (delayed) transmit and its completion.

void RAILCb_Generic(RAIL_Handle_t railHandle, RAIL_Events_t events) {
    (void) railHandle;
    if (events & RAIL_EVENT_CAL_NEEDED) {
        // Calibrate if necessary
        RAIL_Calibrate(railHandle, NULL, RAIL_CAL_ALL_PENDING);
    }
    if (events & RAIL_EVENTS_RX_COMPLETION) {
        // Toggle RX LED and hold the packet if something was received
        BSP_LedToggle(LED_RX);
        packetRx = true;
        if ((events & RAIL_EVENT_RX_PACKET_RECEIVED)
                && packetHandle == RAIL_RX_PACKET_HANDLE_INVALID) {
            packetHandle = RAIL_HoldRxPacket(railHandle);
        }
    }
    if (events & RAIL_EVENT_TX_PACKET_SENT) {
        // Toggle TX LED and print sent message on successful packet sent event
        BSP_LedToggle(LED_TX);
    }
    if (events & RAIL_EVENTS_TX_COMPLETION) {
        // Clear the pending flag if TX is complete (even if it was a failure)
        txPacketPending = false;
    }
}

Handling transmit and receive in the main loop

Inits are done, Callbacks were written, it’s time to create the main functionality of the example!

Processing the received packet

In the main endless loop, the first thing we should do is to check if any packet was received. The easiest way to do that is to check the RAIL_RX_PACKET_HANDLE_INVALID flag. If it’s valid, there’s a packet in the FIFO. All we should do is to copy this packet, process its contents and write them on the screen. After this, we should release the packet making space for the next one.

// If anything was received, process the data and push it to the screen
if (packetHandle != RAIL_RX_PACKET_HANDLE_INVALID) {
    RAIL_RxPacketInfo_t packetInfo;
    RAIL_GetRxPacketInfo(railHandle, packetHandle, &packetInfo);
    RAIL_CopyRxPacket(receiveUnion.raw, &packetInfo);
    // Copy the held packet using its packet info
    RAIL_ReleaseRxPacket(railHandle, packetHandle);
    // Release the packet once it was copied
    packetHandle = RAIL_RX_PACKET_HANDLE_INVALID;
    printf("\f\n\n\n Msg. received!\n\n\n");
    printf(" Msg. nr.: %lu", receiveUnion.data.messageNr);
    printf("\n\n\n Temp: %.3f C", receiveUnion.data.temperature);
    printf("\n\n Hum:  %.3f P", receiveUnion.data.humidity);
}

Transmit mode

In transmit mode a new packet is being scheduled and sent. The temperature and humidity data can be read through the Si7013_MeasureRHAndTemp function. A division by thousand is necessary to get the actual values. After combining the packet to send, we should set the FIFO up and start the scheduled transmit. The delay in general is recommended to give the LCD time to refresh. A 0.5 - 1 second delay also helps the readability of the display. This is the point where we should also set the txPacketPending flag – if scheduling the transmit didn't result in an error –, as we wouldn’t want to send another packet while the previous one is pending, nor do we want to start receiving until the last transfer is not complete. At this point the application waits until the packet is pending, and only after the transmit is complete it writes "Message sent" on the screen along with the appropriate message number.

if (packetTx) {
    uint32_t tempHum;
    int32_t tempTemp;
    Si7013_MeasureRHAndTemp(i2cInit.port, SI7021_ADDR, &tempHum, &tempTemp);
    sendUnion.data.humidity = (float) tempHum / 1000;
    // We get the humidity in millipercent
    sendUnion.data.temperature = (float) tempTemp / 1000;
    // We get the temperature in millicelsius
    sendUnion.data.messageNr++;
    RAIL_Idle(railHandle, RAIL_IDLE, true);
    uint16_t dataLength = sizeof(sendUnion.raw);
    RAIL_SetTxFifo(railHandle, &sendUnion.raw[0], dataLength, dataLength);
    if (RAIL_StartScheduledTx(railHandle, channel, RAIL_TX_OPTIONS_DEFAULT,
    &scheduleTxConfig, NULL) == RAIL_STATUS_NO_ERROR) {
        // Start a scheduled (delayed) transmit with the custom parameters set before
        txPacketPending = true;
        // Mark the packet to be pending with this flag if there were no errors
    } else {
        printf("\f\n\n\n Send ERROR!\n\n\n");
    }
    // Wait until the packet is sent
    while (txPacketPending) {
        ;
    }
    printf("\f\n\n\n Msg. sent!\n\n\n");
    printf(" Msg. nr.: %lu", sendUnion.data.messageNr);
}

Receive mode

The receive part of the main while loop will be perfect for our project as it was written for the simple TRX, no modification is needed here.

Conclusion

This tutorial showed how to integrate drivers usually not included in RAIL example applications. However there are plenty examples available for the EFM32 controllers, it's not always straightforward which steps are required to use the available peripherals when you are working with an EFR SoC . We saw how simply we can modify a working RAIL example to send and also display something variable and useful, by showing the appropriate hardware configuration, the necessary files and initializations, and the functions to utilize the peripherals.

API introduced in this tutorial

Functions

• RETARGET_TextDisplayInit()
• RAILCb_Generic()
• RAIL_HoldRxPacket()
• RAIL_GetRxPacketInfo()
• RAIL_CopyRxPacket()
• RAIL_ReleaseRxPacket()
• Si7013_Detect()
• Si7013_MeasureRHAndTemp()
• RAIL_Idle()
• RAIL_SetTxFifo()
• RAIL_StartScheduledTx()