MAC层API解读.docx

其实也算不上什么解读拉，基本上是把官方的文档翻译了一下。在Zigbee中，是分层结构的，这样做有很多的好处，每一层只负责自己的东西，数据传输更加透明和有效，好了闲话不说，我们开始解读MAC层API，当然是针对Z-Stack的，呵呵 MAC API【802.15.4 MAC API _F8W-2005-1503_.pdf】 常量和结构体 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则停止跟踪。 回调函数事件 呵呵，名字很恐怖，其实就是用来应答请求函数的函数调用而已，不要想的太深奥哦！ 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_IND MAC_MLME_SCAN_CNF MAC_MLME_START_CNF MAC_MLME_SYNC_LOSS_IND MAC_MLME_POLL_CNF MAC_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_ON MAC和无线电电源打开 MAC_PWR_SLEEP_LITE MAC和无线电部分电源关闭 MAC_PWR_SLEEP_DEEP MAC和无线电完全电源关闭 uint8 MAC_PwrOffReq(uint8 mode) 请求MAC关闭无线电硬件电源并进入睡眠模式， 返回值： MAC_SUCCESS 操作成功 MAC_DENIED MAC不能关闭电源 void MAC_PwrOnReq(void) 请求MAC打开无线电硬件电源并唤醒设备 uint8 MAC_PwrMode(void) 返回MAC当前电源模式 uint32 MAC_PwrNextTimeout(void) 返回下一次MAC定时器超时，如果没有定时器运行则返回0 uint8 MAC_RandomByte(void) 从MAC随机数产生器返回一个随机字节 回调接口 void MAC_CbackEvent(macCbackEvent_t *pData) 发送MAC事件到应用，这个函数的执行需要分配一个OSAL消息，然后将事件参数拷贝到消息，然后将消息发送到应用OSAL事件处理函数。这个函数必须从任务或者是中断上下文执行，所以它是可重入的。 参数： typedef struct uint8 event; uint8 status; macEventHdr_t; typedef union macEventHdr_t hdr; macMlmeAssociateInd_t associateInd; macMlmeAssociateCnf_t associateCnf; macMlmeDisassociateInd_t disassociateInd; macMlmeDisassociateCnf_t disassociateCnf; macMlmeBeaconNotifyInd_t beaconNotifyInd; macMlmeOrphanInd_t orphanInd; macMlmeScanCnf_t scanCnf; macMlmeStartCnf_t startCnf; macMlmeSyncLossInd_t syncLossInd; macMlmePollCnf_t pollCnf; macMlmeCommStatusInd_t commStatusInd; macMlmePollInd_t pollInd; macMcpsDataCnf_t dataCnf; macMcpsDataInd_t dataInd; macMcpsPurgeCnf_t purgeCnf; macCbackEvent_t; hdr.event域为下面一些值 MAC_MLME_ASSOCIATE_IND Associate indication. MAC_MLME_ASSOCIATE_CNF Associate confirm. MAC_MLME_DISASSOCIATE_IND Disassociate indication. MAC_MLME_DISASSOCIATE_CN