ZigBee学习之16——ZStack -APS层NWK层API解读4 、5

来源：互联网发布：解放战争知乎编辑：程序博客网时间：2024/04/28 07:56

ZigBee学习之16——ZStack API解读4

应用支持子层（APS）

应用支持子层提供如下管理功能： ? 邦定表管理

? 组表管理 ? 快速地址查找除了管理功能外，APS还提供数据服务，只是应用不能访问数据服务。应用需要通过AF数据接

口AF_DataRequest()来发送数据。如果要使用邦定表函数需要包含BindingTable.h头文件。

邦定表管理

邦定表管理邦定表管理

邦定表管理请注意，绑定服务只能在“互补”设备之间建立。那就是，只有分别在两个节点的简单描述结构

体（simple descriptor structure）中，同时注册了相同的命令标识符（command_id）并且方

向相反（一个属于输出指令“output”，另一个属于输入指令“input”），才能成功建立绑定。

APS邦定表是在静态RAM中定义的一张表，定义在nwk_globals.c中。表的大小可以通过f8wCo

nfig.cfg中的[NWK_MAX_BINDING_ENTRIES和MAX_BINDING_CLUSTER_IDS]莱配置。只有定义了R

EFLECTOR或者COORDINATOR_BINDING才能包含此表，用REFLECTOR编译选项来支持APS层的源

邦定。

邦定表结构

邦定表结构邦定表结构

邦定表结构

–

––

–

BindingEntry_t

BindingEntry_tBindingEntry_t

BindingEntry_t typedef struct

{

uint16 srcIdx; // Address Manager index

uint8 srcEP;

uint8 dstGroupMode; // Destination address type; 0 - Normal address index, 1 -

// Group address

uint16 dstIdx; // This field is used in both modes (group and non-group) to

// save NV and RAM space

// dstGroupMode = 0 - Address Manager index

// dstGroupMode = 1 - Group Address

uint8 dstEP;

uint8 numClusterIds;

uint16 clusterIdList[MAX_BINDING_CLUSTER_IDS];

// Don't use MAX_BINDING_CLUSTERS_ID when

// using the clusterIdList field. Use

// gMAX_BINDING_CLUSTER_IDS

} BindingEntry_t;

srcIdx –源地址（绑定记录的源地址）的地址管理器索引，地址管理器保存着源地址的IEEE

地址和短地址。

srcEP -源终端

dstGroupMode -目的地址类型。

0 普通地址

1 组地址

dstIdx -若dstGroupMode为0，则包含目的地址的地址管理器索引，若dstGroupMode为1，

则包含目的组地址

dstEP -目的终端 numClusterIds -clusterIdList中的入口数目

clusterIdList -簇ID列表。列表的最大数目定义由MAX_BINDING_CLUSTER_IDS [f8wConfig.

cfg]指定

邦定表维护

邦定表维护邦定表维护

邦定表维护 BindingEntry_t *bindAddEntry( zAddrType_t *srcAddr, byte srcEpInt,

zAddrType_t *dstAddr, byte dstEpInt,

byte numClusterIds, uint16 *clusterIds );

在邦定表中增加一个入口。由于每个入口可以有多个cluster ID,所以此函数有可能仅仅在已有

邦定条目上增加cluster ID

srcAddr -邦定记录源地址。为Addr16Bit或者Addr64Bit的addr数据结构

srcEpInt -邦定记录源终端

dstAddr -邦定记录目的地址，为Addr16Bit，Addr64Bit或AddrGroup addrMode，若为AddrGr

oup则组ID（group ID）填充到addr.shortAddr

dstEpInt -邦定记录目标终端，若dstAddr为组地址，则忽略此位

clusterIds -指向要增加的cluster ID（16位）列表。

返回值：BindingEntry_t -指向一条新加入的邦定入口

byte bindRemoveEntry( BindingEntry_t *pBind );

pBind -指向邦定表中一个入口的指针

byte bindRemoveClusterIdFromList( BindingEntry_t *entry, uint16 clusterId );

从已存在的邦定表入口的cluster ID列表中移除一个cluster ID。如果至少移除了一个clust

er ID则返回真。此函数不检查参数的正确性。

entry -指向邦定表的指针

clusterId -要移除的16位的cluster ID

byte bindAddClusterIdToList( BindingEntry_t *entry, uint16 clusterId );

