How it Works
Silicon Labs
Loading...
UG409
User Manual
30 pgs1.48 Mb0
Table of contents
Loading...

Silicon Labs RAILtest, UG409 User Manual

UG409: RAILtest User’s Guide
The RAILtest application (RAILtest) provides you with a simple tool for testing the radio and the functionality of the RAIL library. For more advanced usage, developers must write software against the RAIL library and create a custom radio configuration.
KEY POINTS
• Command Line Interface description
• Application features
• Protocol-s pecific features
• Testing modes
silabs.com | Building a more connected world. Rev. 3.5
UG409: RAILtest User's Guide
Overview

1 Overview

The following is a summary of functionality provided as part of the RAILtest application:
• Transmit and receive packets
• Schedule transmits at a specific time in the RAIL timebase
• Configure RAIL address filtering to receive only specific packets
• Enable CCA mechanisms (CSMA/LBT) to validate that a channel is clear before transmit
• Set a timer callback in the RAIL timebase to see how the RAIL timer API works
• Change the transmit channel within the current configuration's band
• Change the transmit power level
• Enable RF energy sensing of a specified duration across the 2.4 GHz and/or Sub 1-GHz bands, and sleep to wake on this event.
• Output a continuous unmodulated tone for debugging
• Output a continuous modulated PN9 stream for debugging
• Enter into direct mode where data can be sent and received using asynchronous GPIOs as input and output

1.1 About RAILtest Versions

Gecko SDK Suite (GSDK) v3.0 contains an update to RAILtest, released as version 2.9. Users who have not yet transitioned to GSDK v3.0 and are still working with GSDK v2.7.x will be using RAILtest version 2.8. During transition, information is supplied for both versions.

1.2 Modes

RAILtest can be in a number of different modes. Each of these modes enables a subset of the test application's functionality, so that nonsensical commands (such as trying to transmit a tone and a packet at the same time) are ignored. The following lists supported modes, with a short description.
• None - The app is doing nothing, but the radio may be on. Parameters can be set in this mode based on the current radio state, and the timer can be used.
• Stream - Send a stream of pseudo-random bits.
• Tone - Send a tone at the carrier frequency.
• ContinuousTx - Send an unending stream of packets, separated by a configurable delay.
• DirectMode - Send data to and from a GPIO, without any packet handling.
• PacketTx - Send a specific number of packets, with a summary print at the end.
• ScheduledTx - Send one packet scheduled in the future.
• TxAfterRx - Schedule a packet after each RX after a specific delay.
• RxOverflow - Overflow on receive by delaying in RAILCb_RxPacketReceived.
• TxUnderflow - Underflow by not loading data for the next TX sequence.
• TxCancel - Cancel a single packet transmit to force an error callback.
• RfSense - Sense RF energy to wake the radio.
• PER (Packet Error Rate) test - A GPIO is toggled, and stats are gathered on received packets.
• BER (Bit Error Rate) test - Statistics are gathered on received bits.
silabs.com | Building a more connected world. Rev. 3.5 | 2
UG409: RAILtest User's Guide
Command Line Interface

2 Command Line Interface

The most powerful way to interact with the sample application is through the provided command line interface.

2.1 Command Input

The syntax for this interface is the standard command [arg0, arg1, ...] syntax, where the number and type of arguments depend on the specific command. Numeric values can be prefixed with 0x to indicate hexadecimal values.
In RAILtest 2.8 (GSDK v2.7.x), the maximum number of arguments to any command is set by the value of MAX_COMMAND_ARGUMENTS, and the maximum length of each command line is set by the value of APP_COMMAND_INTERFACE_BUFFER_SIZE.
In RAILtest 2.9 (GSDK v3.0), the maximum number of arguments to any command is set by the value of
SL_CLI_MAX_INPUT_ARGUMENTS, and the maximum length of each command line is set by the value of SL_CLI_INPUT_BUFFER_SIZE.
For a full listing of the command options see section 5.3.4 Full Help Text or use the help command.

