Z-stack 应用程序编程接口(API)-网络层

NWK   层为更高层提供了如下功能：·

·   网络管理

·   地址管理

·   网络参数与功能函数

除了管理功能，NWK 还提供了应用程序没有的数据服务。应用程序可以通过 AF数据接口[AF_DataRequest()]来发送数据。

3.4.1.1 网络管理(Network Management)

3.4.1.1.1 NLME_NetworkDiscoveryRequest()

此函数请求网络层寻找相邻路由器。这个函数应该在加入并执行网络扫描之前调用。扫描确认结果将被返回到 ZDO_NetworkDiscoveryConfirmC B()回调函数中。最好不要使用此函数（除非你完全理解网络连接过程），而使用 ZDO_StartDevice()。

函数原型

ZStatus_t   NLME_NetworkDiscoveryRequest(uint32 ScanChannels,byte  ScanDuration );

参数描述

ScanChannels—进行查找的信道。该字段是一个位图，每一位代表一个要扫描的信道。2.4GHz 仅可使用 11-26 信道（0x07FFF800）。

ScanDuration—这规定了在新的网络启动之前，其它网络的每个信道应扫描多长时间。其范围与信标的要求相同：

返回值

zStatus_t—定义在 ZComDef.h 中的状态值。

3.4.1.1.2 NLME_NwkDiscReq2()

此函数请求网络层寻找相邻路由器。使用这个函数执行一个网络扫描，但不会加入该网络。扫描确认（结果）将被返回到 ZDO_NetworkDiscoveryConfirmC B()回调函数中。执行回调函数（结果）之后，调用_NwkDiscTerm()来清除此次行为。

函数原型

ZStatus_t NLME_NwkDiscReq2( NLME_ScanFields_t* fields );

参数描述

fields—扫描结构体

typedef struct

{

uint32 channels;

uint8 duration;

} NLME_ScanFields_t;

channels—进行查找的信道。该字段是一个位图，每一位代表一个要扫描的信道。2.4GHz   仅可使用 11-26 信道（0x07FFF800）。

Duration—这规定了在新的网络启动之前，其它网络的每个信道应扫描多长时间。其范围与信标的要求相同。

返回值

ZStatus_t—定义在 ZComDef.h 中的状态值。

3.4.1.1.3 NLME_NwkDiscTerm()

此函数将清除 NLME_NwkDiscReq2()行为。

函数原型

void NLME_NwkDiscTerm( void );

参数描述

空。

返回值.

空。

3.4.1.1.4 NLME_NetworkFormationRequest()

此函数允许相邻的更高层请求设备组建一个新网络并允许自身成为该网络的ZigBee   协调器。这个行为的结果（状态）返回到 ZDO_NetworkFormationConfirmC B()回调函数中。最好不要直接使用此函数，而使用 ZDO_StartDevice()。

函数原型

ZStatus_t NLME_NetworkFor mation Request( uint16 PanId, uint32 ScanChannels,byte ScanDuration,byte  BeaconOrder,byte SuperframeOrder , byte BatteryLifeExtension );

参数描述

PanId—该字段指定了该设备启动的网络所用的标识符。合法值从 0 到 0x3FFF。如果使用了 0x3FFF，NWK 层将选择 PanId 供网络使用。如果在这里发现网络有同一 PAN ID，这 个 PANID 将递增直到唯一（直到扫描过的 PAN ID）。

ScanChannels-进行查找的信道。该字段是一个位图，每一位代表一个要扫描的信道。2.4GHz   仅可使用 11-26 信道（0x07FFF800）。

ScanDuration—这规定了在新的网络启动之前，其它网络的每个信道应扫描多长时间。其范围与信标顺序相同。

Beaconorder       —       在Zigbee2006规范中该字段是BEACON_ORDER_NO_BEACONS。

SuperframeOrder      —      在 Zigbee 2006规范中该字段是BEACON_ORDER_NO_BEACONS。

BatteryLifeExtension—如果它的值为真，NWK   层将请求 ZigBee   协调器启动支持电池寿命延长的模式（关于这种模式详细介绍参见[R3]）。如果值为假，NWK   层将请求 ZigBee   协调器启动不支持电池寿命延长的模式。

返回值

zStatus_t—定义在 ZComDef.h 中的状态值。

3.4.1.1.5 NLME_StartRouterRequest()

