ZigBee Base Device

The ZigBee Base Device (ZBD) is a mandatory device on all nodes of a ZigBee 3.0 network. It exists alongside one or more other ZigBee device types on a node, but does not require an endpoint. The ZigBee Base Device provides a framework for the use of ZigBee device types. It implements basic functionality that all nodes require and ensures consistent behavior across all nodes, particularly regarding network creation, joining, and security.

The network commissioning and security functionality of the ZigBee Base Device is described in this chapter. The chapter also describes the NXP resources required to implement these features in ZigBee 3.0 applications on the NXP hardware platforms: K32W148-EVK, FRDM-MCXW71, FRDM-MCXW72, MCX-W71-EVK, and MCX-W72-EVK, FRDM-RW612, and RD-RW612-BGA.
These boards (hardware platforms) belong to NXP provided K32W041, K32W061, K32W1, MCXW71, MCXW72, RW612, and JN518x family of wireless microcontrollers.

Detailed information about the ZigBee Base Device is provided in the ZigBee Base Device Behavior Specification (13-0402), available from the ZigBee Alliance.

Initializing and starting the ZigBee Base Device

Initialize the ZigBee Base Device in the application code using the function BDB_vInit(). Call this function after initializing the ZigBee PRO stack and after restoring the ZigBee Base Device attribute bbdbNodeIsOnANetwork from persistent storage.

Note:

  1. BDB_vInit() internally calls the function BDB_vSetKeys(), which loads into memory the pre-configured link key from the file bdb_link_keys.c. Network security and the pre-configured link keys are described in Section 2.3.

  2. The ZigBee Base Device requires a number of internal software times, the number defined by the macro BDB_ZTIMER_STORAGE. Therefore, when the application calls ZTIMER_eInit() to initialize the required software timers and allocate storage (array elements) for them, it must add BDB_ZTIMER_STORAGE timers for use by the ZigBee Base Device. This function must be called before BDB_vInit(). Software timers and their associated functions are described in the ZigBee 3.0 Stack User Guide (JNUG3130).

The ZigBee Base Device is started by calling the function BDB_vStart(). This function may or may not perform an action. It depends on the node type and whether the node was previously a member of a network. In both cases, the function finally invokes the callback function APP_vBdbCallback() with a suitable event.

If the node was not on a network:

For a Router node that supports Touchlink commissioning (see Touchlink), the function selects a radio channel for the node from the set of primary channels for Touchlink specified in the BDBC_TL_PRIMARY_CHANNEL_SET bitmap (see Touchlink constants). Either the first channel of the specified set selects or, if the macro RAND_CHANNEL is set to TRUE (in the file bdb_options.h), a channel selects from the set at random.

For the Coordinator and other Router and End Device nodes, no action is taken. The application must then form a network (Coordinator or Router). Alternatively, it can join the node to a network using one of the commissioning methods described in Network commissioning (End Device or Router).

In the above cases, the function generates a BDB_EVENT_INIT_SUCCESS event.

If the node was on a network:

For Coordinator and Router nodes, no action is taken and the function generates a BDB_EVENT_INIT_SUCCESSevent.

For an End Device node, the function attempts to rejoin the node to the network. It performs a series of rejoin cycles, where each cycle comprises the following three rejoin attempts:

  1. First attempt with the previously used network parameters (without network discovery)

  2. Second attempt with network discovery on the set of primary channels specified in the u32bdbPrimaryChannelSet bitmap (attribute)

  3. Third attempt with network discovery on the set of secondary channels specified in the u32bdbSecondaryChannelSet bitmap (attribute)

The channel bitmaps are ZigBee Base Device attributes, described in Section 2.5.1.

The above rejoin cycle performs up to a maximum of BDBC_IMP_MAX_REJOIN_CYCLES times, which is an implementation-specific ZigBee Base Device constant (see Section 2.5.2).

If a rejoin attempt is successful, the function generates the event BDB_EVENT_REJOIN_SUCCESS.

If all the rejoin attempts are unsuccessful, the function generates the event BDB_EVENT_REJOIN_FAILURE unless unsecured joins are enabled through the APS attribute apsUseInsecureJoin, in which case the function attempts a join through Network Steering (described in Network steering). The nature of the join depends on the value of the Extended PAN ID (EPID) set in the APS attribute ApsUseExtendedPanid:

  • For a non-zero EPID, the node attempts to join the network with this EPID.

  • For a zero EPID, the function attempts to join any available network.

This join is attempted with an automatic call to the functionBDB_eNsStartNwkSteering().

Parent topic:ZigBee Base Device

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

Network security

The ZigBee Base Device supports the following network security modes:

  • Centralized security

  • Distributed security

These security modes are described in the subsections below:

All Router and End Device nodes should support both centralized security and distributed security by adapting to the security scheme employed by the network that they join. A Co-ordinator supports only centralized security.

When the application calls BDB_vInit(), this function internally calls the function BDB_vSetKeys(). This function loads the appropriate pre-configured link key, depending on whether the node type supports centralized and/or distributed security. The pre-configured link keys are defined in the file bdb_link_keys.c.

Centralized security networks

A centralized security network is formed by a Coordinator, which also acts as the Trust Centre for the network. When a node attempts to join the network, it is authenticated by this Trust Centre before it is allowed into the network.

For participation in centralized security networks, all nodes must be pre-configured with a link key. This key is used to encrypt the network key when passing it from the Trust Centre to a newly joined node. When a node joins a network with centralized security, the ZigBee Base Device automatically uses the relevant pre-configured link key. Similar is the case for a Coordinator that forms a new centralized security network.

The following key types can be pre-configured for centralized security:

  • Default Global Trust Centre Link Key: This key is factory-programmed into all nodes and is used to encrypt communications between the Trust Centre and a joining node.

  • Touchlink Pre-configured Link Key: This key is factory-programmed into all nodes that can employ Touchlink commissioning and is used to encrypt communications between the Router parent and a joining node. The Touchlink Pre-configured Link Key can be one of three types:

    • Development key, used during development before ZigBee certification

    • Master key, used after successful ZigBee certification

    • Certification key, used during ZigBee certification testing

      • The link key used in the final products should be a ‘master key’, which results from the successful ZigBee certification of the product.

  • Install Code-derived Pre-configured Link Key: This key is derived by the ZigBee stack from a random install code which is assigned to each Router and End Device node in the factory. The install code is factory-programmed into the node but provided to the Trust Centre via out-of-band means when the node is commissioned. The use of install codes is described in more detail below.

Install Codes

An install code is used to create an initial link key employed in commissioning an individual node into a centralized security network. An install code is assigned to the node in the factory. It is a random code but is not necessarily unique (the same install code may be randomly generated for more than one node). The ZigBee stack derives a link key from the install code using a Matyas-Meyer-Oseas hash function. The install code is factory-programmed into the node and also accompanies the node (for example: in printed form) when it leaves the factory. The process of using an install code to commission a node is outlined below.

In the factory:

  1. An install code is randomly generated for the individual node.

  2. The install code is programmed into the node.

  3. A pre-configured link key is derived from the install code by the ZigBee stack.

  4. The install code is shipped with the node (by some unspecified means).

During installation:

  1. The install code that was shipped with the node is installed into the Co-ordinator/Trust Centre.

  2. The pre-configured link key is derived from the install code by the ZigBee stack of the Co-ordinator/Trust Centre.

  3. The Trust Centre and node then use the pre-configured link key in joining the node to the network (for example: to encrypt/decrypt the network key).

More detailed information about install codes are available in the ZigBee Base Device Behavior Specification (13-0402-08).

Parent topic:Network security

Distributed security networks

A distributed security network is formed by a Router and does not have a Trust Centre. It consists only of Routers and End Devices. When a node attempts to join the network, it is authenticated by its Router parent before it is allowed into the network.

For participation in distributed security networks, all Router and End Device nodes must be pre-configured with a link key. This key is used to encrypt the network key when passing it from a Router parent to a newly joined node. When a Router or End Device joins a network with distributed security, the ZigBee Base Device automatically uses the relevant pre-configured link key. Similar is the case for a Router that forms a new distributed security network.

