802.15.4 HW Accelerated MAC Features#

The APIs introduced in the following chapters can work with any proprietary PHY (just like any PHY defined under the Connect Profile in the Radio Configurator) which meets the 802.15.4 frame format specification. This is the only requirement of the 802.15.4 PHY layer to use the protocol-specific RAIL APIs. The Connect SDK is a great example of how to use the protocol specific features on PHYs that are not fully 802.15.4 compatible.

The hardware does support address and frame filtering, Auto-ACK, and support to handle the frame pending bit in the ACK, implemented in RAIL. To enable it, use the RAIL_IEEE802154_Init() API call and the other calls related to address filtering or frame pending.

You can configure the Address Filtering and Auto-Ack features via the Init API, though those features have individual configuration APIs introduced in the following chapters.

Address Filtering#

To configure address filtering, call RAIL_IEEE802154_SetAddresses() with a structure containing all addresses, or call the individual RAIL_IEEE802154_SetPanId(), RAIL_IEEE802154_SetShortAddress(), and RAIL_IEEE802154_SetLongAddress() APIs.

You can set up the addresses in the RAIL_IEEE802154_Init() API, too.

Configuring the addresses packet reception will be immediately aborted if the configured Address Filtering does not match.

RAIL supports intra-PAN (network) communication using multiple addresses.

Note that IEEE 802.15.4 Address Filter is not the same as the generic RAIL’s Address Filter feature.

Best Practices for Address Filtering#

Broadcast addresses are supported by default without any additional configuration and do not consume extra address slots.

Set unused addresses to the broadcast address (0xFFFF) to avoid false detections.

Do not change addresses during reception. Reconfiguring the Address Filter while receiving a packet may result in undesired behavior.

For more details, see the Detailed Description at IEEE 802.15.4 documentation and RAIL_IEEE802154_AddrConfig_t type’s documentation.

Auto-Ack and Frame Pending#

Auto-ACK is controlled by the ackConfig and timings fields passed to RAIL_IEEE802154_Init(). After initialization, they may be controlled using the normal Auto-ACK and State Transitions APIs.

The ackTimeout field only covers sync word detection of the received packet. Therefore, the ACK’s PHY header and payload time shall be accommodated to get the correct ackTimeout setting. Find an example at RAIL’s IEEE 802.15.4 – Detailed Description.

To listen for an ACK packet, you must transmit the packet with the RAIL_TX_OPTION_WAIT_FOR_ACK option.

The ACK frame includes the same sequence number as the frame that it responds to.

The AR bit in the Frame Control Field specifies whether an acknowledgment is required from the receiver device. Upon a reception, the receiver sends an ACK frame only if the frame passes the filtering. If this bit is 0, the receiver does not send an ACK packet. Usually, the AR is located at the 5th position of the FCF.

The Frame Pending bit is used for data polling. The end device polls the coordinator with a data request command. If the coordinator has a message to the end device, it responds with an ACK packet with the frame pending bit set in the FCF.

When in IEEE 802.15.4 mode, the ACK will generally have a 5-byte length (FCF, sequence number and FCS from the MAC fields, but have no payload), its Frame Type will be ACK, its Frame Version 0 (2003), and its Frame Pending bit will be false unless the RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND event is triggered, in which case, it will default to the RAIL_IEEE802154_Config_t::defaultFramePendingInOutgoingAcks setting. If the default Frame Pending setting is incorrect, the app must call RAIL_IEEE802154_ToggleFramePending() (formerly RAIL_IEEE802154_SetFramePending()) while handling the RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND event.

This event must be turned on by the user and will fire whenever a data request is being received or fully received so that the stack can determine if there is pending data. Note that if the default Frame Pending bit needs to be changed, it must be done quickly. Otherwise, the ACK may already have been transmitted with the default setting. To trigger this event earlier, during the packet reception, use the RAIL_IEEE802154_EnableEarlyFramePending() API.

Check the return code of RAIL_IEEE802154_ToggleFramePending() to be sure that the Frame Pending bit was changed in time.

The RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND is triggered only for Data Request MAC command frames requesting ACK. To trigger this event also for Data type frames call the RAIL_IEEE802154_EnableDataFramePending() API.

Enhanced ACK#

The RAIL_IEEE802154_E_OPTION_ENH_ACK option allows the radio to receive packets with Frame Version 2 in the MAC header, as RAIL normally accepts packets with Frame Version 0 or 1. Enabling this option is required for handling Enhanced ACK frames.

RAIL assembles Immediate ACK frames automatically, but not Enhanced ACK frames. A dedicated RAIL event, RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND, is implemented to parse a partly-received frame to determine the type of ACK needed to provide enough time to generate the ENH-ACK frame.

Note that this feature does not enable receiving Multipurpose frames. It can be enabled via the RAIL_IEEE802154_AcceptFrames() API.

Note: Thread protocol always sets the FP bit to 1.

Implicit Broadcast#

The RAIL_IEEE802154_E_OPTION_IMPLICIT_BROADCAST option enables the MAC implicit broadcast feature. If the Frame Version is 2 and the frame lacks the destination PAN ID and address, then the packet is treated like a broadcast packet. If this option is disabled, such a packet is usually filtered.

Runtime PHY Reconfiguration with SUN FSK and Wi-SUN PHYs#

2B Header Options#

Call RAIL_IEEE802154_ConfigGOptions() with the RAIL_IEEE802154_G_OPTION_GB868 option to support dynamic CRC and whitening reconfiguration coded in a 2B PHR PHY.

In this mode, RAIL automatically reads the PHR field of the transmitted and received packet, and reconfigures the radio (i.e., enables/disables whitening for the rest of the payload, and selects 2/4-bytes CRC configuration) according to the FCS and WHITENING bitfields during the ongoing operation.

Though the API’s name is a bit misleading, this enables all the 802.15.4g available features.

Dynamic FEC#

To enable/disable 802.15.4g dynamic FEC feature use the RAIL_IEEE802154_G_OPTION_DYNFEC option.

SFD field (implemented as the syncword) indicates whether the rest of the packet is FEC encoded or not. As the SFD field is configured as the syncword on the EFR32 radio platform, it enables dual syncword detection to detect whether FEC should be enabled or not.

Address Filtering and FEC work only simultaneously on radio platforms where RAIL_IEEE802154_SUPPORTS_G_DYNFEC is defined. That means on former chips, Promiscuous mode should be enabled to support FEC.

Dynamic FEC configuration is supported on SUN FSK PHYs only.

Find more information at IEEE 802.15.4.

Mode Switch#

The mode switch mechanism enables a device using the MR-FSK PHY to change its symbol rate and/or modulation scheme on a packet-by-packet basis. This feature can be enabled/disabled with the RAIL_IEEE802154_G_OPTION_WISUN_MODESWITCH option.

A specific mode switch PPDU is used to inform the receiver of the mode switch and specifies the new PHY mode of the following PPDU.

Switching to a new PHY mode with a higher rate typically by sending/receiving a specific Mode Switch packet that indicates the incoming new PHY mode. The Mode Switch packet is an FSK-modulated 2-byte PHY header with no payload.

Find more information at IEEE 802.15.4.

Note that this is the Mode Switch feature defined by Wi-SUN and not the 802.15.4g standard.