RFSense is a low power feature of the EFR32 Wireless MCU family. It can "wake up" an MCU from its EM2 or even EM4 power modes. Practically, it is an ultra low power interrupt source, running on ULFRCO clock.

The RFSense is a wide band circuit, it can detect energy in the 100MHz - 5 GHz frequency range, filtered only by the matching network of the RF front end. This is an advantage, as no need for separate PCB components. But it’s also a drawback: it is sensitive to any kind of interferer signal as well.

EFR32xG22 has an updated RFSense module, which improves the performance compared to EFR32 Series 1 in multiple ways:

• RFSense works below 0C degree
• RFSense works if voltage is scaled down
• Introduces Selective mode

Legacy mode

In legacy mode, EFR32xG22 RFSense is fully compatible with the one in Series 1. This means that if the RFSense module detected energy for a configured time, it generates an interrupt.

Selective mode

Selective mode mitigates the unfiltered nature of RFSense. Instead of simply detecting energy for a given time period, it detects "a pattern of energy", which is essentially an OOK packet. The packet is Manchester coded, uses fixed 1kbps bitrate, 1B preamble and 1-4B sync word (no payload added). This packet can be transmitted by any OOK capable device, including all EFR32 wireless MCUs (Series 1 and Series 2).

Selective mode offers 2 configuration options to select from: "optimized for sensitivity" or "optimized for noisy environment".

The Wakeup Packet

The wakeup packet is a fixed-configuration OOK packet with the following settings:

• Starts with a 1 B preamble (always 0x55).
• Followed by a 1-4 B sync word.
• No payload required.
• Both the preamble and sync word are transmitted LSB first.
• 1 kbps bitrate (before coding).
• Recommended carrier is 2.45 GHz.

Selective Mode Transmit Example Without Using API

You can find an example application here, that demonstrates how to transmit wakeup packets without using the RAIL API, for improved range. It can be used on EFR32xG22 and EFR32xG28 devices.

Assume you select 0xb16e as your sync word, and you want to transmit it with only a signal generator (or a simple radio with MSB-first byte handling and no Manchester coder).

First, flip the endianness of both preamble and sync word: 0x55 becomes 0xaa and 0xb16e becomes 0x768d.

The full packet is then 0xaa768d, which after Manchester coding becomes 0x99996a6995a6.

Configuring this encoded packet and transmitting on 2.45 GHz with high enough TX power should wake up a device configured for selective RF Sense with the 0xb16e sync word

For more details on selective mode, see AN1244: EFR32 migration guide for Proprietary applications

Outdate notice

This article was written for Simplicity Studio 4 and GSDK 2, and kept public for those who still need information on it. For the current, recommended version of this article go to https://docs.silabs.com/rail/latest/rail-training-trx/.

This tutorial builds on the following tutorials:

• RAIL Tutorial 1: Introduction and init
• RAIL Tutorial 2: Transmitting a Packet
• RAIL Tutorial 3: Event Handling

Please read them first if you haven't.

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

In this tutorial, we're going to combine what we had from the previous tutorial. We're going to switch between transmit and receive, and we're going to use a few peripherals on the WSTK as a user interface.

Our goal is to transmit a predefined packet when either of the buttons are pressed, and print the packet to the serial console when received. We're also going to toggle LEDs on finished Rx/Tx, but we ignore errors.

You can find a SimpleTRX example in Simplicity Studio, which has similar purpose. However, the result of this tutorial will be somewhat different.

Preparations

We're going to start from the usual, the Simple RAIL with HAL example. However, we'll need some modifications in the Hardware Configurator because we'll need the UART bridge and buttons, which are not enabled by default. To do that, enable the following defaultMode peripheral modules:

• Virtual COM Port
• Button

Next, we'll have to include a few things to have these peripherals, and while some of the peripherals are automatically initialized, not all, so we're going to do that in a function:

#include "bsp.h"
#include "retargetserial.h"
#include "gpiointerrupt.h"
#include <stdio.h>

