RAILtest Examples#

The following examples demonstrate basic IEEE 802.15.4 RAIL features. These tests typically require RAILtest nodes: one transmitter and one receiver. Run the commands on both nodes unless stated otherwise.

For simplicity, these examples use the built-in 2.4 GHz 250 kbps O-QPSK PHY and SubGHz GB PHYs.

Applying a PHY from RAIL#

rx 0 // Configs can be loaded only in radio Idle state
config2p4GHz802154
// or
config863GHz802154
// or
config915MHz802154
rx 1 // Make the RX active
// or
tx 1 // Transmit a packet

The default payload in the RAILtest application is configured to transmit 16-byte frames. When you load SubGHz PHYs, the application also updates the first two bytes of the payload (the PHR) to match this default configuration, unless you have already changed the payload.

To set different payload lengths, see the next example.

Use the getChannel command to check the current channel.

Use the setTxPayload command to configure the payload. The first argument specifies the start offset, and subsequent arguments specify the payload bytes. This allows you to modify the payload partially. To print the configured payload, use the printTxPacket command.

By default, the Rx and Tx FIFO sizes in RAILtest are 512 bytes. This can be a limitation for SUN frame formats, which support frames up to 2048 bytes.

Variable Length Payload#

PHR setup in RAILtest#

RAILtest provides the set802154phr command to configure the PHR for the Tx packet. It sets the length field based on the value configured by the setTxLength command (or 16 bytes by default). The command setTxLength defines the payload length from RAIL's perspective. This value includes the PHR length but excludes the FCS length, which is the opposite of how the length is defined in the PHR. The set802154phr command adjusts this difference. For example, after setTxLength 16, assuming 1-byte PHR and 2-byte FCS, set802154phr sets the length field to 16-1+2=17 bytes.

To perform this conversion and format the PHR correctly, set802154phr requires additional configuration, which you pass as command arguments:

  • format

    • 0 for 1B PHR

    • 1 for 2B PHR (SUN-FSK)

    • 2 for SUN-OFDM 4B PHR

    • 3 for SUN-OQPSK 4B PHR

  • option 1

    • FCS type for SUN-FSK

    • rate for SUN-OFDM

    • spreading for SUN-OQPSK

  • option 2

    • whitening for SUN-FSK

    • scrambler for SUN-OFDM

    • rate for SUN-OQPSK

The second and third arguments can be omitted for a 1-byte PHR.

The 863 and 915 MHz built-in PHYs limit the payload length to 127 (0xFE).

Use the configRxOptions 0x1 to store the CRC on valid packet reception. This also prints the CRC to the console.

Address Filtering#

This example uses the 2.4 GHz PHY.

Enable Address Filtering#

Hardware-accelerated MAC features, such as frame and address filtering, are enabled using the enable802154 command.

rx 0
config2p4GHz802154
enable802154 rx 100 192 1000
rx 1

The default packets transmitted after these commands won't be received on the RX node, because the 802.15.4 mode automatically enables filtering without any address defined (except broadcast messages).

To receive packets without configuring addresses, format a valid broadcast message.

Formatting Broadcast Message#

Configure the Frame Control Field as follows. Pay attention to bit endianness.

  • Frame Type = 0b000 (Beacon)

  • Security Enabled = 0b0

  • Frame Pending = 0b0

  • AR = 0b0

  • PAN ID Compression = 0b0

  • Reserved = 0b0

The first byte of the PSDU is 0x00.

  • Sequence Number Compression = 0b0

  • IE Present = 0b0

  • Destination Addressing Mode = 0b10 (Short, 16-bit)

  • Frame Version = 0b0

  • Source Address = 0b10 (Short, 16-bit)

The second byte is 0x88.

The FCF field is followed by the Sequence Number. This is a random number; we can set it arbitrarily in this example:

  • Sequence Number = 0x00

The third byte is 0x00.

Set the Addressing fields next to the Sequence Number starting by the Destination:

  • Destination PAN ID = 0xFFFF (Broadcast)

  • Destination Address = 0xFFFF (Broadcast)

  • Source PAN ID = 0x1234

  • Source Address = 0x5678

The next 8 bytes are 0xFF 0xFF 0xFF 0xFF 0x34 0x12 0x78 0x56.

And finally, we add 1 byte of MAC payload to the packet:

  • Payload data = 0x55

The last byte configured in the Tx payload is 0x55.

The total length of the packet is 15 bytes, including the header (i.e., the PHR field). Set the first byte according to Example 1.

  • FL = PSDU_LEN = 14 = 0x0E (11B MHR + 1-byte payload + 2-byte CRC)

setTxPayload 0 0x0E 0x00 0x88 0x00 0xFF 0xFF 0xFF 0xFF 0x34 0x12 0x78 0x56 0x55
             | PHR |   FCF   | SN | D. PAN  | D. Addr.| S. PAN  | S. Addr | Payl.|

This packet is now received without defining the address of the receiver.

Short Address Example#

Next, set up an address on the receiver node.

The setPanId802154 command configures the PAN ID of the device and setShortAddr802154 sets the Short Address.

