initialization functions

The AF API contains the below initialization functions.

The functions are listed below.

1. ZPS_eAplAfInit

2. ZPS_vAplAfSetMacCapability

3. ZPS_eAplAibSetApsUseExtendedPanId

4. ZPS_vExtendedStatusSetCallback

5. ZPS_bAppAddBeaconFilter

6. ZPS_eAplFormDistributedNetworkRouter

7. ZPS_eAplInitEndDeviceDistributed

8. ZPS_vAplAfEnableMcpsFilter

9. ZPS_vNwkLinkCostCallbackRegister

Note: The function ZPS_eAplAfInit() is mandatory and must be the first network function called in your application.

ZPS_eAplAfInit

ZPS_teStatus ZPS_eAplAfInit(void);

Description

This function initializes the Application Framework and must be the first network function called in your application code. The function first requests a reset of the Network (NWK) layer of the ZigBee PRO stack. It then initializes certain network parameters with values that have been pre-configured using the ZPS Configuration Editor (see Chapter 13, ZPS Configuration Editor). These parameters include the node type and the Extended PAN ID of the network.

The device is started as the pre-configured node type. If this is a Coordinator, the Extended PAN ID of the node is set to the pre-configured value. Note that if a zero value is specified, the Coordinator uses its own IEEE/MAC address for the Extended PAN ID.

Parent topic:ZPS_eAplAfInit

Parameters

None.

Parent topic:ZPS_eAplAfInit

Returns

• ZPS_E_SUCCESS (AF successfully initialized).

• APS return codes, listed and described in Section 11.2.2.

• NWK return codes, listed and described in Section 11.2.3.

• MAC return codes, listed and described in Section 11.2.4.

Parent topic:ZPS_eAplAfInit

Parent topic:initialization functions

ZPS_vAplAfSetMacCapability

void ZPS_vAplAfSetMacCapability(uint8 u8MacCapability);

Description

This function can be used on a Router or End Device to configure the IEEE 802.15.4 MAC capabilities in the Node descriptor. The MAC capabilities are specified in an 8-bit bitmap, detailed in the table below.

MAC capabilities bitmap

Bits	Description
0	Coordinator capability: 1: Node able to act as Coordinator 0: Node not able to act as Coordinator
1	Device type: 1: Full-Function Device (FFD) 0: Reduced-Function Device (RFD) An FFD can act as any node type while an RFD cannot act as the network Coordinator.
2	Power source: 1: Node is mains-powered 0: Node is not mains-powered
3	Receiver on when idle: 1: Receiver enabled during idle periods 0: Receiver disabled during idle periods to conserve power
4-5	Reserved
6	Security capability: 1: High security 0: Standard security
7	Allocate address: 1: Network address should be allocated to node 0: Network address need not be allocated to node

Parent topic:ZPS_vAplAfSetMacCapability

Parameters

• u8MacCapability Bitmap containing the MAC capabilities to be configured (see table above).

Parent topic:ZPS_vAplAfSetMacCapability

Returns

None.

Parent topic:ZPS_vAplAfSetMacCapability

Parent topic:initialization functions

ZPS_eAplAibSetApsUseExtendedPanId

ZPS_teStatus ZPS_eAplAibSetApsUseExtendedPanId
                            (uint64 u64UseExtPanId);

Description

This function can be used to create an application record of the Extended PAN ID (EPID) of the network to which the local device belongs.

• The only use of this function for a Coordinator is described in Section 6.1.1.

• The function should only be called on a Router or End Device in the manner described in Section 6.1.2.

Parent topic:ZPS_eAplAibSetApsUseExtendedPanId

Parameters

u64UseExtPanId Extended PAN ID of network to which device belongs.

Parent topic:ZPS_eAplAibSetApsUseExtendedPanId

Returns

• ZPS_E_SUCCESS (Extended PAN ID record successfully created).

• NWK return codes, listed and described in Section 11.2.3.

• MAC return codes, listed and described in Section 11.2.4.

• APS return codes, listed and described in Section 11.2.2.

Parent topic:ZPS_eAplAibSetApsUseExtendedPanId

Parent topic:initialization functions

ZPS_vExtendedStatusSetCallback

void ZPS_vExtendedStatusSetCallback(
   tpfExtendedStatusCallBack pfExtendedStatusCallBack);

Description