typedef struct ButtonArray{
  GPIO_Port_TypeDef   port;
  unsigned int        pin;
} ButtonArray_t;

static const ButtonArray_t buttonArray[BSP_BUTTON_COUNT] = BSP_BUTTON_INIT;

void gpioCallback(uint8_t pin);

void peripheralInit(){
  RETARGET_SerialCrLf(1); //converts \n to \r\n
  //set up button GPIOs to input with pullups
  for ( int i= 0; i < BSP_BUTTON_COUNT; i++){
    GPIO_PinModeSet(buttonArray[i].port, buttonArray[i].pin, gpioModeInputPull, 1);
  }
  //set up interrupt based callback function on falling edge
  GPIOINT_Init();
  GPIOINT_CallbackRegister(buttonArray[0].pin, gpioCallback);
  GPIOINT_CallbackRegister(buttonArray[1].pin, gpioCallback);
  GPIO_IntConfig(buttonArray[0].port, buttonArray[0].pin, false, true, true);
  GPIO_IntConfig(buttonArray[1].port, buttonArray[1].pin, false, true, true);
}

As you see, gpioCallback() will be called on button press.

Radio init

By default, after receiving or transmitting a packet, RAIL will switch to idle mode (i.e., turn off the radio). Since we want it to keep receiving future packets, we can use RAIL's auto state transition feature with the RAIL_SetRxTransitions and RAIL_SetTxTransitions APIs.

RAIL_StateTransitions_t transitions = {RAIL_RF_STATE_RX, RAIL_RF_STATE_RX};
RAIL_SetRxTransitions(railHandle, &transitions);
RAIL_SetTxTransitions(railHandle, &transitions);

RAIL_ConfigEvents(railHandle, RAIL_EVENTS_ALL, RAIL_EVENTS_TX_COMPLETION | RAIL_EVENTS_RX_COMPLETION | RAIL_EVENT_CAL_NEEDED);

We're basically saying, after the packets are received/transmitted, we want to return to Rx. We're also enabling some events as we've seen before. The only new one is RAIL_EVENT_CAL_NEEDED - it will have it's own tutorial; for now, it is important to know that it should always be implemented to have the maximum available performance.

Basic Rx and Tx Combined

#define PAYLOAD_LENGTH 16
#define BUFFER_LENGTH 64
static uint8_t payload[BUFFER_LENGTH] = {PAYLOAD_LENGTH-1, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f};
volatile bool startTx = false;

void gpioCallback(uint8_t pin){
  startTx = true;
}

int main(void)
{
  CHIP_Init();
  initRadio();
  peripheralInit();
  RAIL_StartRx(railHandle, 0, NULL);

  while (1){
    if ( startTx ){
      RAIL_SetTxFifo(railHandle, payload, PAYLOAD_LENGTH, BUFFER_LENGTH);
      if ( RAIL_StartTx(railHandle, 0, RAIL_TX_OPTIONS_DEFAULT, NULL) == RAIL_STATUS_NO_ERROR ){
        startTx = false;
      }
    }
  }
  return 0;
}

void RAILCb_Generic(RAIL_Handle_t railHandle, RAIL_Events_t events)
{
  if( events & RAIL_EVENT_CAL_NEEDED ){
    RAIL_Calibrate(railHandle, NULL, RAIL_CAL_ALL_PENDING);
  }
  if ( events & RAIL_EVENTS_TX_COMPLETION ){
    BSP_LedToggle(0);
  }
  if ( events & RAIL_EVENTS_RX_COMPLETION ){
    BSP_LedToggle(1);
  }
}

There's not much new here. We start by initializing everything then going to Rx mode. When a button is pressed startTx will be true, which will start transmitting a packet (changing from Rx to Tx mode). Note that the variable startTx is volatile, because it's changing in interrupt context. If you're unfamiliar with this practice, look it up; it's very important for low-level embedded applications.

In the event handler, we blink LEDs on Rx/Tx completion. In the CAL_NEEDED handler we're basically saying: If any calibration is needed, run it. Again, this is important to get the maximum available performance, but we won't go into details for now.