是上面那个函数的反操作函数

void bindRemoveDev( zAddrType_t *Addr );

移除参数指定的所有邦定表入口，一旦Addr匹配了源地址或者目的地址，则对应的入口将被删

除

void bindRemoveSrcDev( zAddrType_t *srcAddr, uint8 ep );

功能同上，只是限定了终端和源地址的匹配项目

void bindUpdateAddr( uint16 oldAddr, uint16 newAddr );

交换邦定表中的短地址，所有oldAddr将被newAddr取代。

BindingEntry_t *bindFindExisting( zAddrType_t *srcAddr, byte srcEpInt,

zAddrType_t *dstAddr, byte dstEpInt );

按指定参数查找一个已存在的邦定表入口。若找到则返回指向此邦定表入口的指针，否则返回N

ULL。

byte bindIsClusterIDinList( BindingEntry_t *entry, uint16 clusterId );

检查此cluster ID是否在簇ID列表中。如果在列表中则返回真。

邦定表统计函数

邦定表统计函数邦定表统计函数

邦定表统计函数 byte bindNumBoundTo( zAddrType_t *devAddr, byte devEpInt, byte srcMode );

计算符合条件的邦定表入口数目。返回找到的邦定表入口数目。

devAddr -要查找的邦定表地址

devEpInt -终端

srcMode TRUE 查找源地址，FALSE 查找目的地址

uint16 bindNumOfEntries( void );

返回邦定表中的条目数，以cluster计数。

void bindCapacity( uint16 *maxEntries, uint16 *usedEntries );

返回邦定表的可能最大数目，和在用的最大数目，以入口记录计数。

maxEntries -指向最大入口数目的变量，绑定表的最大入口可以通过 NWK_MAX_BINDING_ENTR

IES[f8wConfig.cfg]更改

usedEntries -指向在用的入口数目的变量

邦定表的非易失性储存

邦定表的非易失性储存邦定表的非易失性储存

邦定表的非易失性储存用这些API需要首先设置编译选项NV_RESTORE[f8wConfig.cfg]，推荐用户使用BindWriteNV函

数，因为binding NV初始化和读取在设备启动的时候会自动执行。

void BindWriteNV( void );

把绑定表写入非易失性储存器，如果用户应用改变了邦定表则可以调用此函数。如果邦定表通过

ZDO更新，则ZDO会调用此函数，用户应用就不需调用了。

组表管理

组表管理组表管理

组表管理 APS组表是由分配的RAM[osal_mem_alloc()]定义得链表，因此当组表增加时，OSAL堆也将增加。

表定义在nwk_globals.c，通过调整APS_MAX_GROUPS[f8wConfig.cfg]来改变组表的最大大小。

用这些API需要包含aps_groups.h头文件。

组表结构体

组表结构体组表结构体

组表结构体组：组是用来将一系列节点集合到一个单地址实体的方式。一个数据请求能够到达组中的每个节

点。在Zigbee协议中组是可选配置，但是在某些剖面中是必选的，比如家庭自动化剖面。组关

注的是一系列设备同时执行一个行为。

typedef struct

{

uint16 ID; // Unique to this table

uint8 name[APS_GROUP_NAME_LEN]; // Human readable name of group

} aps_Group_t;

ID -16位的组ID

name -文本组名（人类语言）APS_GROUP_NAME_LEN为16且不可更改。

组表入口

组表入口组表入口

组表入口-

-apsGroupItem_t

apsGroupItem_t apsGroupItem_t

apsGroupItem_t 组表记录（入口）

typedef struct apsGroupItem

{

struct apsGroupItem *next;

uint8 endpoint;

aps_Group_t group;

} apsGroupItem_t;

next -指向组表的下一个入口（组表为链表结构），推荐使用组表查找和维护函数来遍历组表。

endpoint -接受消息的终端

group -组ID和组名

组表维护函数

组表维护函数组表维护函数

组表维护函数 ZStatus_t aps_AddGroup( uint8 endpoint, aps_Group_t *group );

往组表中添加一个组。先定义aps_Group_t，然后填充这个结构，最后调用此函数来添加。若N

V_RESTORE使能，则函数将更新保存到非易失性储存。返回值：成功则返回ZSuccess，否则返回错误，错误可以是：ZApsDuplicateEntry,ZApsTableF

ull,ZMemError[ZComDef.h]

