原创 【原创】ZigBee学习之10——MAC层API解读

其实也算不上什么解读拉，基本上是把官方的文档翻译了一下。在Zigbee中，是分层结构的，这样做有很多的好处，每一层只负责自己的东西，数据传输更加透明和有效，好了闲话不说，我们开始解读MAC层API，当然是针对Z-Stack的，呵呵

MAC API[802.15.4 MAC API _F8W-2005-1503_.pdf]<?xml:namespace prefix = o ns = "urn:schemas-microsoft-com:office:office" />

常量和结构体

typedef uint8 sAddrExt_t[8];

typedef struct

{

  union

  {

    uint16      shortAddr;

    sAddrExt_t  extAddr;

  } addr;

  uint8         addrMode;

} sAddr_t;

shortAddr       - 16位MAC 短地址

extAddr     - 64位MAC 扩展地址

addrMode        - 地址模式

    SADDR_MODE_NONE     - 地址不存在

    SADDR_MODE_SHORT    - 使用16位短地址

    SADDR_MODE_EXT  - 使用64位扩展地址  

状态值

    标准状态值

MAC_SUCCESS             操作成功

MAC_BEACON_LOSS         同步请求中丢失信标

MAC_CHANNEL_ACCESS_FAILURE 由于通道活跃，数据请求失败

MAC_COUNTER_ERROR       接收到的帧的发送源的帧计数器不可用

MAC_DENIED          MAC不能进入低功耗模式

MAC_FRAME_TOO_LONG      接收到的帧或者操作产生的帧或数据请求太长

MAC_IMPROPER_KEY_TYPE  接收到的帧的发送源的KEY不可用

MAC_IMPROPER_SECURITY_LEVEL 接收到的帧的发送源安全等级和最低等级不匹配

MAC_INVALID_ADDRESS     由于没有源地址或目的地址，数据请求失败

MAC_INVALID_HANDLE      清除请求包含不可用的处理

MAC_INVALID_PARAMETER  API函数参数超出范围

MAC_LIMIT_REACHED       由于PAN描述储存达到界限，扫描中止

MAC_NO_ACK          由于没有收到应答，操作或数据请求失败

MAC_NO_BEACON           由于没有收到信标，扫描请求失败

MAC_NO_DATA             由于没有收到关联应答，关联请求失败

MAC_NO_SHORT_ADDRESS        开始请求的短地址错误

MAC_PAN_ID_CONFLICT     检测到一个PAN ID冲突

MAC_READ_ONLY           拥有只读标记的请求

MAC_REALIGNMENT         接收到协调器重排列

MAC_SCAN_IN_PROGRESS    扫描正在进行，新的扫描请求失败

MAC_SECURITY_ERROR      接收到的安全帧密码处理失败

MAC_SUPERFRAME_OVERLAP  信标开始时间超出协调器传输时间

MAC_TRACKING_OFF        没有找到其协调器的信标，开始请求失败

MAC_TRANSACTION_EXPIRED 关联应答，解关联请求，间接数据传输失败

MAC_TRANSACTION_OVERFLOW    数据缓存溢出，操作失败 

MAC_UNAVAILABLE_KEY     安全密钥不可用

MAC_UNSUPPORTED_ATTRIBUTE   由于不支持的特性指令或请求失败

MAC_UNSUPPORTED_LEGACY  不支持的安全方式

MAC_UNSUPPORTED_SECURITY    接收到的帧的安全方式不支持

    私有状态值

MAC_UNSUPPORTED         当前配置不支持的操作

MAC_BAD_STATE           当前状态不支持的操作

MAC_NO_RESOURCES        内存资源不足

    MAC时间值

aBaseSuperframeDuration     构成超帧的符号周期           960 15.36ms(2.4G)

aUnitBackoffPeriod      构成CSMA-CA算法的时间周期的符号周期   20  320us(2.4G)

初始化接口

初始化接口函数都是直接执行函数

void MAC_Init(void)

初始化MAC子系统

void MAC_InitDevice(void)

初始化MAC关联到一个非信标网络，使用此函数初始化一个RFD设备，如果使用此函数，要在调用其它数据和管理API之前调用

void MAC_InitCoord(void)

初始化MAC能进行协调器的操作。此函数用来初始化一个FFD设备，要在调用其它数据和管理API之前调用

void MAC_InitSecurity(void)

使MAC能使用安全功能，要在调用其它数据和管理API之前调用

void MAC_InitBeaconCoord(void)

初始化MAC在信标网络中能进行协调器的操作。此函数要在调用其它数据和管理API之前调用

void MAC_InitBeaconDevice(void)

初始化MAC能关联到一个信标网络，此函数要在调用其它数据和管理API之前调用

