IEEE 802.15.4

IEEE 802.15.4 configuration routines.

Data Structures

struct  RAIL_IEEE802154_Address_t
 Representation of 802.15.4 address This structure is only used for received source address information needed to perform frame pending lookup.
 
struct  RAIL_IEEE802154_AddrConfig_t
 A configuration structure for IEEE 802.15.4 Address Filtering.
 
struct  RAIL_IEEE802154_Config_t
 A configuration structure for IEEE 802.15.4 in RAIL.

Macros

#define RAIL_IEEE802154_MAX_ADDRESSES   (3U)
 The maximum number of allowed addresses of each type.
 
#define RAIL_IEEE802154_E_OPTIONS_NONE   0UL
 A value representing no options enabled.
 
#define RAIL_IEEE802154_E_OPTIONS_DEFAULT   RAIL_IEEE802154_E_OPTIONS_NONE
 All options disabled by default .
 
#define RAIL_IEEE802154_E_OPTION_GB868   (1UL << RAIL_IEEE802154_E_OPTION_GB868_SHIFT)
 An option to enable/disable 802.15.4E-2012 features needed for GB868.
 
#define RAIL_IEEE802154_E_OPTION_ENH_ACK   (1UL << RAIL_IEEE802154_E_OPTION_ENH_ACK_SHIFT)
 An option to enable/disable 802.15.4E-2012 features needed for Enhanced ACKs.
 
#define RAIL_IEEE802154_E_OPTION_IMPLICIT_BROADCAST   (1UL << RAIL_IEEE802154_E_OPTION_IMPLICIT_BROADCAST_SHIFT)
 An option to enable/disable 802.15.4E-2012 macImplicitBroadcast feature.
 
#define RAIL_IEEE802154_E_OPTIONS_ALL   0xFFFFFFFFUL
 A value representing all possible options.
 
#define RAIL_IEEE802154_G_OPTIONS_NONE   0UL
 A value representing no options enabled.
 
#define RAIL_IEEE802154_G_OPTIONS_DEFAULT   RAIL_IEEE802154_G_OPTIONS_NONE
 All options disabled by default .
 
#define RAIL_IEEE802154_G_OPTION_GB868   (1UL << RAIL_IEEE802154_G_OPTION_GB868_SHIFT)
 An option to enable/disable 802.15.4G-2012 features needed for GB868.
 
#define RAIL_IEEE802154_G_OPTIONS_ALL   0xFFFFFFFFUL
 A value representing all possible options.
 
#define RAIL_IEEE802154_ACCEPT_BEACON_FRAMES   (0x01)
 When receiving packets, accept 802.15.4 BEACON frame types.
 
#define RAIL_IEEE802154_ACCEPT_DATA_FRAMES   (0x02)
 When receiving packets, accept 802.15.4 DATA frame types.
 
#define RAIL_IEEE802154_ACCEPT_ACK_FRAMES   (0x04)
 When receiving packets, accept 802.15.4 ACK frame types.
 
#define RAIL_IEEE802154_ACCEPT_COMMAND_FRAMES   (0x08)
 When receiving packets, accept 802.15.4 COMMAND frame types.
 
#define RAIL_IEEE802154_ACCEPT_MULTIPURPOSE_FRAMES   (0x20)
 When receiving packets, accept 802.15.4-2015 Multipurpose frame types.
 
#define RAIL_IEEE802154_ACCEPT_STANDARD_FRAMES
 In standard operation, accept BEACON, DATA and COMMAND frames.

Enumerations

enum  RAIL_IEEE802154_AddressLength_t {
  RAIL_IEEE802154_ShortAddress = 2,
  RAIL_IEEE802154_LongAddress = 3
}
 Different lengths that an 802.15.4 address can have.
 
enum  RAIL_IEEE802154_EOptions_t {
  RAIL_IEEE802154_E_OPTION_GB868_SHIFT = 0,
  RAIL_IEEE802154_E_OPTION_ENH_ACK_SHIFT,
  RAIL_IEEE802154_E_OPTION_IMPLICIT_BROADCAST_SHIFT
}
 802.15.4E-2012 options, in reality a bitmask.
 
enum  RAIL_IEEE802154_GOptions_t { RAIL_IEEE802154_G_OPTION_GB868_SHIFT = 0 }
 802.15.4G-2012 options, in reality a bitmask.

Functions

RAIL_Status_t RAIL_IEEE802154_Init (RAIL_Handle_t railHandle, const RAIL_IEEE802154_Config_t *config)
 Initialize RAIL for IEEE802.15.4 features.
 
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadio (RAIL_Handle_t railHandle)
 Configure the radio for 2.4 GHz 802.15.4 operation.
 
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioAntDiv (RAIL_Handle_t railHandle)
 Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity.
 
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioAntDivCoex (RAIL_Handle_t railHandle)
 Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity optimized for radio coexistence.
 
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioCoex (RAIL_Handle_t railHandle)
 Configure the radio for 2.4 GHz 802.15.4 operation optimized for radio coexistence.
 
RAIL_Status_t RAIL_IEEE802154_ConfigGB863MHzRadio (RAIL_Handle_t railHandle)
 Configure the radio for SubGHz GB868 863 MHz 802.15.4 operation.
 
RAIL_Status_t RAIL_IEEE802154_ConfigGB915MHzRadio (RAIL_Handle_t railHandle)
 Configure the radio for SubGHz GB868 915 MHz 802.15.4 operation.
 
