Network commissioning

Network commissioning covers the following activities:

  • Creating a network

  • Allowing devices to join the network (through the local node)

  • Joining a network

  • Binding a local endpoint to an endpoint on a remote node

  • Adding a remote node to a group

The commissioning activities performed by an individual node depend on the ZigBee node type (Coordinator, Router, End Device) and the commissioning modes that are enabled for the node. A number of different commissioning modes are available through the ZigBee Base Device. These modes are listed in the table below along with the commissioning activities that they support.
Functionality of Commissioning Modes

Commissioning mode

Functionality

Touchlink

•  Creating a new network
•  Allowing other devices to join an existing network
•  Joining local device to an existing network

Network steering

•  Allowing other devices to join an existing network
•  Joining local device to an existing network

Network formation

•  Creating a new network

Finding and binding

•  Binding a local endpoint to an endpoint on a remote node
•  Adding a remote node to a group

The commissioning modes are individually enabled/disabled via the attribute u8bdbCommissioningMode, as indicated in the table below. This attribute is a bitmap with a bit for each of four commissioning mode - a bit is to ‘1’ to enable or ‘0’ to disable the corresponding commissioning mode. Enumerations are available to enable the individual modes (set their bits to ‘1’).

Commissioning Modes (configured via bdbCommissioningMode)

Bit

Commissioning mode

Enumeration

0

Touchlink

BDB_COMMISSIONING_MODE_TOUCHLINK

1

Network steering

BDB_COMMISSIONING_MODE_NWK_STEERING

2

Network formation

BDB_COMMISSIONING_MODE_NWK_FORMATION

3

Finding and binding

BDB_COMMISSIONING_MODE_FINDING_N_BINDING

The current commissioning state on a node is reflected in the attribute ebdbCommissioningStatus.

In the NXP implementation of the ZigBee Base Device, the individual commissioning modes are initiated under application control using supplied API functions. A commissioning mode is invoked by the application if the mode is enabled and the node type is relevant to the mode (for example, an End Device cannot perform Network Formation).

The commissioning modes are outlined in the subsections below. For detailed information on these modes, refer to the ZigBee Base Device Behavior Specification (13-0402-08).

Note: A node is normally be prompted to enter commissioning by a user action, such as pressing a button on the node. This action may be on behalf of the node as a whole or a single endpoint on the node.

Network steering

Network Steering is used to join the local node to an existing network or allow other nodes to join a network via the local node.

If Network Steering is required on a node, enable it via the attribute u8bdbCommissioningMode. You can start Network Steering from your application by calling the function BDB_eNsStartNwkSteering().

The path taken depends on whether the local node is already a member of a network, as indicated by the Boolean attribute bbdbNodeIsOnANetwork. In all cases, the outcome of Network Steering is indicated by events passed into the callback function APP_vBdbCallback().

Node is already on a network

When the node is a member of a network, it opens the network for other nodes to join for a fixed time period. It performs this by broadcasting a Management Permit Joining request (any node type can open the network in this way). This period is 180 seconds by default, but can be configured (in seconds) through the ZigBee Base Device constant BDBC_MIN_COMMISSIONING_TIME (see Constants). After initiating the above broadcast, the event BDB_EVENT_NWK_STEERING_SUCCESS is generated.

Node is not on a network

When the node is not a member of a network and is a Router or End Device, it searches for a suitable network to join. If it finds one, it attempts to join the network, as follows:

  1. The node performs a network discovery by scanning the primary set of radio channels specified through the u32bdbPrimaryChannelSet bitmap (attribute). If no open network is found, the network discovery is repeated on the secondary set of radio channels specified through the u32bdbSecondaryChannelSet bitmap (attribute). If still no network is found, the event BDB_EVENT_NO_NETWORK is generated and the Network Steering is abandoned.

  2. If at least one open network is found, the node then attempts to join each discovered open network one by one, up to a maximum of BDBC_MAX_SAME_NETWORK_RETRY_ATTEMPTS times. If a network is successfully joined, the attribute bbdbNodeIsOnANetwork is set to TRUE. If there is no successful join following a scan of the primary channels, the scan is repeated (Step 1) on the secondary channels. If there is still no successful join following this scan, the BDB_EVENT_NWK_JOIN_FAILURE event is generated and the Network Steering is abandoned.

  3. The joining node is authenticated and receives the network key from its parent. If the network being joined has centralized security and therefore a Trust Centre, the node unicasts a Node Descriptor request to the Trust Centre. The Node Descriptor received back is checked to ensure that the Trust Centre supports the ZigBee PRO stack version r21 or above. If so, the node performs the procedure for retrieving a new Trust Centre link key to replace its pre-configured link key. Failure at any point is indicated to the application by a BDB_EVENT_NWK_JOIN_FAILURE event.

  4. On successful completion of the above steps, the joining node requests that the ‘permit joining’ time (for new nodes to join the network) is extended by BDBC_MIN_COMMISSIONING_TIME (180 s by default) and generates a BDB_EVENT_NWK_STEERING_SUCCESS event for the application.

