Address Filtering#

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.

Modules#

RAIL_AddrConfig_t

Typedefs#

typedef uint8_t

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

Functions#

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.

RAIL_ResetAddressFilter(RAIL_Handle_t railHandle)

Reset the address filtering configuration.

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_SetAddressFilterAddressMask(RAIL_Handle_t railHandle, uint8_t field, const uint8_t *bitMask)

Set an address bit mask for filtering in hardware.

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

Enable address filtering for the specified address.

Macros#

#define

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

#define

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

#define

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

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


Definition at line 3771 of file common/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

A pointer to the configuration structure, which defines how addresses are set up in your packets. May be NULL to reset address filtering.

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.


Definition at line 4512 of file common/rail.h

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.


Definition at line 4528 of file common/rail.h

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.


Definition at line 4536 of file common/rail.h

RAIL_ResetAddressFilter#

RAIL_Status_t RAIL_ResetAddressFilter (RAIL_Handle_t railHandle)

Reset the address filtering configuration.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Status code indicating success of the function call.

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.


Definition at line 4548 of file common/rail.h

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.


Definition at line 4569 of file common/rail.h

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


Definition at line 4601 of file common/rail.h

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.


Definition at line 4615 of file common/rail.h

Macro Definition Documentation#

ADDRCONFIG_MATCH_TABLE_SINGLE_FIELD#

#define ADDRCONFIG_MATCH_TABLE_SINGLE_FIELD
Value:
(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 3696 of file common/rail_types.h

ADDRCONFIG_MATCH_TABLE_DOUBLE_FIELD#

#define ADDRCONFIG_MATCH_TABLE_DOUBLE_FIELD
Value:
(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 3708 of file common/rail_types.h

ADDRCONFIG_MAX_ADDRESS_FIELDS#

#define ADDRCONFIG_MAX_ADDRESS_FIELDS
Value:
(2)

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


Definition at line 3712 of file common/rail_types.h