2.2 Command Responses

All responses to commands are formatted in a human readable yet parsable format. This format has two variations: single and multiline. Both follow these rules.
• Start and end with curly braces { }
• List the command name, enclosed in parentheses ( )
• Contain any number of tag/value pairs enclosed in curly braces { }
• Carriage returns and line feeds are treated as whitespace by any parser

2.2.1 Single Response

Used when a command has a single response.
• There is a single start/end curly brace wrapper
• Tag/value pairs are wrapped in a single set of curly braces, separated by a colon {tag:value}.
Example:
> getchannel {{(getchannel)}{channel:4}}

2.2.2 Multi Response

Used when a command may have multiple responses, such as when reading a block of memory or receiving multiple packets.
• Response starts with a header, delimited by a hash # at the start of the line.
• Header includes the command name, followed by any tags individually wrapped with curly braces { }.
• Following the header, any number of responses can be provided.
• Data lines do not contain the command name or tags, only the values that correspond to the tags in the order described in the header.
Example:
> getmemw 0x20000000 4 #{{(getmemw)}{address}{value}} {{0x20000000}{0x0000e530}} {{0x20000004}{0x000051c6}} {{0x20000008}{0x0000c939}} {{0x2000000c}{0x0000e090}}
silabs.com | Building a more connected world. Rev. 3.5 | 3
UG409: RAILtest User's Guide
Peripherals

3 Peripherals

3.1 Buttons

When enabled, RAILtest can use up to two buttons. When pressed for a short duration (less than 1 second), the first button causes RAILtest to transmit one packet. When pressed for a long duration (greater than 1 second), the first button causes RAILtest to continuously transmit packets until the button is pushed again for a long duration. Pressing the second button causes RAILtest to increment the channel number used for TX and RX until the channel number wraps around to its beginning value.
Starting in RAILtest 2.9 (GSDK v3.0), button functionality is disabled by default. In order to enable button functionality, the Simple Button Driver software component needs to be enabled with an instance name of btn0 for the first button and btn1 for the second button.

3.2 LEDs

When enabled, RAILtest can use up to two LEDs. The first LED toggles when a packet is successfully received, and the second LED toggles when a packet is successfully transmitted.
Starting in RAILtest 2.9 (GSDK v3.0), LED functionality is disabled by default. In order to enable LED functionality, the Simple LED Driver software component needs to be enabled with an instance name of led0 for the first LED and led1 for the second LED.

3.3 LCD

When enabled, RAILtest can use the LCD to show packets received and transmitted as well as the channel selected and radio activity.
Starting in RAILtest 2.9 (GSDK v3.0), LCD functionality is disabled by default. In order to enable LCD functionality, the RAILtest Ap- plication, Graphics software component needs to be enabled.
silabs.com | Building a more connected world. Rev. 3.5 | 4
UG409: RAILtest User's Guide
Application Features

4 Application Features

4.1 Packet Mode

The application starts in packet mode with the receiver enabled. In this mode the application receives and transmits packets using the radio's frame controller hardware. To disable receive use the rx 0 command. To transmit use tx [numPackets] or press button PB0 if button support is enabled. To toggle the continuous transmit mode, hold PB0 for a couple of seconds if button support is enabled, or run the tx 0 command. When transmitting multiple packets or infinite packets there is a configurable delay in between each transmit. By default this is 250 ms, but it can be set with the setTxDelay command.
All received packets are printed to the console with information like CRC, RSSI, and timestamp as long as notifications are enabled. Notifications are enabled by default, but they can be turned off with the setRxNotification 0 command.
The application by default sends a fixed packet, but it is possible to override the values through setTxPayload. The command allows you to modify the values of the payload at specific offsets. For instance, to modify the first 4 bytes sent in the packet to be 0x01 0x02 0x03 0x04, use:
setTxPayload 0 0x01 0x02 0x03 0x04
To view the currently configured TX Packet information, use printTxPacket.
Note: The packet format depends on the current PHY configuration. If your PHY has a dynamic frame length byte then that will be
used to determine how much data should be sent.

