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.

Functions

RAIL_Status_t RAIL_ConfigAddressFilter ( RAIL_Handle_t railHandle, const RAIL_AddrConfig_t *addrConfig)
Configures address filtering.
bool RAIL_EnableAddressFilter ( RAIL_Handle_t railHandle, bool enable)
Enables address filtering.
bool RAIL_IsAddressFilterEnabled ( RAIL_Handle_t railHandle)
Returns whether address filtering is currently enabled.
void RAIL_ResetAddressFilter ( RAIL_Handle_t railHandle)
Resets 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)
Sets an address for filtering in hardware.
RAIL_Status_t RAIL_EnableAddressFilterAddress ( RAIL_Handle_t railHandle, bool enable, uint8_t field, uint8_t index)
Enables 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 can be represented as a 4-bit mask where 1 indicates a match and 0 indicates no match. Representing the Field0 match options as rows and the Field1 options as columns results in a truth table as shown below.

0000 0001 0010 0100 1000
0000 bit0 bit1 bit2 bit3 bit4
0001 bit5 bit6 bit7 bit8 bit9
0010 bit10 bit11 bit12 bit13 bit14
0100 bit15 bit16 bit17 bit18 bit19
1000 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

#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.

0000 0001 0010 0100 1000
0000 0 0 0 0 0
0001 0 1 0 0 0
0010 0 0 1 0 0
0100 0 0 0 1 0
1000 0 0 0 0 1

Definition at line 2001 of file rail_types.h .

#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.

0000 0001 0010 0100 1000
0000 0 1 1 1 1
0001 1 1 1 1 1
0010 1 1 1 1 1
0100 1 1 1 1 1
1000 1 1 1 1 1

Definition at line 1989 of file rail_types.h .

#define ADDRCONFIG_MAX_ADDRESS_FIELDS   (2)

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

Definition at line 2005 of file rail_types.h .

Function Documentation

RAIL_Status_t RAIL_ConfigAddressFilter ( RAIL_Handle_t railHandle,
const RAIL_AddrConfig_t * addrConfig
)

Configures address filtering.

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

This function must be called 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.

Referenced by RAIL_CopyRxPacket() .

bool RAIL_EnableAddressFilter ( RAIL_Handle_t railHandle,
bool enable
)

Enables 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.

Referenced by RAIL_CopyRxPacket() .

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

Enables 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.

Referenced by RAIL_CopyRxPacket() .

bool RAIL_IsAddressFilterEnabled ( RAIL_Handle_t railHandle )

Returns whether address filtering is currently enabled.

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

Referenced by RAIL_CopyRxPacket() .

void RAIL_ResetAddressFilter ( RAIL_Handle_t railHandle )

Resets the address filtering configuration.

Parameters
[in] railHandle A RAIL instance handle.
Returns
void.

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.

Referenced by RAIL_CopyRxPacket() .

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

Sets 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() .
[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.

Referenced by RAIL_CopyRxPacket() .