提供一些ZigBee的配置事例，其他的网络配置请看TI的文档

ZigBee节点设备           ZigBee路由器        ZigBee协调器

MAC_InitDevice();       MAC_InitDevice();       MAC_InitCoord();

                MAC_InitCoord();

数据接口

MAC层用来发送和接收数据的API

数据结构

typedef struct 

{

  uint8     *p;

  uint8     len;

} sData_t;

p – 指向数据

len – 数据的字节长度

数据常量

MAC_MAX_FRAME_SIZE  102         不包含安全域的最大数据长度

MAC_DATA_OFFSET     24      MAC头要求的数据偏移

MAC_ENC_OFFSET 5       加密头要求的数据偏移

MAC_MIC_32_LEN 4       32位认证代码要求的长度

MAC_MIC_64_LEN  8       64位认证代码要求的长度

MAC_MIC_128_LEN     16      128位认证代码要求的长度

void MAC_McpsDataReq(macMcpsDataReq_t *pData)

将应用数据发送到MAC。若MAC拥堵或者不能接受数据请求则发送状态为MAC_TRANSACTION_OVERFLOW的MAC_MCPS_DATA_CNF，最终MAC将变得不拥堵并且为一个缓存的请求发送MAC_MCPS_DATA_CNF。所以应用能在任何时候发送数据，只是数据将被队列。

应用必须分配一定字节的缓存，数目是：MAC_DATA_OFFSET+MAC_ENC_OFFSET（如果使用加密安全）。可用使用MAC_McpsDataAlloc()来方便准确的分配这个缓存。最大的数据帧长度为MAC_MAX_FRAME_SIZE，如果使用加密安全，则还要减去MAC_ENC_OFFSET及其相关的加密代码区域：比如使用AES-MIC128，则最大的数据帧长度为：max = MAC_MAX_FRAME_SIZE - MAC_ENC_OFFSET – MAC_MIC_128_LEN;

参数：

typedef struct

{

  sAddr_t         dstAddr;

  uint16          dstPanId;

  uint8           srcAddrMode;

  uint8           mdsuHandle;

  uint8           txOptions;

  uint8           channel;

  uint8           power;

} macDataReq_t;

typedef struct

{

  macEventHdr_t   hdr;     

  sData_t         msdu;     

  macTxIntData_t  internal;

  macSec_t        sec;

  macDataReq_t    mac;     

} macMcpsDataReq_t;

hdr和internal是内部使用的，mac.mdsuHandle是应用定义的关于数据请求的句柄值，mac.txOptions为TX参数位掩码，有以下一些值，其他的都很好理解了。

MAC_TXOPTION_ACK        应答传输。如果没有收到应答将重传

MAC_TXOPTION_GTS        GTS传输(unused).

MAC_TXOPTION_INDIRECT   间接传输。MAC将队列数据等待目标设备请求此数据。只有协调器才可用这种方式

MAC_TXOPTION_NO_RETRANS 无中继传输。

MAC_TXOPTION_NO_CNF     无确认。这将阻止为此帧发送MAC_MCPS_DATA_CNF事件

MAC_TXOPTION_ALT_BE  Use PIB value MAC_ALT_BE for the minimum backoff exponent.

MAC_TXOPTION_PWR_CHAN   用macDataReq_t结构中的电源和通道值而不用PIB中的值来传输

void MAC_McpsPurgeReq(uint8 msduHandle)

从MAC数据队列中清空并丢弃数据请求，当完成操作后MAC发送MAC_MCPS_PURGE_CNF

macMcpsDataReq_t *MAC_McpsDataAlloc(uint8 len, uint8 securityLevel, uint8 keyIdMode)

如果用此函数分配了MAC_McpsDataReq()所需的数据缓存，在收到MAC_MCPS_DATA_CNF后要通过osal_msg_deallocate(pBuffer)来释放。若不使用安全则设置securityLevel和keyIdMode为MAC_SEC_LEVEL_NONE和MAC_KEY_ID_MODE_NONE

回调函数事件

这些回调函数由应用调用，用来将事件或者数据从MAC传到应用。

MAC_MCPS_DATA_IND

从MAC发送数据到应用。这个事件的参数指向一个动态分配的缓存，当应用用完数据后必须调用osal_msg_deallocate(pData)来释放缓存。MAC还能为应用定义的数据分配额外的空间，应用定义的数据的大小由MAC_MlmeSetReq()的属性MAC_DATA_IND_OFFSET设置。

参数：

typedef struct

{

  sAddr_t       srcAddr;

  sAddr_t       dstAddr;

  uint32        timestamp;

  uint16        timestamp2;

  uint16        srcPanId;

  uint16        dstPanId;

  uint8         mpduLinkQuality;

  uint8         correlation;

  uint8         rssi;

  uint8         dsn;

} macDataInd_t;