uint8 aps_RemoveGroup( uint8 endpoint, uint16 groupID );

移除一个组，若NV_RESTORE使能，则函数将更新保存到非易失性储存。

void aps_RemoveAllGroup( uint8 endpoint );

按给定的参数，移除终端的所有组。

组表查询函数

组表查询函数组表查询函数

组表查询函数 aps_Group_t *aps_FindGroup( uint8 endpoint, uint16 groupID );

endpoint -将接收消息的终端

返回值：指向组元件的指针

uint8 aps_FindGroupForEndpoint( uint16 groupID, uint8 lastEP );

从组ID中查找终端，这个函数用来跳过终端，然后返回下一个终端。

lastEP -返回的终端前要跳过的终端。用APS_GROUPS_FIND_FIRST来指定要查找的第一个终端。

返回终端，或者APS_GROUPS_EP_NOT_FOUND（没有找到或者找到多个）

uint8 aps_FindAllGroupsForEndpoint( uint8 endpoint, uint16 *groupList );

得到一个属于一个组的所有终端。

endpoint -要查找的终端

groupList -指向存放终端所有表的空间

uint8 aps_CountGroups( uint8 endpoint );

uint8 aps_CountAllGroups( void );

组表的非易失性储存

组表的非易失性储存组表的非易失性储存

组表的非易失性储存若定义了编译选项NV_RESTORE，则当组发生改变时会自动储存。组表的NV初始化和恢复在器件

启动时自动执行。若用户应用改变了组表的入口，则必须直接调用Aps_GroupsWriteNV()

void aps_GroupsWriteNV( void )

若是通过正常的组添加，移除函数的调用来更改组表，则不必调用此函数。

快速地址查找

快速地址查找快速地址查找

快速地址查找 APS提供了一对函数用来做快速地址转换（查找），用这些函数在IEEE和短地址之间作转换。

uint8 APSME_LookupExtAddr(uint16 nwkAddr, uint8* extAddr );

基于短地址查找IEEE扩展地址。

nwkAddr -拥有的短地址，用来查找扩展地址。

extAddr -指向扩展地址存放的缓存

uint8 APSME_LookupNwkAddr( uint8* extAddr, uint16* nwkAddr );

网络层（NWK）

网络层为高层提供下面函数功能：

· 网络管理

· 地址管理

· 网络变量和效能函数

除了管理功能外，NWK还提供数据服务，只是应用不能访问数据服务。应用需要通过AF数据接口AF_DataRequest()来发送数据。

网络管理

ZStatus_t NLME_NetworkDiscoveryRequest( uint32 ScanChannels,byte ScanDuration );

用来请求网络层发现邻居路由器。在加入操作执行网络扫描前应该调用此函数。扫描确认（结果）将以回调函数ZDO_NetworkDiscoveryConfirmCB()返回。推荐用户使用ZDO_StartDevice()来代替此函数。（除非你清楚的知道网络加入过程）

ScanChannels -执行发现的通道，2.4GHz条件下只能使用通道11-26（0x07FFF800）

ScanDuration -新网络启动前，每个通道被其他网络扫描的时间

BEACON_ORDER_15_MSEC 0 15.36 milliseconds

BEACON_ORDER_30_MSEC 1 30.72 milliseconds

BEACON_ORDER_60_MSEC 2 61.44 milliseconds

BEACON_ORDER_120_MSEC 3 122.88 milliseconds

BEACON_ORDER_240_MSEC 4 245.76 milliseconds

BEACON_ORDER_480_MSEC 5 491.52 milliseconds

BEACON_ORDER_1_SECOND 6 983.04 milliseconds

BEACON_ORDER_2_SECONDS 7 1966.08 milliseconds

BEACON_ORDER_4_SECONDS 8 3932.16 milliseconds

BEACON_ORDER_7_5_SECONDS 9 7864.32 milliseconds

BEACON_ORDER_15_SECONDS 10 15728.64 milliseconds

BEACON_ORDER_31_SECONDS 11 31457.28 milliseconds

BEACON_ORDER_1_MINUTE 12 62914.58 milliseconds

BEACON_ORDER_2_MINUTES 13 125829.12 milliseconds

BEACON_ORDER_4_MINUTES 14 251658.24 milliseconds

BEACON_ORDER_NO_BEACONS 15 No Beacons transmitted

返回值：ZStatus_t -ZComDef.h中定义的状态值