RAIL_Status_t RAIL_IEEE802154_Deinit (RAIL_Handle_t railHandle)
 De-initialize IEEE802.15.4 hardware acceleration.
 
bool RAIL_IEEE802154_IsEnabled (RAIL_Handle_t railHandle)
 Return whether IEEE802.15.4 hardware acceleration is currently enabled.
 
RAIL_Status_t RAIL_IEEE802154_SetAddresses (RAIL_Handle_t railHandle, const RAIL_IEEE802154_AddrConfig_t *addresses)
 Configure the RAIL Address Filter for 802.15.4 filtering.
 
RAIL_Status_t RAIL_IEEE802154_SetPanId (RAIL_Handle_t railHandle, uint16_t panId, uint8_t index)
 Sets a PAN ID for 802.15.4 address filtering.
 
RAIL_Status_t RAIL_IEEE802154_SetShortAddress (RAIL_Handle_t railHandle, uint16_t shortAddr, uint8_t index)
 Set a short address for 802.15.4 address filtering.
 
RAIL_Status_t RAIL_IEEE802154_SetLongAddress (RAIL_Handle_t railHandle, const uint8_t *longAddr, uint8_t index)
 Set a long address for 802.15.4 address filtering.
 
RAIL_Status_t RAIL_IEEE802154_SetPanCoordinator (RAIL_Handle_t railHandle, bool isPanCoordinator)
 Set whether the current node is a PAN coordinator.
 
RAIL_Status_t RAIL_IEEE802154_SetPromiscuousMode (RAIL_Handle_t railHandle, bool enable)
 Set whether to enable 802.15.4 promiscuous mode.
 
RAIL_Status_t RAIL_IEEE802154_ConfigEOptions (RAIL_Handle_t railHandle, RAIL_IEEE802154_EOptions_t mask, RAIL_IEEE802154_EOptions_t options)
 Configure certain 802.15.4E-2012 / 802.15.4-2015 Frame Version 2 features.
 
RAIL_Status_t RAIL_IEEE802154_ConfigGOptions (RAIL_Handle_t railHandle, RAIL_IEEE802154_GOptions_t mask, RAIL_IEEE802154_GOptions_t options)
 Configure certain 802.15.4G-2012 / 802.15.4-2015 SUN PHY features (only for radio configurations designed accordingly).
 
RAIL_Status_t RAIL_IEEE802154_AcceptFrames (RAIL_Handle_t railHandle, uint8_t framesMask)
 Set which 802.15.4 frame types to accept.
 
RAIL_Status_t RAIL_IEEE802154_EnableEarlyFramePending (RAIL_Handle_t railHandle, bool enable)
 Enable early Frame Pending lookup event notification (RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND).
 
RAIL_Status_t RAIL_IEEE802154_EnableDataFramePending (RAIL_Handle_t railHandle, bool enable)
 Enable Frame Pending lookup event notification (RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND) for MAC Data frames.
 
RAIL_Status_t RAIL_IEEE802154_SetFramePending (RAIL_Handle_t railHandle)
 Set the frame pending bit on the outgoing legacy Immediate ACK.
 
RAIL_Status_t RAIL_IEEE802154_GetAddress (RAIL_Handle_t railHandle, RAIL_IEEE802154_Address_t *pAddress)
 Get the source address of the incoming data request.
 
RAIL_Status_t RAIL_IEEE802154_WriteEnhAck (RAIL_Handle_t railHandle, const uint8_t *ackData, uint8_t ackDataLen)
 Write the AutoACK FIFO for the next outgoing 802.15.4E Enhanced ACK.
 
uint8_t RAIL_IEEE802154_ConvertRssiToLqi (uint8_t origLqi, int8_t rssiDbm)
 Convert RSSI into 802.15.4 Link Quality Indication (LQI) metric compatible with the Silicon Labs Zigbee stack.
 
uint8_t RAIL_IEEE802154_ConvertRssiToEd (int8_t rssiDbm)
 Convert RSSI into 802.15.4 Energy Detection (ED) metric compatible with the Silicon Labs Zigbee stack.

Detailed Description

IEEE 802.15.4 configuration routines.

The functions in this group configure RAIL IEEE 802.15.4 hardware acceleration which includes IEEE 802.15.4 format filtering, address filtering, ACKing, and filtering based on the frame type.

To configure IEEE 802.15.4 functionality, the application must first set up a RAIL instance with RAIL_Init() and other setup functions. Instead of RAIL_ConfigChannels(), however, an application may use RAIL_IEEE802154_Config2p4GHzRadio() to set up the official IEEE 2.4 GHz 802.15.4 PHY. This configuration is shown below.

802.15.4 defines its macAckWaitDuration from the end of the transmitted packet to complete reception of the ACK. RAIL's ackTimeout only covers sync word detection of the ACK. Therefore, subtract the ACK's PHY header and payload time to get RAIL's ackTimeout setting. For 2.4 GHz OQPSK, macAckWaitDuration is specified as 54 symbols; subtracting 2-symbol PHY header and 10-symbol payload yields a RAIL ackTimeout of 42 symbols or 672 microseconds at 16 microseconds/symbol.

