The scope of this document is to specify Wi-SUN Packet Test setup for EFR32, detailed parameter settings and expected results for compliance to the IEEE 802.15.4-2015 SUN PHY specification.
A received packet is determined to be in error if the FCS does not match or the packet was not detected. Unless otherwise specified, the method based on PER shall be implemented for error rate measurement.
What we need to do is to setup a correct SUN PHY packet, then run Railtest for PER test.
2.SUN PHY packet
We use 20 octets SUN FSK(2-FSK) data as an example. In the tests, the 4-octet or 2-octet FCS are appended to the data sequence to create the frame, i.e. the FCS is included in the frame and the frame length indicated above including the length of the FCS (2 octets or 4 octets). SHR and PHR are appended to the frame to create packets. Unless otherwise specified in a particular test, the PHR and PSDU are un-coded, data whitening and mode switch are disabled. The SHR and PHR are set according to section 20.2 [IEEE Std. 802.15.4 - 2015].
2.1 SHR field
The SHR field shall be formatted as illustrated with following figure
2.1.1 Preamble field
The Preamble field shall contain phyFskPreambleLength multiples of the 8-bit sequence “01010101” for 2-FSK.
2.1.2 SFD field
The SFD for 2-FSK shall be a 2-octet sequence selected from the values shown in following table.
2.2 PHR field
2.3 PHY Payload field
2.3.1 Payload code
The PHY Payload field carries the PSDU, in this example it is unencoded.
2.3.2 FCS field
The FCS is located at MFR field. It contains a 16-bit ITU-T CRC or a 32-bit CRC equivalent to ANSI X3.66-1979. The FCS is calculated over the MHR and MAC payload parts of the frame.
3.Data sequence setup on Signal Generator
Bellow data get from section 8.3 [Wi-SUN-PHY-Conformance-Test-Suite-Specification-1V17_RC1]
CRC Polynomial is ANSI X3.66-1979, the seed is 0xFFFFFFFF.
How to determine the FCS will be illustrated in following section.
The full data of frame as shown below
4.Configuration on EFR32 Railtest Project
We need to configure the payload according to SUN-FSK PHY specification, so that EFR32 device can receive the packet. Packet data in LSB order unless stated otherwise.
SUN-FSK defines the length field MSB first. The length can be handled by the hardware, just keep in mind that you must reverse the endianness of these bytes for both RX and TX in the application. All configurations as shown below.
Preamble configuration
SFD configuration (Sync word is SFD)
PHR configuration
FCS configuration (CRC seed is 0xFFFFFFFF)
5.Determine FCS of payload data
FCS contains a 32-bit CRC. The CRC can be calculated by a given polynomial. But it is much reliable if use a sniffer to catch it. We need 2 WSTK boards in this test, we call them TX and Sniffer. TX packet configure just refer to above configuration. Sniffer packet configuration as shown below figure. The payload data list of above contains 16 bytes data plus 4 bytes CRC, so we set the sniffer frame length to fixed 20 bytes. Uncheck the CRC payload, so the sniffer will regard received CRC as a real data and show it up.
Segger J-Link utilities are available for ARM based systems which means it works on Raspberry Pi (regardless of model) Singe Board Computer. It becomes very handy if your WSTK is attached to a Raspberry Pi and you need to update the firmware of a radio board.
Accept the license agreement and download the install archive file (.tar.gz format). If there is no graphical environment running on the Raspberry Pi, maybe it is easier to download the install package on a PC then transfer the file to the SBC.
Extract the archive in a preferred directory and change the directory where the files extracted to.
Usually, is not a good practice to run the tool as root, but rather as a normal user. To achieve this, copy the 99-jlink.rules file to the /etc/udev/rules.d/ directory. Either reboot the system or issue the udevadm control --reload-rules && udevadm trigger command to immediately reload udev rules without reboot.
On older systems you may need to change the 99-jlink.rules file content like:
Issue the ./JLinkExe commad to start the utility. The following screen should appear:
First, the appropriate device must be selected:
J-Link>device EFR32FG14XXXF256 (replace the device which the one matches your hardware)
Issue the command. In the next step specify the hardware settings (except the target interface, which is SWD) keep everything as its default value.
To erase the internal flash issue the erase command:
The firmware image (both .hex and .s37 files are supported) can be downloaded to the chip by the loadfile filename command (assuming the firmware is already copied to the appropriate directory on the Raspberry Pi):
Finally, issue the r (reset target) and g (go) command to execute the firmware:
Exit from J-Link by issuing qc command (close JLink connection and quit).
Additionally it is possible to automate the above process by creating a J-Link script, for example create a script like the one below:
eraseloadfile /home/pi/test_firmware.s37rgqc
Save as test.jlink for example and call J-Link executable with the following parameters:
The WSTK boards factory programmed to support 115200bps. This may no suitable for custom firmware thus there is a possibility to set the baud rate to customer specific value.
To change the VCOM speed first it is necessary to access the Admin console on the WSTK. Currently, two methods are supported:
telnet (using Ethernet connection of the board, supported by all board contoller firmware versions)
Simplicity Studio's Admin console access (supported with board controller firmware 1.1.1+ and recent Studio only)
The console commands are identical for both method.
Access through Ethernet network
To access the Admin console through telnet first need to connect the WSTK to an Ethernet network which provides DHCP server.
If the WSTK's built-in DHCP client was able to receive the address and network configuration was successful, the IP address will appear on the kit's LCD screen.
Use that address to connect to the board by telnet program (you may need to enable / install telnet on - refer to your OS manual about details).
The Admin console accessible on port 4902 (replace the IP address with the one appears on your LCD screen):
telnet 10.5.146.86 4902
On successful connection the prompt WSTK> should appear.
Access from Simplicity Studio
To access the console from Simplicity Studio, only the USB port has to be connected. Select the required J-Link adapter, right-click on it and click on Launch console...
When the console appears Switch to the Admin tab at the top then click into the input text box at the bottom press Enter. The WSTK> prompt should appear.
Changing the baud rate of the Virtual COM port
By issuing the help command a few lines of help appears about the usage of the Admin console:
*************** Root commands ****************
aem AEM commands [ calibrate, current, dump, ... ]
boardid Commands for board ID probe. [ list, probe ]
dbg Debug interface status and control [ info, mode,]
dch Datachannel control and info commands [ message ]
discovery Discovery service commands. [ key ]
net Network commands. [ dnslookup, geoprobe, ip ]
pti Packet trace interface status and control [ config, disable, dump, ... ]
quit Exit from shell
serial Serial channel commands [ vcom ]
sys System commands [ nickname, reset, scratch, ... ]
target Target commands. [ button, flashwrite, go, ... ]
time Time Service commands [ client, disable, server, ... ]
user User management functions [ login,]
WSTK>
To change the Virtual COM port baud rate to 9600bps issue the following command: serial vcom config speed 9600
There is also possible to set handshaking method by issuing the serial vcom config handshake ... command.
This article describes the format of monochrome (1-bit, black and white) pixmap that can be used with various LCDs including the one attached to BRD4001A WSTK.
In case of monochrome images one pixel need one bit to store thus on one byte 8 pixels can be stored. Due to the limited flash memory of the MCUs it is straightforward to optimize memory occupation of a picture and minimize wasted space. To achieve this, GLIB packs the bits of the image to eliminate unused memory spots.
The following example will use a 9 column wide and 9 row tall picture to show how the pixel data transformed to GLIB pixmap format. The picture we will transform to GLIB pixmap is a smiley:
In a GLIB pixmap the pixels are black and white however, the image can be normal or inverted so it may better to reference pixel state as "on" and "off" where "off" means the pixel matches with the background color while "on" means pixel has foreground color. In the picture above column 0 / row 0 spot is "off" and column 2 / row 0 is "on". Bit value "0" corresponds to "off" state, "1" represents "on".
The (0;0) coordinate of the pixmap is in the upper-left corner. The example image is 9 bit wide thus a row obviously not possible to store in 1 byte (8 bits) thus the last pixel of the first row pushed to the next byte. The pixels of the next rows are shifted to fill the space in the consecutive bytes as the figure below shows.
This way the 9-bit row patterns are arranged into 8-bit bytes. The whole image needs 81 bits but this does not exactly fit into integer number of bytes so, there will be unused bits in the last byte (seven unused bits marked with "X" in the left side figure and their values are irrelevant).
Pixel (0;0) of the picture is bit 0 of byte 0 of the image data, (1;0) is byte 0 / bit 1, (9;0) is byte 1 / bit 0, (0;1) is byte 1 / bit 1, and so on. Based on this the data bytes are:
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 is a graphics library that can be used to draw pixels, common shapes, text or bitmaps to a display connected to an MCU. GLIB treats the display as a matrix of pixels which is a model of the physical display. This matrix is exposed to GLIB via an API called DMD (Dot Matrix Display). To draw something on a physical display, the user application needs to provide GLIB with a single implementation of the DMD interface. Sample DMD implementations are provided for the displays that are connected to the Silicon Labs Starter Kits and the Silicon Labs Development Kits.
References
Detailed description is available in the Software documentation of your device. See the same for the Giant Gecko here for your reference.
For an extensive feature showcase, please see MCU example “SLSTKxxxxx_glib” for your MCU development kit in Simplicity Studio.
Initialization
First, glib needs several libraries to be included to work, such as display.h for display specific settings, dmd.h for the Dot Matrix Display library and glib.h for the graphics library itself. The graphics library uses a context for each display. This context must be defined before using glib with
static GLIB_Context_t glibContext;
All the previously listed libraries must be initialized to enable drawing on the screen, by calling the followings:
EMSTATUS status;
/* Initialize the display module. */
status = DISPLAY_Init();
if (DISPLAY_EMSTATUS_OK != status) {
while (1) ;
}
/* Initialize the DMD module for the DISPLAY device driver. */
status = DMD_init(0);
if (DMD_OK != status) {
while (1) ;
}
/* Initialize the glib context */
status = GLIB_contextInit(&glibContext);
if (GLIB_OK != status) {
while (1) ;
}
Drawing on the screen
Drawing usually consist of three steps. First, if we do not want to overlap the previously displayed content and/or are not partially rewriting the display, we should clear it first by calling GLIB_clear(&glibContext). The next step is to set the display content in the context by drawing something on the screen with GLIB_drawXXXX() where XXXX can stand for String, Bitmap, Circle, etc. After the content is set, the last step is to update the display using the DMD driver using DMD_updateDisplay().
In the above example a welcome text is written on the screen. First, we set the back- and foreground colors in the glibContext to white and back respectively. Then, as mentioned before, a screen clear is performed. Before calling the GLIB_drawString() function, the font is set to normal in the context and the string is put together into one character array. The GLIB_drawString() is called with the context, string and its length, along with the X and Y coordinate of the text and with the opaque setting last. The example displays the following on a Giant Gecko STK board:
Updating parts of the screen
When not all the information is outdated on the screen, partial update can be used. In this case do not clear the screen, as then all screen content will be lost. GLIB_clearRegion should be used instead, after setting the clipping region with the GLIB_setClippingRegion() function. This function needs a rectangle as an input, this will be the area the GLIB_clearRegion will clear out. After the clear is complete, you can draw in this territory by providing the appropriate X and Y coordinates to the draw function.
if (refresh) {
GLIB_setClippingRegion(&glibContext, &upperArea);
GLIB_clearRegion(&glibContext);
msgYOffset = 2;
} else {
GLIB_setClippingRegion(&glibContext, &lowerArea);
GLIB_clearRegion(&glibContext);
msgYOffset = 7;
}
/* Update only the current message region using msgYOffset */
GLIB_resetClippingRegion(&glibContext); //reset the clipping region to default
GLIB_applyClippingRegion(&glibContext); //application is not included in the resetting
sprintf(text, "Message from %d,\nRSSI: %d dBm", message->source, message->rssi);
GLIB_drawString(&glibContext, text, strlen(text), X_BORDER,
Y_BORDER + (glibContext.font.fontHeight + glibContext.font.lineSpacing) * msgYOffset, 0);
//print to the upper or lower area using msgYOffset
/* Update display */
DMD_updateDisplay();
refresh = !refresh;
The above example shows a way to display incoming messages alternately in the upper and the lower part of the screen. A previously defined upper and lower area clipping region is cleared and the upper or lower message is displayed using the predefined screen borders and the available font height and line spacing in the glib context.
The Connect stack support MAC mode. Although the Connect stack implements a full-featured network layer, including routing, supporting start and extended start topologies, network formation functionality (association, centralized address allocation), it supports MAC mode as well. In MAC mode, nodes can only communicate directly to each other and no routing is available.
The 802.15.4 MAC layer is used for basic message handling and congestion control and provides security functionality (scanning, authentication, encryption and replay attack protection). Packet size is up to a maximum of 127 bytes at the PHY layer. The MAC layer payload can vary depending on the security options and addressing type as illustrated in the figure below.
Simlpicity Studio provides example project for testing MAC mode. A MAC-device is able to send and receive standard 802.15.4 messages from other 802.15.4 devices in range. Such a device does not relay messages.
Open the following example from Simplicity Studio:
The AppBuilder automatically opens and and make it possible to change the configuration. The default settings are suitable to test MAC mode. Click on 'Generate', compile the project and run on two devices.
Open a terminal (ex.: TeraTerm) an check if the firmware works. After boot the following screen should be appear:
In case of MAC mode there are two modes to setup the devices:
directly commission the network parameters to the devices
setup a coordinator by commission network parameters and allow other devices to join
Before setup the devices it is a good practice to issue the leave command to clear network parameters.
To apply network parameters issue the join-commissioned command:
Directly commissioned network parameters to all devices
join-commissioned 6 0x0001 0xabcd 0 0 where the parameters in order are:
Node type: 6 (6: MAC mode device, 7: MAC mode sleepy device)
Node ID: 0x0001 (must be unique in one PAN)
PAN ID: 0xabcd
TX power: 0
Channel: 0
Issue the command above with different (ex: 0x0002) Node ID on the other device. To check the parameters issue the info that will list the following parameters:
At this point the devices can send messages to each other using the send command. This command has multiple forms based on the addressing modes on source and destination side The following example uses long address for both side:
On the transmitter side the following output should appear:
While the receiver side should print info about reception:
Since the long address is unique for every chip it must be replaced by the actual value to use the example. Since the long address is unique for every chip it must be replaced by the actual value to use the example.
The parameters of the send command are:
"nibble mask": 0x0033 (long address is used on both sides - detailed explanation below)
Source short address: 0xffff (not used in this addressing mode)
Source long address: {99 7c a2 fe ff 57 0b 00}
Destination short address: 0xffff (not used in this addressing mode)
Destination long address: {6f 7c a2 fe ff 57 0b 00}
Source PAN ID: 0xffff (not used in this addressing mode)
Destination PAN ID: 0xffff (not used in this addressing mode)
The addressing format can be mixed, using long address for one of the nodes and short for the other. It is also possible to send message between different PANs (inter-PAN messages).
Setup a coordinator by commission network parameters and allow other devices to join
In this case one node must be coordinator and its network parameters have to commissioned just like in the case above:
join-commissioned 6 0x0000 0xf000 0 0
The other devices have to join to the network, however by default joining is not enabled issue the following command on the coordinator to permit nodes to join:
pjoin 255
The parameter is the time in second during the joining is permitted. There are two special values:
0: joining is not permitted
255 joining is permitted without timeout
On the end-devices issue the join command:
join 6 0xabcd 0 0
The parameters of the join command are:
Node type: 6 (6: MAC mode device, 7: MAC mode sleepy device)
PAN ID: 0xabcd
TX power: 0
Channel: 0
The coordinator assigns random short address to the devices.
Sending messages works the same as in direct commissioned mode.
Join modes
Joining nodes can be MAC-level devices or Sleepy devices. Sleepy devices must poll the parent node for any messages waiting for them to be received. For sleepy nodes, the parent node should have the Parent Support plugin enabled.
RAIL provides some useful options when transmitting and receiving packets. In this tutorial, we're going to cover those.
Tx options
The main tx options should be passed to RAIL using the RAIL_TxOptions_t parameter of the StartTx APIs. The available options are:
RAIL_TX_OPTION_REMOVE_CRC: Ignores the config's CRC setting and does not transmit CRC
RAIL_TX_OPTION_SYNC_WORD_ID: If set, Tx will use the second configured syncword. If unset, it will use the first one
RAIL_TX_OPTION_ANTENNA0: Use antenna0 (usually used when 2 antennas are available for antenna diversity)
RAIL_TX_OPTION_ANTENNA1: Use antenna1 (usually used when 2 antennas are available for antenna diversity)
RAIL_TX_OPTION_WAIT_FOR_ACK: Waits for ACK after transmitting a packet. I.e. the radio will automatically switch to Rx mode after Tx (disregarding auto state transitions) with a timeout.
The usual groups are also defined: RAIL_TX_OPTIONS_ALL, RAIL_TX_OPTIONS_NONE and RAIL_TX_OPTIONS_DEFAULT (which is the same as none).
Listen before talk options
Listen before talk setups are often required in protocols, and a good idea to implement in some proprietary protocols as well: It solves most collisions between transmissions.
Listen before talk operations are built up from 2 tasks:
CCA (Clear channel assessment): the "listen" itself, where the radio is in rx, measuring rssi
Backoffs: randomized delays between CCA operations
Generally, the radio starts with CCA: If the RSSI is below threshold, it starts transmitting. If not, it waits a random backoff period and tries again. The radio should repeat this with increasing backoff periods, until successful transmission or timeout.
CCA period on EFR32 has a limitation: it must take power of 2 number of symbols, i.e. symboltime\*2^x (where x>=1).
The backoffs are implemented on the same timer that handles the scheduling, so it could cause problems if you start a listen before start operation from a scheduled rx, and scheduled listen before talk tx operations are not supported.
CSMA/CA
The most common listen before talk protocol is CSMA/CA, which is fully supported by the EFR32 hardware, including retransmissions. CSMA/CA defines backoffs as a random number between 0 and unit\*2^BE, where BE is the backoff exponent, which should be incremented with each retries.
To trigger a CSMA/CA transmission, you can start transmitting with RAIL_StartCcaCsmaTx instead of RAIL_StartTx. It has an extra parameter, with the type of RAIL_CsmaConfig_t, that configures the CSMA/CA parameters:
ccaBackoff the backoff unit in us.
csmaMinBoExp and csmaMaxBoExp are setting the minimum and maximum backoff exponent (i.e. the first value of BE will be csmaMinBoExp, and it won't increment further if it reached chmaMaxBoExp)
csmaTries sets the number of tries, i.e. how many CCA should be performed before reporting back an error. Setting it to 0 will disable CSMA/CA
ccaDuration sets the duration the CCA should take in us (i.e. how long it should average the rssi).
csmaTimeout in us if the csma/ca operation exceeds this timeout it will stop. This is useful, since due to the random backoffs, the csma/ca duration can vary. Set it to 0 to disable the timeout.
There's also a special setup: if csmaMinBoExp and csmaMaxBoExp are both set to 0, that means a fixed backoff configuration. In this case, the backoff will always take the time set in ccaBackoff.
LBT
Another common listen before talk protocol is the obviously named LBT: LBT defines backoffs as a unit\*BO, where BO is a random number between a minimum and maximum.
LBT is not supported by the EFR32 hardware, it is converted to a CSMA/CA configuration in RAIL. Because of this, if you can chose between the two, you should chose CSMA/CA.
Note that LBT can be configured with a minimum backoff limit, while CSMA/CA's minimum backoff period is always 0. This is not supported by the hardware, so LBT is implemented with a bit of cheating. The CCA period is set to the configured period + unit*minBO. It doesn't really matter if the CCA period is longer, and this guarantees that the minimum backoff is fulfilled
Another limitation is that the maximum backoff must be power of 2, so the configured backoff will be rounded to the closest power of 2
Much like CSMA/CA, LBT has its own StartTx API, RAIL_StartCcaLbtTx, which has the config struct, RAIL_LbtConfig_t to configure the LBT parameters:
lbtBackoff is the backoff unit in us.
lbtMinBoRand and lbtMaxBoRand are setting the limits of the random backoff, just like with CSMA/CA, setting it both to 0 selects the fixed backoff mode
lbtTries sets the number of tries, i.e. how many CCA should be performed before reporting back an error. Setting it to 0 will disable LBT
lbtDuration sets the duration the CCA should take in us (i.e. how long it should average the rssi).
lbtTimeout if the LBT operation exceeds this timeout (in us) it will stop. This is useful, since due to the random backoffs, the csma/ca duration can vary. Set it to 0 to disable the timeout.
Custom listen before talk
Custom listen before talk protocols are not supported. However it might be possible to achieve it, using RAIL_GetRssi(), RAIL_StartAverageRSSI() and regular RAIL_StartRx().
Rx options
Rx options can be configured using RAIL_ConfigRxOptions, which takes two RAIL_RxOptions_t parameter, mask and options. This way, it's easy to change one option, without knowing others. The available options:
RAIL_RX_OPTION_ANTENNA0 Use antenna0 (usually used when 2 antennas are available for antenna diversity)
RAIL_RX_OPTION_ANTENNA1 Use antenna1 (usually used when 2 antennas are available for antenna diversity)
RAIL_RX_OPTION_ANTENNA_AUTO Use both antennas, with antenna diversity (must be configured before using it)
RAIL_RX_OPTION_DISABLE_FRAME_DETECTION disables the frame detection system. Useful, if you only want to check the energy of a channel, and do not want to receive frames, because it would break the application's state machines
RAIL_RX_OPTION_ENABLE_DUALSYNC Enables the detection of both sync word
RAIL_RX_OPTION_IGNORE_CRC_ERRORS Frames will be received even if it failed CRC check. When enabled, the result of the CRC check will be stored in RAIL_RxPacketDetails_t.crcPassed.
RAIL_RX_OPTION_REMOVE_APPENDED_INFO Disables the storage of the appended info. Appended info is used to store the base of RAIL_RxPacketDetails_t, like timestamp and rssi. If not needed, it can be disabled, saving some buffer space
RAIL_RX_OPTION_STORE_CRC By default, RAIL does not store the CRC, only checks it. By enabling this, it will store it as well. It can be used for example for sniffer applications
RAIL_RX_OPTION_TRACK_ABORTED_FRAMES RAIL aborts frame reception when it filters it using the address filter. With this option enabled, it will receive the full frame (but still generates the correct error event) so the network analyzer can display it (through PTI).
The usual groups are also defined: RAIL_RX_OPTIONS_ALL, RAIL_RX_OPTIONS_NONE and RAIL_RX_OPTIONS_DEFAULT (which is the same as none).
Some options, like the antenna selections will restart receive mode (if changed in receive mode).
Address filtering
EFR32 supports hardware based address filtering, as long as the address is stored in the same location in all the frames (unlike 802.15.4, which is only supported through its special API). EFR32 supports 2 address fields (e.g. for group and device address), both can be up to 8 Bytes long. Both fields can be configured for up to 4 addresses (e.g. for broadcast, unicast and 2 multicast address). Any combination can be allowed on these two fields, e.g. enable address1 for field0 only if field1 has addressA, or if field0 has address2, anything is allowed on field1.
Enabling the address filter starts with configuring it, using
Its only parameter (apart from the usual railHandle) is RAIL_AddrConfig_t. RAIL_AddrConfig_t configures
offsets[2], which sets the offset of the addresses in the frame (for the first field, from the end of sync word, for the second field, from the end of the first field. Note that this means that the fields cannot overlap.)
sizes[2], which sets the size of the fields in byte. Setting it to 0 disables the field.
matchTable which configures the enabled combinations of the fields
If you only use a single field, you can safely use ADDRCONFIG_MATCH_TABLE_SINGLE_FIELD. If you need both address fields, you should understand how the match table works. That is out of the scope of this tutorial, but you can rely on the API documentation and this KBA.
Which will enable the address 0xAABBCCDD on field 0, index 1, in enabled state. Make sure your address length matches what you configured for the field. You can later disable (and re-enable) it with
Note that this API is referencing the address by its field and index. If you want to enable/disable addresses based on the value, i.e. the address itself, you should track which index is used for each address.
Finally, to enable (or disable) the whole address filter, use
RAIL_EnableAddressFilter(railHandle, true);
Once address filter is enabled, you can get notifications on filtered frames using the RAIL_EVENT_RX_ADDRESS_FILTERED event.
Proprietary Knowledge Base
Wi-SUN PHY Packet Test on EFR32
1.Introduction
The scope of this document is to specify Wi-SUN Packet Test setup for EFR32, detailed parameter settings and expected results for compliance to the IEEE 802.15.4-2015 SUN PHY specification.
A received packet is determined to be in error if the FCS does not match or the packet was not detected. Unless otherwise specified, the method based on PER shall be implemented for error rate measurement.
What we need to do is to setup a correct SUN PHY packet, then run Railtest for PER test.
2.SUN PHY packet
We use 20 octets SUN FSK(2-FSK) data as an example. In the tests, the 4-octet or 2-octet FCS are appended to the data sequence to create the frame, i.e. the FCS is included in the frame and the frame length indicated above including the length of the FCS (2 octets or 4 octets). SHR and PHR are appended to the frame to create packets. Unless otherwise specified in a particular test, the PHR and PSDU are un-coded, data whitening and mode switch are disabled. The SHR and PHR are set according to section 20.2 [IEEE Std. 802.15.4 - 2015].
2.1 SHR field
The SHR field shall be formatted as illustrated with following figure
2.1.1 Preamble field
The Preamble field shall contain phyFskPreambleLength multiples of the 8-bit sequence “01010101” for 2-FSK.
2.1.2 SFD field
The SFD for 2-FSK shall be a 2-octet sequence selected from the values shown in following table.
2.2 PHR field
2.3 PHY Payload field
2.3.1 Payload code
The PHY Payload field carries the PSDU, in this example it is unencoded.
2.3.2 FCS field
The FCS is located at MFR field. It contains a 16-bit ITU-T CRC or a 32-bit CRC equivalent to ANSI X3.66-1979. The FCS is calculated over the MHR and MAC payload parts of the frame.
3.Data sequence setup on Signal Generator
Bellow data get from section 8.3 [Wi-SUN-PHY-Conformance-Test-Suite-Specification-1V17_RC1]
Preamble:
64bit preamble
SFD:
PHR:
PHR comprises bits that indicate the following settings:
Mode Switch = 0
FCS = 4 Byte
Data Whitening = Off
Frame Length = 20
DATA:
Note that the DATA bytes are sent in LSB order.
FCS:
CRC Polynomial is ANSI X3.66-1979, the seed is 0xFFFFFFFF.
How to determine the FCS will be illustrated in following section.
The full data of frame as shown below
4.Configuration on EFR32 Railtest Project
We need to configure the payload according to SUN-FSK PHY specification, so that EFR32 device can receive the packet. Packet data in LSB order unless stated otherwise.
SUN-FSK defines the length field MSB first. The length can be handled by the hardware, just keep in mind that you must reverse the endianness of these bytes for both RX and TX in the application. All configurations as shown below.
5.Determine FCS of payload data
FCS contains a 32-bit CRC. The CRC can be calculated by a given polynomial. But it is much reliable if use a sniffer to catch it. We need 2 WSTK boards in this test, we call them TX and Sniffer. TX packet configure just refer to above configuration. Sniffer packet configuration as shown below figure. The payload data list of above contains 16 bytes data plus 4 bytes CRC, so we set the sniffer frame length to fixed 20 bytes. Uncheck the CRC payload, so the sniffer will regard received CRC as a real data and show it up.
Set payload on TX side, and transmit it.
Get payload in Sniffer.
The last four bytes are CRC data which is “0x88 0xe2 0xce 0xce”. Data bit should reverse in Signal Generator.
The project files can be found in attachment,they are base on EFR32MG13P733F512GM48(BRD4158A).
6.Test Environment
PC (Win10, Simplicity Studio V4, Flex SDK V2.3.1.0, Control EFR32 device by CLI)
EFR32 (WSTK/Custom board)
Signal Generator (Agilent E4432B)
7.Acronyms and abbreviations
CLI Command Line Interface
CRC Cyclic Redundancy Check
FCS frame check sequence
LSB Least Significant Bit
MFR MAC footer
MHR MAC header
PER packet error rate
PHR PHY header
PSDU PHY service data unit
SFD Start of Frame Delimiter
SHR synchronization header
Wi-SUN Wireless Smart Utility Network
8.Reference
Update EFR32 firmware using J-Link on Raspberry Pi (command line)
Segger J-Link utilities are available for ARM based systems which means it works on Raspberry Pi (regardless of model) Singe Board Computer. It becomes very handy if your WSTK is attached to a Raspberry Pi and you need to update the firmware of a radio board.
The J-Link tool available from Segger:
https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack
Select the ARM version and click on
DOWNLOAD:Accept the license agreement and download the install archive file (.tar.gz format). If there is no graphical environment running on the Raspberry Pi, maybe it is easier to download the install package on a PC then transfer the file to the SBC.
Extract the archive in a preferred directory and change the directory where the files extracted to.
Usually, is not a good practice to run the tool as root, but rather as a normal user. To achieve this, copy the
99-jlink.rulesfile to the/etc/udev/rules.d/directory. Either reboot the system or issue theudevadm control --reload-rules && udevadm triggercommand to immediately reload udev rules without reboot.On older systems you may need to change the
99-jlink.rulesfile content like:SUBSYSTEMS=="usb", ATTRS{idVendor}=="1366", ATTRS{idProduct}=="0105", MODE:="0666"to make the tool work for non-root users.
Issue the
./JLinkExecommad to start the utility. The following screen should appear:First, the appropriate device must be selected:
J-Link>device EFR32FG14XXXF256(replace the device which the one matches your hardware)Issue the command. In the next step specify the hardware settings (except the target interface, which is SWD) keep everything as its default value.
To erase the internal flash issue the
erasecommand:The firmware image (both .hex and .s37 files are supported) can be downloaded to the chip by the
loadfile filenamecommand (assuming the firmware is already copied to the appropriate directory on the Raspberry Pi):Finally, issue the
r(reset target) andg(go) command to execute the firmware:Exit from J-Link by issuing
qccommand (close JLink connection and quit).Additionally it is possible to automate the above process by creating a J-Link script, for example create a script like the one below:
Save as
test.jlinkfor example and call J-Link executable with the following parameters:./JLinkExe -device EFR32FG14PXXXF256 -if SWD -speed 4000 -autoconnect 1 -CommanderScript /home/pi/test.jlinkThe method above allows to update the firmware of the radio board even if the system is at a remote location.
WSTK Virtual COM port baudrate setting
The WSTK boards factory programmed to support 115200bps. This may no suitable for custom firmware thus there is a possibility to set the baud rate to customer specific value.
To change the VCOM speed first it is necessary to access the Admin console on the WSTK. Currently, two methods are supported:
The console commands are identical for both method.
Access through Ethernet network
To access the Admin console through telnet first need to connect the WSTK to an Ethernet network which provides DHCP server.
If the WSTK's built-in DHCP client was able to receive the address and network configuration was successful, the IP address will appear on the kit's LCD screen.
Use that address to connect to the board by telnet program (you may need to enable / install telnet on - refer to your OS manual about details).
The Admin console accessible on port 4902 (replace the IP address with the one appears on your LCD screen):
telnet 10.5.146.86 4902On successful connection the prompt
WSTK>should appear.Access from Simplicity Studio
To access the console from Simplicity Studio, only the USB port has to be connected. Select the required J-Link adapter, right-click on it and click on Launch console...
When the console appears Switch to the Admin tab at the top then click into the input text box at the bottom press Enter. The
WSTK>prompt should appear.Changing the baud rate of the Virtual COM port
By issuing the help command a few lines of help appears about the usage of the Admin console:
To change the Virtual COM port baud rate to 9600bps issue the following command:
serial vcom config speed 9600There is also possible to set handshaking method by issuing the
serial vcom config handshake ...command.GLIB monochrome pixmap format
This article describes the format of monochrome (1-bit, black and white) pixmap that can be used with various LCDs including the one attached to BRD4001A WSTK.
In case of monochrome images one pixel need one bit to store thus on one byte 8 pixels can be stored. Due to the limited flash memory of the MCUs it is straightforward to optimize memory occupation of a picture and minimize wasted space. To achieve this, GLIB packs the bits of the image to eliminate unused memory spots.
The following example will use a 9 column wide and 9 row tall picture to show how the pixel data transformed to GLIB pixmap format. The picture we will transform to GLIB pixmap is a smiley:
In a GLIB pixmap the pixels are black and white however, the image can be normal or inverted so it may better to reference pixel state as "on" and "off" where "off" means the pixel matches with the background color while "on" means pixel has foreground color. In the picture above column 0 / row 0 spot is "off" and column 2 / row 0 is "on". Bit value "0" corresponds to "off" state, "1" represents "on".
The (0;0) coordinate of the pixmap is in the upper-left corner. The example image is 9 bit wide thus a row obviously not possible to store in 1 byte (8 bits) thus the last pixel of the first row pushed to the next byte. The pixels of the next rows are shifted to fill the space in the consecutive bytes as the figure below shows.
This way the 9-bit row patterns are arranged into 8-bit bytes. The whole image needs 81 bits but this does not exactly fit into integer number of bytes so, there will be unused bits in the last byte (seven unused bits marked with "X" in the left side figure and their values are irrelevant).
Pixel (0;0) of the picture is bit 0 of byte 0 of the image data, (1;0) is byte 0 / bit 1, (9;0) is byte 1 / bit 0, (0;1) is byte 1 / bit 1, and so on. Based on this the data bytes are:
0b01111100->0x7c0b00000100->0x040b00000101->0x05...The whole data array should look like this:
To use the created pixmap issue the GLIB
GLIB_drawBitmap()API call. Further reading on using GLIB can be found in Displaying on the LCD screen using glib.Article Creating monochrome bitmap files for LCD / GLIB using GIMP shows how to create monochrome GLIB pixmaps with GIMP using the plug-in developed for that purpose.
Creating monochrome bitmap files for LCD / GLIB using GIMP
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.hwill be created containingTHERMOMETER_WIDTHandTHERMOMETER_HEIGHTdefines and a C file namedthermometer.ccontainingthermometer_bitsarray.To use the pixmaps created with GIMP simply include the header file in the project, for example:
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:
For further reference of using GLIB library see the Displaying on the LCD screen using glib knowledge base article.
Detailed description of GLIB pixmap format can be found in GLIB monochrome pixmap format.
Displaying on the LCD screen using glib
Introduction
GLIB is a graphics library that can be used to draw pixels, common shapes, text or bitmaps to a display connected to an MCU. GLIB treats the display as a matrix of pixels which is a model of the physical display. This matrix is exposed to GLIB via an API called DMD (Dot Matrix Display). To draw something on a physical display, the user application needs to provide GLIB with a single implementation of the DMD interface. Sample DMD implementations are provided for the displays that are connected to the Silicon Labs Starter Kits and the Silicon Labs Development Kits.
References
Detailed description is available in the Software documentation of your device. See the same for the Giant Gecko here for your reference.
For an extensive feature showcase, please see MCU example “SLSTKxxxxx_glib” for your MCU development kit in Simplicity Studio.
Initialization
First, glib needs several libraries to be included to work, such as
display.hfor display specific settings,dmd.hfor the Dot Matrix Display library andglib.hfor the graphics library itself. The graphics library uses a context for each display. This context must be defined before using glib withAll the previously listed libraries must be initialized to enable drawing on the screen, by calling the followings:
Drawing on the screen
Drawing usually consist of three steps. First, if we do not want to overlap the previously displayed content and/or are not partially rewriting the display, we should clear it first by calling
GLIB_clear(&glibContext). The next step is to set the display content in the context by drawing something on the screen withGLIB_drawXXXX()where XXXX can stand for String, Bitmap, Circle, etc. After the content is set, the last step is to update the display using the DMD driver usingDMD_updateDisplay().In the above example a welcome text is written on the screen. First, we set the back- and foreground colors in the
glibContextto white and back respectively. Then, as mentioned before, a screen clear is performed. Before calling theGLIB_drawString()function, the font is set to normal in the context and the string is put together into one character array. TheGLIB_drawString()is called with the context, string and its length, along with the X and Y coordinate of the text and with the opaque setting last. The example displays the following on a Giant Gecko STK board:Updating parts of the screen
When not all the information is outdated on the screen, partial update can be used. In this case do not clear the screen, as then all screen content will be lost.
GLIB_clearRegionshould be used instead, after setting the clipping region with theGLIB_setClippingRegion()function. This function needs a rectangle as an input, this will be the area theGLIB_clearRegionwill clear out. After the clear is complete, you can draw in this territory by providing the appropriate X and Y coordinates to the draw function.The above example shows a way to display incoming messages alternately in the upper and the lower part of the screen. A previously defined upper and lower area clipping region is cleared and the upper or lower message is displayed using the predefined screen borders and the available font height and line spacing in the glib context.
如何在EFR32 sub_GHz参考匹配电路中插入SAW滤波器
EFR32无线Gecko系列芯片在sub-GHz频段内，现有的参考匹配电路使用所谓的直连拓扑结构，即收发通路不使用外部RF开关而直接连在一起。为了能在这种匹配结构中插入SAW滤波器，建议分开接收和发射通路，不建议在发射通路中引入SAW滤波器，因为：
- SAW滤波器有相当大的插损，会降低预期的功率效率,
- SAW滤波器通常为低功率设计的，这也将导致发射功率受限,
- SAW滤波器特别在射频谐波的高频段衰减比较小，因此始终推荐使用分立器件的LPF。
EFR32带SAW滤波器的推荐原理图结构如下：
- 发射通路的匹配可与现有的参考匹配电路一致，建议使用AN923里的元器件值或参考已有的参考设计。
- LPF阶数可以根据发射功率电平，谐波抑制要求来改变。
- 接收通路的匹配使用类似于AN643里面所说的标准4元件巴伦匹配网络。下表中列出了仿真的元器件值。
- RF开关可以用于分离连接到同一根天线的发射端和接收端的匹配电路。
- SAW滤波器的单独匹配网络 (LW1, LW2, CW1, CW2, CW3 and CW4)可能不需要，请参考SAW滤波器的规格书来决定。
英文原文： https://www.silabs.com/community/wireless/proprietary/knowledge-base.entry.html/2018/06/05/how_to_insert_a_saw-aBOx
基于connect的OTA升级
前言
Connect提供两种OTA升级方式：
两种方式都依赖于single image模式的Gecko bootloader(内部或外部flash都一样).OTA通信本身是用开源插件实现的.这些插件是构建在connect stack之上, 是应用无关的.
应用项目配置
为生成一个能OTA升级的应用,首先要在appbuilder的HAL栏使能"Application" bootloader,然后使能下列插件:
广播升级方式:
单播升级方式:
大部分插件都有可配置选项,细节不需要都弄明白,但最好都看过一遍.
Bootloader工程配置
为了升级,很明显需要一个bootloader. Connect现在仅支持单个slot的bootloader, 内部或外部flash都一样. 我们大部分开发板的射频板上都有外部flash.
关于Gecko bootloader详细介绍,请参考Gecko Bootloader User Guide.
根据硬件资源, 创建下列任一Gecko Bootloader工程:
例程不支持内部存储空间小于或等于256KB的设备.当然, 这个空间属性是可配置的, 只是要保证存储空间的一半SIZE可以装载应用程序(这里的一半指的是除去用做NVM/simEEPROM后的一半).
创建升级示例工程
我们将通过sensor-sink工程演示Connect的bootloading. sink将是OTA的服务端, sensor将是OTA客户端. 本文档在上下文是connect网络中用sink/sensor相称, 在上下文是OTA过程中则称为服务端/客户端.
这个升级应该在所有支持connect的Silicon Labs的开发板都可以操作,这里推荐使用xG12/xG13 SOC 开发板,因为它们都含有内部和外部flash.如果用2.4GHz, 请确认在radio configurator里选2.4GHz, 如果用subGHz, 别忘了加天线.
先建bootloader,一般在bootloader工程什么都不用改.
再建sink工程,使能application bootloader在HAL栏,还有使能下列插件:
从插件可以看出,这就是我们OTA的服务端.
推荐在OTA Bootloader Test Common plugin中禁用"Test EBL file inclusion".
创建两个sensor工程,一个通过通用J-Link烧录,另一个我们会用做OTA升级.请确保两个工程有差别, 例如将其中一个的心跳LED闪烁周期改为12 (3秒).
关于bootloading部分, 要在HAL栏使能application bootloader, 并使能以下插件:
这将是OTA客户端,这里仍然使能了服务端插件,这是因为两个插件有共用的配置(也就是说网络中用的endpoint), 这个是定义在服务端插件的. 如果存储空间紧张,可以将这些配置保存在别的地方,即可去除服务端插件了.
生成然后编译这四个工程(bootloader, sink, 两个sensor).
烧录应用程序
为保证应用程序正常工作,先要烧录bootloader.最简单的方法就是用Simplicity commander来烧录. 确保用 something-combined.s37 这个文件,这才是完整的bootloader: Gecko bootloader分为两部分,有个很小的first stage bootloader,可以用来升级main bootloader(在这里不做演示).只有"combined.s37"文件包含first stage bootloader,其他的只有main bootloader,所以无法正常工作.
接着烧录sink还有其中一个sensor应用程序.你可以用任一种方法, 要注意不用使用bin文件, 它没有带地址信息, 烧写这个可能会覆盖bootloader (看你用的是哪一代的产品). 同样要注意不可将flash全擦除.
如果bootloader跟应用程序都准备好了,接下来应该检查板子是否正常工作(心跳LED闪烁,CLI可用).
烧录用于OTA传送的文件
要烧录另一个sensor的GBL文档到sink/OTA服务端bootloader的slot空间:
Connect不能通过串行通讯接收GBL文档, 但我们可以用simplicity commander对内部外部flash烧录, 其中外部flash烧录只适用于Silicon Labs的开发板.
烧录到内部flash
为了写内部flash,首先要知道slot的起始地址.你可以从bootloader工程isc文档中的storage栏获取. 比如我这边看到的是540672. Simplicity commander能识别GBL文档, 我们不期望从GBL中解析地址信息(因为它应该烧到地址0): 我们要把它当做二进制文件来处理, 只要改其后缀为.bin就可以了. 然后我们可以通过GUI写入(要设置起始地址),或从命令行写,如下:
84000是540642的16进制的值, 而sensor-unicast-b.bin是GBL文档改名得来的.
烧录到外部flash
这种方法只能工作在Silicon Labs的开发板, 并只通过CLI来实现:
这个指令会锁住MCU,所以完成后要reset板子.
升级准备
下一步是通过CLI指令设置设备.
存储Flash准备
Sink/OTA服务端
第二条指令检验映像文件,有如下提示(实际会有很多个点):
Sensor/OTA客户端
第二条指令是擦除flash,写之前要求擦除.有如下提示(实际会多很多个点):
准备网络
用通常用的建网加网指令.
Sink/OTA服务端
Sensor/OTA客户端
我一般还用下面指令减少信息输出量:
如果一切顺利你应该可以看到sink与sensor通讯数据每10秒输出一次.
我们还需要给sensor设一个标签,因为OTA升级数据包是广播出来的,加标签后,接收到不一样标签的数据包可以舍去.
下一步我们还需要sensor的nodeid,可以通过”info”指令获取:
单播升级
接下来单播升级和广播升级有点区别.
OTA服务端用下列指令:
这指令将OTA数据包传送目的设成了0x0001,就是上一步获取的nodeid.
用下一条指令就可以开始传送了:
115800是GBL映像的大小,0xaa是OTA客户端所设的标签.
这就开始升级了.在OTA服务端你应该可以看到多行” get segment” (从flash中读的segment), 应该以” image distribution completed, 0x00” 结束. 在OTA客户端可以看到”incoming segment”,应该以”Image download COMPLETED tag=0xAA size=115800”结束.
到这里,客户端输入”bootloader validate-image”应该要返回”valid”.
接着我们输入指令要求更新:
在OTA服务端用下列指令:
1000 是超时时间, 单位为ms,0xaa是标签.
广播升级
在OTA服务端用下列指令:
虽是广播升级,server还是需要知道客户端的nodeid. 因为映像广播完后, 有客户端可能会丢失某些数据包. 所以当服务端完成传送,会询问所有的客户端丢失什么包然后重发.最大的客户端数是50.
上述指令是设nodeid 0x0001的索引号为0.
用下一条指令就可以开始传送了:
118784是GBL映像的大小,0xaa是OTA客户端所设的标签,1是通过” set-target” 设的客户号.
这就开始升级了.在OTA服务端你应该可以看到多行” get segment ”(从flash中读的segment), 应该以” image distribution completed,0x00” 结束. 在OTA客户端可以看到多行”incoming segment”,应该以”Image download COMPLETED tag=0xAA size=118784”结束.
到这里,客户端输入”bootloader validate-image”应该要返回”valid”.
接着我们输入指令要求更新:
在OTA服务端用下列指令:
1000是超时时间, 单位为ms, 后两个参数与上述的” distribute” 相同.
升级完成
升级指令很快能收到并有” bootload request completed ”显示,接着OTA客户端开始升级.升级完后, sensor会重新加入网络, 因为网络信息是存在NVM里的.
英文原版
https://www.silabs.com/community/wireless/proprietary/knowledge-base.entry.html/2018/04/26/ota_bootloading_with-ql8G
Connect MAC-device
The Connect stack support MAC mode. Although the Connect stack implements a full-featured network layer, including routing, supporting start and extended start topologies, network formation functionality (association, centralized address allocation), it supports MAC mode as well. In MAC mode, nodes can only communicate directly to each other and no routing is available.
The 802.15.4 MAC layer is used for basic message handling and congestion control and provides security functionality (scanning, authentication, encryption and replay attack protection). Packet size is up to a maximum of 127 bytes at the PHY layer. The MAC layer payload can vary depending on the security options and addressing type as illustrated in the figure below.
Simlpicity Studio provides example project for testing MAC mode. A MAC-device is able to send and receive standard 802.15.4 messages from other 802.15.4 devices in range. Such a device does not relay messages.
Open the following example from Simplicity Studio:
The AppBuilder automatically opens and and make it possible to change the configuration. The default settings are suitable to test MAC mode. Click on 'Generate', compile the project and run on two devices.
Open a terminal (ex.: TeraTerm) an check if the firmware works. After boot the following screen should be appear:
In case of MAC mode there are two modes to setup the devices:
Before setup the devices it is a good practice to issue the
leavecommand to clear network parameters.To apply network parameters issue the
join-commissionedcommand:Directly commissioned network parameters to all devices
join-commissioned 6 0x0001 0xabcd 0 0where the parameters in order are:Issue the command above with different (ex: 0x0002) Node ID on the other device. To check the parameters issue the
infothat will list the following parameters:At this point the devices can send messages to each other using the
sendcommand. This command has multiple forms based on the addressing modes on source and destination side The following example uses long address for both side:send 0x0033 0xffff {99 7c a2 fe ff 57 0b 00} 0xffff {6f 7c a2 fe ff 57 0b 00} 0xffff 0xffff {01234567}On the transmitter side the following output should appear:
While the receiver side should print info about reception:
Since the long address is unique for every chip it must be replaced by the actual value to use the example. Since the long address is unique for every chip it must be replaced by the actual value to use the example.
The parameters of the
sendcommand are:The "nibble mask" specifies the addressing mode:
Example usage of short address + PAN ID:
send 0x1122 0x0001 {} 0x0002 {} 0xabcd 0xabcd {01234567}The addressing format can be mixed, using long address for one of the nodes and short for the other. It is also possible to send message between different PANs (inter-PAN messages).
Setup a coordinator by commission network parameters and allow other devices to join
In this case one node must be coordinator and its network parameters have to commissioned just like in the case above:
join-commissioned 6 0x0000 0xf000 0 0The other devices have to join to the network, however by default joining is not enabled issue the following command on the coordinator to permit nodes to join:
pjoin 255The parameter is the time in second during the joining is permitted. There are two special values:
On the end-devices issue the
joincommand:join 6 0xabcd 0 0The parameters of the
joincommand are:The coordinator assigns random short address to the devices.
Sending messages works the same as in direct commissioned mode.
Join modes
Joining nodes can be MAC-level devices or Sleepy devices. Sleepy devices must poll the parent node for any messages waiting for them to be received. For sleepy nodes, the parent node should have the Parent Support plugin enabled.
RAIL tutorial: Tx/Rx Options
This tutorial builds on the following tutorials:
You can find other tutorials on the table of contents site.
RAIL provides some useful options when transmitting and receiving packets. In this tutorial, we're going to cover those.
Tx options
The main tx options should be passed to RAIL using the
RAIL_TxOptions_tparameter of the StartTx APIs. The available options are:RAIL_TX_OPTION_REMOVE_CRC: Ignores the config's CRC setting and does not transmit CRCRAIL_TX_OPTION_SYNC_WORD_ID: If set, Tx will use the second configured syncword. If unset, it will use the first oneRAIL_TX_OPTION_ANTENNA0: Use antenna0 (usually used when 2 antennas are available for antenna diversity)RAIL_TX_OPTION_ANTENNA1: Use antenna1 (usually used when 2 antennas are available for antenna diversity)RAIL_TX_OPTION_WAIT_FOR_ACK: Waits for ACK after transmitting a packet. I.e. the radio will automatically switch to Rx mode after Tx (disregarding auto state transitions) with a timeout.The usual groups are also defined:
RAIL_TX_OPTIONS_ALL,RAIL_TX_OPTIONS_NONEandRAIL_TX_OPTIONS_DEFAULT(which is the same as none).Listen before talk options
Listen before talk setups are often required in protocols, and a good idea to implement in some proprietary protocols as well: It solves most collisions between transmissions.
Listen before talk operations are built up from 2 tasks:
Generally, the radio starts with CCA: If the RSSI is below threshold, it starts transmitting. If not, it waits a random backoff period and tries again. The radio should repeat this with increasing backoff periods, until successful transmission or timeout.
CCA period on EFR32 has a limitation: it must take power of 2 number of symbols, i.e.
symboltime\*2^x(where x>=1).The backoffs are implemented on the same timer that handles the scheduling, so it could cause problems if you start a listen before start operation from a scheduled rx, and scheduled listen before talk tx operations are not supported.
CSMA/CA
The most common listen before talk protocol is CSMA/CA, which is fully supported by the EFR32 hardware, including retransmissions. CSMA/CA defines backoffs as a random number between 0 and
unit\*2^BE, where BE is the backoff exponent, which should be incremented with each retries.To trigger a CSMA/CA transmission, you can start transmitting with
RAIL_StartCcaCsmaTxinstead ofRAIL_StartTx. It has an extra parameter, with the type ofRAIL_CsmaConfig_t, that configures the CSMA/CA parameters:ccaBackoffthe backoff unit in us.csmaMinBoExpandcsmaMaxBoExpare setting the minimum and maximum backoff exponent (i.e. the first value of BE will becsmaMinBoExp, and it won't increment further if it reachedchmaMaxBoExp)csmaTriessets the number of tries, i.e. how many CCA should be performed before reporting back an error. Setting it to 0 will disable CSMA/CAccaDurationsets the duration the CCA should take in us (i.e. how long it should average the rssi).csmaTimeoutin us if the csma/ca operation exceeds this timeout it will stop. This is useful, since due to the random backoffs, the csma/ca duration can vary. Set it to 0 to disable the timeout.There's also a special setup: if
csmaMinBoExpandcsmaMaxBoExpare both set to 0, that means a fixed backoff configuration. In this case, the backoff will always take the time set inccaBackoff.LBT
Another common listen before talk protocol is the obviously named LBT: LBT defines backoffs as a
unit\*BO, where BO is a random number between a minimum and maximum.LBT is not supported by the EFR32 hardware, it is converted to a CSMA/CA configuration in RAIL. Because of this, if you can chose between the two, you should chose CSMA/CA.
Note that LBT can be configured with a minimum backoff limit, while CSMA/CA's minimum backoff period is always 0. This is not supported by the hardware, so LBT is implemented with a bit of cheating. The CCA period is set to the configured period + unit*minBO. It doesn't really matter if the CCA period is longer, and this guarantees that the minimum backoff is fulfilled
Another limitation is that the maximum backoff must be power of 2, so the configured backoff will be rounded to the closest power of 2
Much like CSMA/CA, LBT has its own StartTx API,
RAIL_StartCcaLbtTx, which has the config struct,RAIL_LbtConfig_tto configure the LBT parameters:lbtBackoffis the backoff unit in us.lbtMinBoRandandlbtMaxBoRandare setting the limits of the random backoff, just like with CSMA/CA, setting it both to 0 selects the fixed backoff modelbtTriessets the number of tries, i.e. how many CCA should be performed before reporting back an error. Setting it to 0 will disable LBTlbtDurationsets the duration the CCA should take in us (i.e. how long it should average the rssi).lbtTimeoutif the LBT operation exceeds this timeout (in us) it will stop. This is useful, since due to the random backoffs, the csma/ca duration can vary. Set it to 0 to disable the timeout.Custom listen before talk
Custom listen before talk protocols are not supported. However it might be possible to achieve it, using
RAIL_GetRssi(),RAIL_StartAverageRSSI()and regularRAIL_StartRx().Rx options
Rx options can be configured using
RAIL_ConfigRxOptions, which takes twoRAIL_RxOptions_tparameter,maskandoptions. This way, it's easy to change one option, without knowing others. The available options:RAIL_RX_OPTION_ANTENNA0Use antenna0 (usually used when 2 antennas are available for antenna diversity)RAIL_RX_OPTION_ANTENNA1Use antenna1 (usually used when 2 antennas are available for antenna diversity)RAIL_RX_OPTION_ANTENNA_AUTOUse both antennas, with antenna diversity (must be configured before using it)RAIL_RX_OPTION_DISABLE_FRAME_DETECTIONdisables the frame detection system. Useful, if you only want to check the energy of a channel, and do not want to receive frames, because it would break the application's state machinesRAIL_RX_OPTION_ENABLE_DUALSYNCEnables the detection of both sync wordRAIL_RX_OPTION_IGNORE_CRC_ERRORSFrames will be received even if it failed CRC check. When enabled, the result of the CRC check will be stored inRAIL_RxPacketDetails_t.crcPassed.RAIL_RX_OPTION_REMOVE_APPENDED_INFODisables the storage of the appended info. Appended info is used to store the base ofRAIL_RxPacketDetails_t, like timestamp and rssi. If not needed, it can be disabled, saving some buffer spaceRAIL_RX_OPTION_STORE_CRCBy default, RAIL does not store the CRC, only checks it. By enabling this, it will store it as well. It can be used for example for sniffer applicationsRAIL_RX_OPTION_TRACK_ABORTED_FRAMESRAIL aborts frame reception when it filters it using the address filter. With this option enabled, it will receive the full frame (but still generates the correct error event) so the network analyzer can display it (through PTI).The usual groups are also defined:
RAIL_RX_OPTIONS_ALL,RAIL_RX_OPTIONS_NONEandRAIL_RX_OPTIONS_DEFAULT(which is the same as none).Some options, like the antenna selections will restart receive mode (if changed in receive mode).
Address filtering
EFR32 supports hardware based address filtering, as long as the address is stored in the same location in all the frames (unlike 802.15.4, which is only supported through its special API). EFR32 supports 2 address fields (e.g. for group and device address), both can be up to 8 Bytes long. Both fields can be configured for up to 4 addresses (e.g. for broadcast, unicast and 2 multicast address). Any combination can be allowed on these two fields, e.g. enable address1 for field0 only if field1 has addressA, or if field0 has address2, anything is allowed on field1.
Enabling the address filter starts with configuring it, using
Its only parameter (apart from the usual railHandle) is
RAIL_AddrConfig_t.RAIL_AddrConfig_tconfiguresoffsets[2], which sets the offset of the addresses in the frame (for the first field, from the end of sync word, for the second field, from the end of the first field. Note that this means that the fields cannot overlap.)sizes[2], which sets the size of the fields in byte. Setting it to 0 disables the field.matchTablewhich configures the enabled combinations of the fieldsIf you only use a single field, you can safely use
ADDRCONFIG_MATCH_TABLE_SINGLE_FIELD. If you need both address fields, you should understand how the match table works. That is out of the scope of this tutorial, but you can rely on the API documentation and this KBA.Next, you load the addresses, using
Which will enable the address 0xAABBCCDD on field 0, index 1, in enabled state. Make sure your address length matches what you configured for the field. You can later disable (and re-enable) it with
Note that this API is referencing the address by its field and index. If you want to enable/disable addresses based on the value, i.e. the address itself, you should track which index is used for each address.
Finally, to enable (or disable) the whole address filter, use
Once address filter is enabled, you can get notifications on filtered frames using the
RAIL_EVENT_RX_ADDRESS_FILTEREDevent.API introduced in this tutorial
Functions
Types and enums