To keep the example simple, set the PAN ID and Address on the RX node to 0x5555 and 0xAAAA, respectively.

// Tx node

setPanId802154 0x1234
setShortAddr802154 0x5678

// Rx node

setPanId802154 0x5555
setShortAddr802154 0xAAAA

Now send a message addressed to the receiver node, keeping all other packet parameters the same:

setTxPayload 0 0x0E 0x00 0x88 0x00 0x55 0x55 0xAA 0xAA 0x34 0x12 0x78 0x56 0x55

Setting the PAN ID and Short Address on the transmitter does not affect packet transmission.

At this point, you can verify that changing a single bit in the Destination Address or PAN ID prevents the Rx node from receiving the packet:

                                           |
setTxPayload 0 0x0E 0x00 0x88 0x00 0x55 0x57 0xAA 0xAA 0x34 0x12 0x78 0x56 0x55
// or
setTxPayload 0 0x0E 0x00 0x88 0x00 0x55 0x55 0xAE 0xAA 0x34 0x12 0x78 0x56 0x55
                                                |

However, RAIL supports multiple addresses and PAN IDs defined at the same time.

You can register a new address by passing a second, optional argument to the setPanId802154 and setShortAddr802154 commands.

To receive the previous two wrongly formatted packets, use the following commands:

// Rx node

setPanId802154 0x5755 1
setShortAddr802154 0xAAAA 1

setPanId802154 0x5555 2
setShortAddr802154 0xAAAE 2

Notice that the PAN ID and the address must be defined in pairs on a given index. The following packet still can't be received with the registered PAN ID and Short Address pairs:

setTxPayload 0 0x0E 0x00 0x88 0x00 0x55 0x57 0xAE 0xAA 0x34 0x12 0x78 0x56 0x55
                                           |    |

Long Address Example#

As a last address filtering example, receive a packet using the long address.

Set the Source address to 0x0123456789ABCDEF with the setLongAddr802154 command.

The Tx packet changes:

  • Destination address = 0b11 (Long, 64 bit)

The second byte of the FCF is 0x8C.

  • Destination address is now four times longer (8 bytes)

The addressing fields (14 bytes) are: 0x55 0x55 0x01 0x23 0x45 0x67 0x89 0xAB 0xCD 0xEF 0x34 0x12 0x78 0x56.

  • Add 6 bytes to the PHR:

  • FL = PSDU_LEN = 20 = 0x14 (17B MHR + 1B payload + 2B CRC)

setTxPayload 0 0x14 0x00 0x8C 0x00 0x55 0x55 0x01 0x23 0x45 0x67 0x89 0xAB 0xCD 0xEF 0x34 0x12
             | PHR |   FCF   | SN | D. PAN  |     Destination Long Address          | S. PAN  |
0x78 0x56 0x55
 S. Addr | Payl.|

// or load it in two commands if the default argument length does not let the command pass in one run

setTxPayload 0  0x14 0x00 0x8C 0x00 0x55 0x55 0x01 0x23 0x45 0x67
setTxPayload 10 0x89 0xAB 0xCD 0xEF 0x34 0x12 0x78 0x56 0x55

Don't forget to increase the maximum packet length on the transmitter if needed:

setTxLength 19

As a complete example to send and receive a packet with a long address, use the following commands after resetting the devices:

// Rx Node

rx 0
config2p4GHz802154
enable802154 rx 100 192 1000
rx 1
setPanId802154 0x5555
setLongAddr802154 0x01 0x23 0x45 0x67 0x89 0xAB 0xCD 0xEF

// Tx Node

rx 0
config2p4GHz802154
enable802154 rx 100 192 1000
rx 1
setTxPayload 0  0x14 0x00 0x8C 0x00 0x55 0x55 0x01 0x23 0x45 0x67
setTxPayload 10 0x89 0xAB 0xCD 0xEF 0x34 0x12 0x78 0x56 0x55
setTxLength 19

In the examples above, the transmitted frame was a Beacon type message. By default, enabling IEEE 802.15.4 mode, all frame types are enabled to receive. To filter out or reenable messages with different frame types, use the acceptFrames command.

The command's argument sets which frames can be received:

acceptFrames <MAC command> <ACK> <Data> <Beacon> [<Multipurpose>]

For example, after the following command, the receiver rejects data and Beacon type frames, but accepts ACK and MAC command frames.

acceptFrames 1 1 0 0

Notes on Address Filtering#

Broadcast messages are always received, regardless of the configured addresses.

You can deactivate an address by setting it to the broadcast address (0xFFFF) at the corresponding index.

setPanId802154 0xFFFF <index>
setShortAddr802154 0xFFFF <index>

802.15.4 Address Filtering is fully disabled when the device is in promiscuous mode.

setPromiscuousMode 1

There is no constraint between the short and the long address and the PAN ID; you can set each of them independently at any index.

RAIL supports intra-PAN communication via multiple addresses defined using different PAN IDs.

Auto-ACK#

Auto-ACK is automatically enabled by enabling IEEE 802.15.4 mode using the enable802154 command.

rx 0
config2p4GHz802154
enable802154 rx 100 192 1000