这个函数允许相邻的更高层请求设备启动路由器功能。这个行为的结果（状态）返回到StartRouterConfirmCB() 回 调 函 数 中 。 最 好 不 要 直 接 使 用 此 函 数 ， 而 使 用ZDO_StartDevice()。

函数原型

ZStatus_t NLME_StartRouterRequest(byte BeaconOrder,byte SuperframeOrder,byte BatteryLifeExtension );

参数描述

Beaconorder    —   在Zigbee2006规范中该字段是BEACON_ORDER_NO_BEACONS。

SuperframeOrder —   在Zigbee2006 规范中该字段是BEACON_ORDER_NO_BEACONS。

BatteryLifeExtension—如果它的值为真，NWK   层将请求路由器启动支持电池寿命延长的模式（关于这种模式详细介绍参见[R3]）。如果值为假， NWK   层将请求路由器启动不支持电池寿命延长的模式。

返回值

zStatus_t—定义在 ZComDef.h 中的状态值。

3.4.1.1.6 NLME_JoinRequest()

此函数允许相邻的更高层请求设备将自己加入到一个网络中。这个行为的结果（状态）返回到ZDO_JoinConfirmCB()回调函数中。最好不要直接使用此函数而使用  ZDO_StartDevice()。

函数原型

ZStatus_t NLME_Join Request(uint8 *ExtendedPANID,uint16 PanId,byte Channel,byte  CapabilityInfo);

参数描述

ExtendedPANID—该字段包含你试图加入的网络扩展 PAN ID。

PanId——该字段指明了设备即将加入的网络所用的标识符。合法范围从 0 到0x3FFF，可以经过扫描获得。

Channel-目标网络所在的信道。2.4GHz 仅可使用 11-26 信道。

CapabilityInfo—指明了加入设备的可操作容量：

返回值

zStatus_t—定义在 ZComDef.h 中的状态值。

3.4.1.1.7 NLME_ReJoinReque st()

使用此函重新加入一个设备已经加入过的网络。此函数的结果（状态）返回到ZDO_JoinConfirmCB() 回调函数中。

函数原型

ZStatus_t NLME_ReJoinRequest( void );

参数描述

空。

返回值

zStatus_t—定义在 ZComDef.h 中的状态值。

3.4.1.1.8 NLME_OrphanJoinReque st()

此函数请求网络层孤立地连接到网络上。此函数是一个默示加入形式的扫描。此函数的结果（状态值）返回到 ZDO_JoinConfirmCB()回调函数中。最好不要使用此函数（除非你完全理解网络加入过程），而使用 ZDO_StartDevice()。

函数原型

ZStatus_t NLME_OrphanJoin Request( uint32 ScanChannels, byte ScanDuration );

参数描述

ScanChannels—进行查找的信道。该字段是一个位图，每一位代表一个要扫描的信道。2.4GHz仅可使用 11-26 信道（0x07FFF800）。

ScanDuration—这规定了在新的网络启动之前，其它网络的每个信道应扫描多长时间。其范围与信标的要求相同。

返回值

ZStatus_t—定义在 ZComDef.h   中的状态值。

3.4.1.1.9 NLME_PermitJoiningRequest()

此函数定义了相邻的更高层的协调器或路由器如何允许设备在一段固定的时间内加入它的网络。

函数原型

ZStatus_t NLME_PermitJoiningRequest( byte PermitDuration );

参数描述

PermitDuration—设备（协调器或路由器）允许加入的持续时间。值 0x00 和 0xff表示禁止或允许，没有一个具体时间限制。值 0x01 到 0xFE 是允许加入的持续时间，以秒为单位。

返回值

ZStatus_t—定义在 ZComDef.h   中的状态值。

3.4.1.1.10 NLME_DirectJoinRequest()

此函数允许更高层请求 NWK   层的协调器或路由器设备增加另一个设备作为子设备。

函数原型

ZStatus_t NLME_DirectJoin Request( byte *DevExtAddress, byte capInfo );

参数描述

DevExtAddress—指向作为该设备子节点加入的设备的 IEEE 地址的指针。

capInfo — 指 明 了 允 许 加 入 设 备 的 容 量 。 参 见   NLME_JoinRequest() 中 的CapabilityInfo。

返回值

zStatus_t—定义在 ZComDef.h 中的状态值。

3.4.1.1.11 NLME_LeaveReq()

这个函数允许相邻的更高层请求本身或其它设备离开网络。目前，调用这个函数不会造成要离开的设备的父节点重新分配该设备地址。

