Obtaining node properties

Functions are provided to obtain information about the properties of network nodes. Much of this information is held on a node in special structures, referred to as descriptors. Five types of descriptor are used:

  • Node descriptor

  • Node Power descriptor

  • Simple descriptor

  • User descriptor

  • Complex descriptor

In addition to the above, information can be obtained about the active endpoints, primary discovery cache and services of a node.

The required functions are detailed below. Functions are provided to obtain descriptors from the local node and from a remote node. When obtaining information from a remote node, the function sends a request in an APDU (Application Protocol Data Unit) which must first be allocated using the PDUM function PDUM_hAPduAllocateAPduInstance(). The results of the request are reported in a response which must be collected using the function ZQ_bZQueueReceive().

Note:

  1. When obtaining a descriptor of a remote node, the request can be submitted to the node itself or to another node which may hold the required descriptor in its primary discovery cache.

  2. The structures that contain the descriptors (referenced below) are described in Section 7.2 and Section 8.2.1.

  3. Where 64-bit IEEE/MAC addresses are used to identify remote nodes, the corresponding 16-bit network addresses must be available in the local Address Map - see Section 5.2.3.

Node descriptor

The Node descriptor contains basic information about the node, such as its ZigBee node type and the radio frequency bands supported. The following functions can be used to obtain a Node descriptor:

  • zps_eAplAfGetNodeDescriptor() obtains the Node descriptor of the local node. The result is stored in a structure of type zps_tsAplAfNodeDescriptor.

  • zps_eAplZdpNodeDescRequest() requests the Node descriptor of a remote node. The result is stored in a structure of type zps_tsAplZdpNodeDescriptor.

Parent topic:Obtaining node properties

Power descriptor

The Node Power descriptor contains information about the node’s supported power sources and present power source. The following functions can be used to obtain a Power descriptor:

  • zps_eAplAfGetNodePowerDescriptor() obtains the Node Power descriptor of the local node. The result is stored in a structure of type zps_tsAplAfNodePowerDescriptor.

  • zps_eAplZdpPowerDescRequest() requests the Node Power descriptor of a remote node. The result is stored in a structure of type zps_tsAplZdpNodePowerDescriptor.

Note that elements of the Node Power descriptor can be set on the local node using the ZPS Configuration Editor.

Parent topic:Obtaining node properties

Simple descriptor

There is a Simple descriptor for each endpoint on a node. The information in this descriptor includes the ZigBee device type supported by the endpoint as well as details of its input and output clusters. The following functions can be used to obtain a Simple descriptor:

  • zps_eAplAfGetSimpleDescriptor() obtains the Simple descriptor of a particular endpoint on the local node. The result is stored in a structure of type zps_tsAplAfSimpleDescriptor.

  • zps_eAplZdpSimpleDescRequest() requests the Simple descriptor of a particular endpoint on a remote node. The result is stored in a structure of type zps_tsAplZdpSimpleDescReq.

The returned Simple descriptor includes a list of input clusters and a list of output clusters of the endpoint.

When requesting a Simple descriptor from a remote node, if the cluster lists are long, the Simple descriptor may not fit into the APDU of the response. In this case, the returned Simple descriptor will contain incomplete cluster lists, but the remainder of the lists can be recovered using zps_eAplZdpExtendedSimpleDescRequest().

It is also possible to search for nodes on the basis of certain criteria in the Simple descriptors of their endpoints - for example, search for endpoints which have a particular list of input clusters and/or output clusters. Such a search can be performed using the function zps_eAplZdpMatchDescRequest(). Use of this function is described in Section 6.2.2.

Parent topic:Obtaining node properties

User Descriptor

The User descriptor is a user-defined character string, normally used to describe the node (for example, “Thermostat”). The maximum length of the character string is 16, by default. A node need not have a User descriptor - if it has one, this must be indicated in the Node descriptor. The following functions can be used to access a User descriptor:

  • **zps_eAplZdpUserDescSetRequest()**sets the User descriptor of a remote node.

  • **zps_eAplZdpUserDescRequest()**requests the User descriptor of a remote node. The result is stored in a structure of type zps_tsAplZdpUserDescReq.

The above functions can only be used to access the User descriptor of a non-NXP device (which supports this descriptor), since the storage of a User descriptor on an NXP device is not supported.

Parent topic:Obtaining node properties

Complex descriptor

The Complex descriptor is an optional descriptor which contains device information such as manufacturer, model and serial number. The function zps_eAplZdpComplexDescRequest() allows the Complex descriptor of a remote node to be requested. However, the NXP ZigBee PRO stack does not support the functionality to produce a valid response and this function is provided only for compatibility with non-NXP products that do support the relevant functionality.

Parent topic:Obtaining node properties

Active endpoints

An endpoint on the local node can be configured as enabled or disabled using the function zps_eAplAfSetEndpointState(). An enabled endpoint is described as ‘active’. The current state of a local endpoint can be obtained using the function zps_eAplAfGetEndpointState().

It is also possible to configure whether a local endpoint will be included in the results of network discovery operations, for example, when **zps_eAplZdpMatchDescRequest()**is called. The ‘discoverable’ state of a local endpoint can be set using the function zps_eAplAfSetEndpointDiscovery(), while this state can be obtained using the function zps_eAplAfGetEndpointDiscovery().

A list of the active endpoints on a remote can be obtain using the function zps_eAplZdpActiveEpRequest(). This functions submits an Active_EP_req request to the target node, which replies with an Active_EP_rsp response. If the active endpoint list is too long to fit into the APDU of the response, the returned list will be incomplete. However, the remainder of the list can be recovered using the function zps_eAplZdpExtendedActiveEpRequest(). Note that an endpoint is included in the list only if it is active and discoverable.

Parent topic:Obtaining node properties

Primary discovery cache

A ZigBee routing node (Router or the Coordinator) may be able to host a ‘primary discovery cache’. This is a database, held in memory, containing ‘discovery information’ about a set of network nodes, normally children and possibly other descendant nodes. The information held about a node includes the node’s addresses, descriptors (Node, Node Power, Simple) and its list of active endpoints. Remote nodes can then interrogate the primary discovery cache to obtain information about other nodes in the network.

Note: NXP nodes do not have the capability to hold a primary discovery cache, but functions are provided to interface with a primary discovery cache held on a node from another manufacturer.

The function zps_eAplZdpDiscoveryCacheRequest() allows nodes which hold a primary discovery cache to be detected. This function submits a Discovery_Cache_req request to the network. Nodes with a primary discovery cache reply with a Discovery_Cache_rsp response.

In addition, the function zps_eAplZdpFindNodeCacheRequest() can be used to search for nodes with a primary discovery cache that holds information about a particular node. This function submits a Find_node_cache_req request to the network. Nodes with the required node information in their caches reply with a Find_node_cache_rsp response.

Functions for storing node information in a primary discovery cache are described in Section 6.2.5.

Parent topic:Obtaining node properties

Servers

A node can host one or more of the following ‘servers’ in a ZigBee PRO network:

  • Primary Trust Centre

  • Backup Trust Centre

  • Primary Binding Table Cache

  • Backup Binding Table Cache

  • Primary Discovery Cache

  • Backup Discovery Cache

  • Network Manager

The function zps_eAplZdpSystemServerDiscoveryRequest() can be used to discover the servers hosted by other nodes in the network. The function broadcasts a System_Server_Discovery_req request to all nodes. A remote node replies with a System_Server_Discovery_rsp response containing a bitmap indicating the servers hosted by the node.

Parent topic:Obtaining node properties

Parent topic:Discovering the network