The following key types can be pre-configured for distributed security:

  • Distributed Security Global Link Key: This key is factory-programmed into all nodes and is used to encrypt communications between the Router parent and a joining node.

  • Touchlink Pre-configured Link Key: This key is factory-programmed into all nodes that can employ Touchlink commissioning and is used to encrypt communications between the Router parent and a joining node. The Touchlink Pre-configured Link Key can be one of three types:

    • Development key, used during development before ZigBee certification

    • Master key, used after successful ZigBee certification

    • Certification key, used during ZigBee certification testing

      • The link key used in the final products should be a ‘master key’, which results from the successful ZigBee certification of the product.

Parent topic:Network security

Parent topic:ZigBee Base Device

ZigBee base device rejoin handling

For a Router or End Device, there are instances in which the ZigBee PRO stack initiates a network rejoin attempt and include:

  • A Router or End Device which receives a ‘leave with rejoin’ request.

  • An End Device which polls its parent for data but fails to receive a response.

The ZigBee Base Device handles the stack events that result from this rejoin attempt:

  • If the stack event ZPS_EVENT_NWK_FAILED_TO_JOIN is received to indicate an unsuccessful rejoin, the ZigBee Base Device makes a series of rejoin attempts as described for the case “If the node was in a network” in Section 2.1. If a rejoin attempt is successful, the event BDB_EVENT_REJOIN_SUCCESS is generated to notify the application. If all rejoins are unsuccessful, the event BDB_EVENT_REJOIN_FAILURE is generated unless unsecured joins are enabled, in which case a join through Network Steering is attempted.

  • If the stack event ZPS_EVENT_NWK_JOINED_AS_ROUTER or ZPS_EVENT_NWK_JOINED_AS_END_DEVICE is received to indicate a successful rejoin, the event BDB_EVENT_REJOIN_SUCCESS is generated to notify the application.

Parent topic:ZigBee Base Device

Attributes and Constants

Attributes

The attributes of the ZigBee Base Device are contained in the structure BDB_tsAttrib, shown below:

typedefstruct
{
    uint16 u16bdbCommissioningGroupID;
    uint8 u8bdbCommissioningMode;
    BDB_teCommissioningStatusebdbCommissioningStatus;
    uint64 u64bdbJoiningNodeEui64;
    uint8 au8bdbJoiningNodeNewTCLinkKey[16];
    bool_tbbdbJoinUsesInstallCodeKey;
    const uint8 u8bdbNodeCommissioningCapability;
    bool_tbbdbNodeIsOnANetwork;
    uint8 u8bdbNodeJoinLinkKeyType;
    uint32 u32bdbPrimaryChannelSet;
    uint8 u8bdbScanDuration;
    uint32 u32bdbSecondaryChannelSet;
    uint8 u8bdbTCLinkKeyExchangeAttempts;
    uint8 u8bdbTCLinkKeyExchangeAttemptsMax;
    uint8 u8bdbTCLinkKeyExchangeMethod;
    uint8 u8bdbTrustCenterNodeJoinTimeout;
    bool_tbbdbTrustCenterRequireKeyExchange;
    bool_tbTLStealNotAllowed;
    bool_tbLeaveRequested;
}BDB_tsAttrib;

For information on compile-time options, refer to Compile-time Options. The attributes are written to or read at run time through the above structure. The ZigBee Base Device attribute values are initialized at compile time in the bdb_options.h file using the macros listed in the table below.

Note: Both bTLStealNotAllowed and bLeaveRequested are NXP proprietary variables and not ZigBee attributes. Table: ZBD Attributes and Initialization Macros

Attribute

Initialization Macro

u16bdbCommissioningGroupID

BDB_COMMISSIONING_GROUP_ID

u8bdbCommissioningMode

BDB_COMMISSIONING_MODE

ebdbCommissioningStatus

BDB_COMMISSIONING_STATUS

u64bdbJoiningNodeEui64

BDB_JOINING_NODE_EUI64

au8bdbJoiningNodeNewTCLinkKey[16]

-

bbdbJoinUsesInstallCodeKey

BDB_JOIN_USES_INSTALL_CODE_KEY

u8bdbNodeCommissioningCapability

-

bbdbNodeIsOnANetwork

-

u8bdbNodeJoinLinkKeyType

BDB_NODE_JOIN_LINK_KEY_TYPE

u32bdbPrimaryChannelSet

BDB_PRIMARY_CHANNEL_SET

u8bdbScanDuration

BDB_SCAN_DURATION

u32bdbSecondaryChannelSet

BDB_SECONDARY_CHANNEL_SET

u8bdbTCLinkKeyExchangeAttempts

BDB_TC_LINK_KEY_EXCHANGE_ATTEMPTS

u8bdbTCLinkKeyExchangeAttemptsMax

BDB_TC_LINK_KEY_EXCHANGE_ATTEMPTS_MAX

u8bdbTCLinkKeyExchangeMethod

BDB_TC_LINK_KEY_EXCHANGE_METHOD

u8bdbTrustCenterNodeJoinTimeout

BDB_TRUST_CENTER_NODE_JOIN_TIMEOUT

bbdbTrustCenterRequireKeyExchange

BDB_TRUST_CENTER_REQUIRE_KEYEXCHANGE

bTLStealNotAllowed

-

bLeaveRequested

-

The attributes are individually described below. For further details, refer to the ZigBee Base Device Behavior Specification (13-0402-08).

u16bdbCommissioningGroupID

This attribute can only be used on a Finding and Binding initiator endpoint. It contains the identifier of the group in which the initiator puts the target endpoints. If it is equal to 0xFFFF, individual (rather than group) bindings are created. The value of this attribute can be initialized at compile time using the macro BDB_COMMISSIONING_GROUP_ID.

Use of this attribute requires Finding and Binding to be enabled in the u8bdbCommissioningMode attribute.

The Finding and Binding commissioning mode is described in Finding and Binding.

u8bdbCommissioningMode

This attribute is a bitmap used to indicate which commissioning modes are enabled on an endpoint. Each bit corresponds to a commissioning mode and is set (to ‘1’) when the mode is enabled - this means that the node is able to implement this commissioning mode, if necessary. The value of this attribute can be initialized at compile time using the macro BDB_COMMISSIONING_MODE. The bitmap, along with the enumerations used to set the bits is illustrated in the table below.

Table: u8bdbCommissioningMode bitmap

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

4-7

Reserved (set to ‘0’)

-

The commissioning modes are described in Network commissioning.

Note: The attribute is used on all node types. However, in order to enable a commissioning mode, it must be available on the node, as indicated through the attribute u8bdbNodeCommissioningCapability. The enabled commissioning modes are a subset of the commissioning capabilities of the node.

ebdbCommissioningStatus

This attribute indicates the status of the commissioning process that is underway on an endpoint. The attribute takes one of the values defined in the BDB_teCommissioningStatus enumerations (see BDB_teCommissioningStatus). The attribute is used on all node types. The value of this attribute is updated internally by the ZigBee Base Device implementation, but can be read by the application.

u64bdbJoiningNodeEui64

This attribute contains the 64-bit IEEE/MAC address of a node that is in the process of joining a centralized security network. It is used on the network Coordinator only. The value of this attribute is updated internally by the ZigBee Base Device implementation.

au8bdbJoiningNodeNewTCLinkKey

This attribute contains a new link key for use with a node that is joining the network but has not yet been granted full network membership. The value of this attribute is updated internally by the ZigBee Base Device implementation (on a joining node and its parent).

bbdbJoinUsesInstallCodeKey

This attribute indicates whether a pre-configured link key must be available for a node before it is allowed to join the network - this may be a pre-installed link key or may be derived from an install code. A value of TRUE means that a link key is required, while FALSE means that a link key is not required. It is used on the network Co-ordinator/Trust Centre only. The value of this attribute can be initialized at compile time using the macro BDB_JOIN_USES_INSTALL_CODE_KEY. By default, the attribute should be set to FALSE. The attribute is not used by the ZigBee Base Device. If the attribute is set to TRUE, it is the responsibility of the application to handle this functionality directly and to set the required key (see the attribute u8bdbNodeJoinLinkKeyType).

u8bdbNodeCommissioningCapability

This attribute is a bitmap indicating the commissioning capabilities of the node. Each bit corresponds to a commissioning capability and is set (to ‘1’) if the capability is present. The attribute is used on all node types. The application cannot write directly to these bits - they are set according to the options defined in the application makefile. The bitmap and the related makefile options are detailed in the Table below.