static RAIL_Handle_t railHandle = NULL; // Initialized somewhere else.
static const RAIL_IEEE802154_Config_t rail154Config = {
.addresses = NULL,
.ackConfig = {
.enable = true, // Turn on auto ACK for IEEE 802.15.4.
.ackTimeout = 672, // See note above: 54-12 sym * 16 us/sym = 672 us.
.rxTransitions = {
.success = RAIL_RF_STATE_RX, // Return to RX after ACK processing
.error = RAIL_RF_STATE_RX, // Ignored
},
.txTransitions = {
.success = RAIL_RF_STATE_RX, // Return to RX after ACK processing
.error = RAIL_RF_STATE_RX, // Ignored
},
},
.timings = {
.idleToRx = 100,
.idleToTx = 100,
.rxToTx = 192, // 12 symbols * 16 us/symbol = 192 us
.txToRx = 192, // 12 symbols * 16 us/symbol = 192 us
.rxSearchTimeout = 0, // Not used
.txToRxSearchTimeout = 0, // Not used
},
.promiscuousMode = false, // Enable format and address filtering.
.isPanCoordinator = false,
};
void config154(void)
{
// Configure the radio and channels for 2.4 GHz IEEE 802.15.4.
// Initialize the IEEE 802.15.4 configuration using the static configuration above.
RAIL_IEEE802154_Init(railHandle, &rail154Config);
}

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. RAIL supports RAIL_IEEE802154_MAX_ADDRESSES number of address pairs to receive packets from multiple IEEE 802.15.4 networks at the same time. Broadcast addresses are supported by default without any additional configuration so they do not consume one of these slots. If the application does not require all address pairs, be sure to set unused ones to the proper disabled value for each type. These can be found in the RAIL_IEEE802154_AddrConfig_t documentation. Below is an example of setting filtering for one set of addresses.

// PanID OTA value of 0x34 0x12.
// Short Address OTA byte order of 0x78 0x56.
// Long address with OTA byte order of 0x11 0x22 0x33 0x44 0x55 0x66 0x77 0x88.
// Set up all addresses simultaneously.
RAIL_Status_t setup1(void)
{
{ 0x1234, 0xFFFF, 0xFFFF },
{ 0x5678, 0xFFFF, 0xFFFF },
{ { 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88 },
{ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 },
{ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 } }
};
return RAIL_IEEE802154_SetAddresses(railHandle, &nodeAddress);
}
// Alternatively, the addresses can be set up individually as follows:
RAIL_Status_t setup2(void)
{
RAIL_Status_t status;
const uint8_t longAddress[] = { 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88 };
status = RAIL_IEEE802154_SetPanId(railHandle, 0x1234, 0);
if (status != RAIL_STATUS_NO_ERROR) {
return status
}
status = RAIL_IEEE802154_SetShortAddress(railHandle, 0x5678, 0);
if (status != RAIL_STATUS_NO_ERROR) {
return status
}
status = RAIL_IEEE802154_SetLongAddress(railHandle, longAddress, 0);
if (status != RAIL_STATUS_NO_ERROR) {
return status
}
}

Address filtering will be enabled except when in promiscuous mode which can be set with RAIL_IEEE802154_SetPromiscuousMode(). The addresses may be changed at runtime. However, if you are receiving a packet while reconfiguring the address filters, you may get undesired behavior so it's safest to do this while not in receive.

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. When in IEEE 802.15.4 mode, the ACK will generally have a 5 byte length, its Frame Type will be ACK, its Frame Version 0 (2003), and its Frame Pending bit will be set if RAIL_IEEE802154_SetFramePending() is called when the RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND event is triggered. This event must be turned on by the user and will fire whenever a data request is being received so that the stack can determine whether there is pending data. Be aware that the frame pending bit must be set quickly after receiving the event or the ACK may already have been transmitted. Check the return code of RAIL_IEEE802154_SetFramePending() to be sure that the bit was set in time.

Transmit and receive operations are done using the standard RAIL APIs in IEEE 802.15.4 mode. To send packets using the correct CSMA configuration there is a RAIL_CSMA_CONFIG_802_15_4_2003_2p4_GHz_OQPSK_CSMA define that can initialize the csmaConfig structure passed to RAIL_StartCcaCsmaTx().

Macro Definition Documentation

◆ RAIL_IEEE802154_ACCEPT_ACK_FRAMES

#define RAIL_IEEE802154_ACCEPT_ACK_FRAMES   (0x04)

When receiving packets, accept 802.15.4 ACK frame types.

Note
Expected ACK frame types will still be accepted regardless of this setting when waiting for an ACK after a transmit that used RAIL_TX_OPTION_WAIT_FOR_ACK and auto-ACK is enabled.

Definition at line 704 of file rail_ieee802154.h.

◆ RAIL_IEEE802154_ACCEPT_MULTIPURPOSE_FRAMES

#define RAIL_IEEE802154_ACCEPT_MULTIPURPOSE_FRAMES   (0x20)

When receiving packets, accept 802.15.4-2015 Multipurpose frame types.

(Not supported on EFR32XG1.)

Definition at line 710 of file rail_ieee802154.h.

◆ RAIL_IEEE802154_ACCEPT_STANDARD_FRAMES

#define RAIL_IEEE802154_ACCEPT_STANDARD_FRAMES
Value:
#define RAIL_IEEE802154_ACCEPT_COMMAND_FRAMES
When receiving packets, accept 802.15.4 COMMAND frame types.
Definition: rail_ieee802154.h:706
#define RAIL_IEEE802154_ACCEPT_DATA_FRAMES
When receiving packets, accept 802.15.4 DATA frame types.
Definition: rail_ieee802154.h:699
#define RAIL_IEEE802154_ACCEPT_BEACON_FRAMES
When receiving packets, accept 802.15.4 BEACON frame types.
Definition: rail_ieee802154.h:697

In standard operation, accept BEACON, DATA and COMMAND frames.

