ZigBee学习之10――MAC层API解读

1、ZigBee学习之10MAC层API解读其实也算不上什么解读拉,基本上是把官方的文档翻译了一下。在Zigbee中,是分层结构的,这样做有很多的好处,每一层只负责自己的东西,数据传输更加透明和有效,好了闲话不说,我们开始解读MAC层API,当然是针对Z-Stack的,呵呵MAC API802.15.4 MAC API _F8W-2005-1503_.pdf常量和结构体typedef uint8 sAddrExt_t8;typedef structunionuint16 shortAddr;sAddrExt_t extAddr; addr;uint8 addrMode; sAddr_t;short

2、Addr - 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 接收到的帧

3、或者操作产生的帧或数据请求太长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 由于没有收到信标,扫描请求失败M

4、AC_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_EXP

5、IRED 关联应答,解关联请求,间接数据传输失败MAC_TRANSACTION_OVERFLOW 数据缓存溢出,操作失败MAC_UNAVAILABLE_KEY 安全密钥不可用MAC_UNSUPPORTED_ATTRIBUTE 由于不支持的特性指令或请求失败MAC_UNSUPPORTED_LEGACY 不支持的安全方式MAC_UNSUPPORTED_SECURITY 接收到的帧的安全方式不支持私有状态值MAC_UNSUPPORTED 当前配置不支持的操作MAC_BAD_STATE 当前状态不支持的操作MAC_NO_RESOURCES 内存资源不足MAC时间值aBaseSuperframeDura

6、tion 构成超帧的符号周期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设备,要在调用其它数据和管理A PI之前调用void MAC_Ini

7、tSecurity(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_InitC

8、oord(;数据接口MAC层用来发送和接收数据的API数据结构typedef structuint8 *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(ma

9、cMcpsDataReq_t *pData将应用数据发送到MAC。若MAC拥堵或者不能接受数据请求则发送状态为MAC_TRANSACTION_OVE RFLOW的MAC_MCPS_DATA_CNF,最终MAC将变得不拥堵并且为一个缓存的请求发送MAC_MCPS_DAT A_CNF。所以应用能在任何时候发送数据,只是数据将被队列。应用必须分配一定字节的缓存,数目是:MAC_DATA_OFFSET+MAC_ENC_OFFSET(如果使用加密安全。可用使用MAC_McpsDataAlloc(来方便准确的分配这个缓存。最大的数据帧长度为MAC_MAX_FRA ME_SIZE,如果使用加密安全,则还要减

10、去MAC_ENC_OFFSET及其相关的加密代码区域:比如使用AES-MIC128,则最大的数据帧长度为:max = MAC_MAX_FRAME_SIZE - MAC_ENC_OFFSET MAC_ MIC_128_LEN;参数:typedef structsAddr_t dstAddr;uint16 dstPanId;uint8 srcAddrMode;uint8 mdsuHandle;uint8 txOptions;uint8 channel;uint8 power; macDataReq_t;typedef structmacEventHdr_t hdr;sData_t msdu;mac

11、TxIntData_t internal;macSec_t sec;macDataReq_t mac; macMcpsDataReq_t;hdr和internal是内部使用的,mac.mdsuHandle是应用定义的关于数据请求的句柄值,mac.tx Options为TX参数位掩码,有以下一些值,其他的都很好理解了。MAC_TXOPTION_ACK 应答传输。如果没有收到应答将重传MAC_TXOPTION_GTS GTS传输(unused.MAC_TXOPTION_INDIRECT 间接传输。MAC将队列数据等待目标设备请求此数据。只有协调器才可用这种方式MAC_TXOPTION_NO_RET

12、RANS 无中继传输。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

13、_t *MAC_McpsDataAlloc(uint8 len, uint8 securityLevel, uint8 keyIdMod e如果用此函数分配了MAC_McpsDataReq(所需的数据缓存,在收到MAC_MCPS_DATA_CNF后要通过osal_msg_deallocate(pBuffer来释放。若不使用安全则设置securityLevel和keyIdMode为M AC_SEC_LEVEL_NONE和MAC_KEY_ID_MODE_NONE回调函数事件这些回调函数由应用调用,用来将事件或者数据从MAC传到应用。MAC_MCPS_DATA_IND从MAC发送数据到应用。这个事件

14、的参数指向一个动态分配的缓存,当应用用完数据后必须调用osal_msg_deallocate(pData来释放缓存。MAC还能为应用定义的数据分配额外的空间,应用定义的数据的大小由MAC_MlmeSetReq(的属性MAC_DATA_IND_OFFSET设置。参数:typedef structsAddr_t srcAddr;sAddr_t dstAddr;uint32 timestamp;uint16 timestamp2;uint16 srcPanId;uint16 dstPanId;uint8 mpduLinkQuality;uint8 correlation;uint8 rssi;uin

15、t8 dsn; macDataInd_t;typedef structmacEventHdr_t hdr;sData_t msdu;macRxIntData_t internal;macSec_t sec;macDataInd_t mac; macMcpsDataInd_t;mac.timestamp 接收到帧的时间,单位为aUnitBackoffPeriodmac.timestamp2 接收到帧的时间,单位为内部MAC定时器单元mac.correlation The raw correlation value of the received data frame. This value de

16、pends on the radio. See the chip data sheet for details.dsn 接收到的帧的数据序列MAC_MCPS_DATA_CNF每当调用MAC_McpsDataReq(时就会向应用发送这个事件,这个事件返回数据请求的状态这个事件同样返回指向数据缓存的指针,应用能利用这个指针来释放空间。typedef structmacEventHdr_t hdr;uint8 msduHandle;macMcpsDataReq_t *pDataReq;uint32 timestamp;uint16 timestamp2; macMcpsDataCnf_t;hdr.s

17、tatus有如下的值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 structmacEventHdr_t hdr;uint8 msduHandle; mac

18、McpsPurgeCnf_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 | MA C_CHAN_23_MASK;通道MAC_CHAN_11 - MAC_CHAN_28 通道11到28通道页 2.4G 只用通道 0 页 MAC_CHANNEL_PAGE_

19、0 性能信息 这些掩码指示了器件的性能信息，在关联操作中将用到这些信息 MAC_CAPABLE_PAN_COORD MAC_CAPABLE_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_CA

20、P_SLOT(s MAC_SFS_BLE(s MAC_SFS_PAN_COORDINATOR(s MAC_SFS_ASSOCIATION_PERMIT(s 返回信标顺序 返回超帧顺序 返回最后的 CAP 槽 返回电池延寿位 返回 PAN 协调器位 返回关联许可位 器件可以作为 PAN 协调器 器件是 FFD 器件用的是主干线而不是电池 空闲时也打开接收 能够发送和接收安全帧 在关联工程中请求分配短地址 void MAC_MlmeAssociateReq(macMlmeAssociateReq_t *pData 向协调器发送关联请求，当请求完成后 MAC 发送 MAC_MLME_ASSOCIAT

21、E_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 将发送

22、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，解关联完成后

23、 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_UNSUPP

24、ORTED_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_MlmeR

25、esetReq(bool setDefaultPib 重置 MAC，在系统启动时，这个函数必须被调用一次，并且用设置 setDefaultPib 为 true 用 MA C PIB 作为默认值 void MAC_MlmeScanReq(macMlmeScanReq_t *pData 能量检测，激活或失活扫描，在扫描器期间器件不能执行其他的 MAC 管理操作，也不能收发 MAC 数据 typedef struct uint32 scanChannels; uint8 scanType; uint8 scanDuration; uint8 channelPage; uint8 maxResults

26、; 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(mac

27、MlmeStartReq_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 coordReal