Table: bdbCommissioningCapability Bitmap

Bit

Capability

Makefile Options

0

Network Steering

Is set to ‘1’ if BDB_SUPPORT_NWK_STEERING is defined

1

Network Formation

Is set to ‘1’ if BDB_SUPPORT_NWK_FORMATION is defined

2

Finding and Binding

Is set to ‘1’ if either of the following is defined:
•  BDB_SUPPORT_FIND_AND_BIND_INITIATOR
•  BDB_SUPPORT_FIND_AND_BIND_TARGET

3

Touchlink

Is set to ‘1’ if any of the following is defined:
•  BDB_SUPPORT_TOUCHLINK_INITIATOR_END_DEVICE
•  BDB_SUPPORT_TOUCHLINK_INITIATOR_ROUTER
•  BDB_SUPPORT_TOUCHLINK_TARGET

4-7

Reserved (set to ‘0’)

-

The above commissioning modes are described in Network commissioning.

Note: In order to use one of the available commissioning modes, the mode must also be enabled through the attribute u8bdbCommissioningMode. The enabled commissioning modes are a subset of the commissioning capabilities of the node.

bbdbNodeIsOnANetwork

This attribute indicates whether the local node is a member of a network. A value of TRUE means that it is in a network (but not necessarily bound to any remote nodes), while FALSE means that it is not in a network. The attribute is used on all node types but the ZigBee Base Device does not maintain it. The application is responsible for persisting the attribute value and initializing the attribute following a power-cycle (before any other ZigBee Base Device functions are called).

u8bdbNodeJoinLinkKeyType

This attribute indicates the type of link key with which the node is able to decrypt the encrypted network key received over-air when the node joins a new network. The attribute is used by Router and End Device nodes. The attribute values and the corresponding link key types as well as the macros use to define the link keys are listed in the table below.
Table: bdbNodeJoinLinkKeyType Values and Macros

Value

Link Key Type

Link Key Definition Macro

0x00

Default global trust Centre link key

DEFAULT_GLOBAL_TRUST_CENTER_LINK_KEY

0x01

Distributed security global link key

DISTRIBUTED_SECURITY_GLOBAL_LINK_KEY

0x02

Install code derived pre-configured link key

INSTALL_CODE_DERIVED_PRECONFIGURED_LINK _ KEY

0x03

Touchlink pre-configured link key

TOUCHLINK_PRECONFIGURED_LINK_KEY

u32bdbPrimaryChannelSet

This attribute specifies the primary (first-choice) set of 2.4 GHz radio channels that are used in channel scans. The attribute is a bitmap in which each bit corresponds to a channel and should be set to ‘1’ if the channel is to be included in a scan. The bit number corresponds directly to the channel number - for example, bit 11 corresponds to the 2.4 GHz channel 11 and bit 26 corresponds to channel 26. This attribute is used on all node types. The value of this attribute can be initialized at compile time using the macro BDB_PRIMARY_CHANNEL_SET.

u8bdbScanDuration

This attribute determines the duration of a scan operation per 2.4 GHz radio channel. The actual scan duration is calculated from the attribute value as follows:

aBaseSuperframeDuration x (2bdbScanDuration + 1)

where aBaseSuperframeDuration is defined in the IEEE 802.15.4 specification.

The attribute is used on all node types. The value of this attribute is taken from the Scan Duration Time set in the ZPS Configuration Editor.

u32bdbSecondaryChannelSet

This attribute specifies the secondary (second-choice) set of 2.4 GHz radio channels that are used in channel scans. This channel set is used if the scan of primary channels is unsuccessful. The attribute is a bitmap in which each bit corresponds to a channel. In order to include the channel in a scan, set each bit to ‘1’. The bit number corresponds directly to the channel number - for example, bit 11 corresponds to the 2.4 GHz channel 11 and bit 26 corresponds to channel 26. If a scan of secondary channels is not required, the attribute should be set to zero. The attribute is used on all node types. The value of this attribute can be initialized at compile time using the macro BDB_SECONDARY_CHANNEL_SET.

u8bdbTCLinkKeyExchangeAttempts

This attribute indicates the number of attempts to request a new link key that were made when the node joined the network. The attribute is used on Router and End Device nodes. The value of this attribute can be initialized at compile time using the macro BDB_TC_LINK_KEY_EXCHANGE_ATTEMPTS.

u8bdbTCLinkKeyExchangeAttemptsMax

This attribute specifies the maximum number of key establishment attempts that are made before key establishment is abandoned when the node joins a new network. The attribute is used on Router and End Device nodes. The value of this attribute can initialized at compile time using the macro BDB_TC_LINK_KEY_EXCHANGE_ATTEMPTS_MAX.

u8bdbTCLinkKeyExchangeMethod

This attribute specifies the method that was used to obtain a new link key when the node joined the network. The attribute values and corresponding methods are listed in the table below. This attribute is used on Router and End Device nodes.

Table: bdbTCLinkKeyExchangeMethod Values

Value

Key Exchange Method

0x00

APS Request Key

0x01

Certificate Based Key Exchange (CBKE)

The value of this attribute can be initialized at compile time using the macro BDB_TC_LINK_KEY_EXCHANGE_METHOD. It should be initialized to 0x00 (APS Request Key).

u8bdbTrustCenterNodeJoinTimeout

This attribute specifies a timeout (in seconds) for the Trust Centre to delete the Trust Centre-generated link key for a newly joined node when key establishment with the node was unsuccessful. The attribute is used on the network Co-ordinator/Trust Centre only. The value of this attribute can be initialized at compile time using the macro BDB_TRUST_CENTER_NODE_JOIN_TIMEOUT.

bbdbTrustCenterRequireKeyExchange

This attribute specifies whether the Trust Centre requires a joining node to replace its initial link key with a new link key generated by the Trust Centre. A value of TRUE means that the joining node successfully completes the link key exchange procedure and failure to do so results in the node being removed from the network. A value of FALSE means that the joining node is allowed to remain in the network even if it does not successfully complete the link key exchange procedure. The attribute is used on the network Co-ordinator/Trust Centre only. The value of this attribute is initialized at compile time using the macro BDB_TRUST_CENTER_REQUIRE_KEYEXCHANGE. It should be initialized according to the Trust Centre policy that is implemented in the network - by default, set it to FALSE for backward compatibility.

bTLStealNotAllowed

This attribute is an NXP proprietary flag which the application can set to prevent Touchlink commissioning commands from another node in a different network from ‘stealing’ the local node. Clearing the flag allows the node to be stolen, in which case it leaves the current network and either joins the other network or forms a new distributed network, as instructed by Touchlink initiator.

bLeaveRequested

This attribute is an NXP proprietary flag which the application should only read and not write to. If Touchlink commissioning operations cause the ZigBee Base Device to initiate a network leave, then this flag is set by the Base Device. When a ZPS_EVENT_NWK_LEAVE_CONFIRM stack event is generated, the application should read this flag. If it reads as TRUE, the application should not handle the event (since the ZigBee Base Device handles it).

Parent topic:Attributes and Constants

Constants

The ZigBee Base Device constants are divided into two categories:

General constants

The table below lists the ZigBee Base Device constants that can be used on all nodes and also shows the corresponding macros used to define the constant values in the bdb_options.h file.

Table: ZBD General Constants and Macros

Constant

Macro

bdbcMaxSameNetworkRetryAttempts

BDBC_MAX_SAME_NETWORK_RETRY_ATTEMPTS

bdbcMinCommissioningTime

BDBC_MIN_COMMISSIONING_TIME

bdbcRecSameNetworkRetryAttempts

BDBC_REC_SAME_NETWORK_RETRY_ATTEMPTS

bdbcTCLinkKeyExchangeTimeout

BDBC_TC_LINK_KEY_EXCHANGE_TIMEOUT
bdbcMaxSameNetworkRetryAttempts

This constant specifies the maximum number of join or key exchange attempts that the node can make on the same network. The value of this constant is defined using the macro BDBC_MAX_SAME_NETWORK_RETRY_ATTEMPTS and should be set to 10 (as recommended in the ZigBee BDB Specification).

bdbcMinCommissioningTime

