This tutorial requires a basic understanding of Connect Direct Mode. See Connect Tutorial Series: Table of Contents for an overview of Connect basics.

To conduct the following exercises, you'll need two Wireless Starter Kit (WSTK) boards, each equipped with a (preferably identical) radio board. The example application relies on CLI through the WSTK VCOM (over USB) port to issue commands and display status information.

EFR32 Energy Mode 4

EM4 is the lowest possible energy consumption mode of EFR32 devices. Wake-up from EM4 is practically equivalent with wake-up from reset, thus all the initialization steps must be executed, including clock and peripheral configuration, no data retentions. However, this enables the device to reduce current consumption as low as a few tens of nanoamps.

A further limitation of EM4 is that only GPIO pin wake-up is available and only five hardwired pins capable of wake-up the device. These pins are:

• PA3
• PB13
• PC10
• PD14
• PF7 (connected to PB1 on the WSTK)

For more detailed information see the reference manual of the specific device

Connect and EM4

Although, Connect supports low power operation by enabling the Idle/Sleep plugin - it only supports EM2 (in this mode the minimum current consumption is about 2-4uA). To exploit EM4 capability the low power mode must be implemented at the application level using the energy mode support APIs. The drawback of using EM4 with Connect is that the whole initialization process must be executed on wake-up - which in case of Connect stack takes around 200ms until the application code can be executed which have to be considered when planning the application architecture.

The implemented example

The example setup requires two units (WSTK + radio board), one will be the "keyfob" which sends a message on pressing the PB1 button on the WSTK to the other unit, the "controller" which will receive the message and print it on the UART console. The controller is a simple Connect Direct Mode application explained in detail in the above mentioned Connect Tutorial Series. The keyfob implementation uses the same Connect feature set but it is extended with the minimal EM4 specific configuration and one API call to enter EM4 mode.

In this current example set the keyfob sends a single message (with the payload 0x00) to the controller which toggles LED0 on received message and prints the payload on the UART console then acknowledges the message. The keyfob enters to EM4 if the ACK was successfully received or there is no incoming ACK after the retransmissions of the message (the default is three retries). The keyfob enters EM4 immediately if the wake-up button was not sensed (for example if the reset caused by an interruption in the power supply).

Onboard SPI flash

Silabs radio boards are equipped with an external SPI flash memory which is powered from the same rail as the EFR32. This flash memory is not in low power mode after the supply voltage is applied and the current consumption in this mode is roughly 8-10uA - which is two magnitudes higher than the overall current consumption we expect. The onboard flash has a deep power-down mode in which mode its current consumption is negligible, however, it requires to enable the driver from Connect HAL and call the initialization and entering into low power mode commands. Thus the example enables the SPI flash plugin in AppBuilder and calls the following two API functions:

• halEepromInit()
• halEepromShutdown()

This is not necessary on custom hardware without this flash memory attached, so the two lines above should be commented out / deleted and the SPI flash plugin disabled.

EM4 prevents debugging/downloading firmware

The default path of the execution results in (almost) immediate entering to EM4 when the device starts. If the device is in sleep mode the debugger cannot connect to the chip. To avoid locking the debugging checking of PB0 state is implemented to keep the device running. If the device is already programmed and a new firmware should be uploaded, press and hold PB0 during pushing the reset button on the WSTK board. This part of the code is only added to facilitate the development and can be safely eliminated in further phases. If the device enters into sleep mode right after start-up it is possible to recover from that state in Simplicity Commander by applying 'Unlock debug access' - although this erases the whole flash memory of the device.

EM4 configuration and entering into EM4

The following snippet is the only necessary code to configure the device to enable EM4 mode:

  GPIO_PinModeSet(BUTTON_WAKEUP_PORT, BUTTON_WAKEUP_PIN, gpioModeInputPullFilter, 1);

  EMU_EM4Init_TypeDef em4init;
  em4init.em4State = emuEM4Shutoff;
  em4init.retainLfxo = false;
  em4init.retainLfrco = false;
  em4init.retainUlfrco = false;
  em4init.pinRetentionMode = emuPinRetentionEm4Exit;

  EMU_EM4Init(&em4init);

  GPIO_EM4EnablePinWakeup(GPIO_EXTILEVEL_EM4WU1, 0); // PF7

The first line configures PF7 (PB1) as input. EM4 init parameters are mostly straightforward, retention mode emuPinRetentionEm4Exit is set to reset pad state only after exiting EM4 mode. Finally, the last line enables wake-up on PF7 low level.

After the configuration is done, the application can enter EM4:

  GPIO_IntClear(GPIO_IntGet());
  EMU_EnterEM4S();

