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

• psStartupData: Pointer to a structure containing commissioning data (see BDB_tsOobWriteDataToCommission)

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

• psReturnedCommissioningData: Pointer to a structure to receive the obtained commissioning data (see BDB_tsOobReadDataToAuthenticate)

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