Using the Headers and Footers from RAIL#

For radios that use RAIL, the hardware generates everything up to the end of the sync word and from the start of the CRC. Data between the end of the sync word and the start of the CRC is read from the FIFO. This is the general rule, although RAIL and the radio can be configured differently.

In IEEE 802.15.4 terms, this means, the radio generates the SHR (including the SFD) and the FCS, which is part of the MAC footer. The application loads the PHR, MHR, and MAC payload. You can also change the SFD by using separate APIs.

Start of Frame Delimiter (SFD, Sync Word)#

The Radio Configurator can configure up to two sync words, with some limitations. If the selected demodulator supports this feature, the radio can receive both sync words. You can read the sync word of the received packet from the sync_word_id field of sl_rail_rx_packet_details_t.

On transmit, select the sync word by using the SL_RAIL_TX_OPTION_SYNC_WORD_ID Tx option.

For SUN-FSK, the SFD selection determines whether FEC is used. By default, the hardware does not decode or encode this, but you can enable it. See Dynamic FEC in the next section.

Payload header (PHR)#

As discussed above, the PHR should be loaded from RAIL as the beginning of the payload. The most important role of the PHR is the length configuration. With RAIL-supported radios configured for variable length mode, both the Tx and Rx length is automatically configured from the length field. Note that this means that if you load more data to the FIFO than needed, some extra bytes will remain there until reset, or transmitted as part of the next frame.

If you load more data into the FIFO than required, extra bytes remain until you reset the FIFO or transmit the next frame, where they will be included.

The length field in the PHR includes the entire PHY payload. This includes the FCS (CRC) bytes but not the PHR itself. RAIL expects the PHR in the FIFO but not the FCS.

For example, if you set the length field to 16 in a 1-byte PHR and 2-byte FCS configuration, the MAC payload is 14 bytes, while RAIL expects 15 bytes in the FIFO.

1-byte PHR#

The following PHYs use the 1-byte PHR with a 7-bit length field and one reserved bit at the most-significant-bit (MSB):

2.4 GHz 250 kbps O-QPSK PHYs
SubGHz BPSK PHYs
All Connect PHYs
All Long Range PHYs

The radio hardware handles endianness automatically. To set the PHR, set the first byte of the FIFO to a value between 1 and 127.

2-byte PHR#

The following PHYs use the 2-byte PHR with an 11-bit length field and configurable whitening and FCS:

SUN FSK PHYs, including Wi-SUN FSK PHYs
UK metering PHYs

In SUN-FSK, the PHR is transmitted MSB first, while the rest of the packet is least-significant-bit (LSB) first. The radio operates in LSB-first mode, so the application must reverse the PHR bit order (endianness). You can do this by using the following functions:

void set_phr(uint8_t *payload, uint32_t phr, uint8_t phr_size){
  phr = __RBIT(phr);
  for (uint8_t index = 0; index < phr_size; index++) {
    payload[index] = ((phr & (0xFF << index * 8)) >> index * 8);
  }
}

uint32_t get_phr(uint8_t *payload, uint8_t phr_size){
  uint32_t phr = 0;
  for (uint8_t index = 0; index < phr_size; index++) {
    phr |= payload[index] << (index * 8);
  }
  phr = __RBIT(phr);
  return phr;
}void set_phr(uint8_t *payload, uint32_t phr, uint8_t phr_size){
  phr = __RBIT(phr);
  for (uint8_t index = 0; index < phr_size; index++) {
    payload[index] = ((phr & (0xFF << index * 8)) >> index * 8);
  }
}

uint32_t get_phr(uint8_t *payload, uint8_t phr_size){
  uint32_t phr = 0;
  for (uint8_t index = 0; index < phr_size; index++) {
    phr |= payload[index] << (index * 8);
  }
  phr = __RBIT(phr);
  return phr;
}

The code above is flexible and supports PHR sizes up to 4 bytes. Although this approach might be less efficient for a 2-byte PHR, you can use the same code for upcoming 4-byte PHR sections.

Construct the native-endianness PHR as follows:

uint16_t phr = ((fcsType << 12) | (whitening << 11) | frameLength);uint16_t phr = ((fcsType << 12) | (whitening << 11) | frameLength);

The whitening and FCS selection is not automatic in the hardware, but that can be enabled. See 2-byte Header Options in the next chapter.

Mode switch frame#

Mode switch frame can be coded with the 2-byte PHR configuration. Although run-time generation of the Mode Switch PHR is possible, we found that it is simpler to pre-generate them. When generating a Wi-SUN PHY, an an array of structs will be generated as well. This includes the PHR needed to switch to the given PHY.

You must still flip the endianness of this value by using the set_phr() function described above. For information about receiving mode switch frames, see the next page.

36-bit PHR#

The following PHYs use the 36-bit PHR, which has an 11-bit length field, configurable rate and scrambling and has an 8-bit HCS (CRC), and a 6-bit all-zero tail field:

SUN OFDM PHYs
Connect OFDM PHYs

To simplify the application, the radio hardware automatically generates the HCS and Tail on Tx and checks and removes them on Rx. To avoid handling partial bytes, the hardware use a 4-byte pseudo-PHR for both Tx and Rx.

OFDM pseudo PHR

Note: The Rate, Length, and Scrambler field sizes match the IEEE 802.15.4 PHR, but the HCS and Tail fields are not included. To match SUN-FSK handling, you must also flip the endianness of this pseudo-PHR.

In Tx mode, the Rx ID is reserved and must be set to 0. In Rx mode, it is 0xC0. The MSB is always 1 for Softmodem Rx, while the lower bits define the received modulation (1 for OFDM).

The hardware handles the Rate (MCS) and Scrambler. It processes the payload based on the PHR bits for both Tx and Rx.

Use the same function as for the 2-byte PHR to convert endianness. You can assemble the native-endianness PHR as follows:

phr = (rate << 19) | (frameLength << 7) | (scrambler << 3);phr = (rate << 19) | (frameLength << 7) | (scrambler << 3);

3-byte PHR#

The following PHYs use the 3-byte PHR, which has an 11-bit length field, configurable rate and spreading and has an 8-bit HCS (CRC):

SUN OQPSK PHYs

To simplify the application, the radio hardware automatically generates the HCS on Tx and checks and removes it on Rx. Use a similar 4-byte pseudo-PHR for SUN-OQPSK:

OQPSK pseudo PHR

Note: The Rate, Length, and Spreading field sizes match the IEEE 802.15.4 PHR, but the HCS field is not included. To match SUN-FSK handling, you must also flip the endianness of this pseudo-PHR.

In Tx mode, the Rx ID is reserved and must be set to 0. In Rx mode, it is 0xA0. The MSB is always 1 for Softmodem Rx, while the lower bits define the received modulation (2 for SUN-OQPSK).

The hardware handles the Rate and Spreading. It processes the payload based on the PHR bits for both Tx and Rx.

Use the same function as for the 2-byte PHR to convert endianness. You can assemble the native-endianness PHR as follows:

phr = (spreadingMode << 15) | (rateMode << 13) | frameLength;phr = (spreadingMode << 15) | (rateMode << 13) | frameLength;