Before entering into EM4 it is advisable to clear pending GPIO interrupts.

The following screenshot shows a wake-up cycle

Current measurement

Measuring of current in nanoamps range is challenging, especially if it dynamically changes from several microamps to a few tens of nanoamps. Although, there is a current measurement capability of the WSTK and there is built-in Energy Profiler utility in Simplicity Studio, unfortunately, it is not precise enough to measure correct values in the low ranges. In the current example, the EM4 consumption measured by the WSTK was around a few hundreds of nanoamps. This is not only due to the precision of the current measurement but also because of several I/O lines of the chip connected to multiple lines/peripherals on the WSTK board itself.

Measuring the sleep mode current by precision current meter gives ~50-60nA which is close to the theoretically expected current consumption.

Conclusion

Exploiting of EM4 very low current consumption is reasonable when the device spends a long time in sleep mode which compensates the extra energy and time of wake-up from a reset-like state. These kinds of applications can be keyfobs for example where the devices wake-up only a few times a day and spend their lives in the lowest possible power mode most of the time.

Notes

If the devices were used with connect applications previously and the network was configured, the hardwired addresses / PAN ID will not be applied. In this case, a full flash erase is should be applied for correct operation.

Question

I see high radiated spur within the frequency range of the Si4x6x RF chip VCO signal. How can I suppress this?

Answer

In RX only boards due to the lack of additional filtering the VCO signal might be radiated via the antenna too. In that case some filtering between the antenna and the matching balun network is recommended.

Moreover, the filtering of the traces connected to the SDN, GPIO 2, 3 pins (and the DC supply line of a TCXO) is also suggested at the VCO frequency (not only in case of RX only boards).

Use cases where applying additional filtering on SDN, GPIO 2, 3 (and the DC supply line of a TCXO) is strongly recommended:

• 2 layer PCBs (the problematic traces cannot be routed on inner layers, they can operate as hidden antennas)
• High-power (≥20dBm) applications (the level of possible spur is higher for high power parts)

The actual level of this radiated spur can vary with the actual board design.

Note: Not all Si4x6x reference designs use this additional filtering on SDN, GPIO 2, 3 (and TCXO VDD supply) lines. If possible, it is recommended to apply the additional filtering inductors on all customer designs. If BOM cost is critical, these elements can be eliminated from the design, but be aware that depending on the actual PCB layout structure, increased radiated spur in the frequency range of the VCO signal might appear.

The SDN and GPIO 2, 3 filtering on Silicon Labs reference designs is shown in the following figure:

The inductor value should be selected in a way to ensure enhanced suppression at the VCO frequency, so inductors that have SRF at the ~ 3.5 GHz frequency range. 

Question

What Si4x6x reference designs need external power supply even if being connected to the Wireless Motherboard (WMB-930)?

Answer

Si4x6x reference designs with additional external FEM or FET require external power supply even if connected to the Wireless Motherboard, WMB-930. It means to use an external 4xAA battery pack connected to the RF Pico Board. The reference Pico Boards also use an external LDO in order to ensure the required 3.3 or 3.6V power supply for the radio and FEM/FET.

The external power supply is required due to the higher current consumption.

This is the eighth tutorial in a series that demonstrates "the essentials" of building applications based on Silicon Labs Connect. See Connect Tutorial Series: Table of Contents for an overview of topics addressed in the series, general pre-requisites to ensure you get the most out of the exercises, and definitive Connect references for when you're ready to dive deeper.

The previous tutorials covered radio transmit and receive operations, while network configuration was not emphasized. With this eighth tutorial in the series, we examine Connect features and the related API functions that help to manage to Connect direct mode devices.

The Connect stack stores crucial network parameters in a non-volatile space of the device. Currently, two implementations are available to store these data:

• SimEE (SimEE v1 and SimEE v2)
• NVM3

Any of the above can be enabled to store the Connect stack parameters although, NVM3 is the newer and more flexible non-volatile memory implementation thus the recommended one for new application development. Both implementation use wear-leveling to optimize the life cycle of the internal flash memory of the device.

The individual values are stored in the TOKEN area, which is accessible to the application but it is highly recommended to keep the API functions to manipulate the stored values otherwise mysterious issues can be encountered.

For more details about NVM see UG103.7.

To conduct the following exercises, you'll need two Wireless Starter Kit (WSTK) boards, each equipped with a (preferably identical) radio board. The example application relies on CLI through the WSTK VCOM (over USB) port to issue commands and display status information.

Network parameters

The network management API functions manipulate the following parameters:

• Device type (always EMBER_DIRECT_DEVICE in the Direct mode tutorials)
• Node ID (short address)
• PAN ID
• Radio channel (specified in the radio configurator)
• Radio TX power (within the available power range of the device)