ZStatus_t NLME_NwkDiscReq2( NLME_ScanFields_t* fields );

用来请求网络层发现邻居路由器。用此函数来执行一个网络扫描，但是不加入网络。扫描确认（结果）将以回调函数ZDO_NetworkDiscoveryConfirmCB()返回。回调函数执行以后通过调用NLME_NwkDiscTerm()清除此活动。

fields – 扫描结构体

typedef struct

{

uint32 channels;

uint8 duration;

} NLME_ScanFields_t;

void NLME_NwkDiscTerm( void );

ZStatus_t NLME_NetworkFormationRequest( uint16 PanId, uint32 ScanChannels,

byte ScanDuration, byte BeaconOrder,

byte SuperframeOrder, byte BatteryLifeExtension );

函数允许上层请求设备构成网络并成为网络中的协调器。执行结果返回回调函数ZDO_NetworkFormationConfirmCB()。推荐用户使用ZDO_StartDevice()来代替此函数。

PanId -此设备建立网络所使用的ID，值范围：0~0x3FFF。如果0xFFFF被使用，则网络层将为网络选择此PanID。如果发现网络的PAN ID相同，则增加PAN ID直到其唯一。

BeaconOrder – Zigbee 2006中此参数为：BEACON_ORDER_NO_BEACONS.

SuperframeOrder –Zigbee 2006中此参数为：BEACON_ORDER_NO_BEACONS.

BatteryLifeExtension -为TRUE则请求协调器支持电池寿命扩展模式

ZStatus_t NLME_StartRouterRequest( byte BeaconOrder, byte SuperframeOrder,

byte BatteryLifeExtension );

函数允许上层请求设备以路由器功能启动。执行结果返回回调函数 ZDO_StartRouterConfirmCB()。推荐用户使用ZDO_StartDevice()来代替此函数。

BeaconOrder – Zigbee 2006中此参数为：BEACON_ORDER_NO_BEACONS.

SuperframeOrder –Zigbee 2006中此参数为：BEACON_ORDER_NO_BEACONS.

BatteryLifeExtension -为TRUE则请求协调器支持电池寿命扩展模式

ZStatus_t NLME_JoinRequest( uint8 *ExtendedPANID, uint16 PanId,

byte Channel, byte CapabilityInfo );

函数允许上层发送设备加入网络的请求。执行结果返回回调函数 ZDO_JoinConfirmCB()。推荐用户使用ZDO_StartDevice()来代替此函数。

ExtendedPANID -想要加入的网络的扩展PAN ID

CapabilityInfo -加入设备的操作性能

CAPINFO_ALTPANCOORD 0x01

CAPINFO_DEVICETYPE_FFD 0x02

CAPINFO_POWER_AC 0x04

CAPINFO_RCVR_ON_IDLE 0x08

CAPINFO_SECURITY_CAPABLE 0x40

CAPINFO_ALLOC_ADDR 0x80

ZStatus_t NLME_ReJoinRequest( void );

已加入设备的重新加入。执行结果返回到回调函数ZDO_JoinConfirmCB()

ZStatus_t NLME_OrphanJoinRequest( uint32 ScanChannels, byte ScanDuration );

请求网络层孤儿节点的加入。此函数是一个暗含加入的扫描。执行结果返回到回调函数ZDO_JoinConfirmCB()。推荐用户使用ZDO_StartDevice()来代替此函数。

以上的几个函数基本上是被ZDO_StartDevice()的执行所取代了，呵呵！

ZStatus_t NLME_PermitJoiningRequest( byte PermitDuration );

定义了协调器或路由器在一个固定的周期内如何允许设备加入。

PermitDuration -在这个指定的时间（单位为秒）内允许设备关联。0x00和0xff表示分别禁止或允许设备关联。

ZStatus_t NLME_DirectJoinRequest( byte *DevExtAddress, byte capInfo );

请求协调器或路由器设备的网络层加入一个设备作为其子设备。

DevExtAddress -指向设备的IEEE地址

ZStatus_t NLME_LeaveReq( NLME_LeaveReq_t* req );

请求自己或者其他设备脱离网络，执行此函数不会导致其父节点重新分配设备地址。

req – 脱离请求数据结构:

typedef struct

{

uint8* extAddr;

uint8 removeChildren;

uint8 rejoin;

uint8 silent;

} NLME_LeaveReq_t;

