1639 lines
77 KiB
C
1639 lines
77 KiB
C
/**************************************************************************************************
|
|
Filename: mac_api.h
|
|
Revised: $Date: 2011-02-28 16:59:59 -0800 (Mon, 28 Feb 2011) $
|
|
Revision: $Revision: 25230 $
|
|
|
|
Description: Public interface file for 802.15.4 MAC.
|
|
|
|
|
|
Copyright 2005-2010 Texas Instruments Incorporated. All rights reserved.
|
|
|
|
IMPORTANT: Your use of this Software is limited to those specific rights
|
|
granted under the terms of a software license agreement between the user
|
|
who downloaded the software, his/her employer (which must be your employer)
|
|
and Texas Instruments Incorporated (the "License"). You may not use this
|
|
Software unless you agree to abide by the terms of the License. The License
|
|
limits your use, and you acknowledge, that the Software may not be modified,
|
|
copied or distributed unless embedded on a Texas Instruments microcontroller
|
|
or used solely and exclusively in conjunction with a Texas Instruments radio
|
|
frequency transceiver, which is integrated into your product. Other than for
|
|
the foregoing purpose, you may not use, reproduce, copy, prepare derivative
|
|
works of, modify, distribute, perform, display or sell this Software and/or
|
|
its documentation for any purpose.
|
|
|
|
YOU FURTHER ACKNOWLEDGE AND AGREE THAT THE SOFTWARE AND DOCUMENTATION ARE
|
|
PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
|
|
INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE,
|
|
NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL
|
|
TEXAS INSTRUMENTS OR ITS LICENSORS BE LIABLE OR OBLIGATED UNDER CONTRACT,
|
|
NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, BREACH OF WARRANTY, OR OTHER
|
|
LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT DAMAGES OR EXPENSES
|
|
INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, INDIRECT, PUNITIVE
|
|
OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF PROCUREMENT
|
|
OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY CLAIMS BY THIRD PARTIES
|
|
(INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), OR OTHER SIMILAR COSTS.
|
|
|
|
Should you have any questions regarding your right to use this Software,
|
|
contact Texas Instruments Incorporated at www.TI.com.
|
|
**************************************************************************************************/
|
|
|
|
#ifndef MAC_API_H
|
|
#define MAC_API_H
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/* ------------------------------------------------------------------------------------------------
|
|
* Includes
|
|
* ------------------------------------------------------------------------------------------------
|
|
*/
|
|
#include "hal_types.h"
|
|
#include "saddr.h"
|
|
#include "sdata.h"
|
|
|
|
/* ------------------------------------------------------------------------------------------------
|
|
* Constants
|
|
* ------------------------------------------------------------------------------------------------
|
|
*/
|
|
|
|
/* Status */
|
|
#define MAC_SUCCESS 0x00 /* Operation successful */
|
|
#define MAC_AUTOACK_PENDING_ALL_ON 0xFE /* The AUTOPEND pending all is turned on */
|
|
#define MAC_AUTOACK_PENDING_ALL_OFF 0xFF /* The AUTOPEND pending all is turned off */
|
|
#define MAC_BEACON_LOSS 0xE0 /* The beacon was lost following a synchronization request */
|
|
#define MAC_CHANNEL_ACCESS_FAILURE 0xE1 /* The operation or data request failed because of
|
|
activity on the channel */
|
|
#define MAC_COUNTER_ERROR 0xDB /* The frame counter puportedly applied by the originator of
|
|
the received frame is invalid */
|
|
#define MAC_DENIED 0xE2 /* The MAC was not able to enter low power mode. */
|
|
#define MAC_DISABLE_TRX_FAILURE 0xE3 /* Unused */
|
|
#define MAC_FRAME_TOO_LONG 0xE5 /* The received frame or frame resulting from an operation
|
|
or data request is too long to be processed by the MAC */
|
|
#define MAC_IMPROPER_KEY_TYPE 0xDC /* The key purportedly applied by the originator of the
|
|
received frame is not allowed */
|
|
#define MAC_IMPROPER_SECURITY_LEVEL 0xDD /* The security level purportedly applied by the originator of
|
|
the received frame does not meet the minimum security level */
|
|
#define MAC_INVALID_ADDRESS 0xF5 /* The data request failed because neither the source address nor
|
|
destination address parameters were present */
|
|
#define MAC_INVALID_GTS 0xE6 /* Unused */
|
|
#define MAC_INVALID_HANDLE 0xE7 /* The purge request contained an invalid handle */
|
|
#define MAC_INVALID_INDEX 0xF9 /* Unused */
|
|
#define MAC_INVALID_PARAMETER 0xE8 /* The API function parameter is out of range */
|
|
#define MAC_LIMIT_REACHED 0xFA /* The scan terminated because the PAN descriptor storage limit
|
|
was reached */
|
|
#define MAC_NO_ACK 0xE9 /* The operation or data request failed because no
|
|
acknowledgement was received */
|
|
#define MAC_NO_BEACON 0xEA /* The scan request failed because no beacons were received or the
|
|
orphan scan failed because no coordinator realignment was received */
|
|
#define MAC_NO_DATA 0xEB /* The associate request failed because no associate response was received
|
|
or the poll request did not return any data */
|
|
#define MAC_NO_SHORT_ADDRESS 0xEC /* The short address parameter of the start request was invalid */
|
|
#define MAC_ON_TIME_TOO_LONG 0xF6 /* Unused */
|
|
#define MAC_OUT_OF_CAP 0xED /* Unused */
|
|
#define MAC_PAN_ID_CONFLICT 0xEE /* A PAN identifier conflict has been detected and
|
|
communicated to the PAN coordinator */
|
|
#define MAC_PAST_TIME 0xF7 /* Unused */
|
|
#define MAC_READ_ONLY 0xFB /* A set request was issued with a read-only identifier */
|
|
#define MAC_REALIGNMENT 0xEF /* A coordinator realignment command has been received */
|
|
#define MAC_SCAN_IN_PROGRESS 0xFC /* The scan request failed because a scan is already in progress */
|
|
#define MAC_SECURITY_ERROR 0xE4 /* Cryptographic processing of the received secure frame failed */
|
|
#define MAC_SUPERFRAME_OVERLAP 0xFD /* The beacon start time overlapped the coordinator transmission time */
|
|
#define MAC_TRACKING_OFF 0xF8 /* The start request failed because the device is not tracking
|
|
the beacon of its coordinator */
|
|
#define MAC_TRANSACTION_EXPIRED 0xF0 /* The associate response, disassociate request, or indirect
|
|
data transmission failed because the peer device did not respond
|
|
before the transaction expired or was purged */
|
|
#define MAC_TRANSACTION_OVERFLOW 0xF1 /* The request failed because MAC data buffers are full */
|
|
#define MAC_TX_ACTIVE 0xF2 /* Unused */
|
|
#define MAC_UNAVAILABLE_KEY 0xF3 /* The operation or data request failed because the
|
|
security key is not available */
|
|
#define MAC_UNSUPPORTED_ATTRIBUTE 0xF4 /* The set or get request failed because the attribute is not supported */
|
|
#define MAC_UNSUPPORTED_LEGACY 0xDE /* The received frame was secured with legacy security which is
|
|
not supported */
|
|
#define MAC_UNSUPPORTED_SECURITY 0xDF /* The security of the received frame is not supported */
|
|
#define MAC_UNSUPPORTED 0x18 /* The operation is not supported in the current configuration */
|
|
#define MAC_BAD_STATE 0x19 /* The operation could not be performed in the current state */
|
|
#define MAC_NO_RESOURCES 0x1A /* The operation could not be completed because no
|
|
memory resources were available */
|
|
#define MAC_ACK_PENDING 0x1B /* For internal use only */
|
|
#define MAC_NO_TIME 0x1C /* For internal use only */
|
|
#define MAC_TX_ABORTED 0x1D /* For internal use only */
|
|
#define MAC_DUPLICATED_ENTRY 0x1E /* For internal use only - A duplicated entry is added to the source matching table */
|
|
|
|
/* MAC Security Level */
|
|
#define MAC_SEC_LEVEL_NONE 0x00 /* No security is used */
|
|
#define MAC_SEC_LEVEL_MIC_32 0x01 /* MIC-32 authentication is used */
|
|
#define MAC_SEC_LEVEL_MIC_64 0x02 /* MIC-64 authentication is used */
|
|
#define MAC_SEC_LEVEL_MIC_128 0x03 /* MIC-128 authentication is used */
|
|
#define MAC_SEC_LEVEL_ENC 0x04 /* AES encryption is used */
|
|
#define MAC_SEC_LEVEL_ENC_MIC_32 0x05 /* AES encryption and MIC-32 authentication are used */
|
|
#define MAC_SEC_LEVEL_ENC_MIC_64 0x06 /* AES encryption and MIC-64 authentication are used */
|
|
#define MAC_SEC_LEVEL_ENC_MIC_128 0x07 /* AES encryption and MIC-128 authentication are used */
|
|
|
|
/* Key Identifier Mode */
|
|
#define MAC_KEY_ID_MODE_NONE 0x00 /* Key is is not used */
|
|
#define MAC_KEY_ID_MODE_IMPLICIT 0x00 /* Key is determined implicitly */
|
|
#define MAC_KEY_ID_MODE_1 0x01 /* Key is determined from the 1-byte key index */
|
|
#define MAC_KEY_ID_MODE_4 0x02 /* Key is determined from the 4-byte key index */
|
|
#define MAC_KEY_ID_MODE_8 0x03 /* Key is determined from the 8-byte key index */
|
|
|
|
/* Key identifier field length in bytes */
|
|
#define MAC_KEY_ID_IMPLICIT_LEN 0
|
|
#define MAC_KEY_ID_1_LEN 1
|
|
#define MAC_KEY_ID_4_LEN 5
|
|
#define MAC_KEY_ID_8_LEN 9
|
|
|
|
/* Key source maximum length in bytes */
|
|
#define MAC_KEY_SOURCE_MAX_LEN 8
|
|
|
|
/* Key index length in bytes */
|
|
#define MAC_KEY_INDEX_LEN 1
|
|
|
|
/* Frame counter length in bytes */
|
|
#define MAC_FRAME_COUNTER_LEN 4
|
|
|
|
/* Key length in bytes */
|
|
#define MAC_KEY_MAX_LEN 16
|
|
|
|
/* Key lookup data length in bytes */
|
|
#define MAC_KEY_LOOKUP_SHORT_LEN 5
|
|
#define MAC_KEY_LOOKUP_LONG_LEN 9
|
|
#define MAC_MAX_KEY_LOOKUP_LEN MAC_KEY_LOOKUP_LONG_LEN
|
|
|
|
|
|
/* Data constants */
|
|
#if !defined ( MAC_MAX_FRAME_SIZE )
|
|
#define MAC_MAX_FRAME_SIZE 102 /* Maximum application data length without security */
|
|
#endif
|
|
|
|
#define MAC_DATA_OFFSET 24 /* Bytes required for MAC header in data frame */
|
|
#define MAC_ENC_OFFSET 5 /* Data offset required for encryption header */
|
|
#define MAC_MIC_32_LEN 4 /* Length required for MIC-32 authentication */
|
|
#define MAC_MIC_64_LEN 8 /* Length required for MIC-64 authentication */
|
|
#define MAC_MIC_128_LEN 16 /* Length required for MIC-128 authentication */
|
|
|
|
/* MHR length for received frame */
|
|
#define MAC_MHR_LEN 37 /* FCF (2) + Seq (1) + Addr Fields (20) + Security HDR (14) */
|
|
|
|
/* TX Options */
|
|
#define MAC_TXOPTION_ACK 0x01 /* Acknowledged transmission. The MAC will attempt to retransmit
|
|
the frame until it is acknowledged */
|
|
#define MAC_TXOPTION_GTS 0x02 /* GTS transmission (unused) */
|
|
#define MAC_TXOPTION_INDIRECT 0x04 /* Indirect transmission. The MAC will queue the data and wait
|
|
for the destination device to poll for it. This can only be used
|
|
by a coordinator device */
|
|
#define MAC_TXOPTION_PEND_BIT 0x08 /* This proprietary option forces the pending bit set for direct
|
|
transmission */
|
|
#define MAC_TXOPTION_NO_RETRANS 0x10 /* This proprietary option prevents the frame from being retransmitted */
|
|
#define MAC_TXOPTION_NO_CNF 0x20 /* This proprietary option prevents a MAC_MCPS_DATA_CNF
|
|
event from being sent for this frame */
|
|
#define MAC_TXOPTION_ALT_BE 0x40 /* Use PIB value MAC_ALT_BE for the minimum backoff exponent */
|
|
#define MAC_TXOPTION_PWR_CHAN 0x80 /* Use the power and channel values in macDataReq_t
|
|
instead of the PIB values */
|
|
|
|
/* Channels */
|
|
#define MAC_CHAN_11 11
|
|
#define MAC_CHAN_12 12
|
|
#define MAC_CHAN_13 13
|
|
#define MAC_CHAN_14 14
|
|
#define MAC_CHAN_15 15
|
|
#define MAC_CHAN_16 16
|
|
#define MAC_CHAN_17 17
|
|
#define MAC_CHAN_18 18
|
|
#define MAC_CHAN_19 19
|
|
#define MAC_CHAN_20 20
|
|
#define MAC_CHAN_21 21
|
|
#define MAC_CHAN_22 22
|
|
#define MAC_CHAN_23 23
|
|
#define MAC_CHAN_24 24
|
|
#define MAC_CHAN_25 25
|
|
#define MAC_CHAN_26 26
|
|
#define MAC_CHAN_27 27
|
|
#define MAC_CHAN_28 28
|
|
|
|
|
|
/* This macro converts a channel to a mask */
|
|
#define MAC_CHAN_MASK(chan) ((uint32) 1 << (chan))
|
|
|
|
/* Channel Masks */
|
|
#define MAC_CHAN_11_MASK MAC_CHAN_MASK(MAC_CHAN_11)
|
|
#define MAC_CHAN_12_MASK MAC_CHAN_MASK(MAC_CHAN_12)
|
|
#define MAC_CHAN_13_MASK MAC_CHAN_MASK(MAC_CHAN_13)
|
|
#define MAC_CHAN_14_MASK MAC_CHAN_MASK(MAC_CHAN_14)
|
|
#define MAC_CHAN_15_MASK MAC_CHAN_MASK(MAC_CHAN_15)
|
|
#define MAC_CHAN_16_MASK MAC_CHAN_MASK(MAC_CHAN_16)
|
|
#define MAC_CHAN_17_MASK MAC_CHAN_MASK(MAC_CHAN_17)
|
|
#define MAC_CHAN_18_MASK MAC_CHAN_MASK(MAC_CHAN_18)
|
|
#define MAC_CHAN_19_MASK MAC_CHAN_MASK(MAC_CHAN_19)
|
|
#define MAC_CHAN_20_MASK MAC_CHAN_MASK(MAC_CHAN_20)
|
|
#define MAC_CHAN_21_MASK MAC_CHAN_MASK(MAC_CHAN_21)
|
|
#define MAC_CHAN_22_MASK MAC_CHAN_MASK(MAC_CHAN_22)
|
|
#define MAC_CHAN_23_MASK MAC_CHAN_MASK(MAC_CHAN_23)
|
|
#define MAC_CHAN_24_MASK MAC_CHAN_MASK(MAC_CHAN_24)
|
|
#define MAC_CHAN_25_MASK MAC_CHAN_MASK(MAC_CHAN_25)
|
|
#define MAC_CHAN_26_MASK MAC_CHAN_MASK(MAC_CHAN_26)
|
|
#define MAC_CHAN_27_MASK MAC_CHAN_MASK(MAC_CHAN_27)
|
|
#define MAC_CHAN_28_MASK MAC_CHAN_MASK(MAC_CHAN_28)
|
|
|
|
/* Channel Page */
|
|
#define MAC_CHANNEL_PAGE_0 0 /* 2.4 GHz band using O-QPSK */
|
|
#define MAC_CHANNEL_PAGE_1 1 /* 868 and 915 MHz bands using ASK */
|
|
#define MAC_CHANNEL_PAGE_2 2 /* 868 and 915 MHz bands using O-QPSK */
|
|
|
|
/* Capability Information */
|
|
#define MAC_CAPABLE_PAN_COORD 0x01 /* Device is capable of becoming a PAN coordinator */
|
|
#define MAC_CAPABLE_FFD 0x02 /* Device is an FFD */
|
|
#define MAC_CAPABLE_MAINS_POWER 0x04 /* Device is mains powered rather than battery powered */
|
|
#define MAC_CAPABLE_RX_ON_IDLE 0x08 /* Device has its receiver on when idle */
|
|
#define MAC_CAPABLE_SECURITY 0x40 /* Device is capable of sending and receiving secured frames */
|
|
#define MAC_CAPABLE_ALLOC_ADDR 0x80 /* Request allocation of a short address in the associate procedure */
|
|
|
|
/* Standard PIB Get and Set Attributes */
|
|
#define MAC_ACK_WAIT_DURATION 0x40 /* The maximum number of symbols to wait for an acknowledgment frame */
|
|
#define MAC_ASSOCIATION_PERMIT 0x41 /* TRUE if a coordinator is currently allowing association */
|
|
#define MAC_AUTO_REQUEST 0x42 /* TRUE if a device automatically sends a data request if its address
|
|
is listed in the beacon frame */
|
|
#define MAC_BATT_LIFE_EXT 0x43 /* TRUE if battery life extension is enabled */
|
|
#define MAC_BATT_LIFE_EXT_PERIODS 0x44 /* The number of backoff periods during which the receiver is
|
|
enabled following a beacon in battery life extension mode */
|
|
#define MAC_BEACON_PAYLOAD 0x45 /* The contents of the beacon payload */
|
|
#define MAC_BEACON_PAYLOAD_LENGTH 0x46 /* The length in bytes of the beacon payload */
|
|
#define MAC_BEACON_ORDER 0x47 /* How often the coordinator transmits a beacon */
|
|
#define MAC_BEACON_TX_TIME 0x48 /* The time the device transmitted its last beacon frame,
|
|
in backoff period units */
|
|
#define MAC_BSN 0x49 /* The beacon sequence number */
|
|
#define MAC_COORD_EXTENDED_ADDRESS 0x4A /* The extended address of the coordinator with which the device
|
|
is associated */
|
|
#define MAC_COORD_SHORT_ADDRESS 0x4B /* The short address assigned to the coordinator with which the
|
|
device is associated. A value of MAC_ADDR_USE_EXT indicates
|
|
that the coordinator is using its extended address */
|
|
#define MAC_DSN 0x4C /* The data or MAC command frame sequence number */
|
|
#define MAC_GTS_PERMIT 0x4D /* TRUE if the PAN coordinator accepts GTS requests */
|
|
#define MAC_MAX_CSMA_BACKOFFS 0x4E /* The maximum number of backoffs the CSMA-CA algorithm will attempt
|
|
before declaring a channel failure */
|
|
#define MAC_MIN_BE 0x4F /* The minimum value of the backoff exponent in the CSMA-CA algorithm.
|
|
If this value is set to 0, collision avoidance is disabled during
|
|
the first iteration of the algorithm. Also for the slotted version
|
|
of the CSMA-CA algorithm with the battery life extension enabled,
|
|
the minimum value of the backoff exponent will be at least 2 */
|
|
#define MAC_PAN_ID 0x50 /* The PAN identifier. If this value is 0xffff, the device is not
|
|
associated */
|
|
#define MAC_PROMISCUOUS_MODE 0x51 /* TRUE if the MAC is in promiscuous mode */
|
|
#define MAC_RX_ON_WHEN_IDLE 0x52 /* TRUE if the MAC enables its receiver during idle periods */
|
|
#define MAC_SHORT_ADDRESS 0x53 /* The short address that the device uses to communicate in the PAN.
|
|
If the device is a PAN coordinator, this value shall be set before
|
|
calling MAC_StartReq(). Otherwise the value is allocated during
|
|
association. Value MAC_ADDR_USE_EXT indicates that the device is
|
|
associated but not using a short address */
|
|
#define MAC_SUPERFRAME_ORDER 0x54 /* This specifies the length of the active portion of the superframe */
|
|
#define MAC_TRANSACTION_PERSISTENCE_TIME 0x55 /* The maximum time in beacon intervals that a transaction is stored by
|
|
a coordinator and indicated in the beacon */
|
|
#define MAC_ASSOCIATED_PAN_COORD 0x56 /* TRUE if the device is associated to the PAN coordinator */
|
|
#define MAC_MAX_BE 0x57 /* The maximum value of the backoff exponent in the CSMA-CA algorithm */
|
|
#define MAC_MAX_FRAME_TOTAL_WAIT_TIME 0x58 /* The maximum number of CAP symbols in a beacon-enabled PAN, or
|
|
symbols in a non beacon-enabled PAN, to wait for a frame intended
|
|
as a response to a data request frame */
|
|
#define MAC_MAX_FRAME_RETRIES 0x59 /* The maximum number of retries allowed after a transmission failure */
|
|
#define MAC_RESPONSE_WAIT_TIME 0x5A /* The maximum number of symbols a device shall wait for a response
|
|
command to be available following a request command in multiples
|
|
of aBaseSuperframeDuration */
|
|
#define MAC_SYNC_SYMBOL_OFFSET 0x5B /* The timestamp offset from SFD in symbols */
|
|
#define MAC_TIMESTAMP_SUPPORTED 0x5C /* TRUE if the MAC supports RX and TX timestamps */
|
|
#define MAC_SECURITY_ENABLED 0x5D /* TRUE if security is enabled */
|
|
|
|
/* Security PIB Get and Set Attributes */
|
|
#define MAC_KEY_TABLE 0x71 /* A table of KeyDescriptor, entries, each containing keys and related
|
|
information required for secured communications */
|
|
#define MAC_KEY_TABLE_ENTRIES 0x72 /* The number of entries in macKeyTable */
|
|
#define MAC_DEVICE_TABLE 0x73 /* A table of Device-Descriptor entries, each indicating a remote device
|
|
with which this device securely communicates */
|
|
#define MAC_DEVICE_TABLE_ENTRIES 0x74 /* The number of entries in macDeviceTable. */
|
|
#define MAC_SECURITY_LEVEL_TABLE 0x75 /* A table of SecurityLevel-Descriptor entries, each with information
|
|
about the minimum security level expected depending on incoming frame
|
|
type and subtype. */
|
|
#define MAC_SECURITY_LEVEL_TABLE_ENTRIES 0x76 /* The number of entries in macSecurityLevelTable. */
|
|
#define MAC_FRAME_COUNTER 0x77 /* The outgoing frame counter for this device */
|
|
#define MAC_AUTO_REQUEST_SECURITY_LEVEL 0x78 /* The security level used for automatic data requests. */
|
|
#define MAC_AUTO_REQUEST_KEY_ID_MODE 0x79 /* The key identifier mode used for automatic data requests */
|
|
#define MAC_AUTO_REQUEST_KEY_SOURCE 0x7A /* The originator of the key used for automatic data requests. */
|
|
#define MAC_AUTO_REQUEST_KEY_INDEX 0x7B /* The index of the key used for automatic data requests. */
|
|
#define MAC_DEFAULT_KEY_SOURCE 0x7C /* The originator of the default key used for key ID mode 0x01 */
|
|
#define MAC_PAN_COORD_EXTENDED_ADDRESS 0x7D /* The 64-bit address of the PAN coordinator. */
|
|
#define MAC_PAN_COORD_SHORT_ADDRESS 0x7E /* The 16-bit short address assigned to the PAN coordinator. */
|
|
|
|
/* Proprietary Security PIB Get and Set Attributes */
|
|
#define MAC_KEY_ID_LOOKUP_ENTRY 0xD0 /* The key lookup table entry, part of an entry of the key table */
|
|
#define MAC_KEY_DEVICE_ENTRY 0xD1 /* The key device entry, part of an entry of the key table */
|
|
#define MAC_KEY_USAGE_ENTRY 0xD2 /* The key usage entry, part of an entry of the key table */
|
|
#define MAC_KEY_ENTRY 0xD3 /* The MAC key entry, an entry of the key table */
|
|
#define MAC_DEVICE_ENTRY 0xD4 /* The MAC device entry, an entry of the device table */
|
|
#define MAC_SECURITY_LEVEL_ENTRY 0xD5 /* The AMC security level entry, an entry of the security level table */
|
|
|
|
/* Proprietary PIB Get and Set Attributes */
|
|
#define MAC_PHY_TRANSMIT_POWER 0xE0 /* The transmit power in units of -1 dBm */
|
|
#define MAC_LOGICAL_CHANNEL 0xE1 /* The logical channel */
|
|
#define MAC_EXTENDED_ADDRESS 0xE2 /* The extended address of the device */
|
|
#define MAC_ALT_BE 0xE3 /* alternate minimum backoff exponent */
|
|
#define MAC_DEVICE_BEACON_ORDER 0xE4 /* Device beacon order */
|
|
#define MAC_PHY_TRANSMIT_POWER_SIGNED 0xE5 /* Duplicate transmit power attribute in signed
|
|
(2's complement) dBm unit */
|
|
|
|
/* Disassociate Reason */
|
|
#define MAC_DISASSOC_COORD 1 /* The coordinator wishes the device to disassociate */
|
|
#define MAC_DISASSOC_DEVICE 2 /* The device itself wishes to disassociate */
|
|
|
|
|
|
/* Scan Type */
|
|
#define MAC_SCAN_ED 0 /* Energy detect scan. The device will tune to each channel and
|
|
perform and energy measurement. The list of channels and their
|
|
associated measurements will be returned at the end of the scan */
|
|
#define MAC_SCAN_ACTIVE 1 /* Active scan. The device tunes to each channel, sends a beacon
|
|
request and listens for beacons. The PAN descriptors are returned
|
|
at the end of the scan */
|
|
#define MAC_SCAN_PASSIVE 2 /* Passive scan. The device tunes to each channel and listens for
|
|
beacons. The PAN descriptors are returned at the end of the scan */
|
|
#define MAC_SCAN_ORPHAN 3 /* Orphan scan. The device tunes to each channel and sends an orphan
|
|
notification to try and find its coordinator. The status is returned
|
|
at the end of the scan */
|
|
|
|
/* Special address values */
|
|
#define MAC_ADDR_USE_EXT 0xFFFE /* Short address value indicating extended address is used */
|
|
#define MAC_SHORT_ADDR_BROADCAST 0xFFFF /* Broadcast short address */
|
|
#define MAC_SHORT_ADDR_NONE 0xFFFF /* Short address when there is no short address */
|
|
|
|
/* Comm status indication reasons */
|
|
#define MAC_COMM_ASSOCIATE_RSP 0 /* Event sent in response to MAC_AssociateRsp() */
|
|
#define MAC_COMM_ORPHAN_RSP 1 /* Event sent in response to MAC_OrphanRsp() */
|
|
#define MAC_COMM_RX_SECURE 2 /* Event sent as a result of receiving a secure frame */
|
|
|
|
/* Power Mode */
|
|
#define MAC_PWR_ON 0 /* MAC and radio hardware is powered on */
|
|
#define MAC_PWR_SLEEP_LITE 1 /* MAC and radio hardware are partially powered off */
|
|
#define MAC_PWR_SLEEP_DEEP 2 /* MAC and radio hardware are fully powered off */
|
|
|
|
/* MAC Callback Events */
|
|
#define MAC_MLME_ASSOCIATE_IND 1 /* Associate indication */
|
|
#define MAC_MLME_ASSOCIATE_CNF 2 /* Associate confirm */
|
|
#define MAC_MLME_DISASSOCIATE_IND 3 /* Disassociate indication */
|
|
#define MAC_MLME_DISASSOCIATE_CNF 4 /* Disassociate confirm */
|
|
#define MAC_MLME_BEACON_NOTIFY_IND 5 /* Beacon notify indication */
|
|
#define MAC_MLME_ORPHAN_IND 6 /* Orphan indication */
|
|
#define MAC_MLME_SCAN_CNF 7 /* Scan confirm */
|
|
#define MAC_MLME_START_CNF 8 /* Start confirm */
|
|
#define MAC_MLME_SYNC_LOSS_IND 9 /* Sync loss indication */
|
|
#define MAC_MLME_POLL_CNF 10 /* Poll confirm */
|
|
#define MAC_MLME_COMM_STATUS_IND 11 /* Communication status indication */
|
|
#define MAC_MCPS_DATA_CNF 12 /* Data confirm */
|
|
#define MAC_MCPS_DATA_IND 13 /* Data indication */
|
|
#define MAC_MCPS_PURGE_CNF 14 /* Purge confirm */
|
|
#define MAC_PWR_ON_CNF 15 /* Power on confirm */
|
|
#define MAC_MLME_POLL_IND 16 /* Poll indication */
|
|
|
|
/* The length of the random seed is currently set to 16 bytes to match
|
|
the security key length of Z-Stack */
|
|
#define MAC_RANDOM_SEED_LEN 16
|
|
|
|
/* ------------------------------------------------------------------------------------------------
|
|
* Macros
|
|
* ------------------------------------------------------------------------------------------------
|
|
*/
|
|
|
|
/* Returns the number of short addresses in the pending address specification */
|
|
#define MAC_PEND_NUM_SHORT(pendAddrSpec) ((pendAddrSpec) & 0x07)
|
|
|
|
/* Returns the number of extended addresses in the pending address specification */
|
|
#define MAC_PEND_NUM_EXT(pendAddrSpec) (((pendAddrSpec) & 0x70) >> 4)
|
|
|
|
/* Returns the length in bytes of the pending address fields in the beacon */
|
|
#define MAC_PEND_FIELDS_LEN(pendAddrSpec) ((MAC_PEND_NUM_SHORT(pendAddrSpec) * 2) + \
|
|
(MAC_PEND_NUM_EXT(pendAddrSpec) * 8))
|
|
|
|
/* The following macros are provided to help parse the superframe specification */
|
|
#define MAC_SFS_BEACON_ORDER(s) ((s) & 0x0F) /* returns the beacon order */
|
|
#define MAC_SFS_SUPERFRAME_ORDER(s) (((s) >> 4) & 0x0F) /* returns the beacon order */
|
|
#define MAC_SFS_FINAL_CAP_SLOT(s) (((s) >> 8) & 0x0F) /* returns the final CAP slot */
|
|
#define MAC_SFS_BLE(s) (((s) >> 12) & 0x01) /* returns the battery life extension bit */
|
|
#define MAC_SFS_PAN_COORDINATOR(s) (((s) >> 14) & 0x01) /* returns the PAN coordinator bit */
|
|
#define MAC_SFS_ASSOCIATION_PERMIT(s) ((s) >> 15) /* returns the association permit bit */
|
|
|
|
/* ------------------------------------------------------------------------------------------------
|
|
* Typedefs
|
|
* ------------------------------------------------------------------------------------------------
|
|
*/
|
|
|
|
/* MAC event header type */
|
|
typedef struct
|
|
{
|
|
uint8 event; /* MAC event */
|
|
uint8 status; /* MAC status */
|
|
} macEventHdr_t;
|
|
|
|
/* Common security type */
|
|
typedef struct
|
|
{
|
|
uint8 keySource[MAC_KEY_SOURCE_MAX_LEN]; /* Key source */
|
|
uint8 securityLevel; /* Security level */
|
|
uint8 keyIdMode; /* Key identifier mode */
|
|
uint8 keyIndex; /* Key index */
|
|
} macSec_t;
|
|
|
|
/* Key ID Lookup Descriptor */
|
|
typedef struct
|
|
{
|
|
uint8 lookupData[MAC_MAX_KEY_LOOKUP_LEN]; /* Data used to identify the key */
|
|
uint8 lookupDataSize; /* 0x00 indicates 5 octets; 0x01 indicates 9 octets. */
|
|
} keyIdLookupDescriptor_t;
|
|
|
|
/* Key Device Descriptor */
|
|
typedef struct
|
|
{
|
|
uint8 deviceDescriptorHandle; /* Handle to the DeviceDescriptor */
|
|
bool uniqueDevice; /* Is it a link key or a group key? */
|
|
bool blackListed; /* This key exhausted the frame counter. */
|
|
} keyDeviceDescriptor_t;
|
|
|
|
/* Key Usage Descriptor */
|
|
typedef struct
|
|
{
|
|
uint8 frameType; /* Frame Type */
|
|
uint8 cmdFrameId; /* Command Frame Identifier */
|
|
} keyUsageDescriptor_t;
|
|
|
|
/* Key Descriptor */
|
|
typedef struct
|
|
{
|
|
keyIdLookupDescriptor_t *keyIdLookupList; /* A list identifying this KeyDescriptor */
|
|
uint8 keyIdLookupEntries; /* The number of entries in KeyIdLookupList */
|
|
|
|
keyDeviceDescriptor_t *keyDeviceList; /* A list indicating which devices are
|
|
currently using this key, including
|
|
their blacklist status. */
|
|
uint8 keyDeviceListEntries; /* The number of entries in KeyDeviceList */
|
|
|
|
keyUsageDescriptor_t *keyUsageList; /* A list indicating which frame types
|
|
* this key may be used with. */
|
|
uint8 keyUsageListEntries; /* The number of entries in KeyUsageList */
|
|
|
|
uint8 key[MAC_KEY_MAX_LEN]; /* The actual value of the key */
|
|
} keyDescriptor_t;
|
|
|
|
/* Device Descriptor */
|
|
typedef struct
|
|
{
|
|
uint16 panID; /* The 16-bit PAN identifier of the device */
|
|
uint16 shortAddress; /* The 16-bit short address of the device */
|
|
sAddrExt_t extAddress; /* The 64-bit IEEE extended address of the
|
|
device. This element is also used in
|
|
unsecuring operations on incoming frames. */
|
|
uint32 frameCounter; /* The incoming frame counter of the device.
|
|
This value is used to ensure sequential
|
|
freshness of frames. */
|
|
bool exempt; /* Device may override the minimum security
|
|
level settings. */
|
|
} deviceDescriptor_t;
|
|
|
|
/* Security Level Descriptor */
|
|
typedef struct
|
|
{
|
|
uint8 frameType; /* Frame Type */
|
|
uint8 commandFrameIdentifier; /* Command Frame ID */
|
|
uint8 securityMinimum; /* The minimal required/expected security
|
|
level for incoming MAC frames. */
|
|
bool securityOverrideSecurityMinimum;
|
|
/* Indication of whether originating devices
|
|
for which the Exempt flag is set may
|
|
override the minimum security level
|
|
indicated by the SecurityMinimum
|
|
element. If TRUE, this indicates that for
|
|
originating devices with Exempt status,
|
|
the incoming security level zero is
|
|
acceptable. */
|
|
} securityLevelDescriptor_t;
|
|
|
|
/* For internal use only */
|
|
typedef struct
|
|
{
|
|
uint32 timestamp;
|
|
uint16 timestamp2;
|
|
uint16 timeToLive;
|
|
uint8 frameType;
|
|
uint8 txOptions;
|
|
uint8 txMode;
|
|
uint8 txSched;
|
|
uint8 retries;
|
|
uint8 channel;
|
|
uint8 power;
|
|
uint8 mpduLinkQuality;
|
|
uint8 correlation;
|
|
int8 rssi;
|
|
} macTxIntData_t;
|
|
|
|
/* For internal use only */
|
|
typedef struct
|
|
{
|
|
uint8 frameType;
|
|
uint8 flags;
|
|
} macRxIntData_t;
|
|
|
|
/* Data request parameters type */
|
|
typedef struct
|
|
{
|
|
sAddr_t dstAddr; /* The address of the destination device */
|
|
uint16 dstPanId; /* The PAN ID of the destination device */
|
|
uint8 srcAddrMode; /* The source address mode */
|
|
uint8 msduHandle; /* Application-defined handle value associated with this data request */
|
|
uint8 txOptions; /* TX options bit mask */
|
|
uint8 channel; /* Transmit the data frame on this channel */
|
|
uint8 power; /* Transmit the data frame at this power level */
|
|
} macDataReq_t;
|
|
|
|
/* MCPS data request type */
|
|
typedef struct
|
|
{
|
|
macEventHdr_t hdr; /* Internal use only */
|
|
sData_t msdu; /* Data pointer and length */
|
|
macTxIntData_t internal; /* Internal use only */
|
|
macSec_t sec; /* Security parameters */
|
|
macDataReq_t mac; /* Data request parameters */
|
|
} macMcpsDataReq_t;
|
|
|
|
/* Data indication parameters type */
|
|
typedef struct
|
|
{
|
|
sAddr_t srcAddr; /* The address of the sending device */
|
|
sAddr_t dstAddr; /* The address of the destination device */
|
|
uint32 timestamp; /* The time, in backoffs, at which the data were received */
|
|
uint16 timestamp2; /* The time, in internal MAC timer units, at which the
|
|
data were received */
|
|
uint16 srcPanId; /* The PAN ID of the sending device */
|
|
uint16 dstPanId; /* The PAN ID of the destination device */
|
|
uint8 mpduLinkQuality; /* The link quality of the received data frame */
|
|
uint8 correlation; /* The raw correlation value of the received data frame */
|
|
int8 rssi; /* The received RF power in units dBm */
|
|
uint8 dsn; /* The data sequence number of the received frame */
|
|
} macDataInd_t;
|
|
|
|
|
|
/* MCPS data indication type */
|
|
typedef struct
|
|
{
|
|
macEventHdr_t hdr; /* Internal use only */
|
|
sData_t msdu; /* Data pointer and length */
|
|
macRxIntData_t internal; /* Internal use only */
|
|
macSec_t sec; /* Security parameters */
|
|
macDataInd_t mac; /* Data indication parameters */
|
|
} macMcpsDataInd_t;
|
|
|
|
/* MCPS data confirm type */
|
|
typedef struct
|
|
{
|
|
macEventHdr_t hdr; /* Contains the status of the data request operation */
|
|
uint8 msduHandle; /* Application-defined handle value associated with the data request */
|
|
macMcpsDataReq_t *pDataReq; /* Pointer to the data request buffer for this data confirm */
|
|
uint32 timestamp; /* The time, in backoffs, at which the frame was transmitted */
|
|
uint16 timestamp2; /* The time, in internal MAC timer units, at which the
|
|
frame was transmitted */
|
|
uint8 retries; /* The number of retries required to transmit the data frame */
|
|
uint8 mpduLinkQuality; /* The link quality of the received ack frame */
|
|
uint8 correlation; /* The raw correlation value of the received ack frame */
|
|
int8 rssi; /* The RF power of the received ack frame in units dBm */
|
|
} macMcpsDataCnf_t;
|
|
|
|
|
|
/* MCPS purge confirm type */
|
|
typedef struct
|
|
{
|
|
macEventHdr_t hdr; /* Contains the status of the purge request operation */
|
|
uint8 msduHandle; /* Application-defined handle value associated with the data request */
|
|
} macMcpsPurgeCnf_t;
|
|
|
|
/* PAN descriptor type */
|
|
typedef struct
|
|
{
|
|
sAddr_t coordAddress; /* The address of the coordinator sending the beacon */
|
|
uint16 coordPanId; /* The PAN ID of the network */
|
|
uint16 superframeSpec; /* The superframe specification of the network */
|
|
uint8 logicalChannel; /* The logical channel of the network */
|
|
uint8 channelPage; /* The current channel page occupied by the network */
|
|
bool gtsPermit; /* TRUE if coordinator accepts GTS requests */
|
|
uint8 linkQuality; /* The link quality of the received beacon */
|
|
uint32 timestamp; /* The time at which the beacon was received, in backoffs */
|
|
bool securityFailure; /* Set to TRUE if there was an error in the security processing */
|
|
macSec_t sec; /* The security parameters for the received beacon frame */
|
|
} macPanDesc_t;
|
|
|
|
/* MLME associate request type */
|
|
typedef struct
|
|
{
|
|
uint8 logicalChannel; /* The channel on which to attempt association */
|
|
uint8 channelPage; /* The channel page on which to attempt association */
|
|
sAddr_t coordAddress; /* Address of the coordinator with which to associate */
|
|
uint16 coordPanId; /* The identifier of the PAN with which to associate */
|
|
uint8 capabilityInformation; /* The operational capabilities of this device */
|
|
macSec_t sec; /* The security parameters for this message */
|
|
} macMlmeAssociateReq_t;
|
|
|
|
/* MLME associate response type */
|
|
typedef struct
|
|
{
|
|
sAddrExt_t deviceAddress; /* The address of the device requesting association */
|
|
uint16 assocShortAddress; /* The short address allocated to the device */
|
|
uint8 status; /* The status of the association attempt */
|
|
macSec_t sec; /* The security parameters for this message */
|
|
} macMlmeAssociateRsp_t;
|
|
|
|
/* MLME disassociate request type */
|
|
typedef struct
|
|
{
|
|
sAddr_t deviceAddress; /* The address of the device with which to disassociate */
|
|
uint16 devicePanId; /* The PAN ID of the device */
|
|
uint8 disassociateReason; /* The disassociate reason */
|
|
bool txIndirect; /* Transmit Indirect */
|
|
macSec_t sec; /* The security parameters for this message */
|
|
} macMlmeDisassociateReq_t;
|
|
|
|
|
|
/* MLME orphan response type */
|
|
typedef struct
|
|
{
|
|
sAddrExt_t orphanAddress; /* The extended address of the device sending the orphan notification */
|
|
uint16 shortAddress; /* The short address of the orphaned device */
|
|
bool associatedMember; /* Set to TRUE if the orphaned device is associated with this coordinator */
|
|
macSec_t sec; /* The security parameters for this message */
|
|
} macMlmeOrphanRsp_t;
|
|
|
|
/* MLME poll request type */
|
|
typedef struct
|
|
{
|
|
sAddr_t coordAddress; /* The address of the coordinator device to poll */
|
|
uint16 coordPanId; /* The PAN ID of the coordinator */
|
|
macSec_t sec; /* The security parameters for this message */
|
|
} macMlmePollReq_t;
|
|
|
|
/* MLME scan request type */
|
|
typedef struct
|
|
{
|
|
uint32 scanChannels; /* Bit mask indicating which channels to scan */
|
|
uint8 scanType; /* The type of scan */
|
|
uint8 scanDuration; /* The exponent used in the scan duration calculation */
|
|
uint8 channelPage; /* The channel page on which to perform the scan */
|
|
uint8 maxResults; /* The maximum number of PAN descriptor results */
|
|
macSec_t sec; /* The security parameters for orphan scan */
|
|
union {
|
|
uint8 *pEnergyDetect; /* Pointer to a buffer to store energy detect measurements */
|
|
macPanDesc_t *pPanDescriptor; /* Pointer to a buffer to store PAN descriptors */
|
|
} result;
|
|
} macMlmeScanReq_t;
|
|
|
|
/* MLME start request type */
|
|
typedef struct
|
|
{
|
|
uint32 startTime; /* The time to begin transmitting beacons relative to the received beacon */
|
|
uint16 panId; /* The PAN ID to use. This parameter is ignored if panCoordinator is FALSE */
|
|
uint8 logicalChannel; /* The logical channel to use. This parameter is ignored if panCoordinator is FALSE */
|
|
uint8 channelPage; /* The channel page to use. This parameter is ignored if panCoordinator is FALSE */
|
|
uint8 beaconOrder; /* The exponent used to calculate the beacon interval */
|
|
uint8 superframeOrder; /* The exponent used to calculate the superframe duration */
|
|
bool panCoordinator; /* Set to TRUE to start a network as PAN coordinator */
|
|
bool batteryLifeExt; /* If this value is TRUE, the receiver is disabled after MAC_BATT_LIFE_EXT_PERIODS
|
|
full backoff periods following the interframe spacing period of the beacon frame */
|
|
bool coordRealignment; /* Set to TRUE to transmit a coordinator realignment prior to changing
|
|
the superframe configuration */
|
|
macSec_t realignSec; /* Security parameters for the coordinator realignment frame */
|
|
macSec_t beaconSec; /* Security parameters for the beacon frame */
|
|
} macMlmeStartReq_t;
|
|
|
|
/* MAC_MlmeSyncReq type */
|
|
typedef struct
|
|
{
|
|
uint8 logicalChannel; /* The logical channel to use */
|
|
uint8 channelPage; /* The channel page to use */
|
|
bool trackBeacon; /* Set to TRUE to continue tracking beacons after synchronizing with the
|
|
first beacon. Set to FALSE to only synchronize with the first beacon */
|
|
} macMlmeSyncReq_t;
|
|
|
|
/* MAC_MLME_ASSOCIATE_IND type */
|
|
typedef struct
|
|
{
|
|
macEventHdr_t hdr; /* The event header */
|
|
sAddrExt_t deviceAddress; /* The address of the device requesting association */
|
|
uint8 capabilityInformation; /* The operational capabilities of the device requesting association */
|
|
macSec_t sec; /* The security parameters for this message */
|
|
} macMlmeAssociateInd_t;
|
|
|
|
/* MAC_MLME_ASSOCIATE_CNF type */
|
|
typedef struct
|
|
{
|
|
macEventHdr_t hdr; /* Event header contains the status of the associate attempt */
|
|
uint16 assocShortAddress; /* If successful, the short address allocated to this device */
|
|
macSec_t sec; /* The security parameters for this message */
|
|
} macMlmeAssociateCnf_t;
|
|
|
|
/* MAC_MLME_DISASSOCIATE_IND type */
|
|
typedef struct
|
|
{
|
|
macEventHdr_t hdr; /* The event header */
|
|
sAddrExt_t deviceAddress; /* The address of the device sending the disassociate command */
|
|
uint8 disassociateReason; /* The disassociate reason */
|
|
macSec_t sec; /* The security parameters for this message */
|
|
} macMlmeDisassociateInd_t;
|
|
|
|
/* MAC_MLME_DISASSOCIATE_CNF type */
|
|
typedef struct
|
|
{
|
|
macEventHdr_t hdr; /* Event header contains the status of the disassociate attempt */
|
|
sAddr_t deviceAddress; /* The address of the device that has either requested disassociation
|
|
or been instructed to disassociate by its coordinator */
|
|
uint16 panId; /* The pan ID of the device that has either requested disassociation
|
|
or been instructed to disassociate by its coordinator */
|
|
} macMlmeDisassociateCnf_t;
|
|
|
|
/* MAC_MLME_BEACON_NOTIFY_IND type */
|
|
typedef struct
|
|
{
|
|
macEventHdr_t hdr; /* The event header */
|
|
uint8 bsn; /* The beacon sequence number */
|
|
macPanDesc_t *pPanDesc; /* The PAN descriptor for the received beacon */
|
|
uint8 pendAddrSpec; /* The beacon pending address specification */
|
|
uint8 *pAddrList; /* The list of device addresses for which the sender of the beacon has data */
|
|
uint8 sduLength; /* The number of bytes in the beacon payload of the beacon frame */
|
|
uint8 *pSdu; /* The beacon payload */
|
|
} macMlmeBeaconNotifyInd_t;
|
|
|
|
/* MAC_MLME_ORPHAN_IND type */
|
|
typedef struct
|
|
{
|
|
macEventHdr_t hdr; /* The event header */
|
|
sAddrExt_t orphanAddress; /* The address of the orphaned device */
|
|
macSec_t sec; /* The security parameters for this message */
|
|
} macMlmeOrphanInd_t;
|
|
|
|
/* MAC_MLME_SCAN_CNF type */
|
|
typedef struct
|
|
{
|
|
macEventHdr_t hdr; /* Event header contains the status of the scan request */
|
|
uint8 scanType; /* The type of scan requested */
|
|
uint8 channelPage; /* The channel page of the scan */
|
|
uint32 unscannedChannels; /* Bit mask of channels that were not scanned */
|
|
uint8 resultListSize; /* The number of PAN descriptors returned in the results list */
|
|
union
|
|
{
|
|
uint8 *pEnergyDetect; /* The list of energy measurements, one for each channel scanned */
|
|
macPanDesc_t *pPanDescriptor; /* The list of PAN descriptors, one for each beacon found */
|
|
} result;
|
|
} macMlmeScanCnf_t;
|
|
|
|
/* MAC_MLME_START_CNF type */
|
|
typedef struct
|
|
{
|
|
macEventHdr_t hdr; /* Event header contains the status of the start request */
|
|
} macMlmeStartCnf_t;
|
|
|
|
/* MAC_MLME_SYNC_LOSS_IND type */
|
|
typedef struct
|
|
{
|
|
macEventHdr_t hdr; /* Event header contains the reason that synchronization was lost */
|
|
uint16 panId; /* The PAN ID of the realignment */
|
|
uint8 logicalChannel; /* The logical channel of the realignment */
|
|
uint8 channelPage; /* The channel page of the realignment */
|
|
macSec_t sec; /* The security parameters for this message */
|
|
} macMlmeSyncLossInd_t;
|
|
|
|
/* MAC_MLME_POLL_CNF type */
|
|
typedef struct
|
|
{
|
|
macEventHdr_t hdr; /* Event header contains the status of the poll request */
|
|
} macMlmePollCnf_t;
|
|
|
|
/* MAC_MLME_COMM_STATUS_IND type */
|
|
typedef struct
|
|
{
|
|
macEventHdr_t hdr; /* Event header contains the status for this event */
|
|
sAddr_t srcAddr; /* The source address associated with the event */
|
|
sAddr_t dstAddr; /* The destination address associated with the event */
|
|
uint16 panId; /* The PAN ID associated with the event */
|
|
uint8 reason; /* The reason the event was generated */
|
|
macSec_t sec; /* The security parameters for this message */
|
|
} macMlmeCommStatusInd_t;
|
|
|
|
/* MAC_MLME_POLL_IND type */
|
|
typedef struct
|
|
{
|
|
macEventHdr_t hdr;
|
|
uint16 srcShortAddr; /* Short address of the device sending the data request */
|
|
uint16 srcPanId; /* Pan ID of the device sending the data request */
|
|
} macMlmePollInd_t;
|
|
|
|
/* Union of callback structures */
|
|
typedef union
|
|
{
|
|
macEventHdr_t hdr;
|
|
macMlmeAssociateInd_t associateInd; /* MAC_MLME_ASSOCIATE_IND */
|
|
macMlmeAssociateCnf_t associateCnf; /* MAC_MLME_ASSOCIATE_CNF */
|
|
macMlmeDisassociateInd_t disassociateInd; /* MAC_MLME_DISASSOCIATE_IND */
|
|
macMlmeDisassociateCnf_t disassociateCnf; /* MAC_MLME_DISASSOCIATE_CNF */
|
|
macMlmeBeaconNotifyInd_t beaconNotifyInd; /* MAC_MLME_BEACON_NOTIFY_IND */
|
|
macMlmeOrphanInd_t orphanInd; /* MAC_MLME_ORPHAN_IND */
|
|
macMlmeScanCnf_t scanCnf; /* MAC_MLME_SCAN_CNF */
|
|
macMlmeStartCnf_t startCnf; /* MAC_MLME_START_CNF */
|
|
macMlmeSyncLossInd_t syncLossInd; /* MAC_MLME_SYNC_LOSS_IND */
|
|
macMlmePollCnf_t pollCnf; /* MAC_MLME_POLL_CNF */
|
|
macMlmeCommStatusInd_t commStatusInd; /* MAC_MLME_COMM_STATUS_IND */
|
|
macMlmePollInd_t pollInd; /* MAC_MLME_POLL_IND */
|
|
macMcpsDataCnf_t dataCnf; /* MAC_MCPS_DATA_CNF */
|
|
macMcpsDataInd_t dataInd; /* MAC_MCPS_DATA_IND */
|
|
macMcpsPurgeCnf_t purgeCnf; /* MAC_MCPS_PURGE_CNF */
|
|
} macCbackEvent_t;
|
|
|
|
/* Configurable parameters */
|
|
typedef struct
|
|
{
|
|
uint8 txDataMax; /* maximum number of data frames in transmit queue */
|
|
uint8 txMax; /* maximum number of frames of all types in transmit queue */
|
|
uint8 rxMax; /* maximum number of command and data frames in receive queue */
|
|
uint8 dataIndOffset; /* allocate additional bytes in the data indication for
|
|
application-defined headers */
|
|
bool appPendingQueue; /* determine whether MAC_MLME_POLL_IND will be sent to the application or not
|
|
when data request is received and no pending frame is found in the MAC */
|
|
} macCfg_t;
|
|
|
|
|
|
/* ------------------------------------------------------------------------------------------------
|
|
* Internal Functions
|
|
* ------------------------------------------------------------------------------------------------
|
|
*/
|
|
|
|
/* These functions are used when creating the OSAL MAC task. They must not be used for any
|
|
* other purpose.
|
|
*/
|
|
extern void macTaskInit(uint8 taskId);
|
|
extern uint16 macEventLoop(uint8 taskId, uint16 events);
|
|
|
|
|
|
/* ------------------------------------------------------------------------------------------------
|
|
* Functions
|
|
* ------------------------------------------------------------------------------------------------
|
|
*/
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_Init
|
|
*
|
|
* @brief This function initializes the MAC subsystem. It must be called once when the
|
|
* software system is started and before any other function in the MAC API
|
|
* is called.
|
|
*
|
|
* input parameters
|
|
*
|
|
* None.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return None.
|
|
**************************************************************************************************
|
|
*/
|
|
extern void MAC_Init(void);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_InitDevice
|
|
*
|
|
* @brief This function initializes the MAC to associate with a non
|
|
* beacon-enabled network. This function would be used to
|
|
* initialize a device as an RFD. If this function is used it
|
|
* must be called during application initialization before any
|
|
* other function in the data or management API is called.
|
|
*
|
|
* input parameters
|
|
*
|
|
* None.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return None.
|
|
**************************************************************************************************
|
|
*/
|
|
extern void MAC_InitDevice(void);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_InitCoord
|
|
*
|
|
* @brief This function initializes the MAC for operation as a
|
|
* coordinator. A coordinator can start a network, accept
|
|
* associate requests from other devices, send beacons, send
|
|
* indirect data, and other operations. This function would
|
|
* be used to initialize a device as an FFD. If this function
|
|
* is used it must be called during application initialization
|
|
* before any other function in the data or management API
|
|
* is called.
|
|
*
|
|
* input parameters
|
|
*
|
|
* None.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return None.
|
|
**************************************************************************************************
|
|
*/
|
|
extern void MAC_InitCoord(void);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_InitSecurity
|
|
*
|
|
* @brief This function initializes the MAC to allow use of security.
|
|
* If this function is used it must be called during application
|
|
* initialization before any other function in the data or
|
|
* management API is called.
|
|
*
|
|
* input parameters
|
|
*
|
|
* None.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return None.
|
|
**************************************************************************************************
|
|
*/
|
|
extern void MAC_InitSecurity(void);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_InitBeaconCoord
|
|
*
|
|
* @brief This function initializes the MAC for operation as a coordinator in a
|
|
* beacon-enabled network. If this function is used it must
|
|
* be called during application initialization before any other
|
|
* function in the data or management API is called.
|
|
*
|
|
* input parameters
|
|
*
|
|
* None.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return None.
|
|
**************************************************************************************************
|
|
*/
|
|
extern void MAC_InitBeaconCoord(void);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_InitBeaconTrack
|
|
*
|
|
* @brief This function initializes the MAC to allow it to associate
|
|
* with and track a beacon-enabled network. If this function is
|
|
* used it must be called during application initialization
|
|
* before any other function in the data or management API
|
|
* is called.
|
|
*
|
|
* input parameters
|
|
*
|
|
* None.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return None.
|
|
**************************************************************************************************
|
|
*/
|
|
extern void MAC_InitBeaconDevice(void);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_McpsDataReq
|
|
*
|
|
* @brief This function sends application data to the MAC for
|
|
* transmission in a MAC data frame.
|
|
*
|
|
* input parameters
|
|
*
|
|
* @param pData - Pointer to parameters structure.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return None.
|
|
**************************************************************************************************
|
|
*/
|
|
extern void MAC_McpsDataReq(macMcpsDataReq_t *pData);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_McpsPurgeReq
|
|
*
|
|
* @brief This function purges and discards a data request from the
|
|
* MAC data queue. When the operation is complete the MAC sends
|
|
* a MAC_MCPS_PURGE_CNF.
|
|
*
|
|
* input parameters
|
|
*
|
|
* @param msduHandle - The application-defined handle value
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return None.
|
|
**************************************************************************************************
|
|
*/
|
|
extern void MAC_McpsPurgeReq(uint8 msduHandle);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_McpsDataAlloc
|
|
*
|
|
* @brief This direct-execute function simplifies the allocation and
|
|
* preparation of the data buffer MAC_McpsDataReq(). The
|
|
* function allocates a buffer and prepares the data pointer.
|
|
*
|
|
* input parameters
|
|
*
|
|
* @param len - Length of application data in bytes.
|
|
* @param securityLevel - Security level used for this frame.
|
|
* @param keyIdMode - Key ID mode used for this frame.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return Returns a pointer to the allocated buffer. If the function
|
|
* fails for any reason it returns NULL.
|
|
**************************************************************************************************
|
|
*/
|
|
extern macMcpsDataReq_t *MAC_McpsDataAlloc(uint8 len, uint8 securityLevel, uint8 keyIdMode);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_MlmeAssociateReq
|
|
*
|
|
* @brief This function sends an associate request to a coordinator
|
|
* device. The application shall attempt to associate only with
|
|
* a PAN that is currently allowing association, as indicated
|
|
* in the results of the scanning procedure. In a beacon-enabled
|
|
* PAN the beacon order and superframe order must be set by using
|
|
* MAC_MlmeSetReq() before making the call to MAC_MlmeAssociateReq().
|
|
* If not, the associate request frame is likely to be transmitted
|
|
* outside the superframe. When the associate request is complete
|
|
* the MAC sends a MAC_MLME_ASSOCIATE_CNF to the application.
|
|
*
|
|
* input parameters
|
|
*
|
|
* @param pData - Pointer to parameters structure.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return None.
|
|
**************************************************************************************************
|
|
*/
|
|
extern void MAC_MlmeAssociateReq(macMlmeAssociateReq_t *pData);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_MlmeAssociateRsp
|
|
*
|
|
* @brief This function sends an associate response to a device
|
|
* requesting to associate. This function must be called after
|
|
* receiving a MAC_MLME_ASSOCIATE_IND. When the associate response is
|
|
* complete the MAC sends a MAC_MLME_COMM_STATUS_IND to the application
|
|
* to indicate the success or failure of the operation.
|
|
*
|
|
* input parameters
|
|
*
|
|
* @param pData - Pointer to parameters structure.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return MAC_SUCCESS or MAC error code.
|
|
**************************************************************************************************
|
|
*/
|
|
extern uint8 MAC_MlmeAssociateRsp(macMlmeAssociateRsp_t *pData);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_MlmeDisassociateReq
|
|
*
|
|
* @brief This function is used by an associated device to notify the
|
|
* coordinator of its intent to leave the PAN. It is also used
|
|
* by the coordinator to instruct an associated device to leave
|
|
* the PAN. When the disassociate is complete the MAC sends a
|
|
* MAC_MLME_DISASSOCIATE_CNF to the application.
|
|
*
|
|
* input parameters
|
|
*
|
|
* @param pData - Pointer to parameters structure.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return None.
|
|
**************************************************************************************************
|
|
*/
|
|
extern void MAC_MlmeDisassociateReq(macMlmeDisassociateReq_t *pData);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_MlmeGetReq
|
|
*
|
|
* @brief This direct execute function retrieves an attribute value
|
|
* from the MAC PIB.
|
|
*
|
|
* input parameters
|
|
*
|
|
* @param pibAttribute - The attribute identifier.
|
|
* @param pValue - pointer to the attribute value.
|
|
*
|
|
* output parameters
|
|
*
|
|
* @param pValue - pointer to the attribute value.
|
|
*
|
|
* @return The status of the request, as follows:
|
|
* MAC_SUCCESS Operation successful.
|
|
* MAC_UNSUPPORTED_ATTRIBUTE Attribute not found.
|
|
*
|
|
**************************************************************************************************
|
|
*/
|
|
extern uint8 MAC_MlmeGetReq(uint8 pibAttribute, void *pValue);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_MlmeGetSecutityReq
|
|
*
|
|
* @brief This direct execute function retrieves an attribute value
|
|
* from the MAC Secutity PIB. This function only exists when MAC_SECURITY
|
|
* is defined.
|
|
*
|
|
* input parameters
|
|
*
|
|
* @param pibAttribute - The attribute identifier.
|
|
* @param pValue - pointer to the attribute value.
|
|
*
|
|
* output parameters
|
|
*
|
|
* @param pValue - pointer to the attribute value.
|
|
*
|
|
* @return The status of the request, as follows:
|
|
* MAC_SUCCESS Operation successful.
|
|
* MAC_UNSUPPORTED_ATTRIBUTE Attribute not found.
|
|
*
|
|
**************************************************************************************************
|
|
*/
|
|
extern uint8 MAC_MlmeGetSecurityReq(uint8 pibAttribute, void *pValue);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_MlmeOrphanRsp
|
|
*
|
|
* @brief This function is called in response to an orphan notification
|
|
* from a peer device. This function must be called after
|
|
* receiving a MAC_MLME_ORPHAN_IND. When the orphan response is
|
|
* complete the MAC sends a MAC_MLME_COMM_STATUS_IND to the
|
|
* application to indicate the success or failure of the operation.
|
|
*
|
|
* input parameters
|
|
*
|
|
* @param pData - Pointer to parameters structure.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return None.
|
|
**************************************************************************************************
|
|
*/
|
|
extern void MAC_MlmeOrphanRsp(macMlmeOrphanRsp_t *pData);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_MlmePollReq
|
|
*
|
|
* @brief This function is used to request pending data from the
|
|
* coordinator. When the poll request is complete the MAC sends
|
|
* a MAC_MLME_POLL_CNF to the application. If a data frame of
|
|
* nonzero length is received from the coordinator the MAC sends
|
|
* a MAC_MLME_POLL_CNF with status MAC_SUCCESS and then sends a
|
|
* MAC_MCPS_DATA_IND with the data.
|
|
*
|
|
* input parameters
|
|
*
|
|
* @param pData - Pointer to parameters structure.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return None.
|
|
**************************************************************************************************
|
|
*/
|
|
extern void MAC_MlmePollReq(macMlmePollReq_t *pData);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_MlmeResetReq
|
|
*
|
|
* @brief This direct execute function resets the MAC. This function
|
|
* must be called once at system startup before any other
|
|
* function in the management API is called.
|
|
*
|
|
* input parameters
|
|
*
|
|
* @param setDefaultPib - Set to TRUE to reset the MAC PIB to its
|
|
* default values.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return Returns MAC_SUCCESS always.
|
|
*
|
|
**************************************************************************************************
|
|
*/
|
|
extern uint8 MAC_MlmeResetReq(bool setDefaultPib);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_MlmeScanReq
|
|
*
|
|
* @brief This function initiates an energy detect, active, passive,
|
|
* or orphan scan on one or more channels. An energy detect
|
|
* scan measures the peak energy on each requested channel.
|
|
* An active scan sends a beacon request on each channel and
|
|
* then listening for beacons. A passive scan is a receive-only
|
|
* operation that listens for beacons on each channel. An orphan
|
|
* scan is used to locate the coordinator with which the scanning
|
|
* device had previously associated. When a scan operation is
|
|
* complete the MAC sends a MAC_MLME_SCAN_CNF to the application.
|
|
*
|
|
* input parameters
|
|
*
|
|
* @param pData - Pointer to parameters structure.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return None.
|
|
**************************************************************************************************
|
|
*/
|
|
extern void MAC_MlmeScanReq(macMlmeScanReq_t *pData);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_MlmeSetReq
|
|
*
|
|
* @brief This direct execute function sets an attribute value
|
|
* in the MAC PIB.
|
|
*
|
|
* input parameters
|
|
*
|
|
* @param pibAttribute - The attribute identifier.
|
|
* @param pValue - pointer to the attribute value.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return The status of the request, as follows:
|
|
* MAC_SUCCESS Operation successful.
|
|
* MAC_UNSUPPORTED_ATTRIBUTE Attribute not found.
|
|
*
|
|
**************************************************************************************************
|
|
*/
|
|
extern uint8 MAC_MlmeSetReq(uint8 pibAttribute, void *pValue);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_MlmeSetSecurityReq
|
|
*
|
|
* @brief This direct execute function sets an attribute value
|
|
* in the MAC Security PIB. This function only exists when MAC_SECURITY
|
|
* is defined.
|
|
*
|
|
* input parameters
|
|
*
|
|
* @param pibAttribute - The attribute identifier.
|
|
* @param pValue - pointer to the attribute value.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return The status of the request, as follows:
|
|
* MAC_SUCCESS Operation successful.
|
|
* MAC_UNSUPPORTED_ATTRIBUTE Attribute not found.
|
|
*
|
|
**************************************************************************************************
|
|
*/
|
|
extern uint8 MAC_MlmeSetSecurityReq(uint8 pibAttribute, void *pValue);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_MlmeStartReq
|
|
*
|
|
* @brief This function is called by a coordinator or PAN coordinator
|
|
* to start or reconfigure a network. Before starting a
|
|
* network the device must have set its short address. A PAN
|
|
* coordinator sets the short address by setting the attribute
|
|
* MAC_SHORT_ADDRESS. A coordinator sets the short address
|
|
* through association. When the operation is complete the
|
|
* MAC sends a MAC_MLME_START_CNF to the application.
|
|
*
|
|
* input parameters
|
|
*
|
|
* @param pData - Pointer to parameters structure.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return None.
|
|
**************************************************************************************************
|
|
*/
|
|
extern void MAC_MlmeStartReq(macMlmeStartReq_t *pData);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_MlmeSyncReq
|
|
*
|
|
* @brief This function requests the MAC to synchronize with the
|
|
* coordinator by acquiring and optionally tracking its beacons.
|
|
* Synchronizing with the coordinator is recommended before
|
|
* associating in a beacon-enabled network. If the beacon could
|
|
* not be located on its initial search or during tracking, the
|
|
* MAC sends a MAC_MLME_SYNC_LOSS_IND to the application with
|
|
* status MAC_BEACON_LOSS.
|
|
*
|
|
* input parameters
|
|
*
|
|
* @param pData - Pointer to parameters structure.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return None.
|
|
**************************************************************************************************
|
|
*/
|
|
extern void MAC_MlmeSyncReq(macMlmeSyncReq_t *pData);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_PwrOffReq
|
|
*
|
|
* @brief This direct execute function requests the MAC to power off
|
|
* the radio hardware and go to sleep. If the MAC is able to
|
|
* power off it will execute its power off procedure and return
|
|
* MAC_SUCCESS. If the MAC is unable to sleep it will return
|
|
* MAC_DENIED. The MAC is unable to sleep when it is executing
|
|
* certain procedures, such as a scan, data request, or association.
|
|
* If this function is called when the MAC is already in sleep mode
|
|
* it will return MAC_SUCCESS but do nothing.
|
|
*
|
|
* input parameters
|
|
*
|
|
* @param mode - The desired low power mode.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return The status of the request, as follows:
|
|
* MAC_SUCCESS Operation successful; the MAC is powered off.
|
|
* MAC_DENIED The MAC was not able to power off.
|
|
**************************************************************************************************
|
|
*/
|
|
extern uint8 MAC_PwrOffReq(uint8 mode);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_PwrOnReq
|
|
*
|
|
* @brief This function requests the MAC to power on the radio hardware
|
|
* and wake up. When the power on procedure is complete the MAC
|
|
* will send a MAC_PWR_ON_CNF to the application.
|
|
*
|
|
* input parameters
|
|
*
|
|
* None.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return None.
|
|
**************************************************************************************************
|
|
*/
|
|
extern void MAC_PwrOnReq(void);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_PwrMode
|
|
*
|
|
* @brief This function returns the current power mode of the MAC.
|
|
*
|
|
* input parameters
|
|
*
|
|
* None.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return The current power mode of the MAC.
|
|
**************************************************************************************************
|
|
*/
|
|
extern uint8 MAC_PwrMode(void);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_PwrNextTimeout
|
|
*
|
|
* @brief This function returns the next MAC timer expiration in 320 usec units. If no
|
|
* timer is running it returns zero.
|
|
*
|
|
* input parameters
|
|
*
|
|
* None.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return The next MAC timer expiration or zero.
|
|
**************************************************************************************************
|
|
*/
|
|
extern uint32 MAC_PwrNextTimeout(void);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_RandomByte
|
|
*
|
|
* @brief This function returns a random byte from the MAC random number generator.
|
|
*
|
|
* input parameters
|
|
*
|
|
* None.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return A random byte.
|
|
**************************************************************************************************
|
|
*/
|
|
extern uint8 MAC_RandomByte(void);
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_SrcMatchEnable
|
|
*
|
|
* @brief Enabled AUTOPEND and source address matching. if number of source
|
|
* address table entries asked for is more than the hardware
|
|
* supports. It will allocate maximum number of entries and return
|
|
* MAC_INVALID_PARAMETER. This function shall not be called from
|
|
* ISR. It is not thread safe.
|
|
*
|
|
* @param addressType - address type that the application uses
|
|
* SADDR_MODE_SHORT or SADDR_MODE_EXT
|
|
* @param num - number of source address table entries to be used
|
|
*
|
|
* @return MAC_SUCCESS or MAC_INVALID_PARAMETER
|
|
**************************************************************************************************
|
|
*/
|
|
extern uint8 MAC_SrcMatchEnable ( uint8 addrType, uint8 num );
|
|
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_SrcMatchAddEntry
|
|
*
|
|
* @brief Add a short or extended address to source address table. This
|
|
* function shall not be called from ISR. It is not thread safe.
|
|
*
|
|
* @param addr - a pointer to sAddr_t which contains addrMode
|
|
* and a union of a short 16-bit MAC address or an extended
|
|
* 64-bit MAC address to be added to the source address table.
|
|
* @param panID - the device PAN ID. It is only used when the addr is
|
|
* using short address
|
|
*
|
|
* @return MAC_SUCCESS or MAC_NO_RESOURCES (source address
|
|
* table full) or MAC_DUPLICATED_ENTRY (the entry added is duplicated),
|
|
* or MAC_INVALID_PARAMETER if the input parameters are invalid.
|
|
**************************************************************************************************
|
|
*/
|
|
extern uint8 MAC_SrcMatchAddEntry ( sAddr_t *addr, uint16 panID );
|
|
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_SrcMatchDeleteEntry
|
|
*
|
|
* @brief Delete a short or extended address from source address table.
|
|
* This function shall not be called from ISR. It is not thread safe.
|
|
*
|
|
* @param addr - a pointer to sAddr_t which contains addrMode
|
|
* and a union of a short 16-bit MAC address or an extended
|
|
* 64-bit MAC address to be deleted from the source address table.
|
|
* @param panID - the device PAN ID. It is only used when the addr is
|
|
* using short address
|
|
*
|
|
* @return MAC_SUCCESS or MAC_INVALID_PARAMETER (address to be deleted
|
|
* cannot be found in the source address table).
|
|
**************************************************************************************************
|
|
*/
|
|
extern uint8 MAC_SrcMatchDeleteEntry ( sAddr_t *addr, uint16 panID );
|
|
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_SrcMatchAckAllPending
|
|
*
|
|
* @brief Enabled/disable acknowledging all packets with pending bit set
|
|
* The application normally enables it when adding new entries to
|
|
* the source address table fails due to the table is full, or
|
|
* disables it when more entries are deleted and the table has
|
|
* empty slots.
|
|
*
|
|
* @param option - TRUE (acknowledging all packets with pending field set)
|
|
* FALSE (acknowledging all packets with pending field cleared)
|
|
*
|
|
* @return none
|
|
**************************************************************************************************
|
|
*/
|
|
extern void MAC_SrcMatchAckAllPending ( uint8 option );
|
|
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_SrcMatchCheckAllPending
|
|
*
|
|
* @brief Check if acknowledging all packets with pending bit set
|
|
* is enabled.
|
|
*
|
|
* @param none
|
|
*
|
|
* @return MAC_AUTOACK_PENDING_ALL_ON or MAC_AUTOACK_PENDING_ALL_OFF
|
|
**************************************************************************************************
|
|
*/
|
|
extern uint8 MAC_SrcMatchCheckAllPending ( void );
|
|
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_SelectRadioRegTable
|
|
*
|
|
* @brief Select radio register table in case multiple register tables are included
|
|
* in the build
|
|
*
|
|
* @param txPwrTblIdx - TX power register value table index
|
|
* @param rssiAdjIdx - RSSI adjustment value index
|
|
*
|
|
* @return none
|
|
**************************************************************************************************
|
|
*/
|
|
extern void MAC_SetRadioRegTable ( uint8 txPwrTblIdx, uint8 rssiAdjIdx );
|
|
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_CbackEvent
|
|
*
|
|
* @brief This callback function sends MAC events to the application.
|
|
* The application must implement this function. A typical
|
|
* implementation of this function would allocate an OSAL message,
|
|
* copy the event parameters to the message, and send the message
|
|
* to the application's OSAL event handler. This function may be
|
|
* executed from task or interrupt context and therefore must
|
|
* be reentrant.
|
|
*
|
|
* input parameters
|
|
*
|
|
* @param pData - Pointer to parameters structure.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return None.
|
|
**************************************************************************************************
|
|
*/
|
|
extern void MAC_CbackEvent(macCbackEvent_t *pData);
|
|
|
|
|
|
/**************************************************************************************************
|
|
* @fn MAC_CbackCheckPending
|
|
*
|
|
* @brief This callback function returns the number of pending indirect messages queued in
|
|
* the application. Most applications do not queue indirect data and can simply
|
|
* always return zero. The number of pending indirect messages only needs to be
|
|
* returned if macCfg.appPendingQueue to TRUE.
|
|
*
|
|
* input parameters
|
|
*
|
|
* None.
|
|
*
|
|
* output parameters
|
|
*
|
|
* None.
|
|
*
|
|
* @return The number of indirect messages queued in the application or zero.
|
|
**************************************************************************************************
|
|
*/
|
|
extern uint8 MAC_CbackCheckPending(void);
|
|
|
|
/**************************************************************************************************
|
|
*/
|
|
|
|
#ifdef __cplusplus
|
|
};
|
|
#endif
|
|
|
|
#endif /* MAC_API_H */
|
|
|