typedef struct 

{

  macEventHdr_t  hdr;

  sData_t        msdu;

  macRxIntData_t internal;

  macSec_t       sec;

  macDataInd_t   mac;

} macMcpsDataInd_t;

mac.timestamp – 接收到帧的时间，单位为aUnitBackoffPeriod

mac.timestamp2 – 接收到帧的时间，单位为内部MAC定时器单元

mac.correlation – The raw correlation value of the received data frame.  This value depends on the radio.  See the chip data sheet for details.

dsn – 接收到的帧的数据序列

MAC_MCPS_DATA_CNF

每当调用MAC_McpsDataReq()时就会向应用发送这个事件，这个事件返回数据请求的状态这个事件同样返回指向数据缓存的指针，应用能利用这个指针来释放空间。

typedef struct

{

  macEventHdr_t      hdr;

  uint8              msduHandle;

  macMcpsDataReq_t   *pDataReq;

  uint32             timestamp;

  uint16             timestamp2;

} macMcpsDataCnf_t;

hdr.status有如下的值

MAC_SUCCESS             操作成功

MAC_CHANNEL_ACCESS_FAILURE  通道繁忙，请求失败

MAC_FRAME_TOO_LONG      数据太长

MAC_INVALID_PARAMETER   参数超出范围

MAC_NO_ACK          没有收到应答

MAC_TRANSACTION_EXPIRED 传输期到没有收到响应

MAC_TRANSACTION_OVERFLOW    数据buffer溢出

MAC_MCPS_PURGE_CNF

当调用MAC_McpsPurgeReq()时向应用发送这一事件

typedef struct

{

  macEventHdr_t      hdr;

  uint8              msduHandle;

} macMcpsPurgeCnf_t;

hdr.status  - 清空请求的状态

    MAC_SUCCESS         成功

    MAC_INVALID_HANDLE      清空请求包含不可用的处理

管理接口

通用常量和数据结构

通道掩码

MAC_CHAN_11_MASK - MAC_CHAN_28_MASK 通道11到28的掩码

比如要使用通道11，12，23则：uint32 chan = MAC_CHAN_11_MASK | MAC_CHAN_12_MASK | MAC_CHAN_23_MASK;

通道

MAC_CHAN_11 - MAC_CHAN_28   通道11到28

通道页

2.4G只用通道0页MAC_CHANNEL_PAGE_0

性能信息

这些掩码指示了器件的性能信息，在关联操作中将用到这些信息

MAC_CAPABLE_PAN_COORD       器件可以作为PAN协调器

MAC_CAPABLE_FFD         器件是FFD

MAC_CAPABLE_MAINS_POWER     器件用的是主干线而不是电池

MAC_CAPABLE_RX_ON_IDLE      空闲时也打开接收

MAC_CAPABLE_SECURITY            能够发送和接收安全帧

MAC_CAPABLE_ALLOC_ADDR      在关联工程中请求分配短地址

属性

可用通过 MAC_MlmeGetReq()和MAC_MlmeSetReq()来读取和设置，实在是太都了，大家看文档把。

超帧协议

MAC_SFS_BEACON_ORDER(s)         返回信标顺序

MAC_SFS_SUPERFRAME_ORDER(s)     返回超帧顺序

MAC_SFS_FINAL_CAP_SLOT(s)       返回最后的CAP槽

MAC_SFS_BLE(s)          返回电池延寿位

MAC_SFS_PAN_COORDINATOR(s)      返回PAN协调器位

MAC_SFS_ASSOCIATION_PERMIT(s)   返回关联许可位

void MAC_MlmeAssociateReq(macMlmeAssociateReq_t *pData)

向协调器发送关联请求，当请求完成后MAC发送MAC_MLME_ASSOCIATE_CNF给应用

参数：

typedef struct 

{

  uint8         logicalChannel;

  uint8         channelPage;

  sAddr_t       coordAddress;

  uint16        coordPanId;

  uint8         capabilityInformation;

  macSec_t      sec;

} macMlmeAssociateReq_t;

void MAC_MlmeAssociateRsp(macMlmeAssociateRsp_t *pData)

给发送关联请求的设备发送应答，在接收到 MAC_MLME_ASSOCIATE_IND后应该调用此函数，当答复完成后MAC将发送MAC_MLME_COMM_STATUS_IND

typedef struct 

{

  sAddrExt_t       deviceAddress;

  uint16           assocShortAddress;

  uint8            status;

  macSec_t         sec;

} macMlmeAssociateRsp_t;

assocShortAddress 分配给器件的短地址，只有关联成功且器件请求短地址时才会设置此值

void MAC_MlmeDisassociateReq(macMlmeDisassociateReq_t *pData)

