Introduction

There are multiple ways to sniff Connect (IEEE 802.15.4) packets (for example using the RAILTEST utility). This article will describe how to create a simple RAIL based application to configure EFR32 packet sniffing feature necessary to use the Simplicity Studio built-in Network Analyzer. This example uses the Simple TRX demo application as a boilerplate project to develop the sniffer application. In Simple TRX everything is configured (including the enabled PTI) as required only the PHY has to be set to match the packets wanted to sniff and main.c need to contain the appropriate code, which is actually very simple.

To test the sniffer, it is expedient to run a Connect network with at least two devices: a coordinator and an end node. The Sink / Sensor demo applications are excellent candidates to set up the test network.

Establishing the test network

To set up the test network, follow the application note AN902.

Creating the RAIL based sniffer

First, open the Simple TRX demo application and follow the wizard to create the project. In the last step Simplicity Studio will open the AppBuilder. Navigate to the Radio Configuration tab and select the required PHY by setting the Profile to Connect and selecting the appropriate PHY - this must be match with the settings of the devices in the test network.

Only a few lines of code is necessary to achieve the sniffing capability.

To use the IEEE 802.15.4 API functions:

#include "rail_ieee802154.h"

To enable IEEE 802.15.4 mode, turn on promiscuous mode and set PTI protocol format in the radio initialization:

  RAIL_StateTiming_t timings = {
    .idleToTx = 100,
    .idleToRx = 100,
    .rxToTx = 192,
    // Make txToRx slightly lower than desired to make sure we get to
    // RX in time
    .txToRx = 192 - 10,
    .rxSearchTimeout = 0,
    .txToRxSearchTimeout = 0
  };

  RAIL_IEEE802154_Config_t config = {
    .addresses = NULL,
    .ackConfig = {
      .enable = true,
      .ackTimeout = 1000,
      .rxTransitions = {
        .success = RAIL_RF_STATE_RX,
        .error = RAIL_RF_STATE_RX // ignored
      },
      .txTransitions = {
        .success = RAIL_RF_STATE_RX,
        .error = RAIL_RF_STATE_RX // ignored
      }
    },
    .timings = timings,
    .framesMask = RAIL_IEEE802154_ACCEPT_STANDARD_FRAMES,
    .promiscuousMode = true,
    .isPanCoordinator = false
  };

  RAIL_IEEE802154_Init(railHandle, &config);

  RAIL_SetPtiProtocol(railHandle, RAIL_PTI_PROTOCOL_CONNECT);

This example application will be in RX mode during the whole operation so, several of the settings are irrelevant.

The complete main.c file is attached to the article for convenience, it is only necessary to copy over the Simple TRX project's original main.c file with the attached one. The attached main.c contains implementation of counting received packets and printing the packed count over the UART port. The current implementation only counts the packets, however any further filtering can be implemented in RAILCb_Generic(). Note, that PTI is a hardware feature thus implementing any filter in RAILCb_Generic() will not have any effect on PTI data output.

Compiling and running the project should result in continuously counting the packets received from the test network, both from coordinator and end node(s) including the ACK packets too.

Inspecting the test network communication in the Network Analyzer

Open the Network Analyzer perspective:

Connect to the device (right click on its name):

Start capturing:

From this point every packet sent from the sink or sensor device(s) should appear in the Network Analyzer:

See AN822 for more detailed guide on using the Network Analyzer.

Content

• Definition and limitation of RFSENSE
• How to Configure RFSENSE
• Wake up the device with Bluetooth advertising packets
• Measurement result

Software test environment:

• RAIL 2.6 (Flex SDK 2.5.1.0)
• Bluetooth SDK 2.9.2

Hardware used for examination:

• EFR32MG14 based radio board (BRD4169A Rev A02)
• Wireless Starter Kit (BRD4001A)

Introduction

This Knowledge Base Article is a short introduction to RFSENSE feature particularly from the practical view. This means how to configure a device capable to wakeup from sleep mode, where a BLE advertiser device is close to the EFR32 device.