Depending on the outcome of the above Network Steering process:

  • If the node successfully joins a network, you may wish to bind the node to another node or add the node to a group, wherein it is necessary to continue to the Finding and Binding stage, described in Finding and Binding.

  • If the node fails to join a network, you may wish to make sure that the desired network is open for joining and reinitiate this Network Steering procedure. If there is a Router node, the application may opt to form its own distributed network, wherein it is necessary to continue to the Network Formation stage described in Network Formation.

Parent topic:Network commissioning

Network Formation

Network Formation allows a new network to be created by a Coordinator or Router.

  • A Coordinator forms a centralized security network (see Section 2.3.1) and activate its Trust Centre functionality.

  • A Router forms a distributed security network (see Section 2.3.2).

If Network Formation is required on a node, enable it via the attribute u8bdbCommissioningMode. You can start Network Formation from your application by calling the function BDB_eNfStartNwkFormation().

The node performs a scan of the primary set of radio channels specified through the u32bdbPrimaryChannelSet bitmap (attribute) to form a centralized or distributed network with a unique PAN ID on one of the free primary channels. If this network formation fails or the primary channel bitmap is set to zero, the node performs a scan of the secondary set of radio channels. these radio channels are specified through the u32bdbSecondaryChannelSet bitmap (attribute) to form a centralized or distributed network with a unique PAN ID on one of the free secondary channels.

During the formation of a distributed security network by a Router:

  • The above channel scans start with the first channel of the relevant set and cover all the specified channels.

  • If the macro RAND_CHANNEL is TRUE (in the application), a channel is selected at random from the scanned channels.

  • The macro RAND_DISTRIBUTED_NWK_KEY is set to TRUE to choose a network key at random (but may be set to FALSE during application development in order to use a specific network key).

  • The PAN ID and Extended PAN ID are allocated at random (but must not clash with the other networks operating in the neighbourhood).

  • The 16-bit network address of the local is allocated at random.

In all cases, successful Network Formation is indicated by the event BDB_EVENT_NWK_FORMATION_SUCCESS through the callback function APP_vBdbCallback(). The unsuccessful Network Formation is indicated by the event BDB_EVENT_NWK_FORMATION_FAILURE.

If Network Formation is successful, the new network consists of just one node. Further nodes are added to the network using Network Steering (see Network steering) or Touchlink (see Touchlink).

Parent topic:Network commissioning

Finding and Binding

Finding and Binding mode allows a node in the network to pair with another network node - for example, a new lamp may pair with a controller device, to allow control of the lamp. The objective of this commissioning mode is to bind an endpoint on a new node to a compatible endpoint on a remote node in the network (depending on the supported clusters). Alternatively, the new node is added to a group of nodes that are collectively controlled.

If it is required on a node, enable Finding and Binding via the attribute u8bdbCommissioningMode.

In Finding and Binding, a node have one of two roles:

  • Initiator: This node either creates a (local) binding with a remote endpoint or requests that the remote endpoint is added to a group.

  • Target: This node identifies itself, and receives and responds to requests from the initiator.

The intended outcome is a pairing between the initiator and the target. Usually, the initiator is a controller device. The path followed by the Finding and Binding process depends on whether the local endpoint is an initiator or a target.

Initiator Node

Finding and Binding is started on an initiator node by calling the function BDB_eFbTriggerAsInitiator(). This function is called as the result of a user action on the node, such as a button-press. The initiator then remains in Finding and Binding mode for a fixed time-interval (in seconds) defined by the constant BDBC_MIN_COMMISSIONING_TIME. If Finding and Binding does not succeed within this time, the event BDB_EVENT_FB_TIMEOUT is generated and passed into the callback function APP_vBdbCallback().

Once Finding and Binding starts, the initiator node searches for target endpoints by broadcasting an Identify Query command periodically with a period (in seconds) defined through the macro BDB_FB_RESEND_IDENTIFY_QUERY_TIME.

Note: Before each broadcast attempt, the event BDB_EVENT_FB_NO_QUERY_RESPONSE is generated and passed into APP_vBdbCallback(). This event allows the application to exit the current Finding and Binding process (see below).

If the initiator receives an Identify Query response from a remote endpoint, the application must pass the ZCL event BDB_E_ZCL_EVENT_IDENTIFY_QUERY to the Base Device using the function BDB_vZclEventHandler(). This event allows the Base Device to gather information about the identifying device by sending a Simple Descriptor request to the relevant endpoint. If the requested Simple Descriptor is successfully received back, the callback function checks this descriptor for clusters that match those on the initiator. The application is notified of via a BDB_EVENT_FB_HANDLE_SIMPLE_DESC_RESP_OF_TARGET event passed into APP_vBdbCallback().

