MAC Address Filtering#

API and Callbacks for the MAC Address Filtering Component.

This plugin artificially limits what the stack hears by filtering the packets just above the lower MAC. The plugin can be configured on the fly via CLI with the short or long address of devices whose packets will be dropped or allowed. There are two lists, a short address list (2-byte node ID) and a long address list (8-byte IEEE address). Each list may be configured as either an allow list or block list. The default is a block list with no addresses configured (accept all packets normally). A separate option allows or drops packets with no address information (e.g., Beacon Requests). NOTE: The radio will still generate and process MAC ACKs for packets. This plugin cannot be used to effect the behavior of MAC ACKs, which are handled by the RAIL library and radio hardware.

Modules#

MacAddressFilterOptionsDescription

LongAddressFilterMatchStruct

ShortAddressFilterMatchStruct

PanIdFilterMatchStruct

MacAddressFilterGlobals

MAC Address Filtering

API#

void
emberAfPluginMacAddressFilteringClearAll(void)

Clear all lists for MAC address filtering.

EmberStatus
emberAfPluginMacAddressFilteringGetStatsForShortAddress(uint8_t index, uint32_t *matchCountForIndexPtr)

Get stats for a short address.

void
emberAfPluginMacAddressFilteringGetStats(bool shortMode, uint32_t *allowedPacketCountPtr, uint32_t *droppedPacketCountPtr, uint32_t *totalPacketCountPtr)

Get MAC address filtering stats. Get the allowed, dropped and total packet counts.

void
emberAfPluginMacAddressFilteringFilterNoAddress(bool filterNoAddress)

Set the decision to manupulate the MAC address filtering tables.

void
emberAfPluginMacAddressFilteringAddShortAddress(EmberNodeId nodeId)

Add the short address.

void
emberAfPluginMacAddressFilteringAddLongAddress(EmberEUI64 eui64)

Add the long address.

void
emberAfPluginMacAddressFilteringAddPanId(EmberPanId panId)

Add the panID.

void
emberAfPluginMacAddressFilteringSetShortAddressListType(uint8_t *listType)

Set the short address list type.

void
emberAfPluginMacAddressFilteringSetLongAddressListType(uint8_t *listType)

Set the long address list type.

void
emberAfPluginMacAddressFilteringSetPanIdListType(uint8_t *listType)

Set the list type of panId list.

Enumerations#

enum
MacAddressMode {
MAC_ADDRESS_MODE_NONE = 0
MAC_ADDRESS_MODE_SHORT = 1
MAC_ADDRESS_MODE_LONG = 2
}
enum
MacFilterType {
MAC_FILTER_TYPE_NO_ADDRESS = 0
MAC_FILTER_TYPE_SHORT_ADDRESS = 1
MAC_FILTER_TYPE_LONG_ADDRESS = 2
MAC_FILTER_TYPE_PAN_ID = 3
}
enum
FilterResult {
ALLOW_PACKET = 0
DROP_PACKET = 1
}

Typedefs#

Variables#

const EmberEUI64
zeroEui64

Macros#

#define
expectCheckpoint (...)
#define
debug (...)
#define
EMBER_TEST_ASSERT (...)
#define
MAC_FILTER_OPTIONS_NO_ADDRESS_MASK (1 << MAC_FILTER_TYPE_NO_ADDRESS)
#define
MAC_FILTER_OPTIONS_SHORT_ADDRESS_LIST_MASK (1 << MAC_FILTER_TYPE_SHORT_ADDRESS)
#define
MAC_FILTER_OPTIONS_LONG_ADDRESS_LIST_MASK (1 << MAC_FILTER_TYPE_LONG_ADDRESS)
#define
MAC_FILTER_OPTIONS_DEST_PAN_ID_LIST_MASK (1 << MAC_FILTER_TYPE_PAN_ID)
#define
MAC_FILTER_OPTIONS_COUNT 4
#define
MAC_FILTER_OPTIONS_DROP_NO_ADDRESS 0x00
#define
MAC_FILTER_OPTIONS_SHORT_ADDRESS_BLACKLIST 0x00
#define
MAC_FILTER_OPTIONS_LONG_ADDRESS_BLACKLIST 0x00
#define
MAC_FILTER_OPTIONS_ALLOW_NO_ADDRESS 0x01
#define
MAC_FILTER_OPTIONS_SHORT_ADDRESS_WHITELIST 0x02
#define
MAC_FILTER_OPTIONS_LONG_ADDRESS_WHITELIST 0x04
#define
MAC_FILTER_OPTIONS_DEST_PAN_ID_WHITELIST 0x08
#define
MAC_FILTER_OPTIONS_DEST_PAN_ID_BLACKLIST 0x00
#define
BROADCAST_PAN_ID 0xFFFF
#define
MAC_FILTER_OPTIONS_DEFAULTS undefined
#define
MAC_FRAME_CONTROL_FRAME_TYPE_MASK 0x0007
#define
MAC_FRAME_CONTROL_FRAME_TYPE_BEACON 0x0000
#define
MAC_FRAME_CONTROL_FRAME_TYPE_DATA 0x0001
#define
MAC_FRAME_CONTROL_FRAME_TYPE_ACK 0x0002
#define
MAC_FRAME_CONTROL_FRAME_TYPE_COMMAND 0x0003
#define
MAC_FRAME_CONTROL_VERSION_MASK 0x3000
#define
MAC_FRAME_CONTROL_VERSION_SHIFT 12
#define
MAC_FRAME_CONTROL_VERSION_2003 0x0000
#define
MAC_FRAME_CONTROL_VERSION_2012 0x0002
#define
MAC_FRAME_CONTROL_SOURCE_ADDRESS_MODE_SHIFT 14
#define
MAC_FRAME_CONTROL_ADDRESS_MODE_MASK 0x0003
#define
MAC_FRAME_CONTROL_ADDRESS_MODE_NONE 0x0000
#define
MAC_FRAME_CONTROL_ADDRESS_MODE_RESERVED 0x0001
#define
MAC_FRAME_CONTROL_ADDRESS_MODE_SHORT 0x0002
#define
MAC_FRAME_CONTROL_ADDRESS_MODE_LONG 0x0003
#define
MAC_FRAME_CONTROL_DEST_ADDRESS_MODE_SHIFT 10
#define
MAC_FRAME_CONTROL_DEST_ADDRESS_MODE_NONE 0x0000
#define
MAC_FRAME_CONTROL_PANID_COMPRESSION 0x0040
#define
WHITELIST_CHARACTER_INDEX 4

