1. Clarify to yourself what the specific issue is.

2. Apply basic troubleshooting:

• Check hardware connections with multimeter.
• Use logic analyzers/oscilloscopes.
• Use Simplicity Studio Debugger/Energy Profiler/Network Analyzer/WDS, use logging prints.

3. Consult the datasheets and reference manuals. Sources include:

• Simplicity Studio Launcher Documentation Tab
• Silicon Labs Technical Resource Search
• Proprietary knowledge base

4. Search to see if someone has asked the same question already.

5. If you use custom hardware, try to reproduce the issue on a Silicon Labs kit

6. If you have a big firmware project, try to reproduce the issue on one of the Silicon Labs examples with minimal modification

7. If you have a radio configuration problem, try to reproduce it with RAILTest or WDS

8. Include the relevant parts of your development setup in the problem description. Examples include:

• SDK version (WDS version for transceivers)
• Clarify whether you use Connect or RAIL on EFR32
• Part number, revision number
• Radio board vs custom hardware

9. Include steps to reproduce the problem or specific conditions the problem occurs in.

10. Be patient and avoid making duplicates of your question.

For general community usage please refer to the Silicon Labs Community Guidelines.

Question

Where can I find the AN691: EZRadio API Guide application note?

Answer

AN691 is obsolete for a long time and not available on silabs.com.

API documentation is provided in html format and can be found at

EZRadio API Rev B1A

or at

EZRadio API REVC2A

Pick the one that matches your chip revision.

1. Introduction

The EZRadioPro Si4x6x family consists of high-performance transceivers covering the sub-GHz frequency bands, while the EFR32 product family provides high-performance SOCs that combine an energy-friendly MCU with a highly integrated radio transceiver that covers sub-GHz frequency bands and the 2.4GHz frequency band.

This document provides some assistance for migrating from the EZRadioPro family to the EFR32 chip family. The main differences in firmware development (such as initialization, transmit, rx start and packet downloading) between the two chip families are described here. It is highly recommended that the customer read the corresponding data sheets, reference manual, and application notes when converting a design from the EZRadioPro family to the EFR32 family.

 

2. General Differences between EZRadioPro and EFR32

Radio usage and control differs between EZRadioPro and EFR32 due to their different chip architectures.

The EZRadioPro is a transceiver. It provides a SPI interface for the host MCU to control the operations of the chip by sending commands to (or getting responses from) the radio chip. The commands and properties that control the chip are defined in API documents, and the application FW (firmware) runs on the host MCU.

The EFR32 family uses RAIL (Radio Abstraction Interface Layer).  As a SOC device, the integrated radio component can be treated as a peripheral of the chip. In order to simplify access to the radio hardware, Silabs provides an interface layer (RAIL) for developers. The developer can simply treat RAIL as a library which provides the APIs to access the radio hardware of the chip.

The table below shows the main differences between EZRadioPro and EFR32 usage.

	EZRadioPro	EFR32
Example Chip	Si446x	EFR32FG
Chip Architecture	Transceiver	SOC
Frequency Bands	Sub-G	Sub-G, 2.4G, or Sub-G plus 2.4G bands
Development Tool	WDS	Simplicity Studio
Radio Configuration Generation	radio_config.h (from WDS)	rail_config.h/c (from the radio configurator in Simplicity Studio)
Radio Operation Interface	Command/property via SPI with Host	RAIL
Application	Host MCU application	Application on top of RAIL inside SOC
Event Handling	Interrupt plus pending bit	Callbacks plus events
FIFO	TX FIFO (64 Bytes) RX FIFO (64 Bytes) Shared FIFO (129 Bytes)	TX FIFO (defined by application) RX FIFO (512 Bytes by default)
Payload field	Maximum 5 payload fields	One payload field
Downloading Rx data	Read data via SPI command by Host	Read Rx data from RX FIFO

In Sections 3~6, the differences in initialization, transmission and reception are described.

 

3. Difference in Initialization

For chip initialization, both EZRadioPro and EFR32 need register/API values. They use different radio configurator tools to generate register settings based on the radio/modem /packet information input by the developer. EZRadioPro uses the WDS radio configurator, while EFR32 uses the radio configurator within Simplicity Studio (presented as a component within AppBuilder, the tool that configures a project’s  .isc file). For further information on radio configurator usage, please refer to AN692 (for EZRadioPro) or AN971 (for EFR32).

If the developer wants the packet to be correctly received, configurations in both the transmitter and receiver sides should match, including: RF parameters (frequency, data rate, channel, etc.), structure of the packet (preamble, sync words, header, crc, etc.), symbol coding, etc. Regarding the structure of the packet, there is an obvious difference in that one EZRadioPro packet can contain a maximum of 5 packet fields (and every field can be configured individually), but for EFR32 one packet always contains just one payload field.