At this point, you should see LEDs blinking on both devices when you press a button on either of them. So at this point, we added a single concept: we return to Rx state both after receiving a packet, and after transmitting one. This enabled a combined Rx/Tx application. However, there's one important thing we didn't do so far: we did not download the received packet.

Downloading the Packet

Receive FIFO

We already configured Tx FIFO multiple ways. RAIL also implements an Rx FIFO. By default, it's 512B, allocated by the RAIL library. We will use that, but it is configurable. See RAILCb_SetupRxFifo() and RAIL_SetRxFifo() in the API documentation for details.

By default, you cannot use the whole 512B, as RAIL adds a few bytes to each packet to store timestamp, RSSI and similar information in the FIFO (sometimes we call this "appended info").

We're working on what we call packet mode. It's the simpler, and recommended way, but it's not possible to handle packets bigger than 512B with this method,; in which case FIFO mode should be used. We return to that topic in a later tutorial.

The Packet Handler

The FIFO is accessible with RAIL_RxPacketHandle_t variables or packet handles. Obviously, we don't have the handle of the packet we just received, but we have "sentinel" handles:

• RAIL_RX_PACKET_HANDLE_OLDEST
• RAIL_RX_PACKET_HANDLE_NEWEST
• RAIL_RX_PACKET_HANDLE_INVALID

The names are self-explanatory.

When to Read the FIFO

