Examples#

The following examples demonstrate basic functionalities of the 802.15.4 RAIL features. Usually, these tests require 2 RAILtest nodes, one operating as a transmitter and the other as the receiver. Issue the commands on both nodes if not stated otherwise.

For the sake of simplicity, we demonstrate the 802.15.4 features using the in-built 2.4 GHz 250 kbps O-QPSK and the 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

Transmitting a packet (tx 1) from TX node is received on the RX node.

The default payload of the RAILtest application is constructed so that the device will transmit a 16 bytes length frames. Therefore, loading the subGHz PHYs also changes the first two bytes of the payload (the PHR field) to comply with the default 16 byte length packet configuration of the RAILtest application, if the default payload has not been changed yet.

To set different payload lengths, see the next example.

Use the getChannel command to see which channel the radio is on.

Variable Length Payload#

To change the payload length of the transmitted packet, the Frame Length (FL) field of the PHR must be changed. The Frame Length field specifies the total number of bytes in the PSDU (PSDU_LEN). RAIL automatically sets the length of the packet according to the Frame Length field on both TX and RX modes.

The length of the PHR (PHR_LEN) can be 1 or 2 bytes in these PHYs.

Keep in mind that CRC bytes must be included in the Frame Length field. 802.15.4 supports both 2 and 4 bytes length CRC sequences, so the length of the CRC (CRC_LEN) can be 2 or 4.

In the examples below, PACKET_LEN denotes the packet length RAIL uses (including the PHR but excluding the CRC), while PSDU_LEN is the value of the Frame Length field defined by 802.15.4. In other words, RAIL expects PACKET_LEN bytes in the TX FIFO before transmitting the packet.

PACKET_LEN = PSDU_LEN + PHR_LEN – CRC_LEN.

If PACKET_LEN is higher than the default RAILtest payload (16), the setTxLength <MAX_PACKET_LEN> must also be issued, where MAX_PACKET_LEN is the length of the maximum expected payload length to transmit. If PACKET_LEN > MAX_PACKET_LEN RAIL generates a RAIL_EVENT_TX_UNDERFLOW event resulting in packet abort as there are no more bytes stored in the TX FIFO to transmit.

For the 2.4 GHz PHY (1B PHR), the Frame Length field is the 7 LSB bits of the first byte.

setTxPayload 0x00 <FL[6:0]>

where FL can range between 4 - 127. The MSB bit shall be set to 0.

CRC_LEN = 2
PHR_LEN = 1

FL = PSDU_LEN = PACKET_LEN + 1

More examples:

rx 0

config2p4GHz802154

setTxPayload 0x00 0x04 // PACKET_LEN = 3; PSDU_LEN = 4; shortest payload
// or
setTxPayload 0x00 0x0F // PACKET_LEN = 14; PSDU_LEN = 15; default payload
// or
setTxPayload 0x00 0x11 // PACKET_LEN = 16; PSDU_LEN = 18; longest payload using default TX length config
// or
setTxLength 17
setTxPayload 0x00 0x12 // PACKET_LEN = 18; PSDU_LEN = 19; adjust TX length to prevent underflow error

tx 1

For the SubGHz PHYs (2B header), the Frame Length field is the 3 MSB bits of the first byte and all the 8 bits of the second byte in MSB first order.

setTxPayload 0x00 <PHR[0:5] + FL[8:11] >> 5> <FL[0:7]>

where FL can range between 4 - 2047.

CRC_LEN = 2 // default configuration
PHR_LEN = 2

FL = PSDU_LEN = PACKET_LEN

More examples:

rx 0

config863GHz802154
// or
config915MHz802154

setTxPayload 0x00 0x18 0xA0 // PACKET_LEN = PSDU_LEN = 5; shortest payload
// or
setTxPayload 0x00 0x18 0x70 // PACKET_LEN = PSDU_LEN = 14; default payload
// or
setTxPayload 0x00 0x18 0x08 // PACKET_LEN = PSDU_LEN = 16; longest payload using default TX length config
// or
settxlength 17
setTxPayload 0x00 0x18 0x88 // PACKET_LEN = PSDU_LEN = 17; adjust TX length to prevent underflow error

In summary, to transmit a packet with N bytes of payload (i.e., MHR + MAC payload), set:

  • FL to N + CRC_LEN, and

  • MAX_PACKET_LEN to N + PHR_LEN, if needed.

The default RX and TX buffer size of RAILtest is set to 512 bytes.