Here we describe the differences of initialization between EZRadioPro and EFR32 using the example projects “Bidirectional Packet” and “Simple_rail_with_hal”, which can be separately generated from WDS and Simplicity Studio (respectively).

EZRadioPro:

In the EZRadioPro chip, commands should be sent to the chip via SPI. The developer can refer to the sample projects provided in WDS, like Bidirectional Packet project.  This example will be used in this section to show the differences between EZRadioPro family and EFR32 family.

The following is the pseudo code snippet to show the initialization steps. The developer invokes these functions in the host MCU project to send commands to or get responses from the radio chip via SPI.

vRadio_PowerUp ();
si446x_configuration_init (pRadioConfiguration->Radio_ConfigurationArray);
si446x_get_int_status (0u, 0u, 0u);

Step 1: Invoke vRadio_Init() to reset the chip by toggling SDN from high to low. Refer to the following article: Si4x6x-C2A, Si4x55-C2A startup sequence

Step 2: Send the chip register/API setting values to the chip in si446x_configuration_init() function via SPI. The radio/modem/packet/PA setting is generated by WDS and stored in radio_config.h header file.

Step 3: Invoke the function si446x_get_int_status(0u, 0u, 0u) at the end of the initialization function to clear pending interrupts with GET_INT_STATUS command. Please note that this function should be called to clear the pending interrupt after interrupt happens or before entering sleep mode.

Chapter 8 of AN633 describes more details about the initialization for EZRadioPro.

EFR32:

he developer can directly invoke APIs to implement the initialization for EFR32. The following is the pseudo code snippet to show the initialization steps for EFR32:

halInit ();
railHandle = RAIL_Init (&railCfg, NULL);
RAIL_ConfigCal (railHandle, RAIL_CAL_ALL);
RAIL_ConfigChannels (railHandle, channelConfigs[0], NULL);
RAIL_ConfigTxPower (railHandle, &txPowerConfig); 
RAIL_SetTxPower (railHandle, HAL_PA_POWER);

Step 1: Invoke halInit() to initialize system clock and the peripherals that the project uses.

Step 2: Invoke RAIL_Init() to initialize the RAIL. The parameter railCfg of this function includes a callback, where the events of RAIL should be handled in the application layer of the project, such as RAIL_EVENT_TX_PACKET_SENT, RAIL_EVENT_RX_PACKET_RECEIVED, etc.  This function will return a handle which will be used when invoking other RAIL APIs.

Step3: The developer should also initialize RAIL calibration with RAIL_ConfigCal(). Calibration initialization provides the calibration settings that correspond to the current radio configuration.

Step 4: Before performing any radio operations, invoke RAIL_ConfigChannels() to set a valid channel for radio. It will also configure the relevant radio registers with the input parameters. The parameters related to the channels come from rail_config.h, which is generated by the radio configurator in Simplicity Studio. Simplicity Studio provides an easy way (GUI) for developers to configure the parameters and generate the PHY setting of the channel.

Step 5: The developer should invoke the RAIL_ConfigTxPower() and RAIL_SetTxPower() to set the PA mode and Tx power. Note that the second parameter of the RAIL_SetTxPower() is PA power level. The actual Tx power corresponding to the power level can be found with the method described in AN1127.  Also refer to the PA conversions plugin in radio configurator (or PA of the hardware configurator defined in .hwconf) of Simplicity Studio. 

The following article provides more details about initialization: RAIL Tutorial 1: Introduction and Initialization

 

4. Difference in Transmit

Here we describe the differences of transmit between EZRadioPro and EFR32, using the example projects “Bidirectional Packet” and “Simple_trx_with_fifo”.

EZRadioPro:

The chip contains one Tx FIFO (64 Bytes) and one Rx FIFO (64 Bytes). This size cannot be changed (note that for EFR32, the application defines Tx FIFO size), but the chip can be instead configured to have a unified 129 Bytes FIFO shared by both Tx and Rx operation (Refer to API document about property  GLOBAL_CONFIG :

FIFO_MODE).

The following pseudo code snippet shows how to start transmitting and how to handle the tx events. The developer invokes these functions in the host MCU project to send commands to or get responses from the radio chip via SPI.

//write fifo and start tx   
 si446x_change_state (SI446X_CMD_CHANGE_STATE_ARG_NEXT_STATE1_NEW_STATE_ENUM_READY);
si446x_get_int_status (0u, 0u, 0u);
si446x_fifo_info (SI446X_CMD_FIFO_INFO_ARG_FIFO_TX_BIT);
si446x_write_tx_fifo (length, pioRadioPacket);
si446x_start_tx (channel, 0x80, length);
//check and handle tx events
si446x_get_int_status (0u, 0u, 0u);
if (Si446xCmd.GET_INT_STATUS.PH_PEND & SI446X_CMD_GET_INT_STATUS_REP_PH_PEND_PACKET_SENT_PEND_BIT){…}
if (Si446xCmd.GET_INT_STATUS.PH_PEND & SI446X_CMD_GET_INT_STATUS_REP_PH_PEND_TX_FIFO_ALMOST_EMPTY_PEND_BIT){…}