This constant specifies the minimum time-interval (in seconds) for which a network is open to allow new nodes to join or for a device to identify itself. The value of this constant is defined using the macro BDBC_MIN_COMMISSIONING_TIME and should be set to 180 (as recommended in the ZigBee BDB Specification).

bdbcRecSameNetworkRetryAttempts

This constant specifies the recommended number of join or key exchange attempts that the node can make on the same network. The value of this constant is defined using the macro BDBC_REC_SAME_NETWORK_RETRY_ATTEMPTS and should be set to 3 (as recommended in the ZigBee BDB Specification).

bdbcTCLinkKeyExchangeTimeout

This constant specifies the maximum time (in seconds) for which a joining node will wait for a response after an APS key request has been sent to the Trust Centre. The value of this constant is defined using the macro BDBC_TC_LINK_KEY_EXCHANGE_TIMEOUT and should be set to 5 (as recommended in the ZigBee BDB Specification).

Parent topic:Constants

Functions

This section details the C functions that are provided for the ZigBee Base Device. The functions are listed below along with the references to their descriptions.

  1. BDB_vInit

  2. BDB_vSetKeys

  3. BDB_vStart

  4. BDB_eNfStartNwkFormation

  5. BDB_eNsStartNwkSteering

  6. BDB_eFbTriggerAsInitiator

  7. BDB_vFbExitAsInitiator

  8. BDB_eFbTriggerAsTarget

  9. BDB_vFbExitAsTarget

  10. BDB_bIsBaseIdle

  11. BDB_u8OutOfBandCommissionStartDevice

  12. BDB_vOutOfBandCommissionGetData

  13. BDB_eOutOfBandCommissionGetDataEncrypted

  14. BDB_bOutOfBandCommissionGetKey

Note:

  1. The application must provide a user-defined callback function, APP_vBdbCallback(), to handle ZigBee Base Device events. The prototype for this function is given in Events.

  2. The ZigBee Base Device supplies the callback function BDB_vZclEventHandler(), which handles certain ZCL events during the Finding and Binding process, as indicated in Finding and Binding.

BDB_vInit

void BDB_vInit(BDB_tsInitArgs *psInitArgs);

Description

This function initializes the ZigBee Base Device (ZBD) and must be the first ZigBee Base Device function called in your code. The function must be called after initializing the ZigBee PRO stack via a call to ZPS_eAplAfInit(). The ZigBee Base Device attribute bbdbNodeIsOnANetwork is restored from persistent storage (if relevant) before calling this function.

Note: Before calling this function, the application must initialize the required ZigBee software timers using the function ZTIMER_eInit() from the ZigBee PRO Stack libraries. In doing so, it must add a number of timers for internal use by the ZigBee Base Device, where this number is defined by the macro BDB_ZTIMER_STORAGE.

The initialization performed by this function includes the following:

  • Sets the ZigBee Base Device attributes to their default values, unless other values are defined by the application in the file bdb_options.h.

  • Registers the ZigBee Base Device message queue passed into this function - this message queue is used by the ZigBee Base Device to capture stack events.

  • Calls BDB_vSetKeys() to set the initial pre-configured security keys (defined in the file bdb_link_keys.c), according to the node type:

    • For a Coordinator, the Default Global Trust Centre Link Key is set.

    • For a Router or End Device, both the Default Global Trust Centre Link Key and Distributed Security Global Link Key are set.

  • Opens timers for ZigBee Base Device internal use

For more information on the security keys, refer to Section 2.3.

Parameters

  • psInitArgs: Handle of the ZigBee Base Device event queue

Returns

  • None

Parent topic:Functions

BDB_vSetKeys

void BDB_vSetKeys(void);

Description

This function loads into memory the appropriate pre-configured link key on the local node for the initial security state of the node. The function is automatically called by BDB_vInit(). However, it must be called explicitly to restore the link keys after a reset which removes the keys from memory.

The type of link key that is loaded depends on the node type, as follows:

  • On a Coordinator, the Default Global Trust Centre Link Key is loaded for participation in a centralized security network.

  • On a Router or End Device, both of the following keys are loaded:

    • Default Global Trust Centre Link Key for participation in a centralized security network.

    • Distributed Security Global Link Key for participation in a distributed security network.

The pre-configured link keys are defined in the file bdb_link_keys.c, from where they are loaded.

Network security is described in Section 2.3.

Parameters

  • None

Returns

  • None

Parent topic:Functions

BDB_vStart

void BDB_vStart(void);

Description

This function starts the ZigBee Base Device (ZBD) and must be called after BDB_vInit() and just before the application enters the main loop (for example: APP_vMainLoop()).

Depending on the node type and whether the node was previously a member of a network, the function may or may not perform an action. In either case, the function invokes the callback function APP_vBdbCallback() with a suitable event.

  • If the node was not in a network:

    • For a Router node that supports Touchlink commissioning, the function selects a radio channel for the node from the set of primary channels defined for Touchlink.

    • For other Router, Coordinator, and End Device nodes, no action is taken and the application then must join the node to a network.

      • In the above cases, the function generates the event BDB_EVENT_INIT_SUCCESS.

  • If the node was in a network:

    • For Coordinator and Router nodes, no action is taken by the function and the event BDB_EVENT_INIT_SUCCESS is generated.

    • For an End Device node, a series of rejoin attempts are performed. If a rejoin attempt is successful, the event BDB_EVENT_REJOIN_SUCCESS is generated. If all rejoins are unsuccessful, the event BDB_EVENT_REJOIN_FAILURE is generated unless unsecured joins are enabled, in which case a join through Network Steering is attempted.

The above actions are described in more detail in Section 2.1.

Parameters

  • None

Returns

  • None

Parent topic:Functions

BDB_eNfStartNwkFormation

BDB_teStatus BDB_eNfStartNwkFormation(void);

Description

This function starts the Network Formation process and, if necessary, must be called after BDB_vStart(). If it is potentially required on a node, Network Formation must be enabled via the attribute u8bdbCommissioningMode.

The function can be called only on a Coordinator or Router:

  • If called on a Coordinator, a centralized security network is formed.

  • If called on a Router, a distributed security network is formed.

The above network types are described in Network security.

Once Network Formation starts, the function returns and the eventual outcome of the Network Formation process is indicated by an asynchronous event - one of the following:

  • BDB_EVENT_NWK_FORMATION_SUCCESS if a centralized or distributed network has been successfully formed.

  • BDB_EVENT_NWK_FORMATION_FAILURE if a network has not been successfully formed.

Network Formation is described in more detail in Network Formation.

Parameters

  • None

Returns

  • BDB_E_SUCCESS

    (Network Formation has been successfully started)*.

  • BDB_E_ERROR_INVALID_PARAMETER

    (End Device has attempted Network Formation).

  • BDB_E_ERROR_NODE_IS_ON_A_NWK

    (node is already in a network).

The eventual outcome is indicated by a BDB_EVENT_NWK_FORMATION_SUCCESS or BDB_EVENT_NWK_FORMATION_FAILURE event, as described above.

Parent topic:Functions

BDB_eNsStartNwkSteering

BDB_teStatus BDB_eNsStartNwkSteering(void);

Description

This function starts the Network Steering process and, if necessary, must be called after BDB_vStart(). If it is potentially required on a node, enable Network Steering via the attribute u8bdbCommissioningMode.

The actions performed by this function depend on whether the local node is already a member of a network:

  • When the node is already in a network and is a Coordinator or Router, it opens up the network for other nodes to join. This action is for a fixed time-interval of 180 seconds by default, but this interval can be configured (in seconds) using the macro BDBC_MIN_COMMISSIONING_TIME in the bdb_options.h file.

  • When the node is not already in a network, it searches for a suitable network to join. If it finds one, attempts to join the network. Once a node has joined the network, the node is authenticated and receives the network key from its parent. If the network has a Trust Centre, the node may then replace its pre-configured link key with one generated and supplied by the Trust Centre.

Once Network Steering starts, the function returns and the eventual outcome of the Network Steering process is indicated by an asynchronous event - one of the following:

  • BDB_EVENT_NWK_STEERING_SUCCESS if Network Steering has been completed successfully.

  • BDB_EVENT_NO_NETWORK if no open network was discovered for joining.

  • BDB_EVENT_NWK_JOIN_FAILURE if the node attempted to join a network but failed.