Don't receive ACK frames unless waiting for ACK (i.e. only receive expected ACKs).

Definition at line 715 of file rail_ieee802154.h.

◆ RAIL_IEEE802154_E_OPTION_ENH_ACK

#define RAIL_IEEE802154_E_OPTION_ENH_ACK   (1UL << RAIL_IEEE802154_E_OPTION_ENH_ACK_SHIFT)

An option to enable/disable 802.15.4E-2012 features needed for Enhanced ACKs.

This option requires that RAIL_IEEE802154_E_OPTION_GB868 also be enabled, and is enabled automatically on platforms that support this feature. It exists as a separate flag to allow runtime detection of whether the platform supports this feature or not.

When enabled, only an Enhanced ACK is expected in response to a transmitted ACK-requesting 802.15.4E Frame Version 2 frame, and when such a frame is received, the application is expected to generate the Enhanced ACK while processing RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND and call RAIL_IEEE802154_WriteEnhAck() in time for that Enhanced ACK to be sent. For this to work properly, the application should enable both RAIL_IEEE802154_EnableEarlyFramePending() and RAIL_IEEE802154_EnableDataFramePending(), and use RAIL_GetRxIncomingPacketInfo() to determine whether an Enhanced ACK is needed along the contents of that ACK packet.

On 802.15.4E GB868 platforms that lack this support, legacy Immediate ACKs are sent/expected for received/transmitted ACK-requesting 802.15.4E Frame Version 2 frames; calls to RAIL_IEEE802154_WriteEnhAck() have no effect. Attempting to use this feature via RAIL_IEEE802154_ConfigEOptions() returns an error.

Definition at line 589 of file rail_ieee802154.h.

◆ RAIL_IEEE802154_E_OPTION_GB868

#define RAIL_IEEE802154_E_OPTION_GB868   (1UL << RAIL_IEEE802154_E_OPTION_GB868_SHIFT)

An option to enable/disable 802.15.4E-2012 features needed for GB868.

When not promiscuous, RAIL normally accepts only 802.15.4 MAC frames whose MAC header Frame Version is 0 (802.15.4-2003) or 1 (802.15.4-2006), filtering out higher Frame Version packets (as RAIL_RX_PACKET_ABORT_FORMAT). Enabling this feature additionally allows Frame Version 2 (802.15.4E-2012 / 802.15.4-2015) packets to be accepted and passed to the application.

Note
If 802.15.4 MAC-level encryption is used with Frame Version 2 frames, RAIL_IEEE802154_EnableEarlyFramePending() should also be called otherwise data polls may not be recognized to trigger RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND events.
Enabling this feature also automatically enables RAIL_IEEE802154_E_OPTION_ENH_ACK on platforms that support that feature.
This feature does not automatically enable receiving Multipurpose frames; that can be enabled via RAIL_IEEE802154_AcceptFrames()'s RAIL_IEEE802154_ACCEPT_MULTIPURPOSE_FRAMES.

Definition at line 563 of file rail_ieee802154.h.

◆ RAIL_IEEE802154_E_OPTION_IMPLICIT_BROADCAST

#define RAIL_IEEE802154_E_OPTION_IMPLICIT_BROADCAST   (1UL << RAIL_IEEE802154_E_OPTION_IMPLICIT_BROADCAST_SHIFT)

An option to enable/disable 802.15.4E-2012 macImplicitBroadcast feature.

When enabled, received Frame Version 2 frames without a destination PAN ID or destination address are treated as though they are addressed to the broadcast PAN ID and broadcast short address. When disabled, such frames are filtered unless the device is the PAN coordinator and appropriate source addressing information exists in the packet

Definition at line 600 of file rail_ieee802154.h.

◆ RAIL_IEEE802154_E_OPTIONS_ALL

#define RAIL_IEEE802154_E_OPTIONS_ALL   0xFFFFFFFFUL

A value representing all possible options.

Definition at line 603 of file rail_ieee802154.h.

◆ RAIL_IEEE802154_E_OPTIONS_DEFAULT

#define RAIL_IEEE802154_E_OPTIONS_DEFAULT   RAIL_IEEE802154_E_OPTIONS_NONE

All options disabled by default .

Definition at line 539 of file rail_ieee802154.h.

◆ RAIL_IEEE802154_E_OPTIONS_NONE

#define RAIL_IEEE802154_E_OPTIONS_NONE   0UL

A value representing no options enabled.

Definition at line 537 of file rail_ieee802154.h.

◆ RAIL_IEEE802154_G_OPTION_GB868

#define RAIL_IEEE802154_G_OPTION_GB868   (1UL << RAIL_IEEE802154_G_OPTION_GB868_SHIFT)

An option to enable/disable 802.15.4G-2012 features needed for GB868.

Normally RAIL supports 802.15.4-2003 and -2006 radio configurations that have the single-byte PHY header allowing frames up to 128 bytes in size. This feature must be enabled for 802.15.4G-2012 or 802.15.4-2015 SUN PHY radio configurations with the two-byte bit-reversed-length PHY header format.