Step 1: Send data to Tx FIFO. Before starting transmitting, the developer should send the packet payload to the Tx FIFO of the radio chip via SPI. If the payload length is greater than the size of the Tx FIFO, the developer can use the TX_FIFO_ALMOST_EMPTY interrupt to send the payload to the Tx FIFO in several segments.  As with the EFR32, the developer should set a threshold value for the Tx FIFO threshold property PKT_TX_THRESHOLD.  An interrupt is generated when the amount of empty space in the Tx FIFO is equal to or greater than this threshold. When event TX_FIFO_ALMOST_EMPTY_PEND (Refer to API document about command GET_INT_STATUS: PH_PEND:  TX_FIFO_ALMOST_EMPTY_PEND) happens, the application should send more payload bytes to Tx FIFO.

It is suggested that before transmitting starts, the application should reset the chip FIFO with si446x_fifo_info() and clear the previous pending interrupt with si446x_get_int_status (0u, 0u, 0u).

Step 2: Use si446x_start_tx() to startup transmitting. Note that if the parameter TX_LEN of this command is non-zero, the packet will be transmitted with TX_LEN number of data bytes with the definition in the packet field 1 (PKT_FIELD_1_X) configuration options (e.g., CRC, data whitening, Manchester coding, etc.). If TX_LEN is zero, the chip will transmit the data according to the configuration of the packet fields properties PKT_FIELD_X_X (Refer to API document about command START_TX).

Step 3: Check and handle the events. The host MCU application should check the status if an event happens.

The interrupt event (TX_FIFO_ALMOST_EMPTY or PACKET_SENT) is defined in the radio_config.h and enabled in WDS based on the customer selection.

If the relevant interrupts are enabled and one or more enabled interrupts happen, nIRQ pin will be put low. The host MCU application should use si446x_get_int_status() to get status of the chip (Refer to API document about command GET_INT_STATUS) and check which interrupt happened and handle it accordingly.

Settings about state transition. The radio chip can automatically change state after completion of a packet transmission. To achieve this purpose, a desired state defined in TXCOMPLETE_STATE should be passed with the command START_TX (Refer to API document about command START_TX).

EFR32:

The following pseudo code snippet shows the transmit steps for EFR32 (config the events, set/write Tx FIFO, start tx, and events handling):

RAIL_ConfigEvents (railHandle,
                    RAIL_EVENTS_ALL,
                    (RAIL_EVENT_TX_PACKET_SENT
                     | RAIL_EVENT_TX_UNDERFLOW
                     | RAIL_EVENT_TX_FIFO_ALMOST_EMPTY));
RAIL_SetTxFifo (railHandle, txFifo, 0, TX_FIFO_SIZE);
RAIL_SetTxFifoThreshold (railHandle, TX_FIFO_THRESHOLD);
RAIL_WriteTxFifo (railHandle, txPtr, packetLength, true);
RAIL_StartTx (railHandle, channel, RAIL_TX_OPTIONS_DEFAULT, NULL);

if (events & RAIL_EVENT_TX_PACKET_SENT) {…}
if (events & RAIL_EVENT_TX_UNDERFLOW) {…}
if (events & RAIL_EVENT_TX_FIFO_ALMOST_EMPTY) {…}

 Step 1: To transmit a packet, application FW should first set a buffer as the RAIL Tx FIFO. Note that it can only handle Tx buffer sizes of a power of 2 between 64 and 4096.   The pointer of the buffer is passed to RAIL as a parameter of RAIL_SetTxFifo() .  Before calling this function, initialize the buffer with the transmitted payload data so that the transmitted payload data can be passed to Tx FIFO with this function. Another method to pass the transmitted payload data to Tx FIFO is to invoke RAIL_WriteTxFifo() after setting the Tx FIFO (with RAIL_SetTxFifo()). 

Step 2: RAIL_StartTx() should be invoked to send out the packet data in Tx FIFO. When invoking this function, the developer should specify the channel on which the radio will transmit the packet. Some options can be set for the transmission of the packet, such as waiting for ACK, needing CCA etc.

Step 3: Upon finishing transmitting a packet, event RAIL_EVENT_TX_PACKET_SENT will happen. If the length of the packet is greater than the size of Tx FIFO, another event RAIL_EVENT_TX_FIFO_ALMOST_EMPTY is useful (see the description of the event in RAIL API document). While handling this event, we can write more packet data to Tx FIFO – even though the transmit process is still on going. The developer should set a threshold value for the event RAIL_EVENT_TX_FIFO_ALMOST_EMPTY using RAIL_SetTxFifoThreshold().

