Zigbee stack RAM usage configuration

You can adjust the usage of the RAM memory at compile time by using one of the following methods:

• Including a predefined header file
• Using macro definitions with properties
• Creating a custom memory configuration

Each of these methods gives a different granularity to the amount of the RAM memory used by the stack.

Note

The memory configuration must not be changed between firmware versions if the firmware is going to be upgraded using the OTA DFU.

Including a predefined header file

The ZBOSS stack comes with three predefined configuration files that can be included and used with any Zigbee application.

Predefined header files

Where to include header files

To use any of the header files, include it in your main application file.

The following example shows how to configure medium-sized memory buffers.

#include "zboss_api.h"
#include "zb_mem_config_med.h" // This file has to be included after zboss_api.h
...

Effects on RAM usage

The following table shows how the predefined memory configurations affect the RAM usage.

RAM usage by device role (GCC compiler)

The values for end device, router and coordinator were calculated based on light control example built with the GCC compiler.

Note

• You can use different set of settings, depending on the device role. Usually, end devices use much less memory than routers or coordinators. Coordinators have the highest demand on resources.
• For multiprotocol cases, you can configure the memory used by the Zigbee stack in the same way.

Using macro definitions with properties

You can use macro definitions to configure properties of the Zigbee solution. Each macro definition changes several parameters and is related to one property of the solution.

The following properties are available:

• Device role
• Application complexity
• Traffic load
• Maximum network size

For information about how to set the selected macro definition, see Configuring properties.

For information about the default property values, see Parameter reference table.

Device role

The primary property is the device role. Use one of the following parameters to define it:

• ZB_CONFIG_ROLE_ZED
• ZB_CONFIG_ROLE_ZR
• ZB_CONFIG_ROLE_ZC

Note

• For end devices, this property is automatically defined in the ZED library and cannot be configured.
• For routers, this property optimizes the amount of APS link keys that can be stored in the memory.
• For coordinators (Trust Centers), the value of this property corresponds to the amount of nodes in the network.

The following table shows how much RAM you can save on routers by excluding memory buffers that are used only when the device is working as the Zigbee Trust Center.

Application complexity

The application complexity property affects:

• the length of the scheduler queue,
• the detection of incoming APS duplicates.

You can use the following parameters to define the complexity of the application:

• ZB_CONFIG_APPLICATION_SIMPLE
• ZB_CONFIG_APPLICATION_MODERATE
• ZB_CONFIG_APPLICATION_COMPLEX

Traffic load

The traffic load property affects:

• the size of the input and output buffer sizes,
• the capability to handle several broadcast messages at the same time,
• all sorts of retransmissions.

You can use following parameters to define the estimated traffic load that goes through the device:

• ZB_CONFIG_HIGH_TRAFFIC
• ZB_CONFIG_MODERATE_TRAFFIC
• ZB_CONFIG_LIGHT_TRAFFIC

Maximum network size

You must define the maximum network size with the ZB_CONFIG_OVERALL_NETWORK_SIZE parameter. The parameter value must be between 2 and 200.

Depending on the device type, set the maximum network size value:

• For Zigbee end devices: close to the number of devices that ZED will communicate with. Typically then device will directly communicate with a few devices in a network.
• For Zigbee routers: to reflect the maximum network density.
• For Zigbee coordinator: as close to the overall network size as possible.

Configuring properties

To configure the properties, follow these steps.

1. Create a header file for the configuration.
2. In the file, define one parameter for each property.
3. At the end of the file, include the following header files:
   • zb_mem_config_common.h – which translates defined symbols into values,
   • zb_mem_config_context.h – which overrides memory buffers used by the stack.

You can use any of the predefined files mentioned in the Including a predefined header file method as reference.

The following example shows the memory configuration for a complex application with the end device role. The application communicates with around 50 nodes and does not expect a huge traffic load.

#ifndef ZB_MEM_CONFIG_CUSTOM_H
#define ZB_MEM_CONFIG_CUSTOM_H 1
#define ZB_CONFIG_ROLE_ZED
#define ZB_CONFIG_OVERALL_NETWORK_SIZE 50
#define ZB_CONFIG_LIGHT_TRAFFIC
#define ZB_CONFIG_APPLICATION_COMPLEX
#include "zb_mem_config_common.h"
#include "zb_mem_config_context.h"
#endif // ZB_MEM_CONFIG_CUSTOM_H

Creating a custom memory configuration

This is an advanced method. To use it, create your own header file with memory configuration (see Configuring properties).

If the selected method lacks in memory space for a particular property, redefine the value of the property parameter between the two includes in your header file. See Light Switch example from Zigbee Light Control example, which uses custom memory configuration to increase ZB_CONFIG_SCHEDULER_Q_SIZE value.

#ifndef ZB_MEM_CONFIG_CUSTOM_H
#define ZB_MEM_CONFIG_CUSTOM_H 1
#define ZB_CONFIG_ROLE_ZED
#define ZB_CONFIG_OVERALL_NETWORK_SIZE 50
#define ZB_CONFIG_LIGHT_TRAFFIC
#define ZB_CONFIG_APPLICATION_COMPLEX
#include "zb_mem_config_common.h"
#undef ZB_CONFIG_SCHEDULER_Q_SIZE
#define ZB_CONFIG_SCHEDULER_Q_SIZE 56
#include "zb_mem_config_context.h"
#endif //  ZB_MEM_CONFIG_CUSTOM_H

An example of this override is commented out in each of the predefined configuration files (see Including a predefined header file).

The following table shows the parameters that you can adjust with this method.

Customizable parameters

Organization of the binding table

The binding table stores binding entries, that is records composed of the following elements:

• src_addr
• src_endpoint
• cluster_id
• dst_address
• dst_endpoint

In ZBOSS stack the binding table is split into the following minor tables:

• source_binding_table
  • This table contains entries composed of src_addr, src_endpoint, and cluster_id.
  • Maximum number of entries: ZB_CONFIG_APS_SRC_BINDING_TABLE_SIZE
• destination_binding_table
  • This table contains entries composed of dst_address and dst_endpoint.
  • Maximum number of entries: ZB_CONFIG_APS_DST_BINDING_TABLE_SIZE

Each entry in destination_binding_table is linked to its counterpart in source_binding_table by a 5-bit wide index. For this reason, ZB_CONFIG_APS_SRC_BINDING_TABLE_SIZE is limited to 32, even though the total binding table size might be bigger in some configurations.

Parameter reference table

The following table shows the default values of parameters and how the parameters relate to each other.

Note

The "x" sign in different categories represents the logical AND. The "x" sign in the same category represents the logical OR.

Example	Traffic			Application			Role			Network size
	L	M	H	S	M	C	ZED	ZR	ZC	<8	<32	<200
(Light traffic) AND (ZR OR ZED)	x						x	x