While GB868 only supports whitened non-FEC non-mode-switch frames up to 129 bytes including 2-byte CRC, this option also enables:

  • On platforms where RAIL_FEAT_IEEE802154_G_4BYTE_CRC_SUPPORTED is true: automatic per-packet 2/4-byte Frame Check Sequence (FCS) reception and transmission based on the FCS Type bit in the received/transmitted PHY header. This includes ACK reception and automatically-generated ACKs reflect the CRC size of the incoming frame being acknowledged (i.e. their MAC payload will be increased to 7 bytes when sending 4-byte FCS). On other platforms, only the 2-byte FCS is supported.
  • On platforms where RAIL_FEAT_IEEE802154_G_UNWHITENED_RX_SUPPORTED and/or RAIL_FEAT_IEEE802154_G_UNWHITENED_TX_SUPPORTED are true: automatic per-packet whitened/unwhitened reception and transmission, respectively, based on the Data Whitening bit in the received/transmitted PHY header. This includes ACK reception and automatically-generated ACKs which reflect the whitening of the incoming frame being acknowledged. On other platforms, only whitened frames are supported.
  • Support for frames up to 2049 bytes per the radio configuration's maximum packet length setting.
Note
Sending/receiving whitened frames assumes the radio configuration has established an appropriate 802.15.4-compliant whitening algorithm. RAIL does not itself override the radio configuration's whitening settings other than to enable/disable it per-packet based on the packet's PHY header Data Whitening flag.

Definition at line 672 of file rail_ieee802154.h.

◆ RAIL_IEEE802154_G_OPTIONS_ALL

#define RAIL_IEEE802154_G_OPTIONS_ALL   0xFFFFFFFFUL

A value representing all possible options.

Definition at line 675 of file rail_ieee802154.h.

◆ RAIL_IEEE802154_G_OPTIONS_DEFAULT

#define RAIL_IEEE802154_G_OPTIONS_DEFAULT   RAIL_IEEE802154_G_OPTIONS_NONE

All options disabled by default .

Definition at line 636 of file rail_ieee802154.h.

◆ RAIL_IEEE802154_G_OPTIONS_NONE

#define RAIL_IEEE802154_G_OPTIONS_NONE   0UL

A value representing no options enabled.

Definition at line 634 of file rail_ieee802154.h.

◆ RAIL_IEEE802154_MAX_ADDRESSES

#define RAIL_IEEE802154_MAX_ADDRESSES   (3U)

The maximum number of allowed addresses of each type.

Definition at line 215 of file rail_ieee802154.h.

Enumeration Type Documentation

◆ RAIL_IEEE802154_AddressLength_t

Different lengths that an 802.15.4 address can have.

Enumerator
RAIL_IEEE802154_ShortAddress 

2 byte short address.

RAIL_IEEE802154_LongAddress 

8 byte extended address.

Definition at line 185 of file rail_ieee802154.h.

◆ RAIL_IEEE802154_EOptions_t

802.15.4E-2012 options, in reality a bitmask.

Enumerator
RAIL_IEEE802154_E_OPTION_GB868_SHIFT 

Shift position of RAIL_IEEE802154_E_OPTION_GB868 bit.

Definition at line 529 of file rail_ieee802154.h.

◆ RAIL_IEEE802154_GOptions_t

802.15.4G-2012 options, in reality a bitmask.

Enumerator
RAIL_IEEE802154_G_OPTION_GB868_SHIFT 

Shift position of RAIL_IEEE802154_G_OPTION_GB868 bit.

Definition at line 628 of file rail_ieee802154.h.

Function Documentation

◆ RAIL_IEEE802154_AcceptFrames()

RAIL_Status_t RAIL_IEEE802154_AcceptFrames ( RAIL_Handle_t  railHandle,
uint8_t  framesMask 
)

Set which 802.15.4 frame types to accept.

Parameters
[in]railHandleA handle of RAIL instance.
[in]framesMaskA mask containing which 802.15.4 frame types to receive.
Returns
A status code indicating success of the function call.

This function will fail if 802.15.4 hardware acceleration is not currently enabled or framesMask requests an unsupported frame type. This setting may be changed at any time when 802.15.4 hardware acceleration is enabled. Only Beacon, Data, ACK, Command, and Multipurpose (except on EFR32XG1) frames may be received. The RAIL_IEEE802154_ACCEPT_XXX_FRAMES defines may be combined to create a bitmask to pass into this function.

RAIL_IEEE802154_ACCEPT_ACK_FRAMES behaves slightly different than the other defines. If RAIL_IEEE802154_ACCEPT_ACK_FRAMES is set, the radio will accept an ACK frame during normal packet reception, but only a truly expected ACK will have its RAIL_RxPacketDetails_t::isAck true. If RAIL_IEEE802154_ACCEPT_ACK_FRAMES is not set, ACK frames will be filtered unless they're expected when the radio is waiting for an ACK.

◆ RAIL_IEEE802154_Config2p4GHzRadio()

RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadio ( RAIL_Handle_t  railHandle)

Configure the radio for 2.4 GHz 802.15.4 operation.

Parameters
[in]railHandleA handle of RAIL instance.
Returns
A status code indicating success of the function call.

This initializes the radio for 2.4 GHz operation. It takes the place of calling RAIL_ConfigChannels. After this call, channels 11-26 will be available, giving the frequencies of those channels on channel page 0, as defined by IEEE 802.15.4-2011 section 8.1.2.2.

◆ RAIL_IEEE802154_Config2p4GHzRadioAntDiv()

RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioAntDiv ( RAIL_Handle_t  railHandle)

Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity.

Parameters
[in]railHandleA handle of RAIL instance.
Returns
A status code indicating success of the function call.

This initializes the radio for 2.4 GHz operation, but with a configuration that supports antenna diversity. It takes the place of calling RAIL_ConfigChannels. After this call, channels 11-26 will be available, giving the frequencies of those channels on channel page 0, as defined by IEEE 802.15.4-2011 section 8.1.2.2.