The developer should configure these events during initialization with RAIL_ConfigEvents(). Note that the process of event handling is in interrupt context, so they should be handled as fast as possible.

For more details see article: RAIL Tutorial 3: Event Handling

Setting up state transitions after transmitting. After transmitting (either successfully or not), what is the next state of the radio? RAIL provides a way to configure automatic state transitions.  To use this function, the developer should use RAIL_SetTxTransitions() to set the automatic states (RX or IDLE)  before transmitting (see the RAIL API document). Of course, the developer can also manually change the radio states using RAIL_Idle() and RAIL_StartRx().

The following article tells more about transmit on EFR32: RAIL Tutorial 2: Transmitting a Packet

 

5. Difference in Rx Start

Here we describe the differences of rx start between EZRadioPro and EFR32 using the example projects “Bidirectional Packet”  and “Simple_trx_with_fifo”.

EZRadioPro:

The following pseudo code snippet shows how to start Rx and how to handle the Rx events. The developer invokes these functions in the host MCU project to send commands to or get responses from the radio chip via SPI.

//start Rx
si446x_get_int_status (0u, 0u, 0u);
si446x_fifo_info (SI446X_CMD_FIFO_INFO_ARG_FIFO_RX_BIT);
si446x_start_rx (channel, 0u, packetLength,                  SI446X_CMD_START_RX_ARG_NEXT_STATE1_RXTIMEOUT_STATE_ENUM_NOCHANGE,
                  SI446X_CMD_START_RX_ARG_NEXT_STATE2_RXVALID_STATE_ENUM_READY,
                  SI446X_CMD_START_RX_ARG_NEXT_STATE3_RXINVALID_STATE_ENUM_RX );

//Rx interrupt handling
si446x_get_int_status (0u, 0u, 0u);
if (Si446xCmd.GET_INT_STATUS.PH_PEND 
         & SI446X_CMD_GET_INT_STATUS_REP_PH_PEND_PACKET_RX_PEND_BIT) {}
if (Si446xCmd.GET_INT_STATUS.PH_PEND 
         & SI446X_CMD_GET_INT_STATUS_REP_PH_PEND_RX_FIFO_ALMOST_FULL_PEND_BIT) {}
if (Si446xCmd.GET_INT_STATUS.PH_PEND
        & SI446X_CMD_GET_INT_STATUS_REP_PH_STATUS_CRC_ERROR_BIT) {}

 As mentioned in the previous chapter, the chip has two FIFOs: Tx FIFO (64 Bytes) and Rx FIFO (64 Bytes). They can be combined into one FIFO (129 Bytes) as a shared FIFO for both Tx and Rx (Refer to API document about property GLOBAL_CONFIG:FIFO_MODE ). Note that developers should make sure that the data in the shared FIFO will not be lost when the state changes between Tx and Rx. 

Step 1: Use si446x_start_rx() to start Rx. Three next states may be passed with this command to make the radio chip automatically enter to a desired state upon timeout of preamble detection, reception of a valid packet or reception of an invalid packet.

The packet can include maximum of 5 fields. Note that if the parameter length argument of this command is non-zero, the radio chip will receive and decode the packet based on the definition in the packet field 1 (PKT_FIELD_1_X) configuration options (e.g., CRC, data whitening, Manchester coding, etc.). If length is zero, the chip will receive the packet according to the configuration of the packet fields properties PKT_FIELD_X_X (Refer to API document about command START_RX).

Step 2: Handle the Rx events. During reception, the host MCU should check the status of the radio chip by si446x_get_int_status (0u, 0u, 0u). If the relevant interrupts are previously enabled and the interrupt happens, the nIRQ pin will put low to inform the host MCU that events have happened. If a whole packet is received, interrupt PACKET_RX_PEND (Refer to API document about command GET_INT_STATUS : PH_PEND:  PACKET_RX_PEND ) will happen. The host MCU can use command READ_RX_FIFO to read the received data from Rx FIFO. If the size of the whole packet is greater than that of Rx FIFO, the event RX_FIFO_ALMOST_FULL_PEND is useful. When this event happens, the host MCU should immediately read the received data bytes from the Rx FIFO to avoid overflow. The threshold should be set in property PKT_RX_THRESHLOD .

It is suggested that before Rx start, the developer should reset the chip FIFO with si446x_fifo_info() and clear the previous pending interrupt with si446x_get_int_status (0u, 0u, 0u).

EFR32:

The following pseudo code snippet shows the starting Rx steps for EFR32 (config the events, start rx and events handling):

