Address Filtering#
Configuration APIs for receive packet address filtering.
The address filtering code examines the packet as follows.
|
|
|
|
|
|---|---|---|---|---|
|
|
|
|
|
In the above structure, anything listed as Data_# is an optional section of bytes that RAIL will not process for address filtering. The Field_# 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 Field_0 and Field_1 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 frame type decoding, the first start offset is relative to the end of the byte containing the frame type.
Configuring which combinations of Field_0 and Field_1 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 Field_0 matches are the rows and Field_1 matches are the columns.
No Match | Address 0 | Address 1 | Address 2 | Address 3 | |
|---|---|---|---|---|---|
No Match | bit 0 | bit 1 | bit 2 | bit 3 | bit 4 |
Address 0 | bit 5 | bit 6 | bit 7 | bit 8 | bit 9 |
Address 1 | bit 10 | bit 11 | bit 12 | bit 13 | bit 14 |
Address 2 | bit 15 | bit 16 | bit 17 | bit 18 | bit 19 |
Address 3 | bit 20 | bit 21 | bit 22 | bit 23 | bit 24 |
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 RAIL_AddrConfig_t::matchTable field 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#
Typedefs#
A bitmask representation of which 4 filters passed for each ADDRCONFIG_MAX_ADDRESS_FIELDS when filtering has completed successfully.
Functions#
Configure address filtering.
Enable address filtering.
Return whether address filtering is currently enabled.
Reset the address filtering configuration.
Set an address for filtering in hardware.
Set an address bit mask for filtering in hardware.
Enable address filtering for the specified address.
Macros#
A default address filtering match table for configurations that use only one address field.
A default address filtering match table for configurations that use two address fields and want to match the same index in each.
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
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.
3762 of file common/rail_types.hFunction Documentation#
RAIL_ConfigAddressFilter#
RAIL_Status_t RAIL_ConfigAddressFilter (RAIL_Handle_t railHandle, const RAIL_AddrConfig_t * addrConfig)
Configure address filtering.
| [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.
4594 of file common/rail.hRAIL_EnableAddressFilter#
bool RAIL_EnableAddressFilter (RAIL_Handle_t railHandle, bool enable)
Enable address filtering.
| [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.
4610 of file common/rail.hRAIL_IsAddressFilterEnabled#
bool RAIL_IsAddressFilterEnabled (RAIL_Handle_t railHandle)
Return whether address filtering is currently enabled.
| [in] | railHandle | A RAIL instance handle. |
Returns
true if address filtering is enabled and false otherwise.
4618 of file common/rail.hRAIL_ResetAddressFilter#
RAIL_Status_t RAIL_ResetAddressFilter (RAIL_Handle_t railHandle)
Reset the address filtering configuration.
| [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.
4630 of file common/rail.hRAIL_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.
| [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.
4651 of file common/rail.hRAIL_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.
| [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 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.
4683 of file common/rail.hRAIL_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.
| [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.
4697 of file common/rail.hMacro Definition Documentation#
ADDRCONFIG_MATCH_TABLE_SINGLE_FIELD#
#define ADDRCONFIG_MATCH_TABLE_SINGLE_FIELDValue:
(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 |
3687 of file common/rail_types.hADDRCONFIG_MATCH_TABLE_DOUBLE_FIELD#
#define ADDRCONFIG_MATCH_TABLE_DOUBLE_FIELDValue:
(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 |
3699 of file common/rail_types.hADDRCONFIG_MAX_ADDRESS_FIELDS#
#define ADDRCONFIG_MAX_ADDRESS_FIELDSValue:
(2)
The maximum number of address fields that can be used by the address filtering logic.
3703 of file common/rail_types.h