Network Steering is described in more detail in Network steering.

Parameters

  • None

Returns

  • BDB_E_SUCCESS

    (Network Steering has been successfully started)*.

  • BDB_E_ERROR_IMPROPER_COMMISSIONING_MODE

    (Network Steering is not enabled).

  • BDB_E_ERROR_COMMISSIONING_IN_PROGRESS

    (node is already in a commissioning mode).

  • BDB_E_ERROR_INVALID_DEVICE

    (joining node is a Coordinator).

The eventual outcome is indicated by a BDB_EVENT_NWK_STEERING_SUCCESS, BDB_EVENT_NO_NETWORK, or BDB_EVENT_NWK_JOIN_FAILURE event, as described above.

Parent topic:Functions

BDB_eFbTriggerAsInitiator

BDB_teStatus BDB_eFbTriggerAsInitiator(
uint8 u8SourceEndPointId);

Description

This function starts the Finding and Binding process on an initiator endpoint. The function may be called as the result of a user action, such as a button-press. The initiator remains in Finding and Binding mode for a fixed time-interval (in seconds) defined using the macro BDBC_MIN_COMMISSIONING_TIME in the bdb_options.h file.

The initiator node first searches for target endpoints by broadcasting an Identify Query command. If the initiator receives a response from a remote endpoint, it then sends a Simple Descriptor request to this endpoint. If the requested Simple Descriptor is successfully received back, then the initiator checks this descriptor for clusters on the remote endpoint that match its own clusters. 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.

  • 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.

Finding and Binding mode is described in Finding and Binding.

Note: Events are generated during this function call - for details, refer to Initiator Node.

Parameters

  • u8SourceEndPointId: Number of initiator endpoints

Returns

  • BDB_E_SUCCESS

    (Finding and Binding has been successfully started).

  • BDB_E_FAILURE

    (invalid endpoint number or unable to broadcast Identify Query command).

  • BDB_E_ERROR_COMMISSIONING_IN_PROGRESS

    (Finding and Binding already on-going).

Parent topic:Functions

BDB_vFbExitAsInitiator

void BDB_vFbExitAsInitiator(void);

Description

This function stops an on-going Finding and Binding process on an initiator endpoint. The function may be called as the result of a user action, such as a button-press or button-release.

Finding and Binding mode is described in Finding and Binding.

Parameters

  • None

Returns

  • None

Parent topic:Functions

BDB_eFbTriggerAsTarget

BDB_teStatus BDB_eFbTriggerAsTarget(uint8 u8EndPoint);

Description

This function starts the Finding and Binding process on a target endpoint and must be called locally by the application on the target endpoint. The function may be called as the result of a user action, such as a button-press.

The functions put the device into identification mode of the Identify cluster for a time-interval (in seconds) which is at least equal to the value defined using the macro BDBC_MIN_COMMISSIONING_TIME in the bdb_options.h file. During this time, the target device generates responses to Identify Query commands, as well as other Finding and Binding commands.

The endpoint is then brought out of Find and Binding mode locally using the function BDB_vFbExitAsTarget() or remotely (by the initiator) using the Identify cluster function eCLD_IdentifyCommandIdentifyRequestSend().

Finding and Binding mode is described in Finding and Binding.

Parameters

  • u8EndPoint: Number of target endpoints

Returns

  • BDB_E_SUCCESS

    (Finding and Binding has been successfully started).

  • BDB_E_FAILURE

    (invalid endpoint number or Identify cluster is inaccessible).

Parent topic:Functions

BDB_vFbExitAsTarget

void BDB_vFbExitAsTarget(uint8 u8SourceEndpoint);

Description

This function stops an on-going Finding and Binding process on a target endpoint and must be called locally by the application on the target endpoint. The function may be called as the result of a user action, such as a button-press or button-release.

Finding and Binding mode is described in Section 2.2.4.

Parameters

  • u8SourceEndpoint: Number of target endpoint

Returns

  • None

Parent topic:Functions

BDB_bIsBaseIdle

bool_t BDB_bIsBaseIdle(void);

Description

This function determines whether the ZigBee Base Device is busy or idle, and therefore whether the node can enter sleep mode. The function returns a Boolean indicating the activity status of the ZigBee Base Device.

If the ZigBee Base Device is idle and the node can go to sleep (indicated by TRUE), it is then the responsibility of the application to put the device into sleep mode.

Parameters

  • None

Returns

  • TRUE indicates that the ZigBee Base Device is idle and the node can sleep.

  • FALSE indicates that the ZigBee Base Device is busy.

Parent topic:Functions

BDB_u8OutOfBandCommissionStartDevice

uint8 BDB_u8OutOfBandCommissionStartDevice(
BDB_tsOobWriteDataToCommission *psStartupData);

Description

This function initiates out-of-band commissioning which allows the local device to form a network as a Coordinator or to join an existing network as a Router or End Device. The function should be called after ZPS_eAplAfInit(). It is called when commissioning data is received from another device via out-of-band means. This commissioning data must be supplied to the function in a BDB_tsOobWriteDataToCommission structure, described in Section 2.7.5.

Not all the data values are mandatory.

The out-of-band commissioning interface makes sensible assumptions about data values and does not allow certain values already in the node to be over-ridden by the commissioning data. For example:

  • It does not allow the network address of a Coordinator to set to a non-zero value (since the network address of the Coordinator must be zero)

  • It does not allow the rejoin flag to set on a Coordinator (since the Coordinator cannot leave and then rejoin the network)

  • In a centralized network, it does not allow the IEEE/MAC address of Trust Centre to set to any value other than the IEEE/MAC address of Coordinator (since the Coordinator is always the Trust Centre)

For an overview of out-of-band commissioning, refer to Out-Of-Band Commissioning.

Parameters

Returns

  • BDB_E_SUCCESS

    (The device has successfully formed or joined a network).

  • BDB_E_FAILURE

    (The request to form or join a network has not been accepted).

  • ZPS_NWK_ENUM_INVALID_REQUEST

    (The request contained invalid data).

  • ZPS_APL_APS_E_ILLEGAL_REQUEST

    (The stack is not in the correct state to accept the request).

Parent topic:Functions

BDB_vOutOfBandCommissionGetData

void BDB_vOutOfBandCommissionGetData(
BDB_tsOobReadDataToAuthenticate
*psReturnedCommissioningData);

Description

This function is used to obtain locally stored commissioning data. The obtained data is received in a structure described in BDB_tsOobReadDataToAuthenticate and includes the network key. The data is then passed to higher layers which may encrypt it before sending it by out-of-band means to the other device involved in the commissioning.

A similar set of data but with the network key encrypted can be obtained using the function BDB_eOutOfBandCommissionGetDataEncrypted().

For an overview of out-of-band commissioning, refer to Out-Of-Band Commissioning.

Parameters

Returns

  • None

Parent topic:Functions

BDB_eOutOfBandCommissionGetDataEncrypted

BDB_teStatus BDB_eOutOfBandCommissionGetDataEncrypted(
BDB_tsOobWriteDataToAuthenticate *psSrcCredentials,
uint8 *pu8ReturnAuthData,
uint16 *puSize);

Description

This function is used to obtain locally stored commissioning data, including the network key which returns encrypted. Authentication data (including an install code) must be provided which is used to encrypt the network key.

The obtained data is received as a byte stream - the size of the byte stream is also returned. The byte stream contains the following data:

  • IEEE/MAC address of the local node as u64address (8 bytes)

  • Network key encrypted with the data passed via psSrcCredentials (16 bytes)

  • MIC value generated to validate encryption (4 bytes)

  • Key sequence number of active network key (1 byte)

  • Active channel number (1 byte)

  • PAN ID (2 bytes)

  • Extended PAN ID (8 bytes)

The encrypted network key and other obtained data are then sent by out-of-band means to the other device involved in the commissioning. The receiving device may decrypt the key using the BDB_bOutOfBandCommissionGetKey() function.

A similar set of data without encryption of the network key is obtained using the function BDB_u8OutOfBandCommissionStartDevice().

For an overview of out-of-band commissioning, refer to Out-Of-Band Commissioning.

