Developing with ZBOSS
Zigbee stack RAM usage configuration

Table of Contents

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

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.

Configuration file Usage Maximum number of nodes
zb_mem_config_min.h Simple applications and small networks. 16
zb_mem_config_med.h Applications without huge demands on Zigbee features,
for example broadcast transmissions, binding and group membership entries. 		32
zb_mem_config_max.h Complex applications and huge networks. 128
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.

Role Minimum [kB] Medium [kB] Maximum [kB]
Router + BLE 31.4 35.2 50.6
End device 16.1 19.2 24.9
ZED + BLE 19.6 22.7 28.4
Coordinator 17.8 21.6 37.0
Router 20.9 24.7 40.1
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:

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.

Potential RAM savings on routers (GCC compiler)
Router memory configuration Minimum [kb] Medium [kb] Maximum [kb]
ZB_CONFIG_ROLE_ZR 20.8 24.3 37.3
ZB_CONFIG_ROLE_ZC 20.9 24.7 40.1

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.

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

Parameter name Description
ZB_CONFIG_IEEE_ADDR_TABLE_SIZE Address translation table size.
ZB_CONFIG_IOBUF_POOL_SIZE Number of packet buffers in the system.
ZB_CONFIG_APS_BIND_TRANS_TABLE_SIZE Table size for simultaneous transmissions to bound devices.
ZB_CONFIG_APS_SRC_BINDING_TABLE_SIZE Maximum number of entries in source_binding_table. See Organization of the binding table.
ZB_CONFIG_APS_DST_BINDING_TABLE_SIZE Maximum number of entries in destination_binding_table. See Organization of the binding table.
ZB_CONFIG_APS_DUPS_TABLE_SIZE Incoming APS duplicate detection table size.
ZB_CONFIG_N_APS_KEY_PAIR_ARR_MAX_SIZE Number of APS link-key pairs to store on the device.
ZB_CONFIG_N_APS_RETRANS_ENTRIES Number of parallel outgoing APS TX transactions (packets with ACK req 1).
ZB_CONFIG_NEIGHBOR_TABLE_SIZE Neighbor table size.
ZB_CONFIG_NWK_ROUTING_TABLE_SIZE Number of entries in the routing table.
ZB_CONFIG_SCHEDULER_Q_SIZE Callbacks queue, alarms queue size.
ZB_CONFIG_MAC_PENDING_QUEUE_SIZE Number of entries in the pending TX queue for ZR and ZC.
ZB_CONFIG_NWK_MAX_SOURCE_ROUTES Source route table capacity
ZB_CONFIG_SCHEDULER_Q_SIZE_PROTECTED_STACK_POOL Queue size reserved for the ZBOSS stack work
ZB_CONFIG_SINGLE_TRANS_INDEX_SIZE Count of buffers used for simultaneous transmissions to the bound devices
ZB_CONFIG_BUF_POOL_BITMAP_SIZE Size of bitmap storing state of each buffer
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 Nordic's implementation of the Zigbee 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.

Parameter
Traffic
Complexity
Role
Network size
Default value
L
M
H
S
M
C
ZED
ZR
ZC
<8
<32
<200
ZB_CONFIG_APS_BIND_TRANS_TABLE_SIZE
(ZB_CONFIG_IOBUF_POOL_SIZE + 15)/16 * 4
ZB_CONFIG_APS_SRC_BINDING_TABLE_SIZE
x 32
x 24
x 16
ZB_CONFIG_APS_DST_BINDING_TABLE_SIZE
x 32
x 24
x 16
ZB_CONFIG_SINGLE_TRANS_INDEX_SIZE
(ZB_CONFIG_APS_BIND_TRANS_TABLE_SIZE + 7) / 8
ZB_CONFIG_APS_DUPS_TABLE_SIZE
x 32
x 16
x 8
ZB_CONFIG_IEEE_ADDR_TABLE_SIZE
x ZB_CONFIG_OVERALL_NETWORK_SIZE + (ZB_CONFIG_OVERALL_NETWORK_SIZE + 15)/16 * 4
x ZB_CONFIG_OVERALL_NETWORK_SIZE + (ZB_CONFIG_OVERALL_NETWORK_SIZE + 15)/16 * 4
x ZB_CONFIG_OVERALL_NETWORK_SIZE
ZB_CONFIG_IOBUF_POOL_SIZE
x 48
x 32
x x 32
x x 24
x x 20
ZB_CONFIG_MAC_PENDING_QUEUE_SIZE
x x x ZB_CONFIG_IOBUF_POOL_SIZE / 4
x x x ZB_CONFIG_IOBUF_POOL_SIZE / 4
x x x ZB_CONFIG_IOBUF_POOL_SIZE / 4
x 0
ZB_CONFIG_N_APS_KEY_PAIR_ARR_MAX_SIZE
x ZB_CONFIG_OVERALL_NETWORK_SIZE
x 4
x 4
ZB_CONFIG_N_APS_RETRANS_ENTRIES
x (ZB_CONFIG_IOBUF_POOL_SIZE + 8)/9 * 3
x (ZB_CONFIG_IOBUF_POOL_SIZE + 8)/9 * 3
x 6
ZB_CONFIG_NEIGHBOR_TABLE_SIZE
x ZB_CONFIG_OVERALL_NETWORK_SIZE
x ZB_CONFIG_OVERALL_NETWORK_SIZE
x x 32
x x 16
x x 8
x MAX(16, x)
ZB_CONFIG_NWK_ROUTING_TABLE_SIZE
x x x ZB_CONFIG_NEIGHBOR_TABLE_SIZE
x x x ZB_CONFIG_NEIGHBOR_TABLE_SIZE
x x x 8
x 0
ZB_CONFIG_SCHEDULER_Q_SIZE
x 48
x x 48
x x x 32
x 22
ZB_CONFIG_NWK_MAX_SOURCE_ROUTES
x ZB_CONFIG_OVERALL_NETWORK_SIZE
x ZB_CONFIG_OVERALL_NETWORK_SIZE
ZB_CONFIG_SCHEDULER_Q_SIZE_PROTECTED_STACK_POOL
12
ZB_CONFIG_BUF_POOL_BITMAP_SIZE
(ZB_CONFIG_IOBUF_POOL_SIZE + 7) / 8
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