函数原型

ZStatus_t NLME_LeaveReq( NLME_LeaveReq_t* req );

参数描述

req—离开请求结构体

typedef struct

{

uint8* extAddr;

uint8 removeChildren;

uint8 rejoin;

uint8 silent;

} NLME_LeaveReq_t;

extAddr—离开设备的扩展地址。

removeChildren—同时断开设备子节点为真，仅仅断开设备本身为假。应使用假。

Rejoin—允许设备重新加入网络为真，否则为假。

Silent—不发送通知为真，否则为假。

返回值

ZStatus_t—定义在 ZComDef.h 中的状态值。

3.4.1.1.12 NLME_RemoveChild()

这个函数允许相邻的更高层去请求它。

函数原型

void NLME_RemoveCh ild( uint8* extAddr, uint8 dealloc );

参数描述

extAddr—要删除的设备的扩展地址。

Dealloc—不发送通知为真，否则为假。

返回值

ZStatus_t—定义在 ZComDef.h 中的状态值。

3.4.1.1.13 NwkPollReq()

调用此函数手动请求一个 MAC 层的数据请求信息。仅终端设备具有此功能。通常情况下，终端设备的轮询由网络层自动处理，应用程序可以调用 NLME_SetPollRate()控制轮询率。如果询率设置为 0，应用程序通过调用这个函数自动执行轮询功能。

函数原型

ZMacStatus_t NwkPollReq( byte securityEnable );

参数描述

securityEnable —该字段总是设置为假。

返回值

ZMacS tatus_t 和 ZStatus_t   相同—定义在 ZComDef.h 中的状态值。

3.4.1.1.14 NLME_SetPollRate()

使用这个函数设置或修改网络层的轮询率。仅终端设备具有此功能。通常情况下 ，终端设备的轮询由网络层自动处理，应用程序可以调用 NLME_SetPollRate()控制轮询率。

函数原型

void NLME_SetPollRate( uint16 newRate );

参数描述

newRate—数据和父节点之间轮询的毫秒数。在没有设置轮询率的情况下，值为0不执行轮询，为 1 执行一次数据轮询。

返回值

空。

3.4.1.1.15 NLME_SetQueuedPollRate()

使用此函数可以设置或修改队列轮询率。仅终端设备具有此功能。如果数据轮询结果放在一个数据信息中，Queued Poll Rate 中的轮询率立即被设置以遍历父节点的队列数据。函数原型

void NLME_SetQueuedPollRate( uint16 newRate );

参数描述

newRate—队列轮询率毫秒数。值为 0 不执行队列轮询，0x01 -0xFF 代表持续时间。

返回值

空。

3.4.1.1.16 NLME_SetResponseRate()

使用此函数设置或修改响应轮询率。仅终端设备具有此功能。这是发送数据请求后的轮询率，基于期望得到一个快速响应的想法(而不是等待正常的轮询率)。

函数原型

void NLME_SetResponseRate( uint16 newRate );

参数描述

newRate—响应轮询的持续时间，以毫秒为单位。值为 0 禁止响应轮询，0x01 -0xFF代表持续时间。

返回值

空。

3.4.1.1.17 NLME_RouteDiscoveryRequest()

用这个函数来发送路由请求从而实现路由发现，路由请求既可以是单播路由请求来建立一个端到端的路由路径，也可以使多对一的路由请求来建立一个网络中所有设备到一个网络集中器（这个设备被认为是本地设备同时声明了多对一路由请求）的路由。

函数声明

ZStatus_t NLME_RouteDiscoveryRequest( uint16 DstAddress, byte options, uint8  radius );

参数描述

DstAddress—路由请求的目的地址。在单播路由请求时，这个是本地设备尝试建立路由路径的目的设备地址，当是多对一路由请求时，这个参数在函数调用时会被改写成多对一的目的地址，一般是 0xFFFC，表示是所有的路由器和协调器。

options—路由发现选项掩码，可能的值如下表所示：

Radius—路由请求包的多播半径，如果被设置为 0，则多播半径就会被设置成默

认的广播半径。

返回值

ZStatus_t—定义在 ZComDef.h 中的状态值。

3.4.1.2 地址管理（Address Management）

管理层地址提供了提供了低层地址管理，目前，用户不能直接使用此模块。