The following API functions can be used to configure the network:

emberResetNetworkState() set all the parameters to their default value and flags the network state to unconfigured. This function can be called even if the network is unconfigured, in this case, it has no further effect.

emberJoinCommissioned() configures the network using the parameters described above. For Direct mode devices, Node ID can be any short address except EMBER_NULL_ADDRESS (0xFFFF) and ember EMBER_USE_LONG_ADDRESS (0xFFFE). The radio TX power is an int8_t in dBm value but the valid range is device dependent, and additionally not all values can be applied even in the valid range, however, the stack will apply the closest possible value if the specified value is not applicable. If a network is already configured, subsequent configurations will return with an error, the network state must be reset prior to applying a new configuration.

emberNetworkInit() can be used to retrieve previously configured network values. This usually used at the device startup to recover the network without applying new configuration values. If the network was unconfigured the function will return with an error, otherwise, it configures the previously-stored network parameters. It can be a good practice to try to call the API function at startup, and commission network parameters if the initialization returns with error (i.e. the device was not configured previously).

Individual settings

The radio channel and TX power can be set independently from the other parameters of network configuration and also possible to retrieve the current values:

• emberSetRadioChannel()
• emberGetRadioChannel()
• emberSetRadioPower()
• emberGetRadioPower()

emberSetRadioChannel() will return with an error if the specified channel is out of the channel array configured in the radio configurator.

emberSetRadioPower() will set a value which is closest to the specified value, while emberGetRadioPower() will return with the value actually set.

Note, every modification of the channel or power level value triggers a flash write which can wear out the flash area reserved for tokens if these values are intensively updated.

Signal strength

The transmission signal strength can be controlled by the TX power setting and it is also possible to retrieve the signal strength of the received packets (including ACK packets). Both emberIncomingMessageCallback() and emberMessageSentCallback() provides the RSSI (Received Signal Strength Indicator) values. The examples below will show how to extract them from the received messages.

Application Example