Let's say we want to download the packet when it's fully received (although it's possible to access it during reception). We must let RAIL know this in the event RAIL_EVENT_RX_PACKET_RECEIVED. If we don't, RAIL automatically frees the memory allocated to the packet we just received.

We have two options:

• Download the packet from the event handler
• Hold the packet in the FIFO and download later

While the first one is simpler, we also want to print the message on UART, which takes a long time, and that's not a good idea in interrupt context, so we'll use the second one.

To do that, let's create a volatile packetHandle, with invalid value:

volatile RAIL_RxPacketHandle_t packetHandle = RAIL_RX_PACKET_HANDLE_INVALID;
static uint8_t rxBuffer[BUFFER_LENGTH];

We should only write the handle if it's invalid, otherwise we might lose the handle to a locked packet (and essentially lose part of the receive buffer). We'll also need a buffer to copy the packet before printing it.

The Event Handler

Let's implement the event handler so it will only store packets if packetHandle is invalid:

if ( events & RAIL_EVENTS_RX_COMPLETION ){
  BSP_LedToggle(1);
  if ( (events & RAIL_EVENT_RX_PACKET_RECEIVED) &&  packetHandle == RAIL_RX_PACKET_HANDLE_INVALID ){
    packetHandle = RAIL_HoldRxPacket(railHandle);
  }
}

The API RAIL_HoldRxPacket will lock the packet we just received (or receiving) and return its handle.

Download and Print

In the while loop, if there's something in the handle, let's download and print it:

if ( packetHandle != RAIL_RX_PACKET_HANDLE_INVALID ){
  RAIL_RxPacketInfo_t packetInfo;
  RAIL_RxPacketDetails_t packetDetails;
  RAIL_GetRxPacketInfo(railHandle, packetHandle, &packetInfo);
  RAIL_CopyRxPacket(rxBuffer, &packetInfo);
  RAIL_GetRxPacketDetails(railHandle, packetHandle, &packetDetails);
  RAIL_ReleaseRxPacket(railHandle, packetHandle);
  packetHandle = RAIL_RX_PACKET_HANDLE_INVALID;

  printf("RX");
  for(int i=0; i < packetInfo.packetBytes; i++){
    printf(" 0x%02X", rxBuffer[i]);
  }
  printf("; RSSI=%d dBm\n", packetDetails.rssi);
}

Let's go through this, line by line:

First, RAIL_GetRxPacketInfo will return with packetInfo, which has the length of the received packet, and pointers to download it. Note that unlike transmit, this is independent of the length coding method (fixed or variable) we used in the Configurator.

Since the receive buffer is a ring buffer, the download will be always the same 3 lines of code, which is done in the RAIL_CopyRxPacket inline function.

The API RAIL_GetRxPacketDetails will return some useful information of the packet, such as RSSI.

Finally, we release the packet, and set the handle to invalid, so the event handle can write it.

Download in the Event Handle

Downloading the packet in the event handler is essentially the same as what we did in the main loop above:

if (events & RAIL_EVENT_RX_PACKET_RECEIVED) {
  RAIL_RxPacketInfo_t packetInfo;
  RAIL_GetRxPacketInfo(railHandle, RAIL_RX_PACKET_HANDLE_NEWEST, &packetInfo);
  RAIL_CopyRxPacket(rxBuffer, &packetInfo);
  RAIL_GetRxPacketDetails(railHandle, packetHandle, &packetDetails);
}

Note that packetDetails should be a global variable as well in this case.

Conclusion

With this, you can use RAIL for basic transmit and receive, which concludes the getting started series. However, RAIL can do much more - you can continue with the basic tutorials from the table of contents site.

API Introduced in this Tutorial

Functions

• RAIL_SetRxTransitions()
• RAIL_SetTxTransitions()
• RAILCb_SetupRxFifo()
• RAIL_SetRxFifo()
• RAIL_HoldRxPacket()
• RAIL_ReleaseRxPacket()
• RAIL_GetRxPacketInfo()
• RAIL_GetRxPacketDetails()
• RAIL_CopyRxPacket()

Types and enums

• RAIL_RxPacketHandle_t
• RAIL_RX_PACKET_HANDLE_OLDEST
• RAIL_RX_PACKET_HANDLE_NEWEST
• RAIL_RX_PACKET_HANDLE_INVALID

Outdate notice

This article was written for Simplicity Studio 4 and GSDK 2, and kept public for those who still need information on it. For the current, recommended version of this article go to https://docs.silabs.com/rail/latest/rail-training-tx/.

This tutorial builds on the following tutorial/s:

• RAIL Tutorial 1: Introduction and init

Please read them first if you haven't.

You can find other tutorials on the Table of Contents site.

In this tutorial, we’re going to modify the project Simple RAIL with HAL to transmit a packet. Let’s use the default, fixed length 16Byte payload configuration first (assuming you are familiar with using RAIL Test sample application in Flex SDK).

Buffer Handling

Setting Up the Packet Buffer

RAIL requires a buffer (usually called FIFO) to be configured for Tx (this is slightly different from RAIL 1.x, where the library initialized that buffer automatically). First, we have to allocate some memory for that buffer:

#define BUFFER_LENGTH 256
static uint8_t txBuffer[BUFFER_LENGTH];

Note that you can’t use any arbitrary size:; EFR32 creates a FIFO ring buffer on this memory area, and it can only handle buffer sizes of a power of 2 between 64 and 4096 (i.e., 64, 128, 256, 512, 1024, 2048, or 4096).

To load the payload of the packet to the buffer, we have two options: write it via RAIL APIs or write to the memory directly.

Writing to the Buffer Directly

#define PAYLOAD_LENGTH 16
#define BUFFER_LENGTH 256
static const uint8_t payload[PAYLOAD_LENGTH] = {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f};

static uint8_t txBuffer[BUFFER_LENGTH];

void loadPayloadDirectly(){
  memcpy(txBuffer, payload, PAYLOAD_LENGTH);
  RAIL_SetTxFifo(railHandle, txBuffer, PAYLOAD_LENGTH, BUFFER_LENGTH);
}

The memcpy is just a standard C instruction to write to buffers, and we use RAIL_SetTxFifo to pass that buffer to RAIL. We also tell RAIL how long the buffer is, and how much data it has already in it.

Writing to the Buffer Indirectly

#define PAYLOAD_LENGTH 16
#define BUFFER_LENGTH 256
static const uint8_t payload[PAYLOAD_LENGTH] = {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0F};

static uint8_t txBuffer[BUFFER_LENGTH];

void initRadio(){
  //...
  RAIL_SetTxFifo(railHandle, txBuffer, 0, BUFFER_LENGTH);
}

void loadPayloadIndirectly(){
  RAIL_WriteTxFifo(railHandle, payload, PAYLOAD_LENGTH, false); 
}

In this case, we pass the buffer to RAIL when it’s still empty, and we write to that buffer using a RAIL API. Note that using memcpy instead of WriteTxFifo would not work: while it would write the memory itself, it wouldn’t change the read and write pointers of the FIFO, handled by RAIL, so RAIL would still think the buffer is empty.

Direct or Indirect

There are two main factors that could decide which method to use to write the FIFO:

• With indirect mode, the buffer can be used for partial packets and simpler to use for multiple packets.
• Calling RAIL_SetTxFifo does not move any memory, just sets a few register, while calling RAIL_WriteTxFifo does need some time to copy the payload to the buffer.

So in most cases, RAIL_SetTxFifo is better and simpler. If you want to send the same packet over and over (or only change a few bytes in it), it’s much better, since you don’t have to write the whole packet again.

On the other hand, if you want to send longer packets than your buffer, you must use RAIL_WriteTxFifo. It’s also useful if you want to send out a lot of packets (e.g., a segmented message, or a single WriteTxFifo for each packet).

FIFO Reset

The last parameter of RAIL_WriteTxFifo can reset the FIFO, which means it will invalidate the data already in there. This is also possible with RAIL_ResetFifo. I would generally recommend not to use it, a well-written code shouldn’t need it (as it should only store in the FIFO what should be sent out), and it takes extra time.

Transmitting the packet

Starting the transmission is very simple:

RAIL_StartTx(railHandle, 0, RAIL_TX_OPTIONS_DEFAULT, NULL);

This instructs RAIL to start transmitting the data stored in the FIFO on channel 0 (second parameter). The third parameter can change various options, like using the second configured sync word (see RAIL API reference). The last parameter is only required for DMP (dynamic multiprotocol) mode.

Changing the Packet Length

You can change the configured fixed length on the Radio Configurator, but that’s obviously not possible at runtime, which is often needed. Note that the amount of data loaded into the FIFO does not matter as long as it’s equal to or greater than the length of the frame.

Changing Packet Length with a Fixed Length Configuration

With the API RAIL_SetFixedLength(), it’s possible to change the pre-configured length (stored in rail_config.c) at runtime. Note that this changes the length of the packets on the Rx side as well. If you want to return to the pre-configured value, you can use RAIL_SetFixedLength(railHandle, RAIL_SETFIXEDLENGTH_INVALID).

Using Variable Length Configurations

A lot of protocols store the length of the packet in the header of the frame. For example, in 802.15.4, the first byte stores the length (and the maximum is 127). To set this up, use the following settings in the Radio Configurator:

• Set Frame Length Algorithm to VARIABLE_LENGTH
• Enable the Header
• Set the length of the header to 1, and enable CRC over it
• Set variable length bit size to 8
• Set the maximum length to 127

For more information on this setup, and on more advanced variable length configs, see AN971.

With this setup, the radio will always be in variable length mode. This means that:

• During Rx, RAIL decodes the length field and set up the frame accordingly. Invalid length frames will be dropped
• During Tx, RAIL does the same
• RAIL_SetFixedLength() is not available

This means that during Tx, we have to make sure that the committed length in the header matches the amount of bytes you load into the FIFO. It also means that if we set the length field to more than 127, we will get a transmit error.
This would be a valid, 16B frame:

static const uint8_t payload[PAYLOAD_LENGTH] = {PAYLOAD_LENGTH-1, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0F};

We use PAYLOAD_LENGTH-1 in the length field since the 1B length field itself shouldn't be counted.

Conclusion

We didn't care about possible errors generated by RAIL: we do that next time, which also provides hints for receiving packets.

API Introduced in this Tutorial

Functions

• RAIL_SetTxFifo()
• RAIL_WriteTxFifo()
• RAIL_StartTx()
• RAIL_SetFixedLength()