MAC层API解读

其实也算不上什么解读拉，基本上是把官方的文档翻译了一下。在Zigbee中，是分层结构的，这样做有很多的好处，每一层只负责自己的东西，数据传输更加透明和有效，好了闲话不说，我们开始解读MAC层API，当然是针对Z-Stack的，呵呵MACAPI【802.15.4MACAPI_F8W-2005-1503_.pdf】常量和结构体typedefuint8sAddrExt_t【8】;typedefstruct{union{uint16shortAddr;sAddrExt_textAddr;}addr;uint8addrMode;}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_DENIEDMAC不能进入低功耗模式MAC_FRAME_TOO_LONG接收到的帧或者操作产生的帧或数据请求太长MAC_IMPROPER_KEY_TYPE接收到的帧的发送源的KEY不可用MAC_IMPROPER_SECURITY_LEVEL接收到的帧的发送源安全等级和最低等级不匹配MAC_INVALID_ADDRESS由于没有源地址或目的地址，数据请求失败MAC_INVALID_HANDLE清除请求包含不可用的处理MAC_INVALID_PARAMETERAPI函数参数超出范围MAC_LIMIT_REACHED由于PAN描述储存达到界限，扫描中止MAC_NO_ACK由于没有收到应答，操作或数据请求失败MAC_NO_BEACON由于没有收到信标，扫描请求失败MAC_NO_DATA由于没有收到关联应答，关联请求失败MAC_NO_SHORT_ADDRESS开始请求的短地址错误MAC_PAN_ID_CONFLICT检测到一个PANID冲突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构成超帧的符号周期96015.36ms(2.4G)aUnitBackoffPeriod构成CSMA-CA算法的时间周期的符号周期20320us(2.4G)初始化接口初始化接口函数都是直接执行函数voidMAC_Init(void)初始化MAC子系统voidMAC_InitDevice(void)初始化MAC关联到一个非信标网络，使用此函数初始化一个RFD设备，如果使用此函数，要在调用其它数据和管理API之前调用voidMAC_InitCoord(void)初始化MAC能进行协调器的操作。此函数用来初始化一个FFD设备，要在调用其它数据和管理API之前调用voidMAC_InitSecurity(void)使MAC能使用安全功能，要在调用其它数据和管理API之前调用voidMAC_InitBeaconCoord(void)初始化MAC在信标网络中能进行协调器的操作。此函数要在调用其它数据和管理API之前调用voidMAC_InitBeaconDevice(void)初始化MAC能关联到一个信标网络，此函数要在调用其它数据和管理API之前调用提供一些ZigBee的配置事例，其他的网络配置请看TI的文档ZigBee节点设备ZigBee路由器ZigBee协调器MAC_InitDevice();MAC_InitDevice();MAC_InitCoord();MAC_InitCoord();数据接口MAC层用来发送和接收数据的API数据结构typedefstruct{uint8*p;uint8len;}sData_t;p–指向数据len–数据的字节长度数据常量MAC_MAX_FRAME_SIZE102不包含安全域的最大数据长度MAC_DATA_OFFSET24MAC头要求的数据偏移MAC_ENC_OFFSET5加密头要求的数据偏移MAC_MIC_32_LEN432位认证代码要求的长度MAC_MIC_64_LEN864位认证代码要求的长度MAC_MIC_128_LEN16128位认证代码要求的长度voidMAC_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;参数：typedefstruct{sAddr_tdstAddr;uint16dstPanId;uint8srcAddrMode;uint8mdsuHandle;uint8txOptions;uint8channel;uint8power;}macDataReq_t;typedefstruct{macEventHdr_thdr;sData_tmsdu;macTxIntData_tinternal;macSec_tsec;macDataReq_tmac;}macMcpsDataReq_t;hdr和internal是内部使用的，mac.mdsuHandle是应用定义的关于数据请求的句柄值，mac.txOptions为TX参数位掩码，有以下一些值，其他的都很好理解了。MAC_TXOPTION_ACK应答传输。如果没有收到应答将重传MAC_TXOPTION_GTSGTS传输(unused).MAC_TXOPTION_INDIRECT间接传输。MAC将队列数据等待目标设备请求此数据。只有协调器才可用这种方式MAC_TXOPTION_NO_RETRANS无中继传输。MAC_TXOPTION_NO_CNF无确认。这将阻止为此帧发送MAC_MCPS_DATA_CNF事件MAC_TXOPTION_ALT_BEUsePIBvalueMAC_ALT_BEfortheminimumbackoffexponent.MAC_TXOPTION_PWR_CHAN用macDataReq_t结构中的电源和通道值而不用PIB中的值来传输voidMAC_McpsPurgeReq(uint8msduHandle)从MAC数据队列中清空并丢弃数据请求，当完成操作后MAC发送MAC_MCPS_PURGE_CNFmacMcpsDataReq_t*MAC_McpsDataAlloc(uint8len,uint8securityLevel,uint8keyIdMode)如果用此函数分配了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设置。参数：typedefstruct{sAddr_tsrcAddr;sAddr_tdstAddr;uint32timestamp;uint16timestamp2;uint16srcPanId;uint16dstPanId;uint8mpduLinkQuality;uint8correlation;uint8rssi;uint8dsn;}macDataInd_t;typedefstruct{macEventHdr_thdr;sData_tmsdu;macRxIntData_tinternal;macSec_tsec;macDataInd_tmac;}macMcpsDataInd_t;mac.timestamp–接收到帧的时间，单位为aUnitBackoffPeriodmac.timestamp2–接收到帧的时间，单位为内部MAC定时器单元mac.correlation–Therawcorrelationvalueofthereceiveddataframe.Thisvaluedependsontheradio.Seethechipdatasheetfordetails.dsn–接收到的帧的数据序列MAC_MCPS_DATA_CNF每当调用MAC_McpsDataReq()时就会向应用发送这个事件，这个事件返回数据请求的状态这个事件同样返回指向数据缓存的指针，应用能利用这个指针来释放空间。typedefstruct{macEventHdr_thdr;uint8msduHandle;macMcpsDataReq_t*pDataReq;uint32timestamp;uint16timestamp2;}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()时向应用发送这一事件typedefstruct{macEventHdr_thdr;uint8msduHandle;}macMcpsPurgeCnf_t;hdr.status-清空请求的状态MAC_SUCCESS成功MAC_INVALID_HANDLE清空请求包含不可用的处