◆ RAIL_IEEE802154_Config2p4GHzRadioAntDivCoex()

RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioAntDivCoex ( RAIL_Handle_t  railHandle)

Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity optimized for radio coexistence.

Parameters
[in]railHandleA handle of RAIL instance.
Returns
A status code indicating success of the function call.

This initializes the radio for 2.4 GHz operation, but with a configuration that supports antenna diversity optimized for radio coexistence. It takes the place of calling RAIL_ConfigChannels. After this call, channels 11-26 will be available, giving the frequencies of those channels on channel page 0, as defined by IEEE 802.15.4-2011 section 8.1.2.2.

◆ RAIL_IEEE802154_Config2p4GHzRadioCoex()

RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioCoex ( RAIL_Handle_t  railHandle)

Configure the radio for 2.4 GHz 802.15.4 operation optimized for radio coexistence.

Parameters
[in]railHandleA handle of RAIL instance.
Returns
A status code indicating success of the function call.

This initializes the radio for 2.4 GHz operation, but with a configuration that supports radio coexistence. It takes the place of calling RAIL_ConfigChannels. After this call, channels 11-26 will be available, giving the frequencies of those channels on channel page 0, as defined by IEEE 802.15.4-2011 section 8.1.2.2.

◆ RAIL_IEEE802154_ConfigEOptions()

RAIL_Status_t RAIL_IEEE802154_ConfigEOptions ( RAIL_Handle_t  railHandle,
RAIL_IEEE802154_EOptions_t  mask,
RAIL_IEEE802154_EOptions_t  options 
)

Configure certain 802.15.4E-2012 / 802.15.4-2015 Frame Version 2 features.

Parameters
[in]railHandleA handle of RAIL instance.
[in]maskA bitmask containing which options should be modified.
[in]optionsA bitmask containing desired options settings. Bit positions for each option are found in the RAIL_IEEE802154_EOptions_t.
Returns
A status code indicating success of the function call.

This function will fail if 802.15.4 hardware acceleration is not currently enabled or the platform does not support the feature(s). These settings may be changed at any time when 802.15.4 hardware acceleration is enabled.

◆ RAIL_IEEE802154_ConfigGB863MHzRadio()

RAIL_Status_t RAIL_IEEE802154_ConfigGB863MHzRadio ( RAIL_Handle_t  railHandle)

Configure the radio for SubGHz GB868 863 MHz 802.15.4 operation.

Parameters
[in]railHandleA handle of RAIL instance.
Returns
A status code indicating success of the function call.

This initializes the radio for SubGHz GB868 863 MHz operation. It takes the place of calling RAIL_ConfigChannels. After this call, GB868 channels in the 863 MHz band (channel pages 28, 29, and 30 – logical channels 0x80..0x9A, 0xA0..0xA8, 0xC0..0xDA, respectively) will be available, as defined by Rev 22 of the Zigbee Specification, 2017 document 05-3474-22, section D.10.2.1.3.2.

◆ RAIL_IEEE802154_ConfigGB915MHzRadio()

RAIL_Status_t RAIL_IEEE802154_ConfigGB915MHzRadio ( RAIL_Handle_t  railHandle)

Configure the radio for SubGHz GB868 915 MHz 802.15.4 operation.

Parameters
[in]railHandleA handle of RAIL instance.
Returns
A status code indicating success of the function call.

This initializes the radio for SubGHz GB868 915 MHz operation. It takes the place of calling RAIL_ConfigChannels. After this call, GB868 channels in the 915 MHz band (channel page 31 – logical channels 0xE0..0xFA) will be available, as defined by Rev 22 of the Zigbee Specification, 2017 document 05-3474-22, section D.10.2.1.3.2.

◆ RAIL_IEEE802154_ConfigGOptions()

RAIL_Status_t RAIL_IEEE802154_ConfigGOptions ( RAIL_Handle_t  railHandle,
RAIL_IEEE802154_GOptions_t  mask,
RAIL_IEEE802154_GOptions_t  options 
)

Configure certain 802.15.4G-2012 / 802.15.4-2015 SUN PHY features (only for radio configurations designed accordingly).

Parameters
[in]railHandleA handle of RAIL instance.
[in]maskA bitmask containing which options should be modified.
[in]optionsA bitmask containing desired options settings. Bit positions for each option are found in the RAIL_IEEE802154_GOptions_t.
Returns
A status code indicating success of the function call.

This function will fail if 802.15.4 hardware acceleration is not currently enabled, the platform does not support the feature(s), the radio configuration is not appropriate, or the radio is not idle.

◆ RAIL_IEEE802154_ConvertRssiToEd()

uint8_t RAIL_IEEE802154_ConvertRssiToEd ( int8_t  rssiDbm)

Convert RSSI into 802.15.4 Energy Detection (ED) metric compatible with the Silicon Labs Zigbee stack.

Parameters
[in]rssiDbmThe RSSI in dBm, for example from RAIL_RxPacketDetails_t::rssi.
Returns
An Energy Detect value (range 0..255 but not all intermediate values are possible) based on the rssiDbm and the chip's RSSI sensitivity range.

◆ RAIL_IEEE802154_ConvertRssiToLqi()

uint8_t RAIL_IEEE802154_ConvertRssiToLqi ( uint8_t  origLqi,
int8_t  rssiDbm 
)

Convert RSSI into 802.15.4 Link Quality Indication (LQI) metric compatible with the Silicon Labs Zigbee stack.

