MAC Common API

Module for declaring MAC Common API. More...

Data Structures
union	mac_addr_t
	MAC ADDRESS. More...
struct	mac_payload_descriptor_t
	Payload descriptor. More...

Macros
#define	macAckWaitDuration   544
	Maximum interval for acknowledgement frame to arrive in microseconds. More...
#define	aMaxBeaconOverhead   75
	The maximum number of octets added by the MAC sublayer to the MAC payload of a beacon frame.
#define	aUnitBackoffPeriod   20UL
	The number of symbols forming the basic time period used by the CSMA-CA algorithm.
#define	aBaseSlotDuration   60UL
	The number of symbols forming a superframe slot when the superframe order is equal to 0.
#define	aNumSuperframeSlots   16UL
	The number of slots contained in any superframe.
#define	aBaseSuperframeDuration   (aBaseSlotDuration * aNumSuperframeSlots)
	The number of symbols forming a superframe when the superframe order is equal to 0.
#define	aMaxBeaconPayloadLength   (aMaxPHYPacketSize - aMaxBeaconOverhead)
	The maximum size, in octets, of a beacon payload.
#define	aMaxMPDUUnsecuredOverhead   25
	The maximum number of octets added by the MAC sublayer to the PSDU without security.
#define	aMaxMACSafePayloadSize   (aMaxPHYPacketSize - aMaxMPDUUnsecuredOverhead)
	The maximum number of octets that can be transmitted in the MAC Payload field of an unsecured MAC frame that will be guaranteed not to exceed aMaxPHYPacketSize.
#define	aMinMPDUOverhead   9
	The minimum number of octets added by the MAC sublayer to the PSDU.
#define	aMaxMACPayloadSize   (aMaxPHYPacketSize - aMinMPDUOverhead)
	The maximum number of octets that can be transmitted in the MAC Payload field.
#define	aMaxSIFSFrameSize   18
	The maximum size of an MPDU, in octets, that can be followed by a SIFS period.
#define	aMinCAPLength   440
	The minimum number of symbols forming the CAP. More...
#define	aGTSDescPersistenceTime   4
	The number of superframes in which a GTS descriptor exists in the beacon frame of the PAN coordinator.
#define	aMaxLostBeacons   4
	The number of consecutive lost beacons that will cause the MAC sublayer of a receiving device to declare a loss of synchronization.
#define	MAC_MIN_BATT_LIFE_EXT_PERIODS   6
	Maximum number of battery life extension periods.
#define	MAC_MAX_BATT_LIFE_EXT_PERIODS   41
	Minimum number of battery life extension periods.
#define	MAC_MIN_BEACON_ORDER   0
	Minimum value for macBeaconOrder parameter.
#define	MAC_MAX_BEACON_ORDER   15
	Maximum value for macBeaconOrder parameter.
#define	MAC_MIN_MAX_CSMA_BACKOFFS   0
	Minimum value for macMaxCSMABackoffs parameter.
#define	MAC_MAX_MAX_CSMA_BACKOFFS   5
	Maximum value for macMaxCSMABackoffs parameter.
#define	MAC_MIN_MIN_BE   0
	Minimum value for macMinBE parameter.
#define	MAC_MIN_MAX_BE   3
	Minimum value for macMaxBE parameter.
#define	MAC_MAX_MAX_BE   8
	Maximum value for macMaxBE parameter.
#define	MAC_MIN_SUPERFRAME_ORDER   0
	Minimum value for macSuperframeOrder parameter.
#define	MAC_MAX_SUPERFRAME_ORDER   15
	Maximum value for macSuperframeOrder parameter.
#define	MAC_MIN_MAX_FRAME_RETRIES   0
	Minimum value for macMaxFrameRetries parameter.
#define	MAC_MAX_MAX_FRAME_RETRIES   7
	Maximum value for macMaxFrameRetries parameter.
#define	MAC_MIN_RESPONSE_WAIT_TIME   2
	Minimum value for macResponseWaitTime parameter.
#define	MAC_MAX_RESPONSE_WAIT_TIME   64
	Maximum value for macResponseWaitTime parameter.
#define	MAC_SHORT_ADDRESS_NOT_SET   0xFFFF
	A handy macro for a never initialized short address.
#define	MAC_EXTENDED_ADDRESS_NOT_SET   0xFFFFFFFFFFFFFFFFULL
	A handy macro for a never initialized short address.