4.2 Direct Mode

In direct mode the radio will still attempt to decode received packets, but it will only be able to transmit packets sent over the DIN pin. The GPIOs for direct mode are fixed for now to the following pins.
DOUT - EFR32_PC11 -> EXP_HEADER16/WSTK_P13 DIN - EFR32_PC10 -> EXP_HEADER15/WSTK_P12
The data on these pins is asynchronous and can be connected directly to a UART. To enter direct mode, issue the directMode 1 command after starting the app. To leave direct mode use directMode 0. If you want to transmit, you must enable the transmitter by issuing directTx 1 and later stop it with directTx 0. Receive is controlled using the standard rx 1/0 command, but is enabled by default when not transmitting.
Note: Direct mode does not work in certain modulations (for example 4FSK). If you require this mode contact support to verify your
configuration.

4.3 Channels/Frequencies

The specific channel configuration depends on the PHY configuration you have chosen for your test app. To switch between channels use the setChannel [num] command. If RX is active (rx 1) then any TX or RX in progress will be aborted and the new channel switched to. In addition, if button support is enabled, you can use button PB1 to cycle through channels.
To modify your frequency to a value not defined in the channel list, you will need to set the application into the FREQUENCY_OVERRIDE debug mode via setDebugMode which tells the application to ignore the current channel selection. Once in the FREQUENCY_OVERRIDE debug mode, you can use the freqOverride command to switch to another center frequency.
Note: The freqOverride command requires you to be in FREQUENCY_OVERRIDE debug mode. The radio state must also be IDLE
for the frequency to be modified -- call rx 0 first.
setDebugMode 1 freqOverride 865000000
To leave FREQUENCY_OVERRIDE debug mode and return to normal channel-based operation, use setDebugMode 0.
silabs.com | Building a more connected world. Rev. 3.5 | 5
UG409: RAILtest User's Guide
Application Features
Caution: The modem is configured to a specific band. The application will not restrict you from changing the frequency out of band but
this could cause significant issues, including forcing a chip reboot.

4.4 Command Scripting

The command scripting feature built into RAILtest allows for CLI commands to be executed without back-and-forth interaction on the command line. The same commands that can be executed one by one can be queued up within RAILtest and executed sequentially later. Additionally, a command script can be saved to flash, and any script saved to flash will run automatically on device boot.
In RAILtest 2.8 (GSDK v2.7.x) support is integrated into RAILtest to use a command script in RAM, but to use a command script in flash, the Flash Data plugin must be enabled.
In RAILtest 2.9 (GSDK v3.0), to use a command script in RAM, the CLI Storage in RAM software component needs to be enabled with an instance name of inst0. To use a command script in flash, the CLI Storage in NVM3 software component needs to be enabled with an instance name of inst0.
This is an example of how to enter, print, and run a script from RAM. Note that the wait command needs to be used in order to allow time for the first scripted command (that is, tx 1) to successfully run to completion before the second scripted command (that is, tx 2) starts.
enterScript tx 1 wait 500000 tx 2 endScript printScript runScript
This is an example of how to enter, print, run, and clear a script from flash.
enterScript 1 tx 1 wait 500000 tx 2 endScript printScript 1 runScript 1 clearScript 1
This is an example of how to enter and run a script from flash on boot.
enterScript 1 tx 1 wait 500000 tx 2 endScript reset
Note: For rapid command entry (for example, automated testing), you may need to increase the USART RX buffer from its default
value, specified by a define similar to SL_IOSTREAM_USART_VCOM_RX_BUFFER_SIZE in RAILtest 2.9, to account for long command string entry being interrupted by chip interrupts. For lengthy (for example hours long) automated test programs, a notable decrease in test time will come from disabling CLI command history, setting SL_CLI_NUM_HISTORY_BYTES to 0 (RAIL­test 2.9).

