Hi Venkateswaran,

CURR_RSSI can be read when the radio is in RX state (otherwise it is 0). LATCH_RSSI latched on SYNC_DETECT and it is available until the radio switch back to RX state (after a complete or incomplete packet reception), or in other words, it is cleared (set to 0) whenever the device enters RX state.

It might be that the si4455_get_modem_status() API is called by the host MCU too late (when the radio isn't in RX state), depending on how much does it take the SYNC_DETECT to be asserted and handled, and how long packets are received.

However, it is peculiar that
- the signal strength seems to be higher on the device placed further away,
- the issue is appears consistently when the latched RSSI <= 55,
- the measured RSSI changes a lot.

Did you move the sensors, or change the transmit power of them during the measurement?
Did the sensors measuring each other's RSSI? In this case, what does the distance mean?

Best Regards,
Bence

Hi Tony,

I apologize that I forgot to reply on this thread such a long time, I hope I can still give you some guidance.

We published a RAIL Tutorial article, which details RAIL timebase as well as how the timestamps can be obtained on both received and transmitted packets. Also, please disregard my previous advice: It is not good to get timestamp on the RAIL_EVENT_TX_STARTED (or on any other *_EVENT) with RAIL_GetTime() (though I didn't indicated it directly in your code, therefore I just want it emphasize as the referred article does: "save the value of a timer at PACKET_SENT/SYNC1_DETECT or PACKET_RECEIVED, it's not recommended"). Use instead the RAIL_GetTxTimePreambleStartAlt() API (after calling the RAIL_GetTxPacketDetailsAlt2()) or the corresponding APIs for RX: RAIL_GetRxTimePreambleStart/SyncWordEnd/FrameEndAlt() APIs with the RAIL_GetRxPacketDetailsAlt(). 

Also, the referred article covers RAIL's multitimer feature. It uses the same timebase therefore it has the same precision as the simple RAIL timer.

If you haven't encountered with it, I encourage you to visit the Interrupt and thread safety in RAIL article. It discusses, for what should you pay attention implementing interrupt safe code with RAIL APIs. 

Best Regards,
Bence

Hi dh2718,

The transmitted or the received packet's payload length specified by START_TX.TX_LEN or START_RX.RX_LEN respectively. If these fields are 0, the payload's length will be configured according to the radio configuration (generated by the WDS). See the API documentation.

I think the last word of Problem 2 was left for some reason, and I don't completely understand this problem.

Best Regards,
Bence

Hi Graziano,

Does the device return with valid reply to a PART_INFO command right after properly resetting the chip (before issuing POWER_UP command)? However, PART_INFO should work without clock, it ensures that the SPI connection between the host and the radio is correct.

Do you have custom design or a development kit? If it is a custom design, please make sure, that you're crystal is compliant with AN785: Crystal selection guide, and there is oscillation on the crystal's pin.

If the problem occurs only after the initialization, please check whether the arguments of the POWER_UP commands are correct (particularly the FUNC and PATCH bitfields). For more details see the API documentation.

Best Regards,
Bence
 

Hi Rome,

We have an article, which covers systematic basic test methods, if you encounter reception errors. You might try out the debug procedures suggested by the article.

1. -
2. Regarding on what value should be passed as START_TX.TX_LEN for the transmitter, please see either the API documentations or the example application: if you set it to 0, the radio will send out the packet with as many payload bytes as it is configured by the radio configuration. Also, see the referred sources in regards on how to handle CRC's length with variable length config: if you want the length field to include CRC bytes you can config it via the PKT_LEN_ADJUST.LEN_ADJUST field.
3. I'm not sure I understand this point.
4. I think, it is easier not to use SPLIT config.

Do not abort an ongoing packet transmission. Instead of forcing state switch to READY with the CHANGE_STATE command, query the device state REQUEST_DEVICE_STATE until it returns with READY.

Best Regards,
Bence

Marco,

Though, what you described, it's like an LDC scenario, but it lacks the advantages of this feature:
- the radio controlled via the MCU, instead of it works on its own - you shouldn't wake up the MCU on to schedule state transition on the radio;
- with such a long sleep state you will get very high packet loss - the LDC is just for that purpose you want to achieve: you should keep the radio active only for short time period (mainly depending on the bitrate) to detect a preamble, and if it isn't detected, it will go back to SLEEP state automatically (the duration of the SLEEP state depends on the transmitted side).

It is described in the referred article, how to configure the receiver (as well as the transmitter) to get minimal packet loss. Also, see AN632: WDS USER ’S GUIDE FOR EZRADIOPRO® DEVICES on how to create an LDC example application and the radio's datasheet (section 8.2) for further information.

Best Regards,
Bence

Hi Marco,

You need first distinguish between the radio's operation states and the MCU's energy states, as the two parts of the device can be in any state independently. Therefore, it is possible to keep the device in RX state, while the MCU is in EM2, but meanwhile the radio will consume huge current. Even the radio can wake-up the MCU part by an interrupt generated on packet reception, so you wouldn't need a periodic wake-up to check whether the radio received any packet.

Instead of keeping the receiver in constant RX state, you might implement LDC (Low duty cycle) in your application, if you have EZRadioPRO inside of your device (this is the case, if you have an EZR32HG320F64R68G). Please, consider this feature, and let us know, if you need more information/you have any concern regarding it.

Also, please clarify, what do you mean by "the device is in radio sleep mode for 30 seconds". Did you mean EM2 mode of the MCU, or the SLEEP state of the radio part?

Best Regards,
Bence

Hi David,

I moved your question to 32-bit MCU Forum.

Best Regards,
Bence

This tutorial builds on the following tutorials:

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

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

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

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

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

Advanced packet mode features

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

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

Differences in FIFO mode

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

Enabling FIFO mode

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

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

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

Using FIFO mode: transmit

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

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

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

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

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

Using FIFO mode: receive

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

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

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

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

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

Special data sources

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

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

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

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

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

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

Direct mode

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

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

API introduced in this tutorial

Functions

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

Types and enums

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

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.

Note that this tutorial is slightly outdated in Studio v5, since the we now have components, not plugins, and the way we initialize RAIL in the examples are performed by the RAIL Utility, Initialization component, and not by the application. However, these are minor details and the wast majority of this article is accurate.

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.

The event RAIL_EVENT_SCHEDULER_STATUS is also used when a higher priority task interrupts an ongoing radio operation, in which case, RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED will be returned by RAIL_GetSchedulerStatus().

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.