One use case is, when the EFR32 is powered by a coin cell battery, and the goal is to minimize the time in active state. Therefore the radio should be in sleep state most of the time, and it wakes up only when a Bluetooth advertiser getting close to the sleepy device. In this typical use case that the transceiver should be disabled before enabling the RFSENSE. Then the transceiver can be enabled by the wakeup event, or manually disabling the RFSENSE. At the end of this KBA some measurement results shared to understand this practical application better.

What is the RFSENSE

RFSENSE is an Ultra Low Energy RF detector peripheral on EFR32 devices available even in EM4 Shutoff mode. During the device is in sleep mode the RF detector continuously monitors the RF band for any signal and generates a wakeup event when RFSENSE is active - this method can reduce the energy consumption significantly. Once the signal will have sensed the RFSENSE feature will be disabled, thus need to reactivate to further use. The RFSENSE held in reset by default.

There are two configurable parameters in the RFSENSE. The detection period (or sensing time) despite, that it's name indicates temporal nature it relates to the incoming RF energy (value must be determined empirically, due this fact we are sharing our measurement results. The other parameter is the RF sensing band, where the RFSENSE operates. These are discussed in more details in the following section.

Although RFSENSE is a very effective energy saving feature, it has some limitations:

• Below 0 °C the RFSENSE is unreliable, this means that the RFSENSE generates wakeup signals randomly (vid. API documentation).
• The RFSENSE is not band filtered, that means for example if a device operates at 868 MHz, a 900 MHz signal may have enough power to wakeup the device. The radio configuration has no effect on RFSENSE.
• If a radio packet has enough power to wake up the sleepy device, there is no chance for the radio to receive that packet, due to the wakeup period length.

Configure RFSENSE

The RAIL_StartRfSense() API supports configuring both of the RFSENSE peripheral parameters. The API receives 4 parameters (documented in RAIL API Documentation). We will go through the details of these configuration parameters.

Like most RAIL API functions, RAIL_StartRfSense() takes the handle of a RAIL instance. The second parameter is the sensing band selector, it can be any combination of 2.4GHz and SubGHz bands (there are predefined enum types). The third parameter is a RAIL_Time_t instance, which sets what is the minimal period the incoming RF signal should be “sensed”, called as sensing time. Here we have to note that it is a very inaccurate in this mean, a given signal has energy at a given distance (due to interference and free space path losses) and need to consider a custom designed antenna matching circuit, so it doesn’t define the sensing time exactly.

RAILTEST application provides two command line interface (CLI) commands related to RFSENSE. One of these is the sleepcommand which receives 1 to 3 arguments, the first tells which EM mode should be used, and the others are related to the API discussed above: the sensing time and the band selector parameters. The other command (rfsense) implements subset of features of the sleep command, it calls immediately the RAIL_StartRfSense() API without setting any EM Mode.

Although the sleep CLI command is applicable in all EM modes, using the sleep command makes sense in EM2, EM3 and EM4modes only (4s and 4h are also valid on first generation MCUs).

Wake up with a Bluetooth advertiser device

We had tested RFSENSE with soc-empty sample application which is part of Bluetooth SDK. The application serves as a skeleton example for further development. It sends only the beacon frames and gives the opportunity to join.

There are two software configurable parameters, which have impact on target's RFSENSE. If you would like extend the range where the RFSENSE can be activated, generally you have two choices. These are:

• increasing the length of the advertise packet
• increasing the message sending duty cycle

The Generic Access Service holds the Device Name Characteristic where the device's name is defined. This is part of the message and will be sent in every advertisement interval. The easiest way to increase the beacon's length can be done via Bluetooth Configurator (part of Bluetooth SDK).

The gecko_cmd_le_gap_set_advertise_timing() Bluetooth API call sets the minimum and maximum advertisement interval. It's minimal value is 20 ms, therefore it cannot be used as a range extender option when you want to use a Bluetooth advertiser. This means that the first option is the more efficient to extend the RFSENSE operational range in this use case.

Measurement results

For getting exact data we had done conducted RF measurements. We had used two devices, one used as a CW signal transmitter (custom application) and one with RAILTEST application used as sleepy device. The custom application provided with one CLI command for setting the period, the CW signal duty cycle, and the PA power.