4.5 RAIL Timebase

The microsecond RAIL timebase is used for features requiring specific timing. You can read this timebase with getTime, and you can also set this microsecond timebase with setTime. Avoid changing the timebase when the timebase is actively being used, such as during clear channel assessment, during scheduled TX or RX, and so on.
silabs.com | Building a more connected world. Rev. 3.5 | 6
UG409: RAILtest User's Guide
Application Features

4.6 Scheduled TX

The RAIL API has its own timebase that can be used to schedule the start of transmits. It measures time as a 32-bit integer in microsec­onds. As part of this change many APIs will now return the time they were run, all RX packets report the time they were received, and all TX packets return the time that the transmit was completed. There is also the command getTime to print the current time in the RAIL timebase.
To test scheduled transmit we provide two commands: txAt and txAfterRx. These allow you to send a packet at an absolute time in the RAIL timebase or exactly some number of microseconds after each receive, respectively.
Note: These APIs should provide reliable timing but you may have to adjust for overhead that relates to preamble and PA ramp time
in order to transmit at the exact time you want.

4.7 Clear Channel Assessment

The RAIL API provides the ability to specify a Pre-Transmit Operation for every transmit, one of which is Scheduled Transmit discussed above. Others are also provided to support two common medium access methodologies that delay transmission until the channel is clear:
• CSMA-CA (Carrier Sense Multiple Access with Collision Avoidance) -- based on IEEE 802.15.4 specification
• LBT (Listen Before Talk) -- based on ETSI EN 300 220-1 specification
Both CSMA-CA and LBT are similar: Before transmission, a device waits for a random 'backoff' period of time and then performs a CCA (Clear Channel Assessment) for a fixed period of time. If the channel is free, the transmit proceeds; if busy, the process is repeated with a new random backoff period. The random backoff period is determined by a randomly chosen multiple of a fixed backoff unit of time.
For CSMA-CA, the random multiplier is a power-of-2 exponential whose range increases on each try up to a limit, and the CCA period is typically short -- smaller than a backoff unit and around the time it takes a small packet to be transmitted. For LBT, the random multiplier is linear and typically chosen to allow the random period to range up to the CCA period, which can be quite long -- much longer than the on-air time of the actual transmission it's gating. LBT also specifies that if the channel is found busy during CCA, the process cannot repeat until the channel is free.
In RAIL and RAILtest, several parameters are exposed through the setLbtParams and getLbtParams commands to configure either CSMA-CA or LBT operation. Their interpretation depends on which mode has been chosen:
• minBo -- Minimum backoff. For CSMA-CA the first try's power-of-2 random exponential range, that is the backoff multiplier, will
range from 0 to 2^minBo - 1. Subsequent tries increase minBo by 1 up to maxBo. For LBT this is the minimum backoff multiplier for all tries, typically 0.
• maxBo -- Maximum backoff. For CSMA-CA this is the maximum power-of-2 random exponential range to which subsequent tries
can increase. For LBT this is the maximum backoff multiplier for all tries, typically maxBo * backoff = duration. If both minBo and maxBo are 0, a non-random fixed backoff time is configured.
• tries -- The maximum number of tries ('busy' CCAs), up to 15, that the CSMA-CA or LBT operation will tolerate before declaring
the transmission a failure due to channel busy. A value of 0 will perform no CCA assessments, and always transmit immediately.
• thresh -- The CCA RSSI threshold, in dBm, above which the channel is considered 'busy'.
• backoff -- The backoff unit period, in RAIL's microsecond time base. This is multiplied by the random backoff multiplier con-
trolled by minBo and maxBo to determine the overall backoff period. For random backoffs, this value must be in the range 100 to 511 microseconds; for fixed backoffs it can go up to 65535 microseconds.
• duration -- The CCA duration, in RAIL's microsecond time base. The radio determines the maximum RSSI during this period
for comparison against the CCA threshold.
• timeout -- An overall timeout, in RAIL's microsecond time base, for the operation. If transmission does not start before this
timeout expires, the transmission will fail. This is more important for limiting LBT due to LBT's unbounded requirement that if the channel is busy, the next try must wait for the channel to clear. A value of 0 indicates that no timeout is imposed.
Several examples:
• RAILtest's default parameters are suitable for the IEEE 802.15.4 PHY for CSMA-CA, equivalent to: setLbtParams 3 5 4 -
75 320 128 0. This specifies up to 4 CCA attempts. The 1st will choose a random multiplier of 0..7 (2^3-1), the 2nd 0..15
(2^4-1), the 3rd 0..31 (2^5-1), and the 4th 0..31 since the maxBo limit is 5.
silabs.com | Building a more connected world. Rev. 3.5 | 7
UG409: RAILtest User's Guide
Bytes: 0 - 255
0 - 8
0 - 255
0 - 8
Variable
No Match
bit0
bit1
bit2
bit3
bit4
Address 0
Address 1
Address 2
Address 3
Application Features
• ETSI EN 300 220-1 LBT's parameters in the 863 MHz band would be: setLbtParams 0 10 15 -80 500 5000 1000000.
This specifies a 5 millisecond CCA duration with random backoff period of 0..5 milliseconds (0..10 * 0.5 milliseconds) and a 1 second timeout limit in case the channel remains busy.
• A single CCA of 160 microseconds after a fixed 1024 microsecond backoff, against a -70 dBm threshold would be: setLbt-
Params 0 0 1 -70 1024 160 0.
In RAILtest, CSMA-CA and LBT are enabled as a mode applied to subsequent transmits through setLbtMode, whose choices are 'off', 'csma', and 'lbt'.
Note: On EFR32, LBT is currently implemented using the EFR32's CSMA-based hardware engine, so LBT parameters are mapped to
roughly equivalent CSMA parameters.
Note: Scheduled Transmit and Clear Channel Assessment are currently mutually exclusive, with Scheduled Transmit taking prece-
dence.