Parameters

  • psSrcCredentials: Pointer to a structure containing authentication data to be used to encrypt the network key (see BDB_tsOobWriteDataToAuthenticate).

  • pu8ReturnAuthData: Pointer to the start of the returned byte stream containing the obtained data.

  • puSize: Pointer to a location to receive the size of the obtained byte stream.

Returns

  • None

Parent topic:Functions

BDB_bOutOfBandCommissionGetKey

bool_tBDB_bOutOfBandCommissionGetKey(
uint8* pu8InstallCode,
uint8* pu8EncKey,
uint64 u64ExtAddress,
uint8* pu8DecKey,
uint8* pu8Mic);

Description

This function is used to decrypt an encrypted security key. It may be used to decrypt the network key received from another device during out-of-band commissioning.

The function requires the install code that was used to generate the pre-configured link key used to encrypt the key.

For an overview of out-of-band commissioning, refer to Out-Of-Band Commissioning.

Parameters

  • pu8InstallCode: Pointer to install code used to generate the pre-configured link key used in the encryption.

  • pu8EncKey: Pointer to encrypted key.

  • u64ExtAddress: Pointer to IEEE/MAC address of originating device.

  • pu8DecKey: Pointer to location to receive the decrypted key.

  • pu8Mic: Pointer to the MIC value to be used to validate the decryption.

Returns

  • TRUE if key successfully decrypted, otherwise FALSE

Parent topic:Functions

Parent topic:ZigBee Base Device

Structures

BDB_tsBdbEvent

The following structure contains ZigBee Base Device event information that is passed to the APP_vBdbCallback() callback function (see Events).

typedef struct
{
    BDB_teBdbEventTypee EventType;
    BDB_tuBdbEventData uEventData;
}BDB_tsBdbEvent;

where:

  • eEventType is an enumeration indicating the event type - for the possible enumerations, refer to Section 2.9.

  • uEventData is a union structure containing the event information (if any) - for a description of this structure, refer to Section 2.7.2.

Parent topic:Structures

BDB_tuBdbEventData

The following structure is a union containing the data for a ZigBee Base Device event.

typedef union
{
BDB_tsZpsAfEvent sZpsAfEvent;
BDB_tsFindAndBindEvent *psFindAndBindEvent;
}BDB_tuBdbEventData

where:

  • sZpsAfEvent is a structure containing the data for a stack event, indicated by the event type BDB_EVENT_ZPSAF - for a description of this structure, refer to Section 2.7.3.

  • psFindAndBindEvent is a pointer to a structure containing the data for a ‘Finding and Binding’ event (see Section 2.9) - for a description of this structure, refer to Section 2.7.4.

Parent topic:Structures

BDB_tsZpsAfEvent

The following structure contains the data for a ZigBee stack event (see the BDB_EVENT_ZPSAF event in Section 2.9).

typedef struct
{
    uint8 u8EndPoint;
    ZPS_tsAfEvent sStackEvent;
}BDB_tsZpsAfEvent;

where:

  • u8EndPoint is the number of the endpoint on which the event occurred.

  • sStackEvent is a ZPS structure containing the stack event type and data - this structure is detailed in the ZigBee 3.0 Stack User Guide (JNUG3130).

Parent topic:Structures

BDB_tsFindAndBindEvent

The following structure contains the data for a ‘Finding and Binding’ event (see Section 2.9), which is passed to the application during the Finding and Binding process on the initiator.

typedef struct{
    uint8 u8InitiatorEp;
    uint8 u8TargetEp;
    uint16 u16TargetAddress;
    uint16 u16ProfileId;
    uint16 u16DeviceId;
    uint8 u8DeviceVersion;
    union {
        uint16 u16ClusterId;
        uint16 u16GroupId;
    }uEvent;
    ZPS_tsAfZdpEvent *psAfZdpEvent;
    bool bAllowBindOrGroup;
    bool bGroupCast;
}BDB_tsFindAndBindEvent;

where:

  • u8InitiatorEp is the number of the endpoint involved in the binding/grouping on the initiator node.

  • u8TargetEp is the number of the endpoint involved in the binding/grouping on the target node.

  • u16TargetAddress is the 16-bit network address of the target node.

  • u16ProfileId is the identifier of the ZigBee application profile supported by the two nodes (for Lighting & Occupancy devices, this is 0x0104)

  • u16DeviceId is the 16-bit identifier of the ZigBee device type supported by the target endpoints. This must be a device type identifier issued by the ZigBee Alliance.

  • u8DeviceVersion contains 4 bits (bits 0-3) representing the version of the supported device description on the target node (the default is 0000, unless set to another value according to the application profile used).

  • uEvent is a union of the following two fields:

    • u16ClusterId is the identifier of the cluster involved in the binding.

    • u16GroupId is the address of the group to which the target endpoint is assigned.

  • psAfZdpEvent is a pointer to a ZPS_tsAfZdpEvent structure containing the generated Finding and Binding event - this ZPS structure is detailed in the ZigBee 3.0 Stack User Guide (JNUG3130). The event can be any of the following (detailed in Section 2.9):

    • BDB_EVENT_FB_HANDLE_SIMPLE_DESC_RESP_OF_TARGET

    • BDB_EVENT_FB_CHECK_BEFORE_BINDING_CLUSTER_FOR_TARGET

    • BDB_EVENT_FB_CLUSTER_BIND_CREATED_FOR_TARGET

    • BDB_EVENT_FB_BIND_CREATED_FOR_TARGET

    • BDB_EVENT_FB_GROUP_ADDED_TO_TARGET

    • BDB_EVENT_FB_ERR_BINDING_FAILED

    • BDB_EVENT_FB_ERR_BINDING_TABLE_FULL

    • BDB_EVENT_FB_ERR_GROUPING_FAILED

    • BDB_EVENT_FB_NO_QUERY_RESPONSE

    • BDB_EVENT_FB_TIMEOUT

  • bAllowBindOrGroup is a Boolean flag that indicates whether the relevant cluster is permitted to participate in a binding or grouping. The default value is TRUE (permitted) but if the application must exclude the cluster (and block the binding/grouping) then it should set this field to FALSE.

  • bGroupCast is a Boolean flag that indicates whether an ‘Add Group If Identifying’ command should be broadcast to all the identifying targets (TRUE) or an ‘Add Group’ request should be individually unicast to all the identifying targets. The default value is TRUE.

Parent topic:Structures

BDB_tsOobWriteDataToCommission

The following structure contains the data values used to initialize a node at the start of out-of-band commissioning of the node.

typedef struct{
uint64 u64PanId;
uint64 u64TrustCenterAddress;
uint8* pu8NwkKey;
uint8* pu8InstallCode;
uint16 u16PanId;
uint16 u16ShortAddress;
bool_t bRejoin;
uint8 u8ActiveKeySqNum;
uint8 u8DeviceType;
uint8 u8RxOnWhenIdle;
uint8 u8Channel;
uint8 u8NwkUpdateId;
}BDB_tsOobWriteDataToCommission;

where:

  • u64PanId is the Extended PAN ID of the network to be joined.

  • u64TrustCenterAddress is the IEEE/MAC address of the Trust Centre in the centralized network to be joined.

  • pu8NwkKey is a pointer to the network key.

  • pu8InstallCode is a pointer to an initial link key derived from an install code (see Section 2.3.1).

  • u16PanId is the PAN ID of the network to be joined.

  • u16ShortAddress is the network address assigned to the node.

  • bRejoin is the ‘rejoin flag’ which indicates whether the node should attempt to rejoin the network if it leaves (TRUE: rejoin, FALSE: do not rejoin).

  • u8ActiveKeySqNum is the key sequence number associated with the active network key.

  • u8DeviceType is a value indicating the type of ZigBee node:

    • 0: Coordinator

    • 1: Router

    • 2: End Device All other values are reserved.

  • u8RxOnWhenIdle is a value indicating whether the receiver of the node is enabled during idle periods:

    • 0: Receiver off when idle (sleeping device)

    • 1: Receiver on when idle (non-sleeping device) All other values are reserved.

  • u8Channel is the radio channel number on which the network operates.

  • u8NwkUpdateId is a unique byte value which is incremented when the network parameters are updated (and is therefore used to determine whether a receiving node has missed an update).

Parent topic:Structures