rx 1

The third and fourth parameters of the enable802154 command set the Rx-to-Tx turnaround time and the ACK timeout in microseconds, respectively.

Start with the Tx packet and device configuration introduced in the previous example:

setTxPayload 0 0x0E 0x00 0x88 0x00 0x55 0x55 0xAA 0xAA 0x34 0x12 0x78 0x56 0x55

To request an ACK message, the first byte of the FCF field must be changed:

  1. Request ACK packet by setting the AR bit (5th bit).

  2. Beacon frames cannot be acknowledged: set Frame type (3 LS bits) to 0b001 (Data).

The first byte of the FCF shall be 0x21:

setTxPayload 0 0x0E 0x21 0x88 0x00 0x55 0x55 0xAA 0xAA 0x34 0x12 0x78 0x56 0x55

Also, configure RAIL to expect an ACK packet after transmission. To do this, run the following command:

configTxOptions 1

See a complete example for testing Auto-ACK feature below:

// Tx node

rx 0
config2p4GHz802154
enable802154 rx 100 192 1000
setPanId802154 0x1234
setShortAddr802154 0x5678
setTxPayload 0 0x0E 0x21 0x88 0x00 0x55 0x55 0xAA 0xAA 0x34 0x12 0x78 0x56 0x55
configTxOptions 1
rx 1

// Rx node

rx 0
config2p4GHz802154
enable802154 rx 100 192 1000
setPanId802154 0x5555
setShortAddr802154 0xAAAA
rx 1

Review the received ACK message's payload:

0x05 0x02 0x00 0x00

  • 0x05: This is the PHR and the Frame Length is 5

  • 0x02 0x00: The FCF field indicates that it is an ACK frame

  • 0x00: Sequence Number is identical to the packet which is acknowledged by this packet

To change the Sequence Number only, you can use the following command:

setTxPayload 3 0x01

IEEE 802.15.4 ACK frames are automatically assembled in RAIL, there is no need to set it up in the Rx node.

Notes on Auto-ACK#

Auto-ACK is fully disabled when the device is in promiscuous mode.

setPromiscuousMode 1

To disable or reenable Auto-Ack feature use the following command:

autoAckPause <Rx> <Tx>

Changing the ACK payload or its length prevents RAIL from assembling the packet. Printing the ACK packet does not display the automatically generated IEEE 802.15.4 ACK.

setAckPayload
setAckLength
printAckPacket

RAIL sets the frame pending bit in the ACK payload automatically.

Runtime PHY changes#

Whitening and CRC Config#

SUN-FSK PHYs support dynamic radio configuration changes, such as selecting a 2- or 4-byte CRC (FCS type) and enabling or disabling whitening (DW) over the PSDU field. RAIL fully supports these features. The radio is reconfigured on the fly during packet transmission and reception based on the PHR.

This mode can be enabled by the RAIL_IEEE802154_G_OPTION_GB868 option. Use the set802154g command to enable the G_OPTIONs.

// Tx node

rx 0
config915MHz802154
enable802154 rx 100 192 1000
set802154g 1
setPanId802154 0x1234
setShortAddr802154 0x5678
setTxPayload 2 0x00 0x88 0x00 0x55 0x55 0xAA 0xAA 0x34 0x12 0x78 0x56 0x55
setTxLength 14
rx 1

Then, for non-whitened & 4B FCS:

set802154phr 1 0 0 // non-whitened & 4B FCS
set802154phr 1 1 0 // non-whitened & 2B FCS
set802154phr 1 0 1 // whitened & 4B FCS
set802154phr 1 1 1 // whitened & 2B FCS

// Rx node

rx 0
config915MHz802154
enable802154 rx 100 192 1000
set802154g 1
setPanId802154 0x5555
setShortAddr802154 0xAAAA
rx 1

Dynamic FEC#

The SUN-FSK protocol defines a dynamic FEC feature that is supported on certain EFR32 device generations. The SFD field indicates whether FEC is enabled for the transmitted or received packet.

This mode can be enabled by the RAIL_IEEE802154_G_OPTION_DYNFEC option. Use the set802154g command to enable the G_OPTIONs.

// Tx node

rx 0
enable802154 rx 100 192 1000

//set_appropriate_channel
setconfigindex <Y>
setchannel <X>

set802154g 3
setPanId802154 0x1234
setShortAddr802154 0x5678
setTxPayload 2 0x00 0x88 0x00 0x55 0x55 0xAA 0xAA 0x34 0x12 0x78 0x56 0x55
setTxLength 14
set802154phr 1 1 1 // whitened & 2B FCS
rx 1

// Rx node

rx 0
setchannel <set_appropriate_channel>
enable802154 rx 100 192 1000
set802154g 3
setPanId802154 0x5555
setShortAddr802154 0xAAAA
rx 1

Transmit packet without FEC encoding (using sync word #0):

configTxOptions 0
tx 1

Transmit packet without FEC encoding (using sync word #1):

configTxOptions 0x4
tx 1

To use this feature on supported platforms, contact technical support to create an appropriate PHY.

The set802154g command requires an appropriate PHY configuration and idle state.