RAIL_ConfigEvents (railHandle,
                    RAIL_EVENTS_ALL,
                    (RAIL_EVENT_RX_PACKET_RECEIVED
			   | RAIL_EVENT_RX_FIFO_OVERFLOW
                     | RAIL_EVENT_RX_FIFO_ALMOST_FULL
                     | RAIL_EVENT_RX_SYNC1_DETECT));

RAIL_SetRxFifoThreshold (railHandle, RX_FIFO_THRESHOLD); 
RAIL_StartRx (railHandle, channel, NULL);

if (events & RAIL_EVENT_RX_SYNC1_DETECT) {…}
if (events & RAIL_EVENT_RX_PACKET_RECEIVED) {…}
if (events & RAIL_EVENT_RX_FIFO_ALMOST_FULL) {…}
if (events & RAIL_EVENT_RX_FIFO_OVERFLOW) {…}

Step 1: The developer invokes RAIL_StartRx() to start Rx. The channel number should be passed with this function, so the radio component is able to correctly receive and decode the packet.

Step 2: Handle events. If an event happens, the event can be handled in the callback.  Of course, the developer needs to have previously configured the Rx events.  

By default, the size of the Rx FIFO is 512 bytes (max value), so if the size of a packet is greater than that, developer should handle the event RAIL_EVENT_RX_FIFO_ALMOST_FULL and read the received data bytes from Rx FIFO to avoid overflow. The developer should set a threshold value using RAIL_SetRxFifoThreshold().

When the chip receives a whole packet, event RAIL_EVENT_RX_PACKET_RECEIVED will be generated. The developer should handle these events as soon as possible. For more on this topic, see the article: RAIL Tutorial 3: Event Handling

Setting up the state transitions. Similar to Tx, after receiving (either successfully or not), the radio can transition to a predefined state (RX/IDLE) automatically. The next state can be set using function RAIL_SetRxTransitions(). Of course, the developer can also manually change the radio state using RAIL_Idle() and RAIL_StartRx().

 

6. Downloading the Packet

Here we describe the differences about downloading the packet between EZRadioPro and EFR32 using the example projects “Bidirectional Packet” and “Simple_trx_with_fifo”.

EZRadioPro:

The following pseudo code snippet shows how to download the packet from the Rx FIFO. The developer invokes these functions in the host MCU project to send commands to or get responses from radio chip via SPI.

si446x_fifo_info (0x00); 
si446x_read_rx_fifo (Si446xCmd.FIFO_INFO.RX_FIFO_COUNT, &customRadioPacket[0]);
si446x_get_int_status (0u, 0u, 0u);
if ( Si446xCmd.GET_INT_STATUS.PH_PEND 
      & SI446X_CMD_GET_INT_STATUS_REP_PH_PEND_RX_FIFO_ALMOST_FULL_PEND_BIT) {…}
If ( Si446xCmd.GET_INT_STATUS.PH_PEND 
      & SI446X_CMD_GET_INT_STATUS_REP_PH_PEND_PACKET_RX_PEND_BIT) {…}

When RX_FIFO_ALMOST_FULL_PEND or PACKET_RX_PEND event happened, the application can use command si446x_read_rx_fifo() to get the received data from radio chip. Before that, use si446x_fifo_info() to get the length of the received packet in Rx FIFO.

For event RX_FIFO_ALMOST_FULL_PEND.  the developer should set threshold in property  PKT_RX_THRESHOLD.

EFR32:

The following pseudo code snippet shows how to download the packet from the Rx FIFO.

RAIL_GetRxFifoBytesAvailable (railHandle);
RAIL_ReadRxFifo (railHandle, rxPtr, bytesAvailable);

When the amount of the received data bytes in Rx FIFO is equal to or greater than the threshold, event RAIL_EVENT_RX_FIFO_ALMOST_FULL will happen. At this moment, the application can use RAIL_ReadRxFifo() to read the received data. Before reading, the application should get the packet length of the received packet in Rx FIFO with RAIL_GetRxFifoBytesAvailable().

When a whole packet is received, event RAIL_EVENT_RX_PACKET_RECEIVED will happen, the application can read out the data from RX FIFO by RAIL_ReadRxFifo(). The application can also obtain more detailed information about the packet with RAIL_GetRxPacketDetails().

The following article gives more details about downloading the packet: RAIL Tutorial 4: Combining Transmit and Receive.

Introduction

If a Connect device node wants to know whether a coordinator (or extender) available in range it can issue the active scan command. All coordinators in range will reply with beacon to the request which are on the same channel (with corresponding PHY settings), regardless of its PAN ID. Based on the received information the device node can decide to try to join the required coordinator.

Steps of the active scan process

First, the device has to issue the active scan command:

EmberStatus emberStartActiveScan(int channelToScan)

The application informed about result(s) through the callback