API Documentation#

emberAfPluginMacAddressFilteringClearAll#

void emberAfPluginMacAddressFilteringClearAll (void )

Clear all lists for MAC address filtering.

Parameters
TypeDirectionArgument NameDescription
voidN/A

* arguments Ver.: always


emberAfPluginMacAddressFilteringGetStatsForShortAddress#

EmberStatus emberAfPluginMacAddressFilteringGetStatsForShortAddress (uint8_t index, uint32_t * matchCountForIndexPtr)

Get stats for a short address.

Parameters
TypeDirectionArgument NameDescription
uint8_tN/Aindex

Ver.: always

uint32_t *N/AmatchCountForIndexPtr

Ver.: always

Returns

  • EmberStatus status code


emberAfPluginMacAddressFilteringGetStats#

void emberAfPluginMacAddressFilteringGetStats (bool shortMode, uint32_t * allowedPacketCountPtr, uint32_t * droppedPacketCountPtr, uint32_t * totalPacketCountPtr)

Get MAC address filtering stats. Get the allowed, dropped and total packet counts.

Parameters
TypeDirectionArgument NameDescription
boolN/AshortMode

Ver.: always

uint32_t *N/AallowedPacketCountPtr

Ver.: always

uint32_t *N/AdroppedPacketCountPtr

Ver.: always

uint32_t *N/AtotalPacketCountPtr

Ver.: always


emberAfPluginMacAddressFilteringFilterNoAddress#

void emberAfPluginMacAddressFilteringFilterNoAddress (bool filterNoAddress)

Set the decision to manupulate the MAC address filtering tables.

Parameters
TypeDirectionArgument NameDescription
boolN/AfilterNoAddress

Ver.:always


emberAfPluginMacAddressFilteringAddShortAddress#

void emberAfPluginMacAddressFilteringAddShortAddress (EmberNodeId nodeId)

Add the short address.

Parameters
TypeDirectionArgument NameDescription
EmberNodeIdN/AnodeId

Ver.:always


emberAfPluginMacAddressFilteringAddLongAddress#

void emberAfPluginMacAddressFilteringAddLongAddress (EmberEUI64 eui64)

Add the long address.

Parameters
TypeDirectionArgument NameDescription
EmberEUI64N/Aeui64

Ver.:always


emberAfPluginMacAddressFilteringAddPanId#

void emberAfPluginMacAddressFilteringAddPanId (EmberPanId panId)

Add the panID.

Parameters
TypeDirectionArgument NameDescription
EmberPanIdN/ApanId

Ver.:always


emberAfPluginMacAddressFilteringSetShortAddressListType#

void emberAfPluginMacAddressFilteringSetShortAddressListType (uint8_t * listType)

Set the short address list type.

Parameters
TypeDirectionArgument NameDescription
uint8_t *N/AlistType

Ver.:always, listType can be "set-whitelist" or "set-blacklist".


emberAfPluginMacAddressFilteringSetLongAddressListType#

void emberAfPluginMacAddressFilteringSetLongAddressListType (uint8_t * listType)

Set the long address list type.

Parameters
TypeDirectionArgument NameDescription
uint8_t *N/AlistType

Ver.:always, listType can be "set-whitelist" or "set-blacklist".


emberAfPluginMacAddressFilteringSetPanIdListType#

void emberAfPluginMacAddressFilteringSetPanIdListType (uint8_t * listType)

Set the list type of panId list.

Parameters
TypeDirectionArgument NameDescription
uint8_t *N/AlistType

Ver.:always, listType can be "set-whitelist" or "set-blacklist".


Enumeration Documentation#

MacAddressMode#

MacAddressMode
Enumerator
MAC_ADDRESS_MODE_NONE
MAC_ADDRESS_MODE_SHORT
MAC_ADDRESS_MODE_LONG

MacFilterType#

MacFilterType
Enumerator
MAC_FILTER_TYPE_NO_ADDRESS
MAC_FILTER_TYPE_SHORT_ADDRESS
MAC_FILTER_TYPE_LONG_ADDRESS
MAC_FILTER_TYPE_PAN_ID

FilterResult#

FilterResult
Enumerator
ALLOW_PACKET
DROP_PACKET

Typedef Documentation#

MacAddressFilterOptions#

typedef uint8_t MacAddressFilterOptions

Variable Documentation#

macAddressFilterData#

MacAddressFilterGlobals macAddressFilterData

zeroEui64#

const EmberEUI64 zeroEui64