This function can be used to register a callback function for extended error handling (see (Section 6.7)

The prototype of the callback function is:

ZPS_teExtendedStatus vExtendedStatusCb();

The registered callback function is invoked if a subsequent API function call results in one of the following errors:

• 0xA3: ZPS_APL_APS_E_ILLEGAL_REQUEST

• 0xA6: ZPS_APL_APS_E_INVALID_PARAMETER

• 0xC2: ZPS_NWK_ENUM_INVALID_REQUEST

The callback function returns another error code (from those listed and described in Section 11.2.5), which provides a more specific reason for the error.

Parent topic:ZPS_vExtendedStatusSetCallback

Parameters

pfExtendedStatusCallBackPointer to extended error handling callback function to be registered.

Parent topic:ZPS_vExtendedStatusSetCallback

Returns

None.

Parent topic:ZPS_vExtendedStatusSetCallback

Parent topic:ZPS_vAplAfEnableMcpsFilter

Parent topic:initialization functions

ZPS_bAppAddBeaconFilter

void ZPS_bAppAddBeaconFilter(tsBeaconFilterType *psAppBeaconStruct);

Description

This function can be used to introduce a filter that will be used for filtering beacons in network searches (on a Router or End Device). Beacons can be filtered on the basis of PAN ID, Extended PAN ID, LQI value and device joining status/capacity. The filter details are provided in a tsBeaconFilterTypestructure (see Section 8.2.3.5).

If required, this function should be called immediately before ZPS_eAplZdoDiscoverNetworks(), ZPS_eAplZdoRejoinNetwork() or ZPS_eAplZdoStartStack().

Note: A filter should NOT be implemented unless attempting a join, as this would prevent some stack operations from working correctly.

Once the join or discovery has completed, the filter is automatically removed and needs to be re-instated if a retry is required.

Guidelines on the implementation of beacon filters are provided in , Appendix B.4, “Beacon filtering guidelines”.

Parent topic:ZPS_bAppAddBeaconFilter

Parameters

• * psAppBeaconStruct Pointer to a structure containing the beacon filter details. (see Section 8.2.3.5).

Parent topic:ZPS_bAppAddBeaconFilter

Returns

None.

Parent topic:ZPS_bAppAddBeaconFilter

Parent topic:initialization functions

ZPS_eAplFormDistributedNetworkRouter

ZPS_teStatus ZPS_eAplFormDistributedNetworkRouter(
        ZPS_tsAftsStartParamsDistributed *psStartParms,
        bool_t bSendDeviceAnnce);

Description

This function can be used on a Router node to introduce the node into a distributed security network (see Section 6.10.2). The function must be called on the Router node that creates the distributed security network, therefore, the first node of the new network.

Subsequent Router nodes may be introduced using this function, but could be introduced using other commissioning methods, such as Touchlink.

Parent topic:ZPS_eAplFormDistributedNetworkRouter

Parameters

• psStartParms Pointer to structure containing the start parameter values for the Router- see Section 8.2.3.7.

• bSendDeviceAnnce Boolean indicating whether a device announcement message is to be sent:

  • TRUE - send device announcement

  • FALSE - do not send device announcement

Parent topic:ZPS_eAplFormDistributedNetworkRouter

Returns

• ZPS_E_SUCCESS (network successfully created).

• NWK return codes, listed and described in Section 11.2.3.

• MAC return codes, listed and described in Section 11.2.4.

• APS return codes, listed and described in Section 11.2.2.

Parent topic:ZPS_eAplFormDistributedNetworkRouter

Parent topic:initialization functions

ZPS_eAplInitEndDeviceDistributed

ZPS_teStatus ZPS_eAplInitEndDeviceDistributed(
            ZPS_tsAftsStartParamsDistributed *psStartParms);

Description

This function can be used on an End Device node to introduce the node into a distributed security network (see Section 6.10.2). This network must have already been created by a Router using the ZPS_eAplFormDistributedNetworkRouter() function. End Device nodes may be introduced into the network in this way or using other commissioning methods, such as Touchlink.

Parent topic:ZPS_eAplInitEndDeviceDistributed

Parameters

psStartParms Pointer to structure containing the start parameter values for the End Device - see Section 8.2.3.7, ZPS_tsAftsStartParamsDistributed.

Parent topic:ZPS_eAplInitEndDeviceDistributed

Parent topic:ZPS_vAplAfEnableMcpsFilter

Returns

• ZPS_E_SUCCESS (network successfully created).

• NWK return codes, listed and described in Section 11.2.3.

• MAC return codes, listed and described in Section 11.2.4.

• APS return codes, listed and described in Section 11.2.2.

Parent topic:ZPS_eAplInitEndDeviceDistributed

Parent topic:initialization functions

ZPS_vAplAfEnableMcpsFilter

void ZPS_vAplAfEnableMcpsFilter(
                    bool bEnableFilter,
                    uint8 u8LinkCostThreshold);

Description

This function allows packet filtering based on ‘link cost’ to be enabled/disabled, as well as some basic configuration of the filtering. Packet filtering is disabled by default.

The default ‘link cost threshold’ is 5. This means that when packet filtering is enabled, received packets with a link cost of 5 or less are discarded by the stack and not queued for processing. The link cost threshold can be modified (from the default value of 5) using this function.

If required, this function can be called at any time after ZPS_eAplAfInit().

For more information on packet filtering and link costs, refer to Section 6.10.3, Filtering packets on LQI Value/Link cost.

Parent topic:ZPS_vAplAfEnableMcpsFilter

Parameters

psStartParms Pointer to structure containing the start parameter values for the End Device - see Section 8.2.3.7, ZPS_tsAftsStartParamsDistributed.

Parent topic:ZPS_eAplInitEndDeviceDistributed

Parent topic:ZPS_vAplAfEnableMcpsFilter

Returns

None.

Parent topic:ZPS_vExtendedStatusSetCallback

Parent topic:ZPS_vAplAfEnableMcpsFilter

Parent topic:initialization functions

ZPS_vNwkLinkCostCallbackRegister

void ZPS_vNwkLinkCostCallbackRegister(void *pvFn);

Description

This function can be used to register a user-defined callback function that defines custom mappings between LQI values and link costs that are to be used in packet filtering, based on link cost. When packet filtering is enabled, the stack uses a default set of mappings, detailed in Section 6.10.3.1. The callback function is only needed if custom mappings are to be used that will over-ride the default mappings. If required, this registration function must be called before ZPS_eAplAfInit(), and on both cold and warm starts.

The user-defined callback function to be registered has the following prototype:

uint8 APP_u8LinkCost(uint8 u8Lqi);

This callback function translates a measured LQI value (u8Lqi) into a link cost value. An example function is given in Section 6.10.3.3.

For more information on packet filtering and link costs, refer to Section 6.10.3.

Parent topic:ZPS_vNwkLinkCostCallbackRegister

Parameters

pvFn Pointer to user-defined callback function to be registered.

Parent topic:ZPS_vNwkLinkCostCallbackRegister

Returns

None.

Parent topic:ZPS_vNwkLinkCostCallbackRegister

Parent topic:initialization functions

Parent topic:AF API functions