4.8 Address Filtering

The address filtering code examines the packet as follows.
Data0 Field0 Data1 Field1 Data2
In the above structure, anything listed as DataN is an optional section of bytes that will not be processed for address filtering. The FieldN segments reference the specific sections in the packet that will be examined during filtering for addresses. There may be up to four addresses per field and they may each have a size of up to 8 bytes. To set up address filtering, first configure where the addresses are in the packet and how long they are. Next, configure what combinations of matches in Field0 and Field1 should constitute an address match. Lastly, enter addresses into the tables for each field and enable them.
The configAddressFilter command can be used to set the offsets and sizes for the address fields as well as how combinations of matches in Field0 and Field1 are combined to determine whether or not an address matches.
Configuring which combinations of Field0 and Field1 constitute a match is the most complex portion of the address filter. The easiest way to think about this is with a truth table. If you consider each of the four possible address entries in a field, you can have a match on any one of those or a match for none of them. This is shown in the 5x5 truth table below where Field0 matches are the rows and Field1 matches are the columns.
Fields No Match Address 0 Address 1 Address 2 Address 3
bit5 bit6 bit7 bit8 bit9
bit10 bit11 bit12 bit13 bit14
bit15 bit16 bit17 bit18 bit19
bit20 bit21 bit22 bit23 bit24
Since this is only 25 bits it can be represented in one 32bit integer, where a 1 indicates filter pass and a 0 indicates filter fail. This is the matchTable parameter in the configAddressFilter command. For a simple one field configuration set the matchTable to 0x1fffffe and for a two field configuration pairing indices across the fields use 0x1041040.
After you have configured address filtering you must also set which addresses are valid and enable them. This can be done with the
setAddress and setAddressEnable commands. You must also turn on the address filtering feature with the setAddressFilter- ing command.
As an example, to configure an address of 0x00 0x01 0x02 0x03 in field0, index0 for a filter that has one field starting at offset 0 with a length of 4 bytes, use the following commands.
configAddressFilter 0x1fffffe 0 4 0 0 setAddress 0 0 0x00 0x01 0x02 0x03 setAddressEnable 0 0 1 setAddressFiltering 1
silabs.com | Building a more connected world. Rev. 3.5 | 8
UG409: RAILtest User's Guide
Application Features
In addition to the standard address filtering, if the frame length decoding algorithm is by frame type, then additional filtering functionality is available. Address filtering can be enabled or disabled based on the frame type that is decoded. This can be set by the addressFil- terByFrame command. This command takes an 8-bit bitmask, in which each bit represents whether addresses are present in that frame. The least significant bit determines whether to apply the address filter to frame 0, and the most significant bit determines whether to apply the address filter to frame 7. addressFilterByFrame must be called after configAddressFilter for it to take effect.