#define	MAC_NO_BEACONS   15
	A value of MAC beacon order attribute which determines a state with no periodic beacons.
#define	MAC_BROADCAST_SHORT_ADDRESS   0xFFFF
	A handy macro for broadcast address.
#define	MAC_BROADCAST_PANID   0xFFFF
	A handy macro for unknown PAN ID.
#define	MAC_EXTENDED_ADDRESS_ONLY   0xFFFE
	Short address field value that is used when the device does not support short addressing mode.
#define	MAC_FINAL_CAP_SLOT_NBPAN   15
	Final CAP slot field value in the beacon for non-beacon enabled PAN.
#define	MAC_SLOT_AMOUNT   16
	Total amount of slots available in beacon enabled PAN.
#define	MAC_SECURITY_KEY_INDEX_NOT_SET   0xFF
	This is the value of auto request key index until it has been set.
#define	MAC_ADDR_SHORT_LEN   2
	Length of short MAC address in bytes.
#define	MAC_ADDR_EXTENDED_LEN   8
	Length of extended MAC address in bytes.
#define	MAC_PAN_ID_LEN   2
	Length of PAN ID field in bytes.
#define	MAC_MFR_SIZE   2
	MAC footer (FCS) size.
#define	MAC_MAX_AUX_HEADER_SIZE   0
	Maximum auxiliary header length.
#define	MAC_MAX_MHR_SIZE
	Maximum MAC header length. More...
#define	MAC_MAX_BCN_MHR_SIZE
	Maximum MAC header length for beacon frame. More...
#define	MAC_MEMORY_RESERVE   (MAC_MAX_MHR_SIZE + MAC_MFR_SIZE)
	Memory which should be reserved for MAC fields.
#define	MAC_MAX_MSDU_OFFSET   MAC_MAX_MHR_SIZE
	Offset of MAC payload in the frame buffer.

Enumerations
enum	mac_frame_type_t {   MAC_BEACON,   MAC_DATA,   MAC_ACK,   MAC_COMMAND }
	Possible MAC frame types. More...
enum	mac_addr_mode_t {   MAC_ADDR_NONE = 0,   MAC_ADDR_SHORT = 2,   MAC_ADDR_LONG = 3 }
	MAC ADDR MODE. More...
enum	mac_frame_version_t {   MAC_FRAME_VERSION_2003,   MAC_FRAME_VERSION_2006 }
enum	mac_status_t {   MAC_SUCCESS = 0x00,   MAC_COUNTER_ERROR = 0xDB,   MAC_IMPROPER_KEY_TYPE = 0xDC,   MAC_IMPROPER_SECURITY_LEVEL = 0xDD,   MAC_UNSUPPORTED_LEGACY = 0xDE,   MAC_UNSUPPORTED_SECURITY = 0xDF,   MAC_BEACON_LOSS = 0xE0,   MAC_CHANNEL_ACCESS_FAILURE = 0xE1,   MAC_DENIED = 0xE2,   MAC_DISABLE_TRX_FAILURE = 0xE3,   MAC_SECURITY_ERROR = 0xE4,   MAC_FRAME_TOO_LONG = 0xE5,   MAC_INVALID_GTS = 0xE6,   MAC_INVALID_HANDLE = 0xE7,   MAC_INVALID_PARAMETER = 0xE8,   MAC_NO_ACK = 0xE9,   MAC_NO_BEACON = 0xEA,   MAC_NO_DATA = 0xEB,   MAC_NO_SHORT_ADDRESS = 0xEC,   MAC_OUT_OF_CAP = 0xED,   MAC_PAN_ID_CONFLICT = 0xEE,   MAC_REALIGNMENT = 0xEF,   MAC_TRANSACTION_EXPIRED = 0xF0,   MAC_TRANSACTION_OVERFLOW = 0xF1,   MAC_TX_ACTIVE = 0xF2,   MAC_UNAVAILABLE_KEY = 0xF3,   MAC_UNSUPPORTED_ATTRIBUTE = 0xF4,   MAC_INVALID_ADDRESS = 0xF5,   MAC_ON_TIME_TOO_LONG = 0xF6,   MAC_PAST_TIME = 0xF7,   MAC_TRACKING_OFF = 0xF8,   MAC_INVALID_INDEX = 0xF9,   MAC_LIMIT_REACHED = 0xFA,   MAC_READ_ONLY = 0xFB,   MAC_SCAN_IN_PROGRESS = 0xFC,   MAC_SUPERFRAME_OVERLAP = 0xFD,   MAC_IS_NOT_AVAILABLE = 0xFF }
	MAC status. More...