APSME_LoopupExtAddrReq 和 APSME_LookupNwkAddr 这两个函数提供了支持本地地址查找的功能。ZDP_IEEEAddrReq 和 ZDP_NwkAddrReq 这两个函数提供了支持远程地址查找的功能。查询存储在本地设备的远程地址，应执行专有解决方案。

3.4.1.3 网络参数和功能函数（Network Variables and Utility Functions）

3.4.1.3.1 NLME_GetExtAddr()

这个函数将返回指向 IEEE 设备 64 地址的指针。

函数原型

byte *NLME_ GetExtAddr( void );

参数描述

空。

返回值

指向 64 位扩展地址的指针。

3.4.1.3.2 NLME_GetShortAddr()

这个函数将返回设备的(16 位短)   网络地址。

函数原型

uint16 NLME_GetShortAddr( void );

参数描述

空。

返回值.

16 位网络（短）地址。

3.4.1.3.3 NLME_GetCoordShortAddr()

这个函数将返回设备父节点的（16 位短）网络地址，这不是 Zigbee   协调器的短地址(它总是 0x0000)，在 MAC 层的术语里，这个父节点就叫协调器。

函数原型

uint16 NLME_Get CoordShortAddr( void );

参数描述

空。

返回值

16 位网络（短）地址。

3.4.1.3.4 NLME_GetCoordExtAddr()

这个函数是将获得设备的父节点设备的 IEEE(64 位)地址，它不是 Zigbee   协调器的扩展地址。

在 MAC 层的术语里，这个父节点就叫协调器。

函数原型

void NLME_Get CoordExtAddr( byte *buf );

参数描述

指向父节点扩展地址的缓冲器指针。

返回值

空。

3.4.1.3.5 NLME_SetRequest()

这个函数允许相邻的更高层设置网络信息库的属性。

函数原型

ZStatus_t NLME_SetRequest( ZNwkAttributes_t NIBAttribute, uint16 Index,void *Value );

参数描述

NIBAttribute—仅支持如下属性：

nwkProtocolVersion

Index—没有使用。

Value—指向包含属性值的内存位置的指针。

返回值

ZStatus_t—定义在 ZComDef.h 中的状态值。

3.4.1.3.6 NLME_GetRequest()

这个函数允许相邻的更高层获得网络信息库的属性值。

函数原型

ZStatus_t NLME_Get Request( ZNwkAttributes_t NIBAttribute, uint16 Index, void  *Value );

参数描述

NIBAttribute—仅支持如下属性：

nwkCapabilityInfo

nwkNumNeighborTableEntri es

nwkNeighborTable

nwkNumRoutingTable Entries

nwkRoutingTable

Index—用于表的索引。

Value—指向包含属性值的内存位置的指针。

返回值

ZStatus_t—定义在 ZComDef.h 中的状态值。

3.4.1.3.7 NLME_IsAddressBroadcast()

此函数根据设备容量来评估提供的地址，根据给定的设备容量决定它是否是一个有效的广播地址。

函数原型

addr_filter_t NLME_IsAddressBroadcast(uint16 shortAddress);

参数描述

shortAddress —要测试的地址。

返回值

addr_filter_t—函数的结果类型如下：

3.4.1.3.8 NLME_GetProtocolVersion()

这个函数使用 GET API 在 NIB 中检索当前的协议版本。这个函数仅仅为了便于使用。否则它将是一个二级过程(针对这里的实际情况而言)。

函数原型

byte NLME_GetProtocolVersion ();

详细参数

空。

返回值

返回 LSB 中协议版本字节，值为：

3.4.1.3.9 NLME_SetBroadcastFilter()

这个函数根据该设备的容量设置一个掩码，它将用于处理有效的广播地址。

函数原型

void NLME_SetBroadcastFilter(byte capabilities);

参数描述

Capabilities—这个设备的容量用于确定这个设备能处理的广播信息类型。和加入功能中所用的容量相同。

返回值

空。

3.4.1.4 网络 Non-Volitile 存储

如果在预编译程序部分或 f8wConfig.cfg 中定义了 NV_RESTORE，当一个设备加入时，网络信息库将自动地保存这个行为。网络信息库 NV 的初始化和恢复函数在设备启动时自动调用。

如果用户应用程序修改网络信息库，必须直接调用 NLME_UpdateNV()。

3.4.1.4.1 NLME_UpdateNV()

这个函数将把 NIB 写到非易失性存储器。如果用户应用程序对 NIB 有任何修改，此函数都会被调用。