4.9 Automatic State Transitions

RAIL provides an API to configure state transitions to happen automatically on certain radio events:
• a successful receive
• a failed receive
• a successful transmission
• a failed transmission
All of these events can transition to a radio state of idle or receive. In addition, a transmission can be configured to happen after a successful receive.
These states are configured through the setTxTransitions and setRxTransitions commands. Each of these commands take in two radio states, which are passed in as single letter strings. To transition to receive after a transmission, regardless of its success, the command is setTxTransitions r r.
When settings the receive transitions, there is also a third argument, a bitfield to configure which events count as errors. The documen­tation for this bitfield can be found in the RAIL library documentation. Calling setRxTransitions i i 0xFF will ignore all errors that are possible to ignore, and transition the radio to idle after attempting to receive one packet.
In addition to the state transitions, timings can be set for the transitions. The six timings that are currently configurable are:
• idleToRx
• idleToTx
• rxToTx
• txToRx
• rxSearchTimeout
• txToRxSearchTimeout
Each of these timings configures an amount of delay between two states. The search timeouts allow you to set a maximum time that the chip will sit in the RX search state. These can be used to implement short receive timeouts. The rxSearchTimeout is used when transi­tioning to receive from idle and the txToRxSearchTimeout is used when transitioning to receive from a past transmit. Setting [rx|txToRx]SearchTimeout to zero disables the timeout and radio will stay in RX until an event changes the state. Transitions to idle simply happen as fast as possible. Each timing is configurable in microseconds, up to a maximum of 13 ms, with the exception of txToRxSearch­Timeout which could be up to a quarter of the RAIL timebase, which is 2^32/4 microseconds or 18 minutes. For example, to disable the timeouts and set all other transitions to take 200 µs, use:
setStateTimings 200 200 200 200 0 0

4.10 Auto-Acknowledgment

RAIL contains auto-acknowledgment (ACK) APIs that are exposed through the RAILtest command interface. To initialize and enable this functionality use autoAckConfig. For example, autoAckConfig rx 100 192 1000 will configure the 'defaultState', the state at which the radio returns after an ACK operation, to receive. Transitions from idle will take 100 µs. Turnaround transitions will take 192 µs and will wait for an ACK for 1000 µs. To load a custom ACK payload, call setAckPayload and setAckLength.
If a packet is received during the ACK window, then the isAck flag for that packet will be true. The ACK windows begins at the end of the turnaround time and lasts for the timeout length. If auto acknowledgment is not enabled, then the isAck flag will always be false.
To customize ACK functionality, users can use the autoAckPause command to either skip the wait for an ACK on the transmit side or skip the transmit of an ACK on the receive side. To modify if/how the ACK is transmitted after a receive operation, use the setTxAckOp- tions command.
Conversely, after a transmit operation, waiting for ACK is controlled by the TX options configured by configTxOptions. When combined with the txWithOptions command, the configuration is honored. However, whenever a simple tx is called, configured options will be ignored and defaults will be used for the transmit (that is, do not wait for ACK, send CRC, use sync word 0).
silabs.com | Building a more connected world. Rev. 3.5 | 9
Loading...
+ 21 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use