enum	mac_command_id_t {   MAC_CMD_ASSOC_REQ = 0x01,   MAC_CMD_ASSOC_RESP = 0x02,   MAC_CMD_DISASSOC_NTF = 0x03,   MAC_CMD_DATA_REQ = 0x04,   MAC_CMD_PANID_CONFLICT_NTF = 0x05,   MAC_CMD_ORPHAN_NTF = 0x06,   MAC_CMD_BEACON_REQ = 0x07,   MAC_CMD_COORD_REALIGN = 0x08,   MAC_CMD_GTS_REQ = 0x09 }
	Command frame IDs defined by the MAC sublayer that are listed in Table 82 of the standard. More...

Detailed Description

Module for declaring MAC Common API.

The Common MAC module contains declarations of commonly used MAC routines and necessary macros and types.

Macro Definition Documentation

#define aMinCAPLength   440

The minimum number of symbols forming the CAP.

This ensures that MAC commands can still be transferred to devices when GTSs are being used.

#define MAC_MAX_BCN_MHR_SIZE

Value:

(PHY_MAX_HEADER_SIZE + \
 2 /* Frame control field */ + \
 1 /* Beacon sequence number */ + \
 sizeof(uint16_t) /* PAN ID */ + \
 sizeof(uint64_t) /* Extended address */ + \
 MAC_MAX_AUX_HEADER_SIZE)

Maximum MAC header length for beacon frame.

#define MAC_MAX_MHR_SIZE

Value:

(PHY_MAX_HEADER_SIZE + \
 2 /* Frame control */ + \
 1 /* Data sequence number */ + \
 2 * (sizeof(uint16_t) + (sizeof(uint64_t))) /* Two PAN IDs and extended addresses */ + \
 MAC_MAX_AUX_HEADER_SIZE)

Maximum MAC header length.

#define macAckWaitDuration   544

Maximum interval for acknowledgement frame to arrive in microseconds.

macAckWaitDuration = aUnitBackoffPeriod(only for beacon enabled PAN) + aTurnaroundTime + phySHRDuration + ceil(6 * phySymbolsPerOctet) = 20 + 12 + 10 + 6 * 2 = 54 symbols / 62.5 ksymbols/s = 864 us (544 us for beacon disabled PAN)

Enumeration Type Documentation

enum mac_addr_mode_t

MAC ADDR MODE.

Enumerator
MAC_ADDR_NONE	NO address is used.
MAC_ADDR_SHORT	Short address is used.
MAC_ADDR_LONG	Long address is used.

enum mac_command_id_t

Command frame IDs defined by the MAC sublayer that are listed in Table 82 of the standard.

Enumerator
MAC_CMD_ASSOC_REQ	Association request.
MAC_CMD_ASSOC_RESP	Association response.
MAC_CMD_DISASSOC_NTF	Disassociation notification.
MAC_CMD_DATA_REQ	Data request.
MAC_CMD_PANID_CONFLICT_NTF	PAN ID conflict notification.
MAC_CMD_ORPHAN_NTF	Orphan notification.
MAC_CMD_BEACON_REQ	Beacon request.
MAC_CMD_COORD_REALIGN	Coordinator realignment.
MAC_CMD_GTS_REQ	GTS request.

enum mac_frame_type_t

Possible MAC frame types.

Enumerator
MAC_BEACON	Frame is a beacon.
MAC_DATA	Frame is a data frame.
MAC_ACK	Frame is a MAC ACKnowledgement.
MAC_COMMAND	Frame is a MAC command.

enum mac_frame_version_t

Enumerator
MAC_FRAME_VERSION_2003	IEEE 802.15.4-2003 compliant.
MAC_FRAME_VERSION_2006	IEEE 802.15.4-2006 compliant.

enum mac_status_t

MAC status.

In accordance with IEEE Std 802.15.4-2006, section 7.1.17 excluding: MAC_IS_NOT_AVAILABLE This status is necessary for synchronous API.

