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)

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. However, it might be worth using Dynamic Multiprotocol even if you don't need the RAIL scheduler, just for the code clarity it provides by the separation of stacks.

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

Content

• What LDC means, where and why to use it
• LDC theory:
  • Timing and considerations
  • General use cases
• Implementation on EZRadioPRO and EFR32 radios

Introduction and motivation

Low Duty Cycle (LDC, sometimes just Duty Cycle) by definition means switching something periodically on and off. However, in the context of low power radios, we usually use it for receive mode only: In this case, the radio is switching between a low power, long duration sleep state and short active states, wherein the radio is in receive state looking for valid preamble. In this way the radio is able to save huge amount of power.

Furthermore this operation is automatic, means no MCU intervention is needed for scheduling receive intervals, saving more energy. Typically an interrupt line or events are used to indicate a valid packet's arrival.

Synchronous and asynchronous duty cycling

Duty cycling radio protocols can be sorted into asynchronous or synchronous protocols. Asynchronous means that the receiver don't know when the transmitter would send a packet, while in synchronous mode, as its name implies, there is temporal synchronization between the two connected parts, the messages will be sent at a specified time.

Some widely used protocols use LDC (e.g. Bluetooth low energy) in synchronized networks. By spending energy and time for synchronization, the receiver can receive all the packets while it is in sleep state most of the time.

However, in some cases, the overhead required by the synchronization doesn't worth it, e.g. if you need to receive messages from a transmitter that rarely sends anything. In such cases, you probably want to use asynchronous duty cycling on the receiver, but in such cases the transmitter cannot predict when the receiver is listening. The goal of this KBA is to solve this problem, and explain how asynchronous LDC works.

In this KBA the theoretical configuration of LDC will be presented illustrated with application examples (general use cases), and at last some implementation notes will be showed for both EZRadioPRO and EFR32 devices.

Theory of LDC

The main idea behind the LDC is to move the power consumption of RX to the TX side. Though in LDC mode the both side are strongly dependent to each other focus on the RX side first and assume an optimal transmitter.

RX side considerations - Preamble detection period

To minimize the receiver's side average power consumption, the time spent in active state should be minimized. What's the minimum time to keep the receiver on? When and how could the receiver detect an incoming message? What is this event? There are more options for the receiver to detect an incoming message, but we concentrate only to the preamble detection case.

In preamble detection duty cycle mode the radio periodically wakes up for short duration to look for a preamble. When a valid preamble is detected, the radio remains in receive state until the packet is fully received (or an error detected during reception).

Note that the original goal of the preamble is to achieve bit synchronization of the incoming signal (or to restore the clock signal in other words). Therefore, the preamble should be always at least as long as it needs to be to reliably achieve this task. Most radio's datasheets (Si4460/1/3/4 p. 28.) recommends selecting preamble length and preamble detection threshold (aka. preamble detection period), which is a minimal value to achieve 0% PER.

Define the following receiver time terms:

• Tpdp: preamble detection period,
• Tron: receiver's active state time (it will be longer, than the preamble detection period due to packet reception),
• Tsleep: receiver's sleep state time,

and ignore other timing constraints, like wake-up time, radio state transition time, etc.

From this point assume optimal RX, and focus on the TX side.

TX side consideration - application examples - LDC in asynchronous networks

There is tradeoff between the RX side's and the TX side's power consumption: longer sleep period infer longer transmission time (see the examples section).

There is two widely used scenario to ensure package reception on the receiver side in asynchronous networks, one called as "Duty-cycle" mode, and the other is the "Master-slave" or "Master blast" mode.

Duty-cycle mode

This mode requires a packet with a very long preamble at the transmitter side. For the simplest example assume the active time (Tron) and the sleep period (Tsleep) are given. In this case the transmitter should have at least

Tpream = 2 * Tron + Tsleep

long preamble to make sure all packets will be received, independent of the receiver state when the transmission started. The rest of the packet is transmitted in Trest time.

In the worst case scenario, the transmitter starts transmitting slightly after the receiver wakes up, and does not provide long enough preamble for detection (Tpdp) in this wake-on period, continues the transmission during the receiver is in sleep state (Tsleep), and for the next active period (Tpdp+Trest), where the receiver finally detects and receives the packet. This is shown in the picture below.

 

Compared to the case when the receiver is always in receive state, Duty-cycle mode saves approximately the duty-cycle proportion of power on the receiver side.

(Unsynchronized) Master-slave mode

The master term refers to the transmitter and the slave term to the receiver(s).

This mode has a very similar idea, but instead of one packet with long preamble it uses transmit burst with short packets back to back, which transmit time, Tburst, should fit to Tpream determined in the Duty-cycle mode (the preamble length is much shorter in this mode but it has to fit to Tpdp time at least, and we will call it Tpream). Usually the rest of the packet (syncword, header, payload, CRC, etc.) is for Trest time in the air.

 

The slave must be in active state at least 2 * Tpream + Trest = Tron long, which is higher than in the Duty-cycle mode for ensuring packet reception for every case.

Comparison of applications

