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 a received address, which needs to be parsed to discover the type.
 
struct  RAIL_IEEE802154_AddrConfig_t
 Configuration structure for IEEE 802.15.4 Address Filtering.
 
struct  RAIL_IEEE802154_Config_t
 Configuration structure for IEEE 802.15.4 in RAIL.

Macros

#define RAIL_IEEE802154_MAX_ADDRESSES   3
 The maximum number of allowed addresses of each type.
 
#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 If this is not enabled, ACK frame types will only be accepted while waiting for an ack.
 
#define RAIL_IEEE802154_ACCEPT_COMMAND_FRAMES   (0x08)
 When receiving packets, accept 802.15.4 COMMAND 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.

Functions

RAIL_Status_t RAIL_IEEE802154_Init (RAIL_Handle_t railHandle, const RAIL_IEEE802154_Config_t *fifteenFourConfig)
 Initialize RAIL for IEEE802.15.4 features.
 
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadio (RAIL_Handle_t railHandle)
 Configures the radio for 2.4GHz 802.15.4 operation.
 
RAIL_Status_t RAIL_IEEE802154_Deinit (RAIL_Handle_t railHandle)
 De-initializes 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)
 Set 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_AcceptFrames (RAIL_Handle_t railHandle, uint8_t framesMask)
 Set which 802.15.4 frame types to accept.
 
RAIL_Status_t RAIL_IEEE802154_SetFramePending (RAIL_Handle_t railHandle)
 Set the frame pending bit on the outgoing 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.

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 setup a RAIL instance as normal with RAIL_Init() and other setup functions. Instead of RAIL_ConfigChannels() and RAIL_ConfigRadio(), however, an application may use RAIL_IEEE802154_Config2p4GHzRadio() to setup the official IEEE 2.4GHz 802.15.4 PHY. This configuration is shown below.

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 = 864, // 54 symbols * 16 us/symbol = 864 us
.rxTransitions = {
.success = RAIL_RF_STATE_TX, // Go to Tx to send the ACK
.error = RAIL_RF_STATE_RX, // For an always on device stay in Rx
},
.txTransitions = {
.success = RAIL_RF_STATE_RX, // Go to Rx for receiving the ACK
.error = RAIL_RF_STATE_RX, // For an always on device stay in Rx
},
},
.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.4GHz IEEE 802.15.4
// Initialize the IEEE 802.15.4 config using the static config above
RAIL_IEEE802154_Init(railHandle, &rail154Config);
}

To configure address filtering the application can call RAIL_IEEE802154_SetAddresses() with a structure containing all addresses or can call the individual RAIL_IEEE802154_SetPanId(), RAIL_IEEE802154_SetShortAddress(), and RAIL_IEEE802154_SetLongAddress() APIs. RAIL supports RAIL_IEEE802154_MAX_ADDRESSES number of address pairs for situations where you want 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
// Setup all address 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 setup 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 but 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 though they may be controlled using the normal Auto ACK and State Transitions APIs. When in IEEE 802.15.4 mode the ACK will have a 5 byte length, the frame type will be set to ack, and the 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 all 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_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:424
#define RAIL_IEEE802154_ACCEPT_DATA_FRAMES
When receiving packets, accept 802.15.4 DATA frame types.
Definition: rail_ieee802154.h:418
#define RAIL_IEEE802154_ACCEPT_BEACON_FRAMES
When receiving packets, accept 802.15.4 BEACON frame types.
Definition: rail_ieee802154.h:416

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

Only receive ACK frames while waiting for ack

Definition at line 428 of file rail_ieee802154.h.

◆ RAIL_IEEE802154_MAX_ADDRESSES

#define RAIL_IEEE802154_MAX_ADDRESSES   3

The maximum number of allowed addresses of each type.

Definition at line 177 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 153 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]railHandleHandle of RAIL instance
[in]framesMaskMask containing which 802.15.4 frame types to receive
Returns
Status code indicating success of the function call.

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. Only Beacon, Data, Ack, and Command 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. If RAIL_IEEE802154_ACCEPT_ACK_FRAMES is not set, ACK frames will be filtered unless the radio is waiting for an ACK.

◆ RAIL_IEEE802154_Config2p4GHzRadio()

RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadio ( RAIL_Handle_t  railHandle)

Configures the radio for 2.4GHz 802.15.4 operation.

Parameters
[in]railHandleHandle of RAIL instance
Returns
Status code indicating success of the function call.

This initializes the radio for 2.4GHz operation. It takes the place of calling RAIL_ConfigRadio and 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_Deinit()

RAIL_Status_t RAIL_IEEE802154_Deinit ( RAIL_Handle_t  railHandle)

De-initializes IEEE802.15.4 hardware acceleration.

Parameters
[in]railHandleHandle of RAIL instance
Returns
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_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]pAddressPointer to RAIL_IEEE802154_Address_t structure to populate with address information.
Returns
Status code indicating success of the function call.

This function should only be called when handling the RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND event.

◆ RAIL_IEEE802154_Init()

RAIL_Status_t RAIL_IEEE802154_Init ( RAIL_Handle_t  railHandle,
const RAIL_IEEE802154_Config_t fifteenFourConfig 
)

Initialize RAIL for IEEE802.15.4 features.

Parameters
[in]railHandleHandle of RAIL instance
[in]fifteenFourConfigIEEE802154 configuration struct
Returns
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 calls the following functions:

◆ RAIL_IEEE802154_IsEnabled()

bool RAIL_IEEE802154_IsEnabled ( RAIL_Handle_t  railHandle)

Return whether IEEE802.15.4 hardware acceleration is currently enabled.

Parameters
[in]railHandleHandle 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]railHandleHandle of RAIL instance
[in]addressesThe address information that should be used
Returns
Status code indicating success of the function call. If this returns an error, then 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, then 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 ACK.

Parameters
[in]railHandleHandle of RAIL instance
Returns
Status code indicating success of the function call.

This function should be called after receiving RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND, if the given source address has a pending frame. This will return RAIL_STATUS_INVALID_STATE if it is too late to modify the 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]railHandleHandle of RAIL instance
[in]longAddrPointer to a 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]indexWhich long address to set. Must be below RAIL_IEEE802154_MAX_ADDRESSES.
Returns
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]railHandleHandle of RAIL instance
[in]isPanCoordinatorTrue if this device is a PAN coordinator
Returns
Status code indicating success of the function call.

If the device is a PAN Coordinator, then 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 
)

Set a PAN ID for 802.15.4 address filtering.

Parameters
[in]railHandleHandle 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]indexWhich PAN ID to set. Must be below RAIL_IEEE802154_MAX_ADDRESSES.
Returns
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]railHandleHandle of RAIL instance
[in]enableTrue if all frames and addresses should be accepted
Returns
Status code indicating success of the function call.

If promiscuous mode is enabled, then 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]railHandleHandle 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
Status code indicating success of the function call.

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