void emberAfIncomingBeaconExtendedCallback(EmberPanId panId,
                                           EmberMacAddress *source,
                                           int8_t rssi,
                                           bool permitJoining,
                                           uint8_t beaconFieldsLength,
                                           uint8_t *beaconFields,
                                           uint8_t beaconPayloadLength,
                                           uint8_t *beaconPayload)

Implementing the callback is the responsibility of the application. The callback fired multiple times subsequently if the device receives replies from multiple coordinators.

There is a callback to inform the application that the scanning is finished (which also need to be implemented by the application):

void emberAfActiveScanCompleteCallback(void)

Activating the necessary callbacks

Callbacks can be enabled in Appbuilder by selecting the Callbacks tab:

Adding active scan to the CLI

The easiest way to try out how active scan works is to create a Sensor / Sink example project pair (available in the SDK) and add the active scan command and the related code to the Sensor part of the example.

Add active scan to the CLI command array

Implement the CLI command

The active scan API call has only one parameter, the channel to scan.

void startActiveScanCommand(void)
{
  EmberStatus status;
  uint8_t channelToScan = emberUnsignedCommandArgument(0);
  status = emberStartActiveScan(channelToScan);

  if (status != EMBER_SUCCESS) {
    emberAfCorePrintln("Start active scanning failed, status=0x%x", status);
  } else {
    emberAfCorePrintln("Start active scanning: channel %d",
                       channelToScan);
  }
}

Implement the callbacks

Enable the necessary callbacks as described above. The enabled callbacks must be implemented:

void emberAfActiveScanCompleteCallback(void)
{
  emberAfCorePrintln("Active scan complete");
}

void emberAfIncomingBeaconExtendedCallback(EmberPanId panId,
                                           EmberMacAddress *source,
                                           int8_t rssi,
                                           bool permitJoining,
                                           uint8_t beaconFieldsLength,
                                           uint8_t *beaconFields,
                                           uint8_t beaconPayloadLength,
                                           uint8_t *beaconPayload)
{
  int cnt;
  emberAfCorePrintln("Active scan: PAN ID: 0x%2x", panId);
  emberAfCorePrint("Active scan: source MAC address: ");
  for(cnt = 0; cnt < 8; cnt++) {
      emberAfCorePrint("%x", source[cnt]);
  }
  emberAfCorePrintln("");
  emberAfCorePrintln("Active scan: RSSI: %d", rssi);
  emberAfCorePrintln("Active scan: join is %spermitted", permitJoining ? "" : "not ");
  emberAfCorePrintln("Active scan: beacon fields length: %d", beaconFieldsLength);
  emberAfCorePrint("Active scan: beacon fieds: ");
  for(cnt = 0; cnt < beaconFieldsLength; cnt++) {
      emberAfCorePrint("%x ", beaconFields[cnt]);
  }
  emberAfCorePrintln("");
  emberAfCorePrintln("Active scan: beacon payload length: %d", beaconPayloadLength);
  emberAfCorePrint("Active scan: beacon payload: ");
  for(cnt = 0; cnt < beaconPayloadLength; cnt++) {
      emberAfCorePrint("%c", beaconPayload[cnt]);
  }
  emberAfCorePrintln("");
}

Usage