The downside of Duty-cycle mode is comes up when the radio wakes on the beginning of the preamble. This implies a long active period due to the waiting for the whole packet. On the other hand, with Master-slave mode the receiver only needs to be active for as long as it receives a single, short packet. The downside of Master-slave mode is that the receiver must be in active state as long as the longest possible packet is, otherwise it could miss the preamble of the packet.

Therefore the selection of application strongly depends on the protocol, or rather we should say that the used protocol should define the LDC application mode.

Possible improvements in Master-slave mode

With Master-slave mode, it is possible to improve the performance and energy consumption. For example, the transmitter could check for an ACK after each transmit. If the transmission was acknowledged, the transmitter can stop. The drawback with this is that this only works with a single receiver, and the active period of the receiver should be extended to include the time the transmitter spends to wait for an ACK.

Another method to improve Master-slave mode is to use a specific "wake-up" message, and not the actual data. This wake-up message only tells the receiver when the actual data will be transmitted and the receiver can wake-up again for that. This worsens the power consumption on both receiver and transmitter side, but the data length doesn't affect the active time on the slave any more.

Note about preamble detection selection

Low detection threshold may led to misdetection and sensitivity loss, but halting the receiver longer in active state increase energy consumption.

Therefore the threshold should be good enough to achieve the required packet error rate. Note that the data rate may also impact on the threshold selection.

Implementation on EZRadioPRO

EZRadioPro devices have a low frequency (32 KHz) clock system, called as WUT (Wake-Up Timer). It can be operated from an external or an internal clock source (see in the API documentation (GLOBAL_CLK_CFG register, CLK_32_SEL bit fields). The radio uses this clock during sleep state for generating wake-up signal (the WUT activity distinguishes between sleep and standby states), thereby WUT supports LDC mode (and Low Battery Detection as well) by hardware.

Registers with GLOBAL_WUT prefix related to this timer. Both the sleep period and the active period (documentation calls it LDC period) should be set with a mantissa (WUT_M and WUT_LDC bitfields) and a common exponent (WUT_R bitfields). The active period may be less than configured LDC period, when a packet arrived before its expiration (as shown in the second picture). We signed LDC period as Tron and sleep period as Tsleep.

Next to the periods the preamble detection threshold should be configured. It determines the number of valid preamble bits the radio must receive to qualify a valid preamble. A shorter Preamble Detection Threshold may be chosen if occasional false detections can be tolerated.  This threshold can be set through the PREAMBLE_CONFIG_STD_1 register's RX_THRESHOLD bitfields, and all the other preamble related setting is located in the 0x10 Group of the registers.

After issuing a START_RX command the radio's high frequency crystal should be started up, and the PLL requires some calibration time (see AN585 p.1.). This should be take into consideration to set the periods correctly (this start-up time should be subtracted from the sleep period).

Further documentation:

• LDC EZRadioPRO can be found in the AN585, which describes Master-slave mode more in depth.
• How does preamble detection threshold work.
• Detection of the absence of a signal.
• How to set TX preamble length and preamble detection period, for a frequency hopping application, but it can still used for an LDC application as well.

Implementation on EFR32

EFR32 devices have LDC (although this feature called as Duty Cycle mode) implemented as part of Channel Hopping feature. The theory is similar to that, which was described for EZRadioPRO devices, but here is a more simplest implementation, only two relevant APIs should to know:

• RAIL_ConfigRxDutyCycle(): configures the mode and timing for the Duty Cycle operation.
• RAIL_EnableRxDutyCycle(): enables radio's receiver (RAIL_StartRX() or RAIL_ScheduleRx() API should be called after this).
• RAIL_EVENT_RX_DUTY_CYCLE_RX_END: event triggered after a complete active-sleep period, where RAIL_StartRX() or RAIL_ScheduleRx() should be called again.

For a complete documentation visit the API documentation.

Note that the APIs do not put the MCU itself into sleep state. However, RAIL_Sleep() will allow deep sleep while the radio is not active. To enable RAIL timers in EM2 sleep, timer synchronization must be also enabled. For more details, see tutorial on timer synchronization and sleep.

Notes:

• The RAIL_ConfigRxDutyCycle() and the RAIL_EnableRxDutyCycle() APIs are not supported on the EFR32XG1 family of chips, and in multiprotocol applications.
• The RAIL_ConfigRxDutyCycle() and the RAIL_EnableRxDutyCycle() APIs must not be called while the radio is on.
• There is a Duty Cycle example in the Flex SDK, but it does not use the APIs above.

Introduction

There are cases when the communication between devices can happen on multiple channels and the actual channel is not known prior the communication. In these cases, the receiver usually tries to find the transmitter's channel by listening on all possible channels for a short time to catch the transmitter's signal - in most of the cases it searches for valid preamble.

In RAIL it is possible to manually set the required channel, listen and wait for valid preamble then depending on the received signal continues to receive the whole packet or reconfigure the receiver to the next channel and repeat this procedure until receiving a valid packet.

However, manually configuring the receiver to all channels and starting the receiving then checking for valid packet makes the code needlessly difficult and additionally it is inefficient.

RAIL provides a hardware accelerated method to achieve the channel scanning in a very simple and efficient way. This method is called RX channel hopping.

Note: This feature is not supported on the EFR32XG1 family of chips and currently not supported in multiprotocol.

Configuring and enabling RX channel hopping

There are two API function to support channel hopping:

• RAIL_ConfigRxChannelHopping()
• RAIL_EnableRxChannelHopping()

Configuring channel hopping

As its name suggests RAIL_ConfigRxChannelHopping() is responsible to configure the hardware to the required operation mode. Beside a RAIL handle, it takes one input which is a RAIL_RxChannelHoppingConfig_t structure. It contains a buffer for channel hopping information, number of channels which is in channel hopping sequence and most importantly the entries of channels (RAIL_RxChannelHoppingConfigEntry_t) contains the parameters of the specified channels.

The channel hopping information buffer (must be allocated by the application) and size can be defined as follows:

#define CHANNEL_HOPPING_NUMBER_OF_CHANNELS 10
#define SIZEOF_UINT32_DELTA_SUBTRACT 4
#define SIZEOF_UINT32_DELTA_ADD 4

#define CHANNEL_HOPPING_BUFFER_SIZE (                                                   \
  3 +                                                                                   \
  RAIL_CHANNEL_HOPPING_BUFFER_SIZE_PER_CHANNEL * CHANNEL_HOPPING_NUMBER_OF_CHANNELS +   \
  2 * SIZEOF_UINT32_DELTA_SUBTRACT +                                                    \
  2 * SIZEOF_UINT32_DELTA_ADD * CHANNEL_HOPPING_NUMBER_OF_CHANNELS                       \
)