Parameters
[in]origLqiThe original LQI, for example from RAIL_RxPacketDetails_t::lqi. This parameter is not currently used but may be used in the future.
[in]rssiDbmThe RSSI in dBm, for example from RAIL_RxPacketDetails_t::rssi.
Returns
An LQI value (range 0..255 but not all intermediate values are possible) based on the rssiDbm and the chip's RSSI sensitivity range.

This function is compatible with RAIL_ConvertLqiCallback_t and is suitable to pass to RAIL_ConvertLqi().

◆ RAIL_IEEE802154_Deinit()

RAIL_Status_t RAIL_IEEE802154_Deinit ( RAIL_Handle_t  railHandle)

De-initialize IEEE802.15.4 hardware acceleration.

Parameters
[in]railHandleA handle of RAIL instance.
Returns
A status code indicating success of the function call.

Disables and resets all IEE802.15.4 hardware acceleration features. This function should only be called when the radio is IDLE. This calls the following:

◆ RAIL_IEEE802154_EnableDataFramePending()

RAIL_Status_t RAIL_IEEE802154_EnableDataFramePending ( RAIL_Handle_t  railHandle,
bool  enable 
)

Enable Frame Pending lookup event notification (RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND) for MAC Data frames.

Parameters
[in]railHandleA handle of RAIL instance.
[in]enableTrue to enable, false to disable.
Returns
A status code indicating success of the function call.

Normally RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND is triggered only for MAC command frames whose MAC command byte indicates the packet is a data request. Enabling this feature causes this event to also be triggered for MAC data frames right after receiving the source address information in the MAC header – necessary to support the Thread Basil-Hayden Enhanced Frame Pending feature.

This function will fail if 802.15.4 hardware acceleration is not currently enabled. This setting may be changed at any time when 802.15.4 hardware acceleration is enabled.

◆ RAIL_IEEE802154_EnableEarlyFramePending()

RAIL_Status_t RAIL_IEEE802154_EnableEarlyFramePending ( RAIL_Handle_t  railHandle,
bool  enable 
)

Enable early Frame Pending lookup event notification (RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND).

Parameters
[in]railHandleA handle of RAIL instance.
[in]enableTrue to enable, false to disable.
Returns
A status code indicating success of the function call.

Normally RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND is triggered after receiving the entire MAC header for a MAC command and the MAC command byte indicating the packet is a data request. Enabling this feature causes this event to be triggered earlier, right after receiving the source address information in the MAC header, allowing for more time to perform the lookup and call RAIL_SetFramePending() to set Frame Pending in the outgoing ACK for the incoming frame. This feature is also necessary for handling 802.15.4 MAC-encrypted frames where the MAC Command byte is encrypted (MAC Frame Version 2) – see RAIL_IEEE802154_Enable154E().

This function will fail if 802.15.4 hardware acceleration is not currently enabled, or on platforms that do not support this feature. This setting may be changed at any time when 802.15.4 hardware acceleration is enabled.

◆ RAIL_IEEE802154_GetAddress()

RAIL_Status_t RAIL_IEEE802154_GetAddress ( RAIL_Handle_t  railHandle,
RAIL_IEEE802154_Address_t pAddress 
)

Get the source address of the incoming data request.

Parameters
[in]railHandleA RAIL instance handle.
[out]pAddressA pointer to RAIL_IEEE802154_Address_t structure to populate with source address information.
Returns
A status code indicating success of the function call.

This function must only be called when handling the RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND event. This will return RAIL_STATUS_INVALID_STATE if the address information is stale (i.e. it is too late to affect the outgoing ACK).

◆ RAIL_IEEE802154_Init()

RAIL_Status_t RAIL_IEEE802154_Init ( RAIL_Handle_t  railHandle,
const RAIL_IEEE802154_Config_t config 
)

Initialize RAIL for IEEE802.15.4 features.

Parameters
[in]railHandleA handle of RAIL instance.
[in]configAn IEEE802154 configuration structure.
Returns
A status code indicating success of the function call.

This function calls the following RAIL functions to configure the radio for IEEE802.15.4 features.

Initializes the following:

  • Enables IEEE802154 hardware acceleration
  • Configures RAIL Auto ACK functionality
  • Configures RAIL Address Filter for 802.15.4 address filtering

It saves having to call the following functions individually:

◆ RAIL_IEEE802154_IsEnabled()

bool RAIL_IEEE802154_IsEnabled ( RAIL_Handle_t  railHandle)

Return whether IEEE802.15.4 hardware acceleration is currently enabled.

Parameters
[in]railHandleA handle of RAIL instance.
Returns
True if IEEE802.15.4 hardware acceleration was enabled to start with and false otherwise.

◆ RAIL_IEEE802154_SetAddresses()

RAIL_Status_t RAIL_IEEE802154_SetAddresses ( RAIL_Handle_t  railHandle,
const RAIL_IEEE802154_AddrConfig_t addresses 
)

Configure the RAIL Address Filter for 802.15.4 filtering.

Parameters
[in]railHandleA handle of RAIL instance.
[in]addressesThe address information that should be used.
Returns
A status code indicating success of the function call. If this returns an error, the 802.15.4 address filter is in an undefined state.

Set up the 802.15.4 address filter to accept messages to the given addresses. This will return false if any of the addresses failed to be set. If NULL is passed in for addresses, all addresses will be set to their reset value.

◆ RAIL_IEEE802154_SetFramePending()

RAIL_Status_t RAIL_IEEE802154_SetFramePending ( RAIL_Handle_t  railHandle)