After applying the above and clicking on Generate in AppBuilder build and download the project to the hardware (don't forget to generate and build the Sink project as well and download to one another board). Code snippets above can be placed into flex-callbacks.c.

Open the serial terminal for both device.

On the coordinator (Sink) issue the following commands:

form 0
pjoin 255

This will form a Connect network on channel 0. The command pjoin 255 allows devices to join to the coordinator, while pjoin 0 disables joining.

On the device node (Sensor) issue the following command:

start-active-scan 0

It should scan the channel and print out the info comes from available coordinator(s), like

Active scan: PAN ID: 0x01FF
Active scan: source MAC address: 0000A80027000100
Active scan: RSSI: -21
Active scan: join is permitted
Active scan: beacon fields length: 4
Active scan: beacon fieds: FF 6F 00 00 
Active scan: beacon payload length: 0
Active scan: beacon payload:
Active scan complete

Content

• Introduction and motivation
• Theory
• Implementation
• Further references

Introduction and motivation

Channel scanning is a receiver side feature. Scanning usually means that a receiver switches its center frequency regularly to be able receiving packets in more frequency bands.

Most of the protocols Silicon Labs RF Software stacks support (BLE, Zigbee, Wi-Fi, Connect) use channel scanning, therefore it is important to get to know more about this topic. The usefulness of this feature is shown through the wide variety of applications, but in this article we will focus only on one type presenting the design steps and showing up several implementation tradeoffs.

First it need to be cleared, what channel does mean in context of Channel scanning. Channel is a medium between the transmitter and receiver side, characterized with physical layer parameters (carrier frequency, modulation type, bitrate, etc.). Mostly two channel differ in center frequency in a concrete protocol. This article will focus on these cases.

We should say some words about the transmitter's side. There may be more transmitter in the same network, all working on its own frequency channel or one which switches between channels (call it as Channel hopping) reducing the chance of interference with other transmitters. Channel hopping implies that one particular channel will be used less than if every packet would be sent on the same channel. Hopping may coexist with LBT and CSMA features also, further decreasing the chance of interference.

Channel hopping and so the scanning can be done either in synchronous way - as FHSS (Frequency Hopping Spread Spectrum) does - or in asynchronous way. Here the synchrony means prior experience at the receiver side. The topic of this article is the asynchronous scanning, when we only known what frequency bands are used by the transmitter(s), but nothing about the time frames, when the channel will be occupied. Our example will show how a Channel scanner can be designed to get every packet.

There is a strong relation between LDC and asynchronous Channel scanning, particularly in the sense of realization. Both has the main concept of detecting empty channel as fast as possible at the receiver side. The purpose of LDC is energy saving in a sparse network, while the purpose of the Channel scanning is rather the better frequency allocation in a dense network, so channel scanning infer a more active receiver with no sleep state.

Design steps for asynchronous Channel scanning

The goal of this section is to show how to build an asynchronous channel scanning application from the beginning assuming ideal transmitter side. We should first define (or get from the standard) the channels with their center frequency. Take care of the false detection on the image frequencies.

In a Channel scanning application the task may not only be to detect the presence of a transmitter but the detection of the lack of any packet in the channel, aiding to switch channel more quickly, raising the chance to capturing a packet (and reducing both sides' power consumption). If it is desired to receive every packet on every channel, some timing consideration should be taken into account.

Since the receiver don't have prior experience about the transmitter, the application should be created with a presumption that every channel will be used with the same chance. In general the receiver scans over a hop table, which tells in what order are the channels scanned.

Receiver's timing considerations

There are several ways to trigger a channel-switching at the receiver side. These triggers can be used together as backup mechanisms as well, to avoid false detection. This is an incomplete list of the possible trigger events:

1. RSSI timeout:
   • can be useful, when packet loss is permissible, and the goal is to detect only the presence of the transmitter,
   • cannot distinguish between desired and undesired signals.
2. Preamble detection timeout:
   • may trigger on invalid preamble pattern as well,
   • the length of the timeout period may depend on AFC (Automatic Frequency Control).
3. Sync word invalid timeout:
   • triggers when invalid or no sync word detected after the preamble,
   • typical use case, if a protocol define similar preamble but different syncwords,
   • it is the longest but most secure option to detect a desired signal.
4. Timing detection timeout:
   • Very similar to Preamble detection timeout,
   • typically it detects absence faster than preamble detection, but causes sensitivity degradation.
5. Digital signal arrival (DSA) detection:
   • usually used for fast absence detection,
   • the fastest, so the most energy efficient option.

Not all features described above are available for every Silicon Labs radios, see the relevant documentation for the possibilities!

In this article we target to use Preamble detection timeout as trigger event. Let's suppose that the transmitter is optimal. This means it transmits long enough packets (most part of the packet is the preamble) on every channel to ensure reception. To quantify this timing requirement the following variables need to introduce:

• T_ri: the receiver's transition time from channel i to the next, (from the end of the RX state to the start of the following one)
• T_detecti: preamble detection timeout (the time of the clear channel detection in this particular case) for the receiver on the i'th channel,
• N: number of channels.

T_ri and T_detecti can be determined empirically and theoretically, respectively.

The former may differ depending on what are the differences between the two channels and how the channel switching functionality is implemented. Therefore it should be measured after defining the hop table.

The latter is described more depth in the LDC KBA at the preamble detection threshold section. The less the configured detection time, the worse the sensitivity, and the accuracy of the detection, but the lower the necessary transmit time as well.

The turnaround time (T_ta), which shows how often will the receiver listen in the same channel, can be calculated by summing T_ri and T_detecti values for all channels.

Transmitter's configuration

In a typical channel scanning application the transmitter transmits relatively long preambles. To ensure detection at the receiver side, the preamble should be on the air at least for one turnaround time. This is true for every channel.

Knowing the data rate at channel i (DR_i, [bit/s]) the preamble length (L_preami, [bit]) can be calculated as follows:

L_preami = T_ta * DR_i.

Summary of design steps

1. Select the number of channels (N) and place them:
   • with the number of channels the RX turnaround time scales linearly,
   • take care of image frequencies.
2. Determine hopping and detection times,
   • from measurements and datasheets.
3. Calculate the minimal transmitted preamble length (in bits) to ensure detection for each channel:
   • the minimal time is the receiver's turnaround time.

Implementation

The channel transition time at the receiver may vary with the implementation: how much time the radio module needs to get the setting parameters (from the host) for channel switching and set those up.

EZRadioPRO

EZRadioPRO supports channel scanning without host MCU control. The RX_HOP property group has a 64 entry RX hop table for predefining channels. Each of the entries hold a channel number corresponding to the channel offset (channel number * channel spacing) from the base frequency, so the channels are placed next to each other by distance of channel spacing. Enabling this "automatic RX Hop" feature the host MCU can switch to sleep state, while the receiver scans all those channels and wakes-up the MCU only when an incoming packet detected (or received).

Other kind of implementation called as "Manual frequency Hopping" is also available on EZRadioPRO devices. The RX_HOP command sets a new listening frequency (usually issued in RX state). With this command channel hop is faster but it needs permanently awake host MCU for scanning.

There are two examples ("Auto frequency hop RX" and "Manual frequency hop RX") among the WDS example projects implementing Auto and Manual hopping applications. We recommend using WDS to generate radio configuration for a manual as well as an automatic RX Channel scanner application, due to the property setting's complexity.

EFR32

The current hopping application example (RAIL Simple TRX MultiPHY) implements frequency hopping with RAIL_Timer and RAIL_StartRx(). It had been developed exactly the same manner as we described above, but its channel configuration has a subGHz and a 2.4 GHz channel with different data rates.

Flex SDK supports also Automatic RX-side channel hopping with APIs RAIL_ConfigRxChannelHopping()and RAIL_EnableRxChannelHopping(). These API's cannot be called when the radio is on. We have an article on how to use those APIs and how to configure the RAIL_RxChannelHoppingConfig_t structure. Note that RX Channel Hopping APIs work on EFR32xG12 and newer parts, but not supported with multiprotocol.

The RAIL API supports to define unlimited number of channels (limited only by the available RAM), and one channel can be defined multiple times, even with different scan times. What's more, RAIL supports more flexible channel definition, so not only the frequency but other Physical layer settings can be defined per channel. After configuring hopping parameters calling RAIL_StartRx() starts on the first channel. There is no need to call other API, the radio automatically hops over the predefined channels. If a packet is received, the radio returns to the idle state (or to the state defined in the auto state transition configuration).

Further References:

• Article series of EZRadioPRO channel scanning feature,
  • Guidance and detailed example to avoid sensing on IF frequency
  • Preamble detection threshold values
  • Trigger scenarios
• RAIL API docs RX Channel Hopping section
• Si446x Datasheet (subsection 5.3.1.1)
• AN633 Programming guide for EZRadioPRO devices (section 10.13 and 10.14)
• RAIL Channel hopping KBA
• Image frequency consideration

Introduction

The connect stack internally accounts several types of events, like number of transmitted / received packets, number of successful / unsuccessful ACKs, transmission retries, etc.

These counters can be advantageous for application debugging / profiling, hence Connect makes them accessible by the applications.

Retrieving the values of the counters

To get access to the counters the Stack Packet Counters plugin must be enabled in AppBuilder (Plugins tab, Connect Debug section):

Stack counters enabled by default.

To retrieve the counter values use the emberGetCounter() API function:

EmberStatus status = emberGetCounter(counterType, &counter);

In variable counterType the stack counter type is passed, which is an EmberCounterType enum and declared in ember-types.h where the meaning of the counter types are explained.

The counter value returns in counter as a uint32_t number.

The API function return value can indicate success or indicating fail as the type is invalid (no such counter) or library not present (can happen if Stack Packet Counters Stub).

Example

The provided Connect example projects contains query of counters from CLI using the counter command:

Where 1 is EMBER_COUNTER_PHY_OUT_PACKETS.

Notes

Library not present is the result of enabling Stack Packet Counters Stub instead of Stack Packet Counters which makes sense to reduce the stack footprint).

Counter types EMBER_COUNTER_UART* and EMBER_ASH_V3* are related to NCP, these values are always remain zero for SoC applications.

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.

The BT factor on the Gaussian pulse shaping filter is often used for narrowing spectral emissions at the Tx side to fit into a regulatory / applications standard mask requirement. On how to adjust the BT factor on the EZRadioPro familiy you can read here.

Note that adjusting the BT factor will only alter the spectrum emission of the modulated signal, it will not affect discrete spurious emissions that are not part of the modulation, like these.

Adjusting the BT factor, however does have an effect on sensitivity at the Rx side. This is quite often overlooked and may result in a huge loss in the link budget. To that end find below two graphs showing sensitivity versus BT factor parameterized with modulation index. (These measurements were taken on revision revB1B but hold up for revC2A/ A2A.)

Key takeaway:

Don’t ever go to a lower BT factor than 0.25 if the modulation index <= 2. If narrower emissions are required lower the modulation index instead.

Also be prepared that the frequency offset tolerance of the Rx degrades by dropping BT and / or the modulation index.

 

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)