Address Filtering

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)
 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_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 2717 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 2705 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 2721 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]railHandleA RAIL instance handle.
[in]addrConfigThe 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]railHandleA RAIL instance handle.
[in]enableAn 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]railHandleA RAIL instance handle.
[in]enableAn argument to indicate whether or not to enable address filtering.
[in]fieldIndicates an address for the address.
[in]indexIndicates 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]railHandleA 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]railHandleA 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.

◆ 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]railHandleA RAIL instance handle.
[in]fieldIndicates an address field for this address.
[in]indexIndicates a match entry for this address for a given field.
[in]valueA 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]enableA 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.