BDB_tsOobReadDataToAuthenticate

The following structure contains data values that are read from the local node during out-of-band commissioning of the node.

typedef struct{
uint8 au8Key[16]__attribute__((aligned(16)));
uint64 u64TcAddress;
uint64 u64PanId;
uint16 u16ShortPanId;
uint8 u8ActiveKeySeq;
uint8 u8Channel;
}BDB_tsOobReadDataToAuthenticate;

where:

  • au8Key[16]__attribute__((aligned (16))) is an array containing the current network key, with one byte per array element.

  • u64TcAddress is the IEEE/MAC address of the Trust Centre of the network to which the node is being commissioned.

  • u64PanId is the Extended PAN ID of the network to which the node is being commissioned.

  • u16ShortPanId is the PAN ID of the network to which the node is being commissioned.

  • u8ActiveKeySeq is the key sequence number of the currently active network key.

  • u8Channel is the radio channel number on which the network operates.

Parent topic:Structures

BDB_tsOobWriteDataToAuthenticate

The following structure contains authentication data that is used to encrypt a security key during out-of-band commissioning of the node.

typedef struct{
    uint64 u64ExtAddr;
    uint8* pu8InstallCode;
}BDB_tsOobWriteDataToAuthenticate;

where:

  • u64ExtAddr is the IEEE/MAC address of the node.

  • pu8InstallCode is a pointer to a 16-bit install code to be used in the key encryption.

Parent topic:Structures

Parent topic:ZigBee Base Device

Enumerations

This section lists and describes the enumerations used on the ZigBee Base Device. However, the ZigBee Base Device event enumerations are detailed in Events.

BDB_teStatus

The following enumerations indicate the status of certain function calls.

typedef enum
{
    BDB_E_SUCCESS,
    BDB_E_FAILURE,
    BDB_E_ERROR_INVALID_PARAMETER,
    BDB_E_ERROR_INVALID_DEVICE,
    BDB_E_ERROR_NODE_IS_ON_A_NWK,
    BDB_E_ERROR_IMPROPER_COMMISSIONING_MODE,
    BDB_E_ERROR_COMMISSIONING_IN_PROGRESS,
}BDB_teStatus;

The enumerations are listed and described in the Table 11:

Enumeration

Description

BDB_E_SUCCESS

Function call is successful in its purpose

BDB_E_FAILURE

Function call fails in its purpose and no other error code is appropriate

BDB_E_ERROR_INVALID_PARAMETER

A specified parameter value is invalid

BDB_E_ERROR_INVALID_DEVICE

Device type is not valid for the operation

BDB_E_ERROR_NODE_IS_ON_A_NWK

Node is already in a network

BDB_E_ERROR_IMPROPER_COMMISSIONING_MODE

The commissioning mode is not appropriate

BDB_E_ERROR_COMMISSIONING_IN_PROGRESS

The commissioning process is in progress

Parent topic:Enumerations

BDB_teCommissioningStatus

The following enumerations are used to indicate the status of the commissioning process for the node.

typedef enum
{
    E_BDB_COMMISSIONING_STATUS_SUCCESS,
    E_BDB_COMMISSIONING_STATUS_IN_PROGRESS,
    E_BDB_COMMISSIONING_STATUS_NOT_AA_CAPABLE,
    E_BDB_COMMISSIONING_STATUS_NO_NETWORK,
    E_BDB_COMMISSIONING_STATUS_FORMATION_FAILURE,
    E_BDB_COMMISSIONING_STATUS_NO_IDENTIFY_QUERY_RESPONSE,
    E_BDB_COMMISSIONING_STATUS_BINDING_TABLE_FULL,
    E_BDB_COMMISSIONING_STATUS_NO_SCAN_RESPONSE,
    E_BDB_COMMISSIONING_STATUS_NOT_PERMITTED,
    E_BDB_COMMISSIONING_STATUS_TCLK_EX_FAILURE
}BDB_teCommissioningStatus;

The enumerations are listed and described in the table below:

Commissioning Status Enumerations

Enumeration

Description

E_BDB_COMMISSIONING_STATUS_SUCCESS

Commissioning is successfully completed

E_BDB_COMMISSIONING_STATUS_IN_PROGRESS

Commissioning is on-going

E_BDB_COMMISSIONING_STATUS_NOT_AA_CAPABLE

Parent cannot assign address to joining node

E_BDB_COMMISSIONING_STATUS_NO_NETWORK

No network is found that can be joined

E_BDB_COMMISSIONING_STATUS_FORMATION_FAILURE

Network formation failed

E_BDB_COMMISSIONING_STATUS_NO_IDENTIFY_QUERY _ RESPONSE

No responses received to an Identify Query command

E_BDB_COMMISSIONING_STATUS_BINDING_TABLE_FULL

The local Binding table is full

E_BDB_COMMISSIONING_STATUS_NO_SCAN_RESPONSE

No responses received during a channel scan

E_BDB_COMMISSIONING_STATUS_NOT_PERMITTED

Requested commissioning is not permitted

E_BDB_COMMISSIONING_STATUS_TCLK_EX_FAILURE

Trust Centre link key exchange failed

Parent topic:Enumerations

Parent topic:ZigBee Base Device

Events

The ZigBee Base Device has a number of associated events. Some API functions (described in Functions) return immediately and the outcome of the process they invoke is later indicated with the generation of an asynchronous event. A user-defined callback function must be defined in the application to handle these events. The prototype of this callback function is as follows:

void APP_vBdbCallback(BDB_tsBdbEvent *psBdbEvent)

where psBdbEvent is a pointer to a BDB_tsBdbEvent event structure containing the event information to be passed to the function (for this structure, see BDB_tsBdbEvent).

The enumerations for the ZigBee Base Device events are listed below.

typedef enum
 {
    BDB_EVENT_NONE,
    BDB_EVENT_ZPSAF,
    BDB_EVENT_INIT_SUCCESS,
    BDB_EVENT_REJOIN_SUCCESS,
    BDB_EVENT_REJOIN_FAILURE,
    BDB_EVENT_NWK_STEERING_SUCCESS,
    BDB_EVENT_NO_NETWORK,
    BDB_EVENT_NWK_JOIN_SUCCESS,
    BDB_EVENT_NWK_JOIN_FAILURE,
    BDB_EVENT_APP_START_POLLING,
    BDB_EVENT_NWK_FORMATION_SUCCESS,
    BDB_EVENT_NWK_FORMATION_FAILURE,
    BDB_EVENT_FB_HANDLE_SIMPLE_DESC_RESP_OF_TARGET,
    BDB_EVENT_FB_CHECK_BEFORE_BINDING_CLUSTER_FOR_TARGET,
    BDB_EVENT_FB_CLUSTER_BIND_CREATED_FOR_TARGET,
    BDB_EVENT_FB_BIND_CREATED_FOR_TARGET,
    BDB_EVENT_FB_GROUP_ADDED_TO_TARGET,
    BDB_EVENT_FB_ERR_BINDING_FAILED,
    BDB_EVENT_FB_ERR_BINDING_TABLE_FULL,
    BDB_EVENT_FB_ERR_GROUPING_FAILED,
    BDB_EVENT_FB_NO_QUERY_RESPONSE,
    BDB_EVENT_FB_TIMEOUT,
    BDB_EVENT_FB_OVER_AT_TARGET,
    BDB_EVENT_LEAVE_WITHOUT_REJOIN,
 }
 BDB_teBdbEventType;

These events are described below.

The events with ‘FB’ in their names are used in the ‘Finding and Binding’ process and the event data is contained in the structure BDB_tsFindAndBindEvent (see BDB_tsFindAndBindEvent).

