Address Filtering
RAIL API > Receive

Configuration APIs for receive packet address filtering.

Data Structures

struct RAIL_AddrConfig_t
A structure to configure the address filtering functionality in RAIL.

Macros

#define ADDRCONFIG_MATCH_TABLE_SINGLE_FIELD (0x1FFFFFE)
A default address filtering match table for configurations that use only one address field.
#define ADDRCONFIG_MATCH_TABLE_DOUBLE_FIELD (0x1041040)
A default address filtering match table for configurations that use two address fields and want to match the same index in each.
#define ADDRCONFIG_MAX_ADDRESS_FIELDS (2)
The maximum number of address fields that can be used by the address filtering logic.

Typedefs

typedef uint8_t RAIL_AddrFilterMask_t
A bitmask representation of which 4 filters passed for each ADDRCONFIG_MAX_ADDRESS_FIELDS when filtering has completed successfully.

Functions

RAIL_Status_t RAIL_ConfigAddressFilter ( RAIL_Handle_t railHandle, const RAIL_AddrConfig_t *addrConfig)
Configure address filtering.
bool RAIL_EnableAddressFilter ( RAIL_Handle_t railHandle, bool enable)
Enable address filtering.
bool RAIL_IsAddressFilterEnabled ( RAIL_Handle_t railHandle)
Return whether address filtering is currently enabled.
void RAIL_ResetAddressFilter ( RAIL_Handle_t railHandle)
Reset the address filtering configuration.
RAIL_Status_t RAIL_SetAddressFilterAddress ( RAIL_Handle_t railHandle, uint8_t field, uint8_t index, const uint8_t *value, bool enable)
Set an address for filtering in hardware.
RAIL_Status_t RAIL_SetAddressFilterAddressMask ( RAIL_Handle_t railHandle, uint8_t field, const uint8_t *bitMask)
Set an address bit mask for filtering in hardware.
RAIL_Status_t RAIL_EnableAddressFilterAddress ( RAIL_Handle_t railHandle, bool enable, uint8_t field, uint8_t index)
Enable address filtering for the specified address.

Detailed Description

Configuration APIs for receive packet address filtering.

The address filtering code examines the packet as follows.

Bytes: 0 - 255 0 - 8 0 - 255 0 - 8 Variable
Data0 Field0 Data1 Field1 Data2

In the above structure, anything listed as DataN is an optional section of bytes that RAIL will not process for address filtering. The FieldN segments reference specific sections in the packet that will each be interpreted as an address during address filtering. The application may submit up to four addresses to attempt to match each field segment and each address may have a size of up to 8 bytes. To set up address filtering, first configure the locations and length of the addresses in the packet. Next, configure which combinations of matches in Field0 and Field1 should constitute an address match. Last, enter addresses into tables for each field and enable them. The first two of these are part of the RAIL_AddrConfig_t structure while the second part is configured at runtime using the RAIL_SetAddressFilterAddress() API. A brief description of each configuration is listed below.

The offsets and sizes of the fields are assumed fixed for the RAIL address filter. To set them, specify arrays for these values in the sizes and offsets entries in the RAIL_AddrConfig_t structure. A size of zero indicates that a field is disabled. The start offset for a field is relative to the previous start offset and, if you're using FrameType decoding, the first start offset is relative to the end of the byte containing the frame type.

Configuring which combinations of Field0 and Field1 constitute a match is the most complex portion of the address filter. The easiest way to think about this is with a truth table. If you consider each of the four possible address entries in a field, you can have a match on any one of those or a match for none of them. This is shown in the 5x5 truth table below where Field0 matches are the rows and Field1 matches are the columns.

No Match Address 0 Address 1 Address 2 Address 3
No Match bit0 bit1 bit2 bit3 bit4
Address 0 bit5 bit6 bit7 bit8 bit9
Address 1 bit10 bit11 bit12 bit13 bit14
Address 2 bit15 bit16 bit17 bit18 bit19
Address 3 bit20 bit21 bit22 bit23 bit24