extAddr -要脱离的设备的扩展地址

removeChildren -true 子设备也脱离，false只脱离当前设备。目前只能用false

rejoin -true 允许设备重新加入网络，false 不允许设备重新加入网络

silent – true will. false if the。

void NLME_RemoveChild( uint8* extAddr, uint8 dealloc );

dealloc – true will. false if the.

ZMacStatus_t NwkPollReq( byte securityEnable );

手动发送一个MAC数据请求（此函数只适用于终设备（end devices））。正常情况下终设备的数据检测（poll）由网络层自动处理，应用可以通过调用NLME_SetPollRate()来改变速率，如果速率设为0则可以调用此函数来手动推送数据。

securityEnable – 设为false.

返回值：ZMacStatus_t is the same as ZStatus_t –status values defined in ZComDef.h

void NLME_SetPollRate( uint16 newRate );

（此函数只适用于终设备（end devices））

newRate -单位为ms，数据推送到父设备的时间。

void NLME_SetQueuedPollRate( uint16 newRate );

设置/改变队列推送（poll）速率。（此函数只适用于终设备（end devices）），如果一个数据推送产生了数据消息，则数据推送率马上设置到 Queued Poll Rate以排空父设备的队列数据。

newRate -有效值为：0x01-0xff，0为禁止队列推送。

void NLME_SetResponseRate( uint16 newRate );

设置/改变应答推送（poll）速率。（此函数只适用于终设备（end devices）），我们可以让应答快一些。

newRate -有效值为：0x01-0xff，0为禁止队列推送。

地址管理

地址管理模块提供底层的地址管理，用户不能直接访问这个模块。APSME_LookupExtAddr和APSME_LookupNwkAddr提供本地地址查找，ZDP_IEEEAddrReq和ZDP_NwkAddrReq提供远程地址查找。

byte *NLME_GetExtAddr( void );

返回指向设备64位IEEE地址的指针。

uint16 NLME_GetShortAddr( void );

返回设备的16位网络地址（短地址）。

uint16 NLME_GetCoordShortAddr( void );

返回设备父亲的网络地址（16位短地址），注意这个地址不是Zigbee协调器的短地址（总为0x0000）

void NLME_GetCoordExtAddr( byte *buf );

返回设备父亲的IEEE地址（64位），注意这个地址不是Zigbee协调器的扩展地址

ZStatus_t NLME_SetRequest( ZNwkAttributes_t NIBAttribute,

uint16 Index,

void *Value );

设置NIB属性的值。

NIBAttribute -只支持nwkProtocolVersion属性

ZStatus_t NLME_GetRequest( ZNwkAttributes_t NIBAttribute,

uint16 Index, void *Value );

NIBAttribute -只支持如下属性：

nwkCapabilityInfo

nwkNumNeighborTableEntries

nwkNeighborTable

nwkNumRoutingTableEntries

nwkRoutingTable

addr_filter_t NLME_IsAddressBroadcast(uint16 shortAddress);

基于设备性能，这个函数评估参数中提供的地址，决定是否是广播地址

shortAddress -要测试的地址

addr_filter_t - ADDR_NOT_BCAST 不是一个广播地址

ADDR_BCAST_FOR_ME 是一个广播地址，且这个设备是正确的设备类型

ADDR_BCAST_NOT_ME 是一个广播地址，这个设备是不是正确的目标

byte NLME_GetProtocolVersion();

获得NIB中的协议版本

返回值： ZB_PROT_V1_0 1

ZB_PROT_V1_1 2

void NLME_SetBroadcastFilter(byte capabilities);

基于设备的性能设置位掩码，用来处理有效的广播地址

capabilities -用来决定设备能处理哪些广播消息

网络的非易失性储存

若设置了NV_RESTORE，当设备加入时网络信息（NIB）会自动储存。当设备启动时会自动执行NIB NV初始化和恢复。如果用户应用改变NIB（_NIB）则必须调用NLME_UpdateNV()

void NLME_UpdateNV( byte enables );

enables -位掩码

NWK_NV_NIB_ENABLE 0x01 粗存网络层NIB

NWK_NV_DEVICELIST_ENABLE 0x02 储存设备列表

NWK_NV_BINDING_ENABLE 0x04 储存绑定表

NWK_NV_ADDRMGR_ENABLE 0x08 储存地址管理表