Note: In addition, certain ZCL events are generated during the Finding and Binding process. These events are passed to the callback function BDB_vZclEventHandler(), which is supplied with the ZigBee Base Device. For these events, refer to Finding and Binding.

  1. BDB_EVENT_ZPSAF

    This event indicates that a ZigBee stack event has occurred. In this case, the uEventData field (of the BDB_tsBdbEvent structure) contains a BDB_tsZpsAfEvent structure, which itself includes the ZPS_tsAfEvent stack event structure.

  2. BDB_EVENT_INIT_SUCCESS

    This event is generated when the ZigBee Base Device has been successfully initialized.

  3. BDB_EVENT_REJOIN_SUCCESS

    This event is generated when the node has successfully rejoined its previous network.

  4. BDB_EVENT_REJOIN_FAILURE

    This event is generated when the node attempts to rejoin its previous network has failed.

  5. BDB_EVENT_NWK_STEERING_SUCCESS

    This event is generated when the Network Steering process has successfully completed and the local node has broadcast either of the following messages:

    • Management Permit Joining message to request the network to be opened for other devices to join (this message is broadcast when the local node was already in the network before Network Steering).

    • Device Announce message to announce that the local node has joined the network (this message is broadcast when the local node was not in the network before Network Steering).

  6. BDB_EVENT_NO_NETWORK

    This event is generated when no open network open was discovered in a channel scan performed by a device attempting to join a network.

  7. BDB_EVENT_NWK_JOIN_SUCCESS

    This event is generated when the node has successfully joined a network.

  8. BDB_EVENT_NWK_JOIN_FAILURE

    This event is generated when the node attempted to join a network but failed.

  9. BDB_EVENT_APP_START_POLLING

    This event is generated on an End Device during the Trust Centre link key exchange procedure to instruct the application to start fast polling of its parent, in order to retrieve packets received as part of the exchange procedure.

  10. BDB_EVENT_NWK_FORMATION_SUCCESS

    This event is generated at the end of the Network Formation process when a centralized or distributed has been successfully formed by the local node.

  11. BDB_EVENT_NWK_FORMATION_FAILURE

    This event is generated at the end of the Network Formation process if the local node failed to form a network.

  12. BDB_EVENT_FB_HANDLE_SIMPLE_DESC_RESP_OF_TARGET

    This event indicates that the initiator has received a Simple Descriptor response from a target. This event can be used by the application to determine which type of device (for example: Dimmable Light, On/Off Light) the initiator is binding to. The information provided to the application is:

    u8InitiatorEp
u8TargetEp
u16TargetAddress
u16ProfileId
u16DeviceId
u8DeviceVersion
psAfZdpEvent \(points to received Simple Descriptor\)

  13. BDB_EVENT_FB_CHECK_BEFORE_BINDING_CLUSTER_FOR_TARGET

    This event is generated just before creating a Binding table entry for a cluster. It allows the application to exclude clusters from binding by setting the bAllowBindOrGroup flag to FALSE (by default it is TRUE). This event can also be used when the application must perform a group binding by setting the attribute u16bdbCommissioningGroupID to a value other than 0xFFFF. Moreover, this event also allows the application to decide whether to broadcast an ‘Add Group If Identifying’ or unicast an ‘Add Group’ command. An ‘Add Group If Identifying’ is broadcast to all the identifying targets by setting bGroupCast to TRUE. By default, this parameter is set to FALSE and allows unicasting an ‘Add Group’ request individually to all the identifying targets. The information provided to the application is:

    u8InitiatorEp
u8TargetEp
u16TargetAddress
u16ClusterId
bAllowBindOrGroup
bGroupCast
psAfZdpEvent \(points to received Simple Descriptor\)

  14. BDB_EVENT_FB_CLUSTER_BIND_CREATED_FOR_TARGET

    This event is generated per cluster for every binding or grouping created. The event may be generated more than once for the same target device. For example, when binding a color Dimmer Switch to a Dimmable Light, the event is generated twice: once for the On/Off cluster and once for the Level Control Cluster. The information provided to the application is:

    u8InitiatorEp
u8TargetEp
u16TargetAddress
u16ClusterId

  15. BDB_EVENT_FB_BIND_CREATED_FOR_TARGET

    This event is generated once all address bindings have been completed. The application can then send a ‘Stop Identifying’ command to the bound target. The information provided to the application is:

    u8InitiatorEp
u8TargetEp
u16TargetAddress

  16. BDB_EVENT_FB_GROUP_ADDED_TO_TARGET

    This event is generated once the ‘Add Group’ or ‘Add Group If Identifying’ has been sent, in order to inform the application that grouping has been completed from the perspective of the initiator. The application can then groupcast a ‘Stop Identifying’ command to the grouped targets. The information provided to the application is:

    u8InitiatorEp
u8TargetEp
u16GroupId
u16TargetAddress
psAfZdpEvent

  17. BDB_EVENT_FB_ERR_BINDING_FAILED

    This event is generated to indicate that an unexpected error has occurred while creating a Binding table entry.

  18. BDB_EVENT_FB_ERR_BINDING_TABLE_FULL

    This event is generated to inform the application that the Binding table is full and therefore the Finding and Binding process has failed. As a result, the ZigBee Base Device exits the Finding and Binding process.

  19. BDB_EVENT_FB_ERR_GROUPING_FAILED

    This event is generated to indicate that a grouping has failed, since the initiator was not able to send an ‘Add Group’ or ‘Add Group If Identifying’ request.

  20. BDB_EVENT_FB_NO_QUERY_RESPONSE

    This event indicates that the initiator did not receive an Identify Query response within BDB_FB_RESEND_IDENTIFY_QUERY_TIME (default value is 10) seconds. The information provided to the application is:

    u8InitiatorEp

  21. BDB_EVENT_FB_TIMEOUT

    This event indicates that the commissioning timer expired after a period defined by the constant BDBC_MIN_COMMISSIONING_TIME (180 seconds by default). The information provided to the application is:

    u8InitiatorEp

  22. BDB_EVENT_FB_OVER_AT_TARGET

    This event indicates that the Finding and Binding process has ended on the target node because the identify time reached zero or a remote node forced it to go to zero.

  23. BDB_EVENT_LEAVE_WITHOUT_REJOIN

    This event is generated when the node has been instructed to leave the network without attempting to rejoin the network.

Parent topic:ZigBee Base Device

Compile-time Options

Compile-time options can be configured through definitions in the file bdb_options.h. This option allows custom values to be defined for ZigBee Base Device attributes and constants. If the value of an attribute or constant is not defined in this file, the default value for the attribute or constant is used.

Attributes

The following macros can be used to pre-configure values for the ZigBee Base Device attributes (listed and described in Section 2.5.1):

  • BDB_COMMISSIONING_GROUP_ID

  • BDB_COMMISSIONING_MODE

  • BDB_COMMISSIONING_STATUS

  • BDB_JOINING_NODE_EUI64

  • BDB_JOIN_USES_INSTALL_CODE_KEY

  • BDB_NODE_JOIN_LINK_KEY_TYPE

  • BDB_PRIMARY_CHANNEL_SET

  • BDB_SCAN_DURATION

  • BDB_SECONDARY_CHANNEL_SET

  • BDB_TC_LINK_KEY_EXCHANGE_ATTEMPTS

  • BDB_TC_LINK_KEY_EXCHANGE_ATTEMPTS_MAX

  • BDB_TC_LINK_KEY_EXCHANGE_METHOD

  • BDB_TRUST_CENTER_NODE_JOIN_TIMEOUT

  • BDB_TRUST_CENTER_REQUIRE_KEYEXCHANGE

For example, to set the maximum number of key establishment attempts to 5, include the following line:

#define BDB_TC_LINK_KEY_EXCHANGE_ATTEMPTS_MAX5

Constants

The following macros can be used to set values for the ZigBee Base Device constants (listed and described in Section 2.5.2):

  • BDBC_MAX_SAME_NETWORK_RETRY_ATTEMPTS

  • BDBC_MIN_COMMISSIONING_TIME

  • BDBC_REC_SAME_NETWORK_RETRY_ATTEMPTS

  • BDBC_TC_LINK_KEY_EXCHANGE_TIMEOUT

  • BDBC_TL_INTERPAN_TRANS_ID_LIFETIME

  • BDBC_TL_MIN_STARTUP_DELAY_TIME

  • BDBC_TL_PRIMARY_CHANNEL_SET

  • BDBC_TL_RX_WINDOW_DURATION

  • BDBC_TL_SCAN_TIME_BASE_DURATION_MS

  • BDBC_TL_SECONDARY_CHANNEL_SET

For example, to set the minimum commissioning time for which a network is open to join to 240 seconds, include the following line:

#define BDBC_MIN_COMMISSIONING_TIME240

(this minimum commissioning time should set to a value below 255 seconds)

Parent topic:ZigBee Base Device