RAIL_RxChannelHoppingConfigEntry_t channelHoppingEntries[CHANNEL_HOPPING_NUMBER_OF_CHANNELS];
uint32_t channelHoppingBuffer[CHANNEL_HOPPING_BUFFER_SIZE];

The channel hopping configuration must be prepared as well

RAIL_RxChannelHoppingConfig_t channelHoppingConfig = {
  .buffer = channelHoppingBuffer,
  .bufferLength = CHANNEL_HOPPING_BUFFER_SIZE,
  .numberOfChannels = CHANNEL_HOPPING_NUMBER_OF_CHANNELS,
  .entries = channelHoppingEntries
  };

The individual channel parameters must be defined in the channel hopping entries, each entry contains parameters for one channel. The channel hopping will happened in the order of entry elements, so the channel order can be arbitrary - it is even possible to add a channel multiple times in the sequence however in this case multiple entry is necessary for that channel.

The parameters of a channel must be placed into RAIL_RxChannelHoppingConfigEntry_t structures. Although these parameters can be different for each entries, for simplicity reasons this example uses same parameters for all channels.

for(int channel = 0; channel < CHANNEL_HOPPING_NUMBER_OF_CHANNELS; channel++) {
  channelHoppingEntries[channel].channel = channel;
  channelHoppingEntries[channel].mode = RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE;
  channelHoppingEntries[channel].parameter = 100;
  channelHoppingEntries[channel].delay = 0;
  channelHoppingEntries[channel].delayMode = RAIL_RX_CHANNEL_HOPPING_DELAY_MODE_STATIC;
  }

The entry structure has a .parameter member and the meaning of this member depends on the .mode setting - in the current case it means microseconds and determines how long the hardware will listen on the current channel before hops to the next one. This value depends on the PHY settings may need to finetune experimentally. For different settings see the RAIL API documentation.

If the configuration is complete simply call

RAIL_ConfigRxChannelHopping(railHandle, &channelHoppingConfig);

Enabling channel hopping

To enable RX channel hopping call

RAIL_EnableRxChannelHopping(railHandle, true, true);

The second parameter enables channel hopping while the third one specify whether hopping should be reset to start from the channel at index zero, or continue from the channel last hopped to.

Note: The radio should not be on when this API is called.

Starting receiving

If the radio is configured as shown above, there is only one step remaining, to start the reception.

It can be done by calling

RAIL_StartRx(railHandle, 0, NULL);

The radio will continuously remain in RX mode and run the hopping sequence until a packet received. If a packet is received the radio returns to idle state.

This behavior can be modified by setting auto state transition (see RAIL API documentation for details about auto state transition feature).

Channel hopping complete event

Sometimes it is advantageous to know when the hopping sequence finished. RAIL provide an event for this purpose: RAIL_EVENT_RX_CHANNEL_HOPPING_COMPLETE if this event is enabled, the RAILCb_Generic() will be fired every time the hopping sequence completed.

Receiving this event does not mean that channel hopping is stopped, it only signals that one round of the sequence is finished and it will be continued with the next round.

The TX side

To successfully receive a packet by the receiver side it is necessary to choose a preamble length on the transmitter side which long enough for the receiver to complete at least one whole sequence. So, if the receiver needs 10ms to complete on sequence of scanning the transmitter's preamble length must be at least 10ms. As the preamble in the Radio Configurator is specified in symbols (bits) it is the customers responsibility to convert the preamble length from time to symbols.