The 863 and 915 MHz inbuilt PHYs limits the payload length to 127 (0xFE).

Use the printTxPacket command to see the TX payload!

Use the configRxOptions 0x1 to store the CRC on valid packet reception.

2. Address Filtering#

In this example, we will use the 2.4 GHz PHY only.

Enable Address Filtering#

HW accelerated MAC features, such as frame and address filtering, are enabled by enabling 802.15.4 mode 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).

We should format a valid broadcast message to get the packet received without defining any address.

Formatting Broadcast Message#

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

  • Frame Type = 3b000 (Beacon)

  • Security Enabled = 1b0

  • Frame Pending = 1b0

  • AR = 1b0

  • PAN ID Compression = 1b0

  • Reserved = 1b0

The first byte of the PSDU is 0x00.

  • Sequence Number Compression = 1b0

  • IE Present = 1b0

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

  • Frame Version = 1b0

  • Source address = 2b10 (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 + 1B payload + 2B 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#

As the next step, we 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, we 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 we can send a message directly addressed to our receiver node, keeping all other parameters of the packet the same as before:

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

Setting PAN ID and Short Address on the transmitter does not filter packets from transmitting.

You can check at this point that changing only 1 bit in the Destination Address or PAN ID makes the RX node not receive 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 shall be changed:

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

The second byte of the FCF is 0x8C.

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

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

  • We should 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 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 will reject data and Beacon type frames, but accept Ack and MAC command frames.

acceptFrames 1 1 0 0

Notes on Address Filtering#

Broadcast messages can always be received regardless of the configured addresses.

Addresses can be deactivated by setting the address 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 802.15.4 mode using the enable802154 command.

rx 0
config2p4GHz802154
enable802154 rx 100 192 1000

rx 1

The third and the fourth parameter of the enable802154 command sets the RX-to-TX turnaround time and the ACK timeout in microseconds, respectively.

Let's start with the TX packet and corresponding 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 Acknowledge 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 3b001 (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, RAIL must be informed that, after transmitting the packet, an ACK packet is expected to be received. To do that, issue 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

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 to assemble the packet. Also, printing the ACK packet will not result in printing the auto 15.4 ACK packet.

setAckPayload
setAckLength
printAckPacket

RAIL sets the Frame Pending bit in the ACK payload automatically.

Runtime PHY changes#

Whitening and CRC Config#

The SUN FSK PHYs define dynamic radio config changes (i.e., selecting 2/4 byte CRC - FCS type - or enabling/disabling whitening - DW - over the PSDU field) which is fully supported by RAIL. The radio is reconfigured on the fly during packet transmission and reception according to the PHR field.

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
rx 1

settxpayload 0x00 0x00 0x70 // not-whitened & 4B FCS
settxpayload 0x00 0x08 0x70 // not-whitened & 42 FCS
settxpayload 0x00 0x10 0x70 // whitened & 4B FCS
settxpayload 0x00 0x18 0x70 // whitened & 2B FCS

// RX node

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

Alternatively, you can use the set802154PHR command once the radio is configured with a PHY capable of handling dynamic PHY reconfiguration.

For SUN FSK compatibility, the first argument should be 1. The second and third arguments set up which CRC is being used and whether whitening is enabled on the transmitted packet.

This command also sets up the frame length derived from the setTxLength <PACKET_LEN> config.

For the 2.4 GHz PHY, pass 0 as the first and omit the other arguments to set up the Frame Length in the PHR according to the configured TX packet length.

settxpayload 0x00 0x00 0x70 // not-whitened & 4B FCS
set802154PHR 1 0 0

settxpayload 0x00 0x08 0x70 // not-whitened & 42 FCS
set802154PHR 1 1 0

settxpayload 0x00 0x10 0x70 // whitened & 4B FCS
set802154PHR 1 0 1

settxpayload 0x00 0x18 0x70 // whitened & 2B FCS
set802154PHR 1 1 1

Dynamic FEC#

SUN FSK protocol defines the dynamic FEC feature which is supported on certain EFR32 device generations. The SFD field type indicates whether FEC is enabled or not on the transmitted/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
settxpayload 0x00 0x18 0x70 // 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 syncword #0):

configTxOptions 0
tx 1

Transmit packet without FEC encoding (using syncword #1):

configTxOptions 0x4
tx 1

Using it on platforms where it is supported requires help from technical support to create an appropriate PHY.

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