To begin, create a new Connect (SoC): Empty Example Flex SDK Project as described in tutorial 1 "Getting Started with Application Development". (Just create a new project for this tutorial 8 and give it an appropriate name - you don't need to actually repeat the tutorial 1 exercise.) Then, copy the provided flex-callbacks.c and connect_tutorial_08.isc files to the project root directory, open connect_tutorial_08.isc and click on Generate. We'll keep the default configuration for CLI, which enables access to the EFR32 serial port through the VCOM (over USB) port on the WSTK board.

The Example Code

The example code intentionally will not initialize the network at startup - usually, that's not the case, we do this for demonstrational purposes. So regardless of whether the network parameters are uninitialized (in the non-volatile storage) or previously those were initialized but the device has been restarted the network will be down after a restart.

Commissioning network parameters

To configure the network issue the following command:

commission 0x0001 0x01ff 0 5

The parameters in order:

• 0x0001 the Node ID of the device
• 0x01ff the PAN ID
• 0 radio channel
• 5 the requested transmit power in dBm

This command not just sets the parameters but brings up the network, from this point the device is ready to send and receive messages. If the configuration was successful, the message below will be printed on the console (otherwise an error code will be printed):

network is up

The network parameters can be checked by issuing the info command:

  network state: 0x02
      node type: 0x05
          eui64: >000B57FFFEA27C22
        node id: 0x0001
         pan id: 0x01FF
        channel: 0
          power: 5

If the commissioning command is issued more times without resetting the network it will return with error:

commissioning failed, status=0x70

Configure additional device(s) as the example shows above, The Node ID must be unique and the PAN ID and the radio channel have to match. The following examples assume that the other device's Node ID is 0x002.

Unconfiguring the network

To reset the network to an unconfigured state, issue the leave command. After issuing this command the network will be down and radio communication will be disabled.

Usage:

leave

Network initialization

The network initialization function reads the previously stored network parameter from the non-volatile memory. Its primary goal to bring up the network after the device restarts. While it would be possible to commission the network parameters on every startup it writes the device flash on every execution. Calling the initialization function, however, helps to avoid flash memory wearing.

The usual way of using the initialization function:

  EmberStatus status;
  if (emberNetworkInit() == EMBER_NOT_JOINED) {
    status = emberJoinCommissioned(EMBER_DIRECT_DEVICE, LOCAL_NODE_ID, &parameters);

If the network parameters had been initialized on a previous run, it will simply retrieve them and bring up the network. Otherwise, it will commission the parameters and bring up the network.

Radio channel management

Independently of the initialization or commissioning it is possible to switch to another logical channel (configured in Radio configurator). By default 20 channels are available with the predefined radio configurations.

Use the following command to switch between channels (the parameter is the channel number):

setchannel 1

To retrieve the current channel issue the info command.

Signal strength setting

Although transmit power is set by the commission function it can be modified individually:

setpower -10

The command above tries to set -10dBm TX power and reads back the current value then prints the actual power:

power set to -8dBm

Again, the specified values may differ from the possible ones.

Received signal strength (RSSI)

Connect maintains RSSI values for both received messages and received ACKs.

To inspect RSSI values the application implements a send command by which a node can send a message to another node specifying its Node ID and the message. Assuming that two nodes are configured (Node ID for node #1 is 0x0001 and 0x0002 for node #2), node #1 can send "test" to node #2:

send 0x0002 "test"

Node #2 will print several message parameters on reception including the RSSI value of the received message:

incoming message: source=0x0001, RSSI=-34, options=0x02, endpoint=0, length=4, payload=[test]

Since the ACK was required node #2 send the ACK to node #1 and the RSSI value of the received ACK message will be printed on node #1:

message successfully sent, ackRSSI=-25

The RSSI values are vary based on the distance between the boards and the applied TX power. Try to increase/decrease the distance of the radio boards and change the TX power by the setpower command.

Conclusion

All the possible Network parameters can be tuned by a limited number of API functions. Network parameters are stored in a non-volatile space and can be retrieved on a startup.

API References

Functions

• emberJoinCommissioned()
• emberResetNetworkState()
• emberNetworkInit()
• emberSetRadioChannel()
• emberGetRadioChannel()
• emberSetRadioPower()
• emberGetRadioPower()
• emberAfIncomingMessageCallback()
• emberAfMessageSentCallback()
• emberMessageSend

Type definitions

• EmberNetworkParameters
• EmberNodeId

Defines

• EMBER_NETWORK_UP
• EMBER_NETWORK_DOWN
• EMBER_DIRECT_DEVICE

Introduction

The Connect stack supports sending encrypted messages using a pre-shared (AES-128) key, which must be common for the whole network (hereinafter referred to as network key). However, sometimes it is not feasible to pre-share the key (for example burning the key to the device at production) or apply the key manually (like typing in on some kind of console as the UART of the device). Fortunately, it is possible to create a shared key (hereinafter referred to as shared key) between two devices using the Diffie-Hellman algorithm while any third party will not have the information to recover the key from the data sent over the communication medium. This key however unique between every two parties, so the current implementation will use this shared key to securely distribute the network key to other devices. Note, that the method used in this example does not protect against physical access to the devices or against man-in-the-middle attack (MITM).

Prerequisites

The provided method applicable for any Connect based application with any EFR32 device which supports Connect, this article uses Connect (SoC): Empty Example. In this example, we will use BRD4255A radio boards.

Further readings:

• Connect online documentation
• Connect tutorial series

Prepare the application

Open the Connect (SoC): Empty Example through Simplicity Studio project wizard.

In AppBuilder enable mbedTLS plugin to be able to use mbedTLS API functions:

Also, enable Security AES to enable security for Connect messages:

The complete example enables several plugins and options for working with CLI which are not detailed here as their description is out of the scope of this document, but the attached files configured properly.

When the setting is done in AppBuilder and the files are generated, the next step is implementing the code in the flex-callbacks.c. Just as the settings in AppBuilder, the complete code is not described in this document please refer to the resources described in prerequisites.

Major steps of key exchange

Although the same code runs on both (each) devices, one of the devices will act as the server and the others will be clients (if a device becomes a server or a client depends on the executed CLI commands only).

• creating private/public key pair locally on the devices using ECC
• exporting the public part (X and Y points) as 32-byte arrays
• transferring the public part to another device
• creating a shared secret and shared key which can be used for secure data transfer
• the server sends the network key to the remote side securely using the shared key for encryption
• the client sets the network key on to securely communicate with the members of the network using the network key

Implementation

There are only four functions implemented in the current application to support ECDH key exchange:

• static bool seedRandomNumber(void)
  • initializes the ECDH context
• static void clearEcdhContext(void)
  • clears the ECDH context, only used if anything goes wrong during initialization, otherwise, it kept to be able to run ECDH related function during the whole lifetime of the application
• static bool setupEcdhPeer(mbedtls_ecdh_context *peerCtx, unsigned char *ecpPointX, unsigned char *ecpPointY)
  • generates the public key and exports as X and Y points to be transferred to the remote side
• static bool generatePeerKeySecret(mbedtls_ecdh_context *peerCtx, unsigned char *ecpPointX,unsigned char *ecpPointY)
  • generates the shared secret based on the transferred X and Y points

These functions are built on mbedTLS API calls. For reference of these API calls navigate to mbedTLS documentation.

The functions above are ported from the ARM mbedTLS ecdh_curve25519.c example code.

Besides the functions above the are several CLI related functions that help to configure the devices and allow them to set up the network, generating keys, sending messages. These functions are not detailed here, please refer to the provided source code.

Completing the steps above, compile and run the firmware.

Testing the application

If everything went well, a CLI interface should be available where the user can issue the necessary commands.

Example

Private and public keys are generated once, at startup (in emberAfMainInitCallback()) and will be reused for subsequent generations of shared keys.

Assume there are two devices a server (node ID will be 1) and a client (node ID will be 2). Any of the devices can act as a server or act as a client. First, issue the leave command on both parties - that's not mandatory (especially for the first use when none of the addresses are commissioned), but it makes sure that the network state is reset, no short addresses are assigned.

leave

The next step is to choose a network key (this will be used as the common key in the network for Connect encrypted messages). The key can be an arbitrary chosen 16-byte long value. set-network-key does not apply the key, it just stores in a variable which will be set to the default value (all 0x00s) on device restart. This command must be executed on the server.

set-network-key {00112233445566778899aabbccddeeff}

Choose a node ID for the server:

set-node-id 1

Then choose a node ID for the client:

set-node-id 2

Send the server's public key for the client:

send-publickey 2

Send the client's public key for the server:

send-publickey 1

At this point, all the necessary information is available on both sides to create the shared secret (and the shared key), but no third party who may observe the communication can recover the shared secret from the messages exchanged.

Generate the shared key (issue the command on both server and client):

generate-shared key

For convenience there is a CLI command to show the shared key, to check whether the same key generated on both sides:

print-shared-key

To send the network key to the client, issue the send-network-key on the server. The network key will be AES encrypted using the shared key. Connect's message encryption will not be used here (security bit is not set) - since the network key is not known at this point, so the message will be sent unencrypted but the payload which transfers the key will be protected by encrypting the payload with the previously generated shared key.

send-network-key

To check whether the network keys match issue the following command on both sides:

print-network-key

To apply the network key (write the key to the non-volatile memory) apply-network-key on the server and on the client as well.

apply-network-key

To enable secure communication between the parties (using Connect's security feature), issue the following command on both devices (if the parameter is 0, the security feature will be turned off).

set-security 1

From this point, secure communication is possible between the devices, the command below will send the text Hi! from the client to the server but obviously the opposite direction should work as well.

send-message 1 "Hi!"

Notes

In normal use cases, it is not necessary to write the key on the server and the clients at every restart. The usual workflow is that the network key is stored in the non-volatile space of the server - in the code memory for example and apply once (at first power up or initiated by a CLI command, etc.). Although, Connect's emberSetSecurityKey() API function stores the network key in a non-volatile space, there is no API call to read it back - thus the application must store the network key in a retrievable form to be able to send it to the clients.

The security can be enabled at the beginning of the process above, due to the fact that enabling security for the messages is only makes sense for sent messages, received messages are passed to the application if the network keys match (the device can decode the message) or if the message is unencrypted. If the encryption status is not checked by the application for the incoming messages malicious devices can trick the devices in the network.

The above method for transferring the network key works with multiple client devices, but in that the key sharing process must be repeated between the server and every client one by one.

Conclusion

Although the Connect does not support ECDH key exchange at the plugin level, the way to implement is fairly easy and straightforward.

Files used in the project

• ecdh.isc
• flex-callbacks.c

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

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

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

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

Legacy mode

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

Selective mode

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

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

What is the Dynamic Configurator?

Dynamic Configurator is a Simplicity Studio feature that allows experimentation with radio configurations on EFR32 devices.

What is the typical use case?

Typically dynamic configuration is used to easily reconfigure the EFR32 of a Silabs development board or a custom radio board

• to evaluate the radio of the EFR32 (the other node of the link is a generator or spectrum analyzer)
• to find compatible configuration (the other node of the link is a fixed configuration/third party radio ).

How does it work?

There are CLI (Command Line Interface) commands implemented in a plugin of the RAILTest sample application, called Ram Modem Reconfiguration Commands.

Using these commands Simplicity Studio generates scripts of the user configured radio settings and applies them over a virtual COM port to  the target EFR32 to dynamically change the radio modem configuration, without the need for recompiling the RAILTest application and reflashing the target.

The virtual COM port consists of a physical UART between the target device and the board controller of the WSTK (Wireless Starter Kit) Mainboard, and a logical function in the board controller that makes the serial port available to the host PC, over USB or Ethernet.

How to use it?

1. Set up your development environment and create a new or open an existing RAILTest sample application for your connected Silabs or custom HW, according to the description in https://www.silabs.com/documents/public/quick-start-guides/qsg138-flex-efr32.pdf. You will end up in the Simplicity IDE perspective of Simplicity Studio with a RAILTest project open.
2. Open the isc file and in the configurator window set the initial configuration according to your needs. Make sure that the "Railtest Ram Modem Reconfiguration" plugin is enabled. Generate and compile the application.
3. Upload the application to the target without starting a debug session.
4. Open a terminal window for the virtual COM port of the target by right clicking on the target adapter in the "Debug Adapters window" and selecting "Launch Console…"
5. In the console window select the "Serial 1" tab and by pressing Enter in the text box check if the connection with the RAILTest is alive.
6. Now you can start using RAILTest with your initial configuration. See https://www.silabs.com/documents/public/user-guides/ug409-railtest-users-guide.pdf for help.
7. When you need to modify the configuration, do it in the configurator window. Note that the dynamic configurator can support only the first Channel Group of the first Protocol configuration.
8. In the configurator window click on the Dynamic Radio Configuration button of the isc editor, open the "Adapters" tab and select your target adapter.
9. Then go to the "Create configuration" tab. It will create and display the dynamic configuration script as soon as you click on the "Generate dynamic Railtest Configuration" button.
10. To send the script to the target, go to the "Apply Configuration" tab and click the "Apply Configuration" button. The commands of the script and the responses will appear in the previously opened console window. In case of success the radio will start to behave according to the modified configuration.

Note that the dynamic config modifies only radio registers, so getConfigIndex, printDataRates or similar CLI commands that get values from other sources may return incorrect values. The overwritten configuration can be reverted by a reset or setConfigIndex CLI command.

Note also that the RAM Modem Reconfiguration CLI Commands (writeRmrStructure, updateConfigurationPointer and reconfigureModem) are intended to be used only by Simplicity Studio and not directly from the CLI.)

The function RAIL_Idle() takes a mode argument, with which you select one of the four available methods of idling the radio to use. Though the API documentation briefly describes each mode, it might be difficult to understand their differences without seeing examples and usecases. This document aims to help you more clearly understand each mode.

General recommendations

In most cases, RAIL_IDLE is the recommended mode to use with this API. RAIL_IDLE_ABORT is helpful when you want to also abort an ongoing ("active") tx or rx operation.

On the other hand, RAIL_IDLE_FORCE_SHUTDOWN is not recommended for use, and RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS should be handled with care.

RAIL_IDLE

The mode RAIL_IDLE turns off the radio after the current operation is finished. It also cancels any transmit or receive scheduled in the future. Current operations that won't be aborted include:

• active transmit, which starts when the first bit (usually preamble) is transmitted and ends when the last bit (usually CRC) is transmitted.
• active receive, which starts at sync word detect, and ends when the last bit is received (which depends on the decoded length of the packet).

RAIL_IDLE_ABORT

The mode RAIL_IDLE_ABORT works the same as RAIL_IDLE, but it will also abort active operations. However, RAIL_IDLE_ABORT will always wait for a stable state before turning off the radio, e.g. if the radio was preparing to enter rx mode and is waiting for the PLL to lock, RAIL will wait until the rx state is reached before idling the radio.

RAIL_IDLE_FORCE_SHUTDOWN

Unlike RAIL_IDLE_ABORT (which waits for a stable radio state), RAIL_IDLE_FORCE_SHUTDOWN immediately forces the radio off. As this is an abrupt transition, it may corrupt data in the receive or transmit buffers. This buffer corruption can only be resolved by completely clearing the FIFO - which loses data, and can also consume additional time.

In our experience, it's almost always slower than RAIL_IDLE_ABORT, so the costs typically outweigh the benefit of using RAIL_IDLE_FORCE_SHUTDOWN (except when recommended by our support team for diagnostic purposes).

RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS

The mode RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS works the same as RAIL_IDLE_FORCE_SHUTDOWN, but it also clears any pending events. For more details on scenarios where this can be useful, see the article on RAIL interrupt safety.

In embedded software development, some of the most complicated debug challenges are caused by calling non-reentrant functions in interrupt context. Hence, it's in the developer's best interest to carefully design their application to avoid these scenarios.

To do so, however, requires sufficiently detailed knowledge of the interrupts and API functions - which are not accessible in a closed-source product like RAIL. This document aims to provide the information required to develop interrupt- and thread-safe applications in RAIL.

Thread Safety

In an application without a task scheduler, only an interrupt request can interrupt the main program. If you use a preemptive scheduler, like the scheduler available in most embedded OSes (including Micrium OS), higher priority tasks can interrupt lower priority tasks as well. Regardless, when looking at the RAIL APIs, the same concerns are present in either case:

• Is it safe to interrupt this API?
• Is it safe to call this API from a thread/interrupt which interrupted something?

The Event Handler

RAIL uses an event handler, which is set up by RAIL_Init(). In our examples, it's usually called RAILCb_Generic(). This function is called by the RAIL library, and it's almost always called from an interrupt handler. This means the event handler should be used with care:

• It should be kept in mind that interrupts are disabled when the event handler is running, so the function must not take long to return
• More importantly, the function might be interrupting the main loop (or some other task)

Note that the first point above might not be completely true if interrupt priorities are used, in which case only interrupts at the same and lower priorities are disabled. However, the event handler will never be interrupted by another event handler as all RAIL interrupts must be used at the same priority.

General Rules for the RAIL API

First, let's collect the general rules of the API, and we'll detail exceptions in later points:

1. Calling any RAIL API from the main thread (or a single OS thread) is safe.
2. Calling any API from multiple threads is unsafe, except for DMP.
3. Calling most APIs from an interrupt handler is safe (see exceptions below).

Dynamic Multiprotocol (DMP)

In general, if you have a multi-threaded application, you should use RAIL from a single thread. The exception to this guidance is DMP, where in most cases each protocol runs in its own thread. In this scenario, using RAIL from each thread is safe, as each protocol has its own railHandle. So, a more generalized wording of rule 2 is:

Calling any API from multiple threads is only safe if each thread has a dedicated railHandle, and each thread only accesses RAIL with its own handle.

The few APIs that don't use railHandle - like RAIL_GetTime(), RAIL_Sleep(), or RAIL_Wake() - can be called from any thread.

Interrupt Safety in general

In general, calling an API which changes the radio state (i.e. between rx, idle and tx) can be risky. The simplest way to write interrupt safe application is to not call state changing APIs from any interrupt handler, including the RAIL event handler. This can be achieved by setting a flag or changing a state variable in the event handler instead of calling an API directly:

typedef enum  {
  S_IDLE,
  S_START_RX,
  S_START_TX,
} state_t;

volatile state_t state;
volatile RAIL_Time_t lastEvent;

int main(){
  //init code

  state = S_START_TX;
  while(1){
    switch(state){
      case S_START_TX:
        RAIL_StartTx(railHandle, 0, RAIL_TX_OPTIONS_DEFAULT, NULL);
        state = S_IDLE;
        break;
      case S_START_RX:
        RAIL_StartRx(railHandle, 0, NULL);
        state = S_IDLE;
        break;
      default:
        break;
    }
  }
  return 0;
}

void RAILCb_Generic(RAIL_Handle_t railHandle, RAIL_Events_t events)
{
  lastEvent = RAIL_GetTime();
  if ( events & RAIL_EVENTS_TX_COMPLETION ){
    state = S_START_RX;
    RAIL_SetTxPower(railHandle, 200);
  }
}

Note that some RAIL API was called from the event handler, but none of those were state changing APIs.

Interrupt safety with state changing APIs

In some (usually time critical) cases however, it's not possible to avoid calling state changing APIs from the event handler (or other interrupt handler). State changing APIs are not always risky: Some APIs might be safe, as long as they don't interrupt another specific API.

Hence, in the following list, we identify the risky API after first specifying which initially-running (i.e., "interrupted") API makes it risky (and how). We've included in this list some interrupt combinations that might be "safe", but the end result is not predictable - i.e. the radio might be in rx or in idle, depending on which API is called first.

• Interrupting RAIL_Start<something>() with another RAIL_Start<something>() is risky, especially if they would start on different channels.
• Interrupting RAIL_Idle(handle, <something>, true) with any RAIL_Start<something>() is risky.
• Interrupting RAIL_Idle(handle, <something>, false) with any RAIL_Start<something>() is safe, but the end result is not predictable (i.e. the radio will either be in Idle, or start the requested operation).
• Interrupting RAIL_Start<something>() with RAIL_Idle() is safe but the end result is not predictable, and might cause strange events (see the next section for details).
• Interrupting RAIL_StopTxStream() with any RAIL_Start<something>() is very risky (the radio might remain in test configuration and start transmitting/receiving).
• Interrupting RAIL_StopTx() is safe. Interrupting RAIL_StopTx() with RAIL_Start<something>() is safe but the end result is not predictable (i.e. the radio will either be in Idle, or start the requested operation).
• Interrupting anything with RAIL_StopTx() is safe (see next section for important clarification). Interrupting RAIL_StartTx() with RAIL_StopTx(handle, RAIL_STOP_MODE_ACTIVE) is safe, but not predictable.
• Interrupting anything with RAIL_StopTxStream() is safe. Interrupting RAIL_StartTxStream() with RAIL_StopTxStream() is safe but not predictable.

RAIL_Idle in the Event Handler

Calling RAIL_Idle() or RAIL_StopTx(handle, RAIL_STOP_MODE_ACTIVE) from the event handler might cause strange results. For example, let's say you're receiving on a channel and want to detect preambles using the event RAIL_EVENT_RX_PREAMBLE_DETECT and RAIL_EVENT_RX_PREAMBLE_LOST. The following scenario may unfold:

• Preamble lost interrupt is received, so (at least) other radio interrupts are temporarily disabled.
• You enter the event handler with RAIL_EVENT_RX_PREAMBLE_LOST.
• At this point, the radio detects a preamble. The interrupt is logged, but the handler cannot run since the interrupts are masked.
• Still in the event handler, you decide to turn off the radio with RAIL_Idle(railHandle, RAIL_IDLE_ABORT, true).
• The radio turning off will generate a preamble lost interrupt.
• The radio is now off, and you return from the event handler.
• Interrupts are enabled again, so the pending preamble detect interrupt handler starts running.
• You enter the event handler with RAIL_EVENT_RX_PREAMBLE_DETECT and RAIL_EVENT_RX_PREAMBLE_LOST both set at the same time

So you end up with a preamble detect event, even though the radio is off. This is usually harmless, since you always have the _LOST or _ABORTED event as well - but this demonstrates why your design must carefully consider in what order to handle events.

The easiest way to avoid this conflicted outcome is to disable the events that might cause problems when turning off the radio.

Another way to avoid this issue is to use RAIL_Idle(handle, RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS, true), which will clear the pending interrupts. However, using RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS has other drawbacks. It does force the radio state machine to idle state, and it might corrupt the transmit or receive FIFOs - in which case it must clear them, losing all data that might already be in there. It could also take more time to finish running than RAIL_IDLE_ABORT.

Critical Blocks

One usual way to avoid internal safety issues is to create critical (a.k.a. atomic) blocks, in which interrupts are disabled, in the main thread to make sure some code segment is never interrupted. However, this can create other problems, so it should be used carefully. There's no general rule to avoid this kind of "collateral damage", but here's an example that should be avoided:

RSSI averaging is running, and just before it finishes, we interrupt it with RAIL_StartTx() which is called from a critical block. The following race condition could happen:

• We enter the critical block, interrupts are disabled.
• RSSI averaging done interrupt is received, but the interrupt handler won't start since interrupts are masked.
• StartTx turns off the radio, prepares it for transmit, then starts transmitting.
• We leave the critical block, interrupts are enabled again.
• RSSI averaging done interrupt handler runs at this point which will turn off the radio, aborting the current transmit.

One way to avoid the problem above is to clear interrupts in the critical block. This can be done by using RAIL_Idle(handle, RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS, true) at the beginning of the critical block, but the drawbacks of doing so (mentioned above) should be kept in mind. In general, it's better to avoid risky interrupts without using critical blocks in the main thread.

Using FORCE_SHUTDOWN

In the two sections above we mentioned two usecases where RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS can be useful. In general however, RAIL_IDLE or RAIL_IDLE_ABORT is a sufficient and preferred way to stop transmitting/receiving - therefore the FORCE_SHUTDOWN modes should be only used when they are really needed (as in the specific scenarios described here). For more details, see the article on the idle modes.

The following signals are necessary for RX direct mode

RX data clock output

RX data output

You can assign them to any radio GPIO pin by setting the corresponding GPIO_MODE to RX_DATA_CLK or RX_DATA via the GPIO_PIN_CFG command.

The following signals are necessary for TX direct mode

TX data clock output

You can assign it to any radio GPIO pin by setting the corresponding GPIO_MODE to TX_DATA_CLK via the GPIO_PIN_CFG command.

TX data input

The TX_DIRECT_MODE_GPIO field of the MODEM_MOD_TYPE property determines which radio GPIO pin is selected as the modulation data source during TX Direct mode. Also the GPIO_MODE of the corresponding radio GPIO has to be set to INPUT via the GPIO_PIN_CFG command.

When generating the configuration from WDS, GPIO mode can be selected on the "GPIO and FRR" tab of the configurator. However the TX_DIRECT_MODE_GPIO field is left by WDS always in the default GPIO0 setting and can be modified only by hand in the generated config header.

Note 1: For Si4x55 the TX data input can be assigned only to GPIO0.

Note 2: For active signals like data and clock, the GPIO0 and GPIO1 pins should be primarily used , because these have less susceptibility to generating spurious components in the synthesizer than GPIO2 and GPIO3 have.