If there is at least one matching cluster, the initiator does one of the following:

  • If binding is required (indicated by the u16bdbCommissioningGroupID attribute being equal to 0xFFFF), the initiator adds the remote endpoint to the local Binding table (but should first request the IEEE/MAC address of the remote node).

  • If grouping is required (indicated by the u16bdbCommissioningGroupID attribute being equal to a 16-bit group address), the initiator requests that the target endpoint adds the group address to its Group Address table.

The application is notified of a successful binding or grouping via the following events:

  • For a binding:

    • BDB_EVENT_FB_BIND_CREATED_FOR_TARGET for success

    • BDB_EVENT_FB_ERR_BINDING_FAILED for failure

  • For a grouping:

    • BDB_EVENT_FB_GROUP_ADDED_TO_TARGET for success

    • BDB_EVENT_FB_ERR_GROUPING_FAILED for failure

At this point, the application can remotely stop identification mode (and therefore Finding and Binding) on the target node by calling the Identify cluster function eCLD_IdentifyCommandIdentifyRequestSend() to request that the identification mode period is set to zero.

A Finding and Binding process is stopped on the initiator endpoint using the function BDB_vFbExitAsInitiator(). This function is typically called in the callback function APP_vBdbCallback() as the result of a user action, such as a button-press or button-release.

Parent topic:Finding and Binding

Target Node

Finding and Binding is started on a target node by calling the function BDB_eFbTriggerAsTarget(). This function is called as the result of a user action on the node, such as a button-press.

The target node then uses the Identify cluster to put itself into identification mode for a fixed time period. This period (in seconds) is determined by u16IdentifyTime, an Identify cluster attribute which is automatically set to the value of the constant BDBC_MIN_COMMISSIONING_TIME. In identification mode, the cluster responds to any received Identify Query commands, as well as other Finding and Binding commands. The node may also visually or audibly indicate that it is in identification mode. On exiting identification mode at the end of the above period, the cluster is no longer able to process Identify Query commands but the node is still able to service other commands from the initiator related to the binding/grouping. The Identify cluster is fully described in the ZigBee Cluster Library User Guide (JNUG3132).

A target node can be brought out of the Finding and Binding process in either of the following ways:

  • The local application can call the function BDB_vFbExitAsTarget() as the result of a user action, such as a button-press or button-release.

  • The remote application (on the initiator) can call the Identify cluster function eCLD_IdentifyCommandIdentifyRequestSend() to request that the identification mode period is set to zero. To indicate to the Base Device that the identification process has ended, the application must pass the ZCL event BDB_E_ZCL_EVENT_IDENTIFY to the Base Device using the BDB_vZclEventHandler() function. This allows the Base Device to exit the ‘Finding and Binding’ process on the target endpoint.

Parent topic:Finding and Binding

Parent topic:Network commissioning

Out-Of-Band Commissioning

A node is commissioned to a ZigBee network via out-of-band means - that is, not using IEEE802.15.4 packets operating in the radio channel used by the target network. For example, the out-of-band commissioning is conducted from another ZigBee device using inter-PAN packets (operating in a different radio channel) or by a commissioning device that uses NFC (Near Field Communication).

Out-of-band commissioning creates a new network by starting the Coordinator or to join a Router or End Device to an existing network. To do this, commissioning data must be sent to the node via an out-of-band means. This data includes details of the network (see Section 2.7.5). The application must pass the received commissioning data to the ZigBee Base Device and start out-of-band commissioning using the function BDB_u8OutOfBandCommissionStartDevice(). The data is then stored locally.

As part of the out-of-band commissioning of a node to an existing centralized network, the Trust Centre of the joined network must validate the new node by checking that the node contains appropriate data values, such as the correct network key and Trust Centre address. If such a validation request is received by the node, the required data values are obtained by the application in either of two ways:

  • The function BDB_vOutOfBandCommissionGetData() is used to read the relevant data values. In this case, the application should encrypt the obtained network key before sending the data to the Trust Centre. The install code for the node should be used in this encryption.

  • The function BDB_eOutOfBandCommissionGetDataEncrypted() is used to read the relevant data values and encrypt the obtained network key - therefore, the network key is delivered encrypted. The install code for the node used in this encryption must be specified in the function call. The application then sends the obtained data to the Trust Centre.

Once the Trust Centre receives the requested data, it decrypts the obtained network key using the function BDB_bOutOfBandCommissionGetKey() and then checks if the correct key is used. This function requires the install code for the new node, which must be supplied to the Trust Centre via out-of-band means (for example, via a keypad).

Security keys and install codes are described in Section 2.3.

Parent topic:Network commissioning

Parent topic:ZigBee Base Device