Discovering the network

This section describes how to discover properties of the network, including general network properties, node addresses and features, and the services offered by nodes. The important task of finding nodes that can communicate with each other is described. Maintenance of the ‘primary discovery cache’ of a node is also described - this cache contains information about other nodes of the network (not all nodes will host a primary discovery cache - only the Coordinator and Routers are allowed to).

Obtaining network properties

A ‘network discovery’ is implemented when the function **zps_eAplZdoStartStack()**is called to start the stack on an End Device or Router node (which needs to find a network to join). In addition, a network discovery can be explicitly started by calling the function zps_eAplZdoDiscoverNetworks(). For example, this function could be called if the initial network discovery did not find any suitable networks to join, in which case the function may be used to initiate a scan of previously unscanned channels (detailed in the stack event described below, resulting from the initial discovery).

Both of these function calls eventually result in the stack event zps_EVENT_NWK_DISCOVERY_COMPLETE on the End Device or Router, where this event reports the following properties of the discovered networks:

  • Extended PAN ID

  • ZigBee version

  • ZigBee stack profile

This stack event also indicates the recommended network to join, which is taken to be the first ZigBee PRO network detected that is allowing nodes to join.

For information on joining a network, refer to Section 6.1.2.

Parent topic:Discovering the network

Finding compatible endpoints

An endpoint on a newly joined node must find compatible endpoints on remote nodes with which to communicate. The decision of whether a remote endpoint is compatible is based on the endpoint properties stored in its Simple descriptor, notably the input/ output clusters supported.

The endpoint application can discover compatible nodes by sending out a Match_Desc_req request identifying the required clusters. This request is submitted by calling the function zps_eAplZdpMatchDescRequest(), which allows the request to be sent as a broadcast to all nodes or as a unicast to a particular node (the sending node may already have a record of the network nodes and their addresses, as each node automatically announces itself in a broadcast when it joins the network). The

request is sent in an APDU (Application Protocol Data Unit) which must first be allocated using the PDUM function PDUM_hAPduAllocateAPduInstance().

A receiving endpoint which satisfies the supplied criteria replies to the request with a Match_Desc_rsp response which, when received, must be collected on the requesting node using the function ZQ_bZQueueReceive(). The requesting application may bind to a compatible endpoint (see Section 5.4) and communicate with the endpoint using binding or addressing (see Section 5.5).

Parent topic:Discovering the network

Obtaining and maintaining node addresses

The addresses of network nodes are needed in order to access node information (see Section 6.2.4), send data from one node to another (see Section 6.5) and bind nodes together (see Section 6.4). In most of these operations, an application can specify either 64-bit IEEE/MAC addresses or 16-bit network addresses, but the ZigBee PRO stack always works with network addresses. If the IEEE address (rather than the network address) of a remote node is specified by the application, the network address must still be available to the stack in an Address Map - see below.

The IEEE address of a node is assigned at the time of device manufacture and is fixed, while its network address is dynamically allocated by its parent when the device joins the network (this address may change if the network is re-started or the device later leaves and rejoins the network). Functions are provided to obtain the IEEE address of a node given its network address or to obtain the network address given the IEEE address. Use of these functions is described in Section 6.2.3.1 and Section 6.2.3.2.

Note: The IEEE/MAC and network addresses of a node can be broadcast to all other nodes in the network using the function zps_eAplZdpDeviceAnnceRequest(). For example, this function would typically be called when the node joins or rejoins the network. The information is sent in a Device_annce announcement, which must be collected by the recipient nodes using the function ZQ_bZQueueReceive().

An Address Map table can be maintained on a node, where each entry of this table contains the pair of addresses for a remote node - the 64-bit IEEE/MAC address and 16-bit network address. In fact, the IEEE/MAC address is not directly stored in the Address Map table but in a MAC Address table - the Address Map table contains the index of this address in the MAC Address table. The Address Map is automatically updated by the stack when a Device_annce announcement is received from a remote node (described in the Note above), but you can also add an address-pair to this table using the function zps_eAplZdoAddAddrMapEntry()- never write to the Address Map table directly. The Address Map must be properly maintained if the application employs IEEE/MAC addresses to identify remote nodes. In addition, when application- level security (see Section 6.8) is used in sending data from one node to another, the Address Map on the sending node must contain an entry for the target node.

Obtaining IEEE address

You may wish to obtain the IEEE address of the node with a given network address - for example, in order to know which physical node corresponds to a particular dynamically allocated network address.