已关联的设备通知协调器脱离PAN，或者是协调器指示一个已关联设备脱离PAN，解关联完成后MAC发送 MAC_MLME_DISASSOCIATE_CNF

typedef struct 

{

  sAddr_t          deviceAddress;

  uint16           devicePanId;

  uint8            disassociateReason;

  bool             txIndirect;

  macSec_t         sec;

} macMlmeDisassociateReq_t;

uint8 MAC_MlmeGetReq(uint8 pibAttribute, void *pValue)

从MAC PIB取得属性

pibAttribute    属性项

pValue      指向属性值的指针

返回值：

MAC_SUCCESS             操作成功

MAC_UNSUPPORTED_ATTRIBUTE   没有找到对应的属性

void MAC_MlmeOrphanRsp(macMlmeOrphanRsp_t *pData)

回应节点的orphan宣告

void MAC_MlmePollReq(macMlmePollReq_t *pData)

从协调器请求未决数据，当完成后MAC发送MAC_MLME_POLL_CNF和MAC_MCPS_DATA_IND

typedef struct 

{

  sAddr_t          coordAddress;

  uint16           coordPanId;

  macSec_t         sec;

} macMlmePollReq_t;

uint8 MAC_MlmeResetReq(bool setDefaultPib)

重置MAC，在系统启动时，这个函数必须被调用一次，并且用设置setDefaultPib为true用MAC PIB作为默认值

void MAC_MlmeScanReq(macMlmeScanReq_t *pData)

能量检测，激活或失活扫描，在扫描器期间器件不能执行其他的MAC管理操作，也不能收发MAC数据

typedef struct 

{

  uint32           scanChannels;

  uint8            scanType;

  uint8            scanDuration;

  uint8            channelPage;

  uint8            maxResults;

  macSec_t         sec;

  {

    uint8         *pEnergyDetect;

    macPanDesc_t  *pPanDescriptor;

  } result;

} macMlmeScanReq_t;

uint8 MAC_MlmeSetReq(uint8 pibAttribute, void *pValue)

设置属性值到MAC PIB中

返回值：

MAC_SUCCESS          操作成功

MAC_UNSUPPORTED_ATTRIBUTE   不支持的属性

MAC_INVALID_PARAMETER       值越界

MAC_READ_ONLY           属性为只读

void MAC_MlmeStartReq(macMlmeStartReq_t *pData)

协调器或者PAN协调器调用此函数开始或者重新配置一个网络。在开始一个网络前，器件必须设置短地址，PAN协调器通过设置属性MAC_SHORT_ADDRESS来设置短地址，协调器通过关联设置短地址。

typedef struct 

{

  uint32           startTime;

  uint16           panId;

  uint8            logicalChannel;

  uint8            channelPage;

  uint8            beaconOrder;

  uint8            superframeOrder;

  bool             panCoordinator;

  bool             batteryLifeExt;

  bool             coordRealignment;

  macSec_t         realignSec;

  macSec_t         beaconSec;

} macMlmeStartReq_t;

startTime   - 开始传输信标的时间，若是PAN协调器或者是非信标网络则忽略此项

panId       - 如果panCoordinator为FALSE则忽略此项

logicalChannel  - 如果panCoordinator为FALSE则忽略此项

channelPage - 如果panCoordinator为FALSE则忽略此项

beaconOrder - 计算信标帧间隔的指数，对于非信标帧则设为15

superframeOrder-用来计算超帧时间，非信标网络忽略此项

batteryLifeExt- 若设为真，则MAC_BATT_LIFE_EXT_PERIODS完全信标帧帧间后的完全backoff期间，关闭接收，非信标网络忽略此项

coordRealignment-当设为真时在改变超帧前发送协调器重列

void MAC_MlmeSyncReq(macMlmeSyncReq_t *pData)

请求MAC通过信标统协调器同步，推荐在和信标网络关联前和协调器同步，如果信标不能被定为，则MAC向应用发送包含MAC_BEACON_LOSS状态的MAC_MLME_SYNC_LOSS_IND。在调用这个函数前必须设置用来同步的协调器的地址。MAC成功同步以后将发送MAC_MLME_BEACON_NOTIFY_IND，应用在收到这个事件后将设置MAC_AUTO_REQUEST为真用来停止接收信标宣言。

typedef struct 

{

  uint8            logicalChannel;

  uint8            channelPage;

  bool             trackBeacon;

} macMlmeSyncReq_t;

trackBeacon     - 设置为真将继续跟踪同步信标后的其他信标，设为假则只用第一个信标同步。如果已开始跟踪，设为FALSE则停止跟踪。

今天先来这么多，剩下的部分我再研究研究以后再发生来，呵呵