Because this is only 25 bits, it can be represented in one 32-bit integer where 1 indicates a filter pass and 0 indicates a filter fail. This is the matchTable parameter in the configuration structure and is used during filtering. For common simple configurations, two defines are provided with the truth tables as shown below. The first is ADDRCONFIG_MATCH_TABLE_SINGLE_FIELD , which can be used if only using one address field (either field). If using two fields and want to force in the same address entry in each field, use the second define: ADDRCONFIG_MATCH_TABLE_DOUBLE_FIELD . For more complex systems, create a valid custom table.

Note
Address filtering does not function reliably with PHYs that use a data rate greater than 500 kbps. If this is a requirement, filtering must currently be done by the application.

Macro Definition Documentation

◆ ADDRCONFIG_MATCH_TABLE_DOUBLE_FIELD

#define ADDRCONFIG_MATCH_TABLE_DOUBLE_FIELD   (0x1041040)

A default address filtering match table for configurations that use two address fields and want to match the same index in each.

The truth table for address matching is shown below.

No Match Address 0 Address 1 Address 2 Address 3
No Match 0 0 0 0 0
Address 0 0 1 0 0 0
Address 1 0 0 1 0 0
Address 2 0 0 0 1 0
Address 3 0 0 0 0 1

Definition at line 2615 of file rail_types.h .

◆ ADDRCONFIG_MATCH_TABLE_SINGLE_FIELD

#define ADDRCONFIG_MATCH_TABLE_SINGLE_FIELD   (0x1FFFFFE)

A default address filtering match table for configurations that use only one address field.

The truth table for address matching is shown below.

No Match Address 0 Address 1 Address 2 Address 3
No Match 0 1 1 1 1
Address 0 1 1 1 1 1
Address 1 1 1 1 1 1
Address 2 1 1 1 1 1
Address 3 1 1 1 1 1

Definition at line 2603 of file rail_types.h .

◆ ADDRCONFIG_MAX_ADDRESS_FIELDS

#define ADDRCONFIG_MAX_ADDRESS_FIELDS   (2)

The maximum number of address fields that can be used by the address filtering logic.

Definition at line 2619 of file rail_types.h .

Typedef Documentation

◆ RAIL_AddrFilterMask_t

typedef uint8_t RAIL_AddrFilterMask_t

A bitmask representation of which 4 filters passed for each ADDRCONFIG_MAX_ADDRESS_FIELDS when filtering has completed successfully.

It's layout is: | Bit 7 | Bit 6 | Bit 5 | Bit 4 | Bit 3 | Bit 2 | Bit 1 | Bit 0 | |-----—+-----—+-----—+-----—+-----—+-----—+-----—+-----—| | Second Address Field Nibble | First Address Field Nibble | | Addr 3 | Addr 2 | Addr 1 | Addr 0 | Addr 3 | Addr 2 | Addr 1 | Addr 0 | | match | match | match | match | match | match | match | match | |-----—+-----—+-----—+-----—+-----—+-----—+-----—+-----—|

Note
This information is valid in RAIL_IEEE802154_Address_t on all platforms, but is only valid in RAIL_RxPacketInfo_t on platforms where RAIL_SUPPORTS_ADDR_FILTER_MASK is true.

Definition at line 2678 of file rail_types.h .

Function Documentation

◆ RAIL_ConfigAddressFilter()

RAIL_Status_t RAIL_ConfigAddressFilter ( RAIL_Handle_t railHandle,
const RAIL_AddrConfig_t * addrConfig
)

Configure address filtering.

Parameters
[in] railHandle A RAIL instance handle.
[in] addrConfig The configuration structure, which defines how addresses are set up in your packets.
Returns
Status code indicating success of the function call.

You must call this function to set up address filtering. You may call it multiple times but all previous information is wiped out each time you call and any configured addresses must be reset.