First we had done a sensing time resolution and programmed vs. real PA power level examination, then we measured the necessary transmission time at constant PA level at 20 unit each on the whole range (0-252) to wake up the target device. Then we measured the minimal PA power required to activate the RFSENSE by a continuously radiated CW signal.

At last we captured some radiated measurement with using RAILTEST and soc-empty applications on the two device, but the results are not exact due to the behave of the radiated signals, so we ended this KBA a few normative notes.

Sensing time resolution/accuracy

In the first table we are showing the possible values of sensing time in microseconds. Sensing time selection above 1 second does not have practical meaning, so we are not representing the full range of applicable sensing time. The growing of the real sensing time values are quadratic.

On the top row are the sensing time ranges (from previous column + 1 to the Max value), serves as the second parameter of sleep CLI command and so for the RAIL_StartRfSense() API, and the lower is the return value of the API, the real configured sensing time. The RFSENSE can be disabled if this parameter is 0.

PA Power and minimum radiation time

The second table shows the sufficient transmission time at fix power to waking up the sleepy device. The radio are not able to transmit shorter than 42 us CW signal. The sensing time is 1 for maximal sensitivity.

Minimum power

The minimum transmission power required to wake up the sleepy device using continuous CW signal was about 4 dBm (RAIL_TxPowerLevel_t unit) when conducting measurement was applied.

Radiated measurements installation and results

With two unmodified sample applications (RAILTEST and soc-empty) it is possible to try how RFSENSE works.

Use Simplicity Studio to generate these two sample application and to flash your devices. Then open your favorite terminal program and send the sleep command to the RAILTEST device. Recommended parameter values for sleep command are:

 > sleep 2 1 1

where '2' stands for EM2 mode, '1' stands for the lowest sensing time and the last '1' means the 2.4 GHz band is selected.

After sending this command you will receive:

 > {{(sleep)}{RfSense:Enabled}{None:Disabled}{Time:264106245}}
 > {{(sleep)}{EM:2}{SerialWakeup:On}{RfSense:GHz}}

