ZigBee学习之10—MAC层API解读

《ZigBee学习之10—MAC层API解读》由会员上传分享，免费在线阅读，更多相关内容在教育资源-天天文库。

MAC层API解读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_CNF macMcpsDataReq_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清空请求包含不可用的处理管理接口通用常量和数据结构通道掩码MAC_CHAN_11_MASK-MAC_CHAN_28_MASK通道11到28的掩码 比如要使用通道11，12，23则：uint32chan=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器件是FFDMAC_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)返回关联许可位voidMAC_MlmeAssociateReq(macMlmeAssociateReq_t*pData)向协调器发送关联请求，当请求完成后MAC发送MAC_MLME_ASSOCIATE_CNF给应用参数：typedefstruct{uint8logicalChannel;uint8channelPage;sAddr_tcoordAddress;uint16coordPanId;uint8capabilityInformation;macSec_tsec;}macMlmeAssociateReq_t; voidMAC_MlmeAssociateRsp(macMlmeAssociateRsp_t*pData)给发送关联请求的设备发送应答，在接收到MAC_MLME_ASSOCIATE_IND后应该调用此函数，当答复完成后MAC将发送MAC_MLME_COMM_STATUS_INDtypedefstruct{sAddrExt_tdeviceAddress;uint16assocShortAddress;uint8status;macSec_tsec;}macMlmeAssociateRsp_t;assocShortAddress分配给器件的短地址，只有关联成功且器件请求短地址时才会设置此值voidMAC_MlmeDisassociateReq(macMlmeDisassociateReq_t*pData)已关联的设备通知协调器脱离PAN，或者是协调器指示一个已关联设备脱离PAN，解关联完成后MAC发送MAC_MLME_DISASSOCIATE_CNFtypedefstruct{sAddr_tdeviceAddress;uint16devicePanId;uint8disassociateReason;booltxIndirect;macSec_tsec;}macMlmeDisassociateReq_t;uint8MAC_MlmeGetReq(uint8pibAttribute,void*pValue)从MACPIB取得属性pibAttribute属性项pValue指向属性值的指针返回值：MAC_SUCCESS操作成功MAC_UNSUPPORTED_ATTRIBUTE没有找到对应的属性voidMAC_MlmeOrphanRsp(macMlmeOrphanRsp_t*pData)回应节点的orphan宣告voidMAC_MlmePollReq(macMlmePollReq_t*pData)从协调器请求未决数据，当完成后MAC发送MAC_MLME_POLL_CNF和MAC_MCPS_DATA_INDtypedefstruct{sAddr_tcoordAddress; uint16coordPanId;macSec_tsec;}macMlmePollReq_t;uint8MAC_MlmeResetReq(boolsetDefaultPib)重置MAC，在系统启动时，这个函数必须被调用一次，并且用设置setDefaultPib为true用MACPIB作为默认值voidMAC_MlmeScanReq(macMlmeScanReq_t*pData)能量检测，激活或失活扫描，在扫描器期间器件不能执行其他的MAC管理操作，也不能收发MAC数据typedefstruct{uint32scanChannels;uint8scanType;uint8scanDuration;uint8channelPage;uint8maxResults;macSec_tsec;{uint8*pEnergyDetect;macPanDesc_t*pPanDescriptor;}result;}macMlmeScanReq_t;uint8MAC_MlmeSetReq(uint8pibAttribute,void*pValue)设置属性值到MACPIB中返回值：MAC_SUCCESS操作成功MAC_UNSUPPORTED_ATTRIBUTE不支持的属性MAC_INVALID_PARAMETER值越界MAC_READ_ONLY属性为只读voidMAC_MlmeStartReq(macMlmeStartReq_t*pData)协调器或者PAN协调器调用此函数开始或者重新配置一个网络。在开始一个网络前，器件必须设置短地址，PAN协调器通过设置属性MAC_SHORT_ADDRESS来设置短地址，协调器通过关联设置短地址。typedefstruct{uint32startTime;uint16panId;uint8logicalChannel; uint8channelPage;uint8beaconOrder;uint8superframeOrder;boolpanCoordinator;boolbatteryLifeExt;boolcoordRealignment;macSec_trealignSec;macSec_tbeaconSec;}macMlmeStartReq_t;startTime-开始传输信标的时间，若是PAN协调器或者是非信标网络则忽略此项panId-如果panCoordinator为FALSE则忽略此项logicalChannel-如果panCoordinator为FALSE则忽略此项channelPage-如果panCoordinator为FALSE则忽略此项beaconOrder-计算信标帧间隔的指数，对于非信标帧则设为15superframeOrder-用来计算超帧时间，非信标网络忽略此项batteryLifeExt-若设为真，则MAC_BATT_LIFE_EXT_PERIODS完全信标帧帧间后的完全backoff期间，关闭接收，非信标网络忽略此项coordRealignment-当设为真时在改变超帧前发送协调器重列voidMAC_MlmeSyncReq(macMlmeSyncReq_t*pData)请求MAC通过信标同协调器同步，推荐在和信标网络关联前和协调器同步，如果信标不能被定为，则MAC向应用发送包含MAC_BEACON_LOSS状态的MAC_MLME_SYNC_LOSS_IND。在调用这个函数前必须设置用来同步的协调器的地址。MAC成功同步以后将发送MAC_MLME_BEACON_NOTIFY_IND，应用在收到这个事件后将设置MAC_AUTO_REQUEST为真用来停止接收信标宣言。typedefstruct{uint8logicalChannel;uint8channelPage;booltrackBeacon;}macMlmeSyncReq_t;trackBeacon-设置为真将继续跟踪同步信标后的其他信标，设为假则只用第一个信标同步。如果已开始跟踪，设为FALSE则停止跟踪。MAC层API解读2回调函数事件呵其实就是用来应答请求函数的函数调用而已！MAC_MLME_ASSOCIATE_IND当MAC从其他器件接收到关联请求时发送给应有。应用在接收到这个事件后必须调用 MAC_MlmeAssociateRsp()，这个事件只发送给FFD应用，且这个FFD的PIB属性MAC_ASSOCIATION_PERMIT为真。MAC_MLME_ASSOCIATE_CNF作为对MAC_MlmeAssociateReq()的回应，MAC发送这个事件到应用，此事件指示了关联的状态，如果关联成功且请求了短地址，则短地址将被包含在事件中，否则短地址参数不可用。MAC_MLME_DISASSOCIATE_IND指示器件已经解关联MAC_MLME_DISASSOCIATE_CNF作为MAC_MlmeDisassociateReq()的回应发送给应用，此事件指示解关联操作的状态。MAC_MLME_BEACON_NOTIFY_IND当MAC接收到一个信标帧并且信标帧包含负载数据或者MAC_AUTO_REQUEST属性为FALSE时发送次事件到应有，此事件也包含LQI测量值、信标帧接收时间。MAC_MLME_ORPHAN_INDMAC_MLME_SCAN_CNFMAC_MLME_START_CNFMAC_MLME_SYNC_LOSS_INDMAC_MLME_POLL_CNFMAC_MLME_COMM_STATUS_IND发送这个事件的原因有多种，比如指示MAC_MlmeAssociateRsp()和MAC_MlmeOrphanRsp()的状态，也可以指示MAC接收到安全帧，但是安全处理出错。MAC_MLME_POLL_IND只有在MAC用一系列间接数据配置，设置macCfg.appPendingQueue为真，才能发送这个事件。当从其他设备接收到数据请求命令帧时发送此事件，应用应该调用MAC_McpsDataReq()来发送数据到那个设备，并且配置TX属性为MAC_TXOPTION_NO_RETRANS设置。扩展接口提供了一些非802.15.4协议定义的函数，比如电源管理。通用常量和数据结构电源模式MAC_PWR_ONMAC和无线电电源打开MAC_PWR_SLEEP_LITEMAC和无线电部分电源关闭MAC_PWR_SLEEP_DEEPMAC和无线电完全电源关闭uint8MAC_PwrOffReq(uint8mode)请求MAC关闭无线电硬件电源并进入睡眠模式， 返回值：MAC_SUCCESS操作成功MAC_DENIEDMAC不能关闭电源voidMAC_PwrOnReq(void)请求MAC打开无线电硬件电源并唤醒设备uint8MAC_PwrMode(void)返回MAC当前电源模式uint32MAC_PwrNextTimeout(void)返回下一次MAC定时器超时，如果没有定时器运行则返回0uint8MAC_RandomByte(void)从MAC随机数产生器返回一个随机字节回调接口voidMAC_CbackEvent(macCbackEvent_t*pData)发送MAC事件到应用，这个函数的执行需要分配一个OSAL消息，然后将事件参数拷贝到消息，然后将消息发送到应用OSAL事件处理函数。这个函数必须从任务或者是中断上下文执行，所以它是可重入的。参数：typedefstruct{uint8event;uint8status;}macEventHdr_t;typedefunion{macEventHdr_thdr;macMlmeAssociateInd_tassociateInd;macMlmeAssociateCnf_tassociateCnf;macMlmeDisassociateInd_tdisassociateInd;macMlmeDisassociateCnf_tdisassociateCnf;macMlmeBeaconNotifyInd_tbeaconNotifyInd;macMlmeOrphanInd_torphanInd;macMlmeScanCnf_tscanCnf;macMlmeStartCnf_tstartCnf;macMlmeSyncLossInd_tsyncLossInd;macMlmePollCnf_tpollCnf;macMlmeCommStatusInd_tcommStatusInd; macMlmePollInd_tpollInd;macMcpsDataCnf_tdataCnf;macMcpsDataInd_tdataInd;macMcpsPurgeCnf_tpurgeCnf;}macCbackEvent_t;hdr.event域为下面一些值MAC_MLME_ASSOCIATE_INDAssociateindication.MAC_MLME_ASSOCIATE_CNFAssociateconfirm.MAC_MLME_DISASSOCIATE_INDDisassociateindication.MAC_MLME_DISASSOCIATE_CNFDisassociateconfirm.MAC_MLME_BEACON_NOTIFY_INDBeaconnotifyindication.MAC_MLME_ORPHAN_INDOrphanindication.MAC_MLME_SCAN_CNFScanconfirm.MAC_MLME_START_CNFStartconfirm.MAC_MLME_SYNC_LOSS_INDSynclossindication.MAC_MLME_POLL_CNFPollconfirm.MAC_MLME_COMM_STATUS_INDCommunicationstatusindication.MAC_MLME_POLL_INDPollindication.MAC_MCPS_DATA_CNFDataconfirm.MAC_MCPS_DATA_INDDataindication.MAC_MCPS_PURGE_CNFPurgeconfirm.MAC_PWR_ON_CNFPoweronconfirm.uint8MAC_CbackCheckPending(void)返回应用中的间接消息队列配置配置常量MAC用数据结构来包含多种用户配置参数。这个数据结构叫macCfg在mac_cfg.c中定义typedefstruct{uint8txDataMax;uint8txMax;uint8rxMax;uint8dataIndOffset;boolappPendingQueue;}macCfg_t;txDataMax传输数据队列中的最大数据帧队列数目，范围：1-255，默认值：2txMax传输数据队列中的最大帧队列数目，范围：1-255，默认值：5rxMax接收数据队列中的数据帧队列数目，范围：1-255，默认值：2dataIndOffset为应用定义的头发配额外的数据字节，范围：0-127，默认值：0 appPendingQueue当设置为真时，在从其他设备接收到数据请求帧将发送MAC_MLME_POLL_IND，默认值为FALSE编译时配置MAC源码有一些编译时配置的参数。MAC_NO_PARAM_CHECK设置为FALSE，则会检测API函数的参数是否符合IEEE规范。设置为TRUE则可以减少代码量，默认为FALSEMACNODEBUG如果定义了这个宏，则允许MAC_ASSERT()进行运行时检测。不定义这个宏可以优化代码量MAC_RX_ONOFF_DEBUG_LED如果为TRUE，LED将会随着接收的开关而开关。