如果网络信息库通过加入正常更新，则不需要调用此函数。

函数原型

void NLME_UpdateNV( byte enables );

参数描述

Enables—要保存的项目的掩码：

返回值

空。

3.4.1.5 PAN ID 冲突（PAN ID Conflict）

因为 16 比特的 PAN ID 不是唯一的，所以在本地网络的邻居中可能存在 PAN ID的冲突。当一个节点检测到 PAN ID 冲突时，它会给指定的网络管理器发送网络报告命令，而网络管理器收到这个网络报告的命令后就会给网络重新选择一个新的 PAN ID。一旦新的 PAN ID 选择好了，网络管理器就会向网络广播一个网络更新的命令（包含了新的 PAN ID），收到这个命令后，网络中所有的设备就把它们当前的 PAN ID 改成新的选定的 PAN ID。

3.4.1.5.1 NLME_SendNetworkReport ()

这个函数用来发送网络报告命令。这个网络报告命令允许一个设备向在网络层信息库（NIB）里指定地址为 nwkManagerAddr 的设备报告网络事件。这些事件是指信道冲突和 PAN ID 冲突。

函数原型

void NLME_SendNetworkReport ( uint16 dstAddr, uint8 reportType, uint8 *EPID,uint8 reportInfoCnt,uint16 *panIDs );

参数描述

dstAddr –   消息的目的地址

reportType –   报告命令的类型

EPID –   设备所在网络的 64 比特的扩展 PAN   ID

reportInfoCnt –   在 panIDs 域里包含的记录数目

panIDs –   报告设备的邻居使用的 16 比特 PAN   ID 列表

返回值

空

3.4.1.5.2 NLME_SendNetworkUpdate()

这个函数用来发送网络更新命令。这个网络更新命令允许在网络信息库（NIB）被指定了 nwkManagerAddr 这个属性的设备向网络中的所有设备广播网络的更改信息，比如，广播网络即将更改它的短 PAN 值。

函数原型

void NLME_SendNetworkUpdate ( uint16 dstAddr, uint8 updateType, uint8 *EPID,

uint8 updateId, uint16 newPID );

参数描述

dstAddr –   消息的目的地址

updateType –   更新命令的类型

EPID –即将被更新的网络的 64 比特的扩展 PAN   ID

updateId –   发送这个更像命令的设备目前的 nwkUpdateId 属性值

newPID –   网络使用的新 PAN ID

返回值

空

3.4.1.6 PAN 间信息发送（Inter-PAN Transmission）

Stub APS 子层提供了接口用来交换 PAN 间数据，改变 PAN 间通信信道，和检查PAN 间消息。

3.4.1.6.1 StubAPS_SetInterPanChannel()

这个函数允许应用程序改变 PAN 间通信的信道。

函数原型

ZStatus_t StubAPS_SetInterPanChannel( uint8 channel );

参数描述

channel –   新的通信信道

返回值

ZStatus_t –   在 ZComDef.h.定义的状态值

3.4.1.6.2 StubAPS_SetIntraPanChannel()

这个函数允许应用程序把信道改变回原来的在网络信息库里（NIB）定义的信道

函数原型

ZStatus_t StubAPS_SetIntraPanChannel( void );

参数描述

空

返回值

ZStatus_t –   在 ZComDef.h.定义的状态值

3.4.1.6.3 StubAPS_InterPan()

这个函数允许应用程序查看是否正在和一个不同的 PAN 进行通信

函数原型

uint8 StubAPS_InterPan( uint16 panId, uint8 endPoint );

参数描述

panId –   PAN   ID

endpoint –   端口号

返回值

返回真如果是 PAN 间通信，否则返回假

3.4.1.6.4 StubAPS_RegisterApp()

这个函数允许应用程序在 Stub APS 层注册自己。

函数原型

uint8 StubAPS_RegisterApp( endPointDesc_t *epDesc );

参数描述

epDesc –   应用程序端口号描述符

返回值

空

3.4.1.7 ZMac 层设置发送功率（ZMacSetTransmitPower）

函数原型

uint8 ZMacSetTransmitPower( ZMacTransmitPower_t level );

参数描述

level –   在 ZMAC.h 定义的有效的功率水平级数

返回值

返 回   ZMacSuccess   如 果发现了 PHY_TRANSMIT_POWER ， 否则返回  ZMacUnsupportedAttribute 。