Enumerator
MAC_COUNTER_ERROR	Operation is successful.
MAC_IMPROPER_KEY_TYPE	The frame counter purportedly applied by the originator of the received frame is invalid.
MAC_IMPROPER_SECURITY_LEVEL	The key purportedly applied by the originator of the received frame is not allowed to be used with that frame type according to the key usage policy of the recipient.
MAC_UNSUPPORTED_LEGACY	The security level purportedly applied by the originator of the received frame does not meet the minimum security level required/expected by the recipient for that frame type.
MAC_UNSUPPORTED_SECURITY	The received frame was purportedly secured using security based on IEEE Std 802.15.4-2003, and such security is not supported by this standard.
MAC_BEACON_LOSS	The security purportedly applied by the originator of the received frame is not supported.
MAC_CHANNEL_ACCESS_FAILURE	The beacon was lost following a synchronization request.
MAC_DENIED	A transmission could not take place due to activity on the channel, i.e. the CSMA-CA mechanism has failed.
MAC_DISABLE_TRX_FAILURE	The GTS request has been denied by the PAN coordinator.
MAC_SECURITY_ERROR	The attempt to disable the transceiver has failed.
MAC_FRAME_TOO_LONG	Cryptographic processing of the received secured frame failed.
MAC_INVALID_GTS	Either a frame resulting from processing has a length that is greater than aMaxPHYPacketSize or a requested transaction is too large to fit in the CAP or GTS.
MAC_INVALID_HANDLE	The requested GTS transmission failed because the specified GTS either did not have a transmit GTS direction or was not defined.
MAC_INVALID_PARAMETER	A request to purge an MSDU from the transaction queue was made using an MSDU handle that was not found in the transaction table.
MAC_NO_ACK	A parameter in the primitive is either not supported or is out of the valid range.
MAC_NO_BEACON	No acknowledgment was received after macMaxFrameRetries.
MAC_NO_DATA	A scan operation failed to find any network beacons.
MAC_NO_SHORT_ADDRESS	No response data was available following a request.
MAC_OUT_OF_CAP	The operation failed because a 16-bit short address was not allocated.
MAC_PAN_ID_CONFLICT	A receiver enable request was unsuccessful because it could not be completed within the CAP. Note The enumeration description is not used in this standard, and it is included only to meet the backwards compatibility requirements for IEEE Std 802.15.4-2003.
MAC_REALIGNMENT	A PAN identifier conflict has been detected and communicated to the PAN coordinator.
MAC_TRANSACTION_EXPIRED	A coordinator realignment command has been received.
MAC_TRANSACTION_OVERFLOW	The transaction has expired and its information was discarded.
MAC_TX_ACTIVE	There is no capacity to store the transaction.
MAC_UNAVAILABLE_KEY	The transceiver was in the transmitter enabled state when the receiver was requested to be enabled. Note The enumeration description is not used in this standard, and it is included only to meet the backwards compatibility requirements for IEEE Std 802.15.4-2003.
MAC_UNSUPPORTED_ATTRIBUTE	The key purportedly used by the originator of the received frame is not available or, if available, the originating device is not known or is blacklisted with that particular key.
MAC_INVALID_ADDRESS	A SET/GET request was issued with the identifier of a PIB attribute that is not supported.
MAC_ON_TIME_TOO_LONG	A request to send data was unsuccessful because neither the source address parameters nor the destination address parameters were present.
MAC_PAST_TIME	A receiver enable request was unsuccessful because it specified a number of symbols that was longer than the beacon interval.
MAC_TRACKING_OFF	A receiver enable request was unsuccessful because it could not be completed within the current superframe and was not permitted to be deferred until the next superframe.
MAC_INVALID_INDEX	The device was instructed to start sending beacons based on the timing of the beacon transmissions of its coordinator, but the device is not currently tracking the beacon of its coordinator.
MAC_LIMIT_REACHED	An attempt to write to a MAC PIB attribute that is in a table failed because the specified table index was out of range.
MAC_READ_ONLY	A scan operation terminated prematurely because the number of PAN descriptors stored reached an implementation specified maximum.
MAC_SCAN_IN_PROGRESS	A SET/GET request was issued with the identifier of an attribute that is read only.
MAC_SUPERFRAME_OVERLAP	A request to perform a scan operation failed because the MLME was in the process of performing a previously initiated scan operation.
MAC_IS_NOT_AVAILABLE	The device was instructed to start sending beacons based on the timing of the beacon transmissions of its coordinator, but the instructed start time overlapped the transmission time of the beacon of its coordinator. MAC is not available.