Then place the two devices close to each other (it should be ~5cm distance between the patch antennas and you will get the following message in the terminal window:

 > {{(sleepWoke)}{EM:2}{SerialWakeup:No}{RfSensed:Yes}{RfUs:268}}
 > {{(appMode)}{None:Enabled}{RfSense:Disabled}{Time:117512626}}

With a longer advertisement packet we can extend this distance to ~30 cm.

This article shows how to create monochrome icons / bitmaps to display on the LCD attached to the developer boards.

Since The GLIB pixmap format is not standard and additional plug-in has to be installed in GIMP (the plug-in is attached to this article). In GIMP Edit -> Preferences find the Plug-in folder and copy the attached GIMP plug-in to this directory then restart GIMP (on Linux the file attribute of the plug-in must be set to executable).

​

First create a new image, set the required size (width and height):

​

Edit the image - preferably use only black and white color as the color depth of the LCD display on the WSTK is 1 bit.

​

By default the color mode of the image is RGB for a newly created picture. This must be changed to indexed to be processable by the plugin thus change it: Image -> Mode -> Indexed.

​

Select Use black and white (1-bit) palette:

​

From File menu choose Export GLIB pixmap... to save the pixmap files:

​

Select the appropriate folder for the files (it is a good practice to create a directory in the Studio project to store the pixmaps and export the files to that folder directly) and choose a suitable name for the picture (don't add file extension it will be generated by the plug-in):

​

Press OK to save the C and header files - be careful, there is no confirmation the existing files will be overwritten.

The plug-in creates a file with .c extension which contains the actual image data and a file with extension .h containing two defines for the image width and height. Files, defines and the data array named based on the Output name. For example if the Output name is thermometer a header file named thermometer.h will be created containing THERMOMETER_WIDTH and THERMOMETER_HEIGHT defines and a C file named thermometer.c containing thermometer_bits array.

To use the pixmaps created with GIMP simply include the header file in the project, for example:

#include "thermometer.h"

The header files must be in the include path - it may need to add the pixmap folder in project properties.

The created pixmap can be used by the GLIB_drawBitmap() GLIB API function:

GLIB_drawBitmap(&glibContext, 0, 0, THERMOMETER_WIDTH, THERMOMETER_HEIGHT, thermometer_bits);

For further reference of using GLIB library see the following knowledge base article:

Displaying on the LCD screen using glib

Introduction

The following quick guide will show you how to set up and enable the security in Connect through a MAC-Device example. This article uses two Wireless Starter Kits with BRD4257A radio boards (Flex Gecko, 19 dBm, 915 MHz). However, the following is applicable for all Connect applications, disregarding the radio board.

If you are new to Connect, please consider going through the User Guide series UG235 starting with UG235.01 to learn more. For more information on the MAC-Device example and an introduction how to set it up, please see Connect MAC-Device KBA.

Security in Connect

Connect is based on the IEEE 802.15.4-2011 standard which defines various Physical (PHY) and Media Access Control (MAC) layer modes designed for short-range communication in Personal Area Networks (PANs). IEEE 802.15.4 supports the following security services:

• Data confidentiality
• Data authenticity
• Replay attack protection

The Auxiliary Security Header can have various arrangements, depending on the security and key setup available. However, with Silicon Labs Connect, when security is enabled it:

• Always uses a 128-bit key, which was set by the application (that is, there is no IEEE 802.15.4 key identifier field).
• Uses all three of the above services.

This means that the Auxiliary Security Header is five bytes long:

Only the lowest three bits are used from Security Control, which selects the security mode (always 5). The Frame Counter is a counter on each device that enables replay protection: The counter is part of the authenticated data (that is, MIC is calculated over it) and a receiver should not accept frames with the same/lower count. The Frame Counter must be valid even if the device reboots.

To guarantee data authenticity, a 4-byte MIC will be added at the end of the MAC payload (before the FCS). In the security mode supported by Silicon Labs Connect, the security headers and footers use nine bytes of the MAC payload.

Configuring and enabling security

The steps you need to go through to enable security are:

1. Set the key on all the nodes (same key) using the "set-key" command
2. Enable security on all the nodes by setting the 1st bit of the tx options on each of them, using the "set-options" command (give 3 as a parameter to enable security and keep ACKing on)

mac-device> set-key "Almafa"
mac-device> set-options 3
Send options set: 0x03

Limitations in MAC Mode

Short addressing only partially work in MAC mode with security enabled. The limitation is that the source address has to be long, therefore using a short destination and a long source address, or both long source and destination addresses are acceptable.

mac-device> send 0x0033 0xffff {99 7c a2 fe ff 57 0b 00} 0xffff
{50 81 a7 fe ff 57 0b 00} 0xffff 0xffff {01234567} // long-long addressing
MAC frame submitted
mac-device> send 0x1123 0x0000 {99 7c a2 fe ff 57 0b 00} 0xA4E3
{} 0xABCD 0xABCD {01234567} //long-short addressing
MAC frame submitted

Note: From Flex SDK 2.6.0 there is a new API available, emberMacAddShortToLongAddressMapping which can map the short addresses to the long ones. By using this API and mapping the appropriate addresses, the above limitation can be worked around, the short-short addressing can be used as well in MAC mode while security is enabled.

Introduction

This article intends to show how to configure an On-off keying modulation profile in the Radio Configurator in Simplicity Studio. In this example we will be using two Wireless Starter Kit with BRD4257A radio boards (Flex Gecko, 19 dBm, 915 MHz). However, considering the following guidelines, the radio link can be set up for any base frequency and/or radio board.

The guide is not going into details about most of the controls found in the Radio Configurator and assumes basic radio technology and RAIL application creational knowledge. For more information on custom radio configurations, please see AN971.

OOK modulation

The On-off keying modulation method is a simple type of the amplitude-shift keying modulation. It codes the transmitted data at the presence or the absence of the carrier wave (binary one and zero respectively).

This type of modulation is quite popular due to its simplicity and rather low implementation costs. Its main advantage is that it can let the transmitter run in idle while transmitting zeros, which can preserve power. The biggest disadvantage of the technology is its sensitivity to noise. Since zero means nothing is transmitted, with a significant amount of background noise the ones and zeros can be a challenge to distinguish on the receiving end.

Radio configurator setup

Create a new RAILTEST example application to set up the radio link in the radio configurator. It is easier to start with a base profile, in our case we chose one of the 915 MHz profiles. Naturally, you can set the profile and the following settings based on your requirements.

General radio link parameters

After all the settings were loaded, switch to "Custom settings" to enable edit. Here choose OOK as the modulation type to switch to On-off Keying modulation.  In our case the data rate is set to 4.8 Kbps, as OOK transmissions are usually used with lower data rates. For this modulation, deviation is not relevant. 

Important: Make sure to uncheck all settings under the "Advanced tab" in the bottom, letting the configurator determine all the parameters.

If you are setting up a receiver, also make sure to define your RX and TX crystal accuracy under the "Crystal" tab. This will help the configurator determine a valid receive bandwidth. Alternatively, if you have a predefined receiver bandwidth, you can set it under the Advanced section, "Channel bandwidth" option. If neither the crystal accuracy nor the bandwidth is known, in general 200 kHz can be recommended.

BT parameter recommendations

At this point the modulation probably will not work yet, as the Shaping Filter Parameter (BT) is set for FSK2 (or any other which you used as a base profile) and not for OOK modulation. Set this parameter to 1.5 for the best results, see explanation below.

In yellow you can see the output and its spectrum generated with low BT parameter, in this case 0.5. It's visible how the signal is over-filtered, the edges are rounded down too much for the receiver to interpret this as an OOK modulation.

We can get an ideal OOK output signal by completely disabling the filtering, these outputs are marked with purple. You can see it on the time domain diagram how perfect it looks like, however significant background noise and regular side-bands appeared on its spectrum at the same time.

The output of the recommended configuration with the Gaussian filter on, using a BT of 1.5 is marked with teal on the figures. In time domain a lesser "rounding" effect came back, however by using this filter we can suppress the side-bands of the spectrum emission and less background noise is generated, while the receiver can interpret the signal without any issue.

Therefore, for the best results our recommended value is 1.5 for the BT parameter. See the final settings of the radio link below.

You can also find this configuration attached for the aforementioned base band and radio board.

Testing the radio link using railtest

With the settings above applied, it's time to generate the example code and build, flash it on the devices. After opening the console on both targets, or by just pushing the PB0 a few times shortly, we can check the functionality of the radio link.

See a test method with results in the following to get an approximate PER of the link created:

TX side

RAIL Test App - Built: Feb 12 2019 11:13:18
> settxdelay 10
{{(setTxDelay)}{txDelay:10}}
> tx 1000
> {{(tx)}{PacketTx:Enabled}{None:Disabled}{Time:47701122}}
{{(appMode)}{None:Enabled}{PacketTx:Disabled}{Time:84048987}}
{{(txEnd)}{txStatus:Complete}{transmitted:1000}{lastTxTime:84048937}{failed:0}
{lastTxStatus:0x0}{isAck:False}}

RX side

RAIL Test App - Built: Feb 12 2019 11:13:18
> setnotifications 0
{{(setNotifications)}{Peripherals:Enabled}{Notifications:Disabled}}
> status
{{(status)}{UserTxCount:0}{AckTxCount:0}{UserTxAborted:0}{AckTxAborted:0}{UserTxBlocked:0}
{AckTxBlocked:0}{UserTxUnderflow:0}{AckTxUnderflow:0}{RxCount:999}{SyncDetect:999}
{NoRxBuffer:0}{RfSensed:0}{ackTimeout:0}{ackTxFpSet:0}{ackTxFpFail:0}{RfState:Rx}
{RAIL_state_active:0}{RAIL_state_rx:1}{RAIL_state_tx:0}{Channel:0}{AppMode:None}
{TimingLost:0}{TimingDetect:0}{FrameErrors:0}{RxOverflow:0}{AddrFilt:0}{Aborted:0}
{Calibrations:1}{TxChannelBusy:0}{TxClear:0}{TxCca:0}{TxRetry:0}}

As you can see out of a 1000 packets sent with rather small delay, 999 arrived successfully, resulting a 0.1% error rate, which can be considered acceptable.