◆ RAIL_EnableAddressFilter()

bool RAIL_EnableAddressFilter ( RAIL_Handle_t railHandle,
bool enable
)

Enable address filtering.

Parameters
[in] railHandle A RAIL instance handle.
[in] enable An argument to indicate whether or not to enable address filtering.
Returns
True if address filtering was enabled to start with and false otherwise.

Only allow packets through that pass the current address filtering configuration. This does not reset or change the configuration so you can set that up before turning on this feature.

◆ RAIL_EnableAddressFilterAddress()

RAIL_Status_t RAIL_EnableAddressFilterAddress ( RAIL_Handle_t railHandle,
bool enable,
uint8_t field,
uint8_t index
)

Enable address filtering for the specified address.

Parameters
[in] railHandle A RAIL instance handle.
[in] enable An argument to indicate whether or not to enable address filtering.
[in] field Indicates an address for the address.
[in] index Indicates a match entry in the given field you want to enable.
Returns
Status code indicating success of the function call.

◆ RAIL_IsAddressFilterEnabled()

bool RAIL_IsAddressFilterEnabled ( RAIL_Handle_t railHandle )

Return whether address filtering is currently enabled.

Parameters
[in] railHandle A RAIL instance handle.
Returns
True if address filtering is enabled and false otherwise.

◆ RAIL_ResetAddressFilter()

void RAIL_ResetAddressFilter ( RAIL_Handle_t railHandle )

Reset the address filtering configuration.

Parameters
[in] railHandle A RAIL instance handle.

Resets all structures related to address filtering. This does not disable address filtering. It leaves the radio in a state where no packets pass filtering.

◆ RAIL_SetAddressFilterAddress()

RAIL_Status_t RAIL_SetAddressFilterAddress ( RAIL_Handle_t railHandle,
uint8_t field,
uint8_t index,
const uint8_t * value,
bool enable
)

Set an address for filtering in hardware.

Parameters
[in] railHandle A RAIL instance handle.
[in] field Indicates an address field for this address.
[in] index Indicates a match entry for this address for a given field.
[in] value A pointer to the address data. This must be at least as long as the size specified in RAIL_ConfigAddressFilter() . The first byte, value[0], will be compared to the first byte received over the air for this address field.
[in] enable A boolean to indicate whether this address should be enabled immediately.
Returns
Status code indicating success of the function call.

This function loads the given address into hardware for filtering and starts filtering if you set the enable parameter to true. Otherwise, call RAIL_EnableAddressFilterAddress() to turn it on later.

◆ RAIL_SetAddressFilterAddressMask()

RAIL_Status_t RAIL_SetAddressFilterAddressMask ( RAIL_Handle_t railHandle,
uint8_t field,
const uint8_t * bitMask
)

Set an address bit mask for filtering in hardware.

Parameters
[in] railHandle A RAIL instance handle.
[in] field Indicates an address field for this address bit mask.
[in] bitMask A pointer to the address bitmask. This must be at least as long as the size specified in RAIL_ConfigAddressFilter() . The first byte, bitMask[0], will be applied to the first byte received over the air for this address field. Bits set to 1 in the bit mask indicate which bit positions in the incoming packet to compare against the stored addresses during address filtering. Bits set to 0 indicate which bit positions to ignore in the incoming packet during address filtering. This bit mask is applied to all address entries.
Returns
Status code indicating success of the function call.

This function loads the given address bit mask into hardware for use when address filtering is enabled. All bits in the stored address bit mask are set to 1 during hardware initialization and when either RAIL_ConfigAddressFilter() or RAIL_ResetAddressFilter() are called.

Note
This feature/API is not supported on the EFR32XG1 family of chips or the EFR32XG21. Use the compile time symbol RAIL_SUPPORTS_ADDR_FILTER_ADDRESS_BIT_MASK or the runtime call RAIL_SupportsAddrFilterAddressBitMask() to check whether the platform supports this feature.