The IEEE address of the local node can be obtained simply by calling the function zps_u64AplZdoGetIeeeAddr()

The IEEE address of a remote node can be obtained in either of two ways, depending on whether an entry for the node exists in the local Address Map table:

  • The function zps_u64AplZdoLookupIeeeAddr() can be used to search the local Address Map table for the IEEE address which corresponds to a given network address.

  • The required IEEE address can be obtained directly from the remote node by using the function zps_eAplZdpIeeeAddrRequest() to submit a request for the IEEE address of the node with a particular network address. This request, of type IEEE_addr_req, is sent in an APDU (Application Protocol Data Unit) which must first be allocated using the PDUM function PDUM_hAPduAllocateAPduInstance(). The request details are specified through the structure zps_tsAplZdpIeeeAddrReq, which includes an option to also request the IEEE addresses of all the target node’s children (if any). The results are reported in an IEEE_addr_resp response.

Parent topic:Obtaining and maintaining node addresses

Obtaining network address

You may wish to obtain the network address of the node with a given IEEE address - for example, in order to know the network address that has been dynamically allocated to a particular physical node.

The network address of the local node can be obtained simply by calling the functionzps_u16AplZdoGetNwkAddr().

The network address of a remote node can be obtained in either of two ways, depending on whether an entry for the node exists in the local Address Map table:

  • zps_u16AplZdoLookupAddr() can be used to search the local Address Map table for the network address which corresponds to a given IEEE address.

  • The required network address can be obtained directly from within the network by using the function zps_eAplZdpNwkAddrRequest() to submit a request for the network address of the node with a particular IEEE address. This request can be either unicast or broadcast, as follows:

    • Unicast to another node that will ‘know’ the required network address (this may be the parent of the node of interest or the Coordinator)

    • Broadcast to the network

This request, of type NWK_addr_req, is sent in an APDU (Application Protocol Data Unit) which must first be allocated using the PDUM function PDUM_hAPduAllocateAPduInstance(). The request details are specified through the structure zps_tsAplZdpNwkAddrReq, which includes an option to also request the network addresses of all the target node’s children (if any). The results are reported in a NWK_addr_resp response.

Parent topic:Obtaining and maintaining node addresses

Parent topic:Discovering the network

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

Maintaining a primary discovery cache

Some routing nodes of a ZigBee PRO network may be capable of hosting a primary discovery cache, which contains ‘discovery information’ relating to other nodes in the network - see Primary Discovery Cache.

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.

Functions are provided for storing the local node’s ‘discovery information’ in another node’s primary discovery cache (normally in the parent or another ascendant node). First of all, zps_eAplZdpDiscoveryStoreRequest() must be called to allocate memory space for this information in the remote node’s cache. This function sends a Discovery_store_req request to the remote node, which replies with a Discovery_store_rsp response. The local node’s information can then be stored in the remote node’s primary discovery cache using the following functions (which all operate on a request/response basis):

  • Node descriptor: Stored using zps_eAplZdpNodeDescStoreRequest()

  • Power descriptor: Stored using zps_eAplZdpPowerDescStoreRequest()

  • Simple descriptor: Stored using zps_eAplZdpSimpleDescStoreRequest()

  • Active endpoints list: Stored using zps_eAplZdpActiveEpStoreRequest()

A node’s information can be removed from a primary discovery cache using the function zps_eAplZdpRemoveNodeCacheRequest(). This function can be called on the local node to remove a third node’s information from the primary discovery cache of a remote node.

Parent topic:Discovering the network

Discovering Routes

The route from one network node to another can be pre-established by implementing a route discovery. As a result, each routing node along the route will contain a Routing table entry for the destination node, where this entry consists of the destination address and the ‘next hop’ address. Routing and route discovery are fully introduced in Section 3.5.

Two functions are provided in the ZigBee PRO API to initiate route discoveries:

  • zps_eAplZdoRouteRequest() can be used to establish a route from the local node to a specific destination node. This kind of end-to-end route discovery is outlined in Section 3.5.2.

  • zps_eAplZdoManyToOneRouteRequest() can be used on a ‘concentrator’ node to implement a ‘many-to-one’ route discovery back to itself. The result is that Routing tables in routing nodes within a certain radius of the concentrator will acquire entries with the concentrator as the destination. Many-to-one routing is outlined in Section 3.5.3.

Parent topic:Discovering the network

Parent topic:Application coding with ZigBee PRO APIs