Set the frame pending bit on the outgoing legacy Immediate ACK.

Parameters
[in]railHandleA handle of RAIL instance.
Returns
A status code indicating success of the function call.

This function must only be called while processing the RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND, if the given source address has a pending frame. It's intended only for use with 802.15.4 legacy Immediate ACKs and not 802.15.4E Enhanced ACKs. This will return RAIL_STATUS_INVALID_STATE if it is too late to modify the outgoing Immediate ACK.

◆ RAIL_IEEE802154_SetLongAddress()

RAIL_Status_t RAIL_IEEE802154_SetLongAddress ( RAIL_Handle_t  railHandle,
const uint8_t *  longAddr,
uint8_t  index 
)

Set a long address for 802.15.4 address filtering.

Parameters
[in]railHandleA handle of RAIL instance.
[in]longAddrA pointer to an 8-byte array containing the long address information. The long address must be in over-the-air byte order. This will be matched against the destination long address of incoming messages. Set to 0x00 00 00 00 00 00 00 00 to disable for this index.
[in]indexIndicates which long address to set. Must be below RAIL_IEEE802154_MAX_ADDRESSES.
Returns
A status code indicating success of the function call.

Set up the 802.15.4 address filter to accept messages to the given long address.

◆ RAIL_IEEE802154_SetPanCoordinator()

RAIL_Status_t RAIL_IEEE802154_SetPanCoordinator ( RAIL_Handle_t  railHandle,
bool  isPanCoordinator 
)

Set whether the current node is a PAN coordinator.

Parameters
[in]railHandleA handle of RAIL instance.
[in]isPanCoordinatorTrue if this device is a PAN coordinator.
Returns
A status code indicating success of the function call.

If the device is a PAN Coordinator, it will accept data and command frames with no destination address. This function will fail if 802.15.4 hardware acceleration is not currently enabled. This setting may be changed at any time when 802.15.4 hardware acceleration is enabled.

◆ RAIL_IEEE802154_SetPanId()

RAIL_Status_t RAIL_IEEE802154_SetPanId ( RAIL_Handle_t  railHandle,
uint16_t  panId,
uint8_t  index 
)

Sets a PAN ID for 802.15.4 address filtering.

Parameters
[in]railHandleA handle of RAIL instance.
[in]panIdThe 16-bit PAN ID information. This will be matched against the destination PAN ID of incoming messages. The PAN ID is sent little endian over the air, meaning panId[7:0] is first in the payload followed by panId[15:8]. Set to 0xFFFF to disable for this index.
[in]indexIndicates which PAN ID to set. Must be below RAIL_IEEE802154_MAX_ADDRESSES.
Returns
A status code indicating success of the function call.

Set up the 802.15.4 address filter to accept messages to the given PAN ID.

◆ RAIL_IEEE802154_SetPromiscuousMode()

RAIL_Status_t RAIL_IEEE802154_SetPromiscuousMode ( RAIL_Handle_t  railHandle,
bool  enable 
)

Set whether to enable 802.15.4 promiscuous mode.

Parameters
[in]railHandleA handle of RAIL instance.
[in]enableTrue if all frames and addresses should be accepted.
Returns
A status code indicating success of the function call.

If promiscuous mode is enabled, no frame or address filtering steps will be performed other than checking the CRC. This function will fail if 802.15.4 hardware acceleration is not currently enabled. This setting may be changed at any time when 802.15.4 hardware acceleration is enabled.

◆ RAIL_IEEE802154_SetShortAddress()

RAIL_Status_t RAIL_IEEE802154_SetShortAddress ( RAIL_Handle_t  railHandle,
uint16_t  shortAddr,
uint8_t  index 
)

Set a short address for 802.15.4 address filtering.

Parameters
[in]railHandleA handle of RAIL instance
[in]shortAddr16 bit short address value. This will be matched against the destination short address of incoming messages. The short address is sent little endian over the air meaning shortAddr[7:0] is first in the payload followed by shortAddr[15:8]. Set to 0xFFFF to disable for this index.
[in]indexWhich short address to set. Must be below RAIL_IEEE802154_MAX_ADDRESSES.
Returns
A status code indicating success of the function call.

Set up the 802.15.4 address filter to accept messages to the given short address.

◆ RAIL_IEEE802154_WriteEnhAck()

RAIL_Status_t RAIL_IEEE802154_WriteEnhAck ( RAIL_Handle_t  railHandle,
const uint8_t *  ackData,
uint8_t  ackDataLen 
)

Write the AutoACK FIFO for the next outgoing 802.15.4E Enhanced ACK.

Parameters
[in]railHandleA handle of RAIL instance.
[in]ackDataPointer to ACK data to transmit
[in]ackDataLenLength of ACK data, in bytes
Returns
A status code indicating success of the function call.

This function sets the AutoACK data to use in acknowledging the frame being received. It must only be called while processing the RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND, and is intended for use when packet information from RAIL_GetRxIncomingPacketInfo() indicates an 802.15.4E Enhanced ACK must be sent instead of a legacy Immediate ACK. RAIL_IEEE802154_SetFramePending() should not be called for an Enhanced ACK; instead the Enhanced ACK's Frame Control Field should have the Frame Pending bit set appropriately in its ackData. This will return RAIL_STATUS_INVALID_STATE if it is too late to write the outgoing ACK – a situation that will likely trigger a RAIL_EVENT_TXACK_UNDERFLOW event. When successful, the Enhanced ackData will only be sent once. Subsequent packets needing an Enhanced ACK will each need to call this function to write their ACK information.