1. Introduction
This wiki provides information on memory allocation APIs, the typical memory footprint of a Zigbee application, STM32WBA stack heap size configuration for a Zigbee device, and estimation formulas for the total memory required to start the Zigbee stack.
2. Startup file and linker script
The startup file and the linker script allow initializing the microcontroller's hardware and link the various sections of the code together.
The startup file includes functions that set up the stack, initialize the memory, and configure the clock and other peripherals so that the user application can run. The linker script determines how the code and data are organized in memory. It defines the ROM_start, ROM_end, RAM_start, and RAM_end for example.
2.1. Linker file on STM32WBA
On the STM32WBA, a single linker file is used to map all the code and data to the correct memory regions. Typically, this linker file also defines a specific region for the NVM. The example below shows a typical linker file (based on the IAR toolchain) defining the different regions used by a standard Zigbee application on the STM32WBA.
3. STM32WBA Zigbee software architecture
As a reminder, the STM32WBA MCUs are built with Arm® Cortex®-M33 core. The architecture is depicted in the figure below.
| STM32WBA Zigbee architecture |
|---|
STM32WBA5x devices contain a 1 Mbyte flash memory from address offset 0x00 0000 to 0x0F FFFF, and 128 KB of SRAM defined below:
- SRAM1 region start = 0x20000000
- SRAM1 region end = 0x2000FFFF
- SRAM2 region start = 0x20010000
- SRAM2 region end = 0x2001FFFF
STM32WBA6x devices contain a 2 Mbyte flash memory, and 512 KB of SRAM as defined below:
- SRAM1 region start = 0x20000000
- SRAM1 region end = 0x2003FFFF
- SRAM2 region start = 0x20040000
- SRAM2 region end = 0x2007FFFF
4. STM32WBA stack memory requirements
4.1. Memory consideration
The stack allocates run-time objects, such as packets, timers, and endpoints, using the ZbHeap. The stack needs also to configure different tables which depend on device capabilities and network topology. These values depend on the use case which is targeted. This is the reason why dynamic memory allocation is being used inside the stack. The FFD library requires more memory than the RFD library so it can handle routing packets and the overhead that entails.
Inside the Zigbee stack, two functions are used to allocate memory : ZIGBEE_PLAT_HeapMalloc() and ZIGBEE_PLAT_ZbHeapMalloc()
ZIGBEE_PLAT_HeapMalloc()is used to allocate memory from the system during stack initialization (via ZbInit()), and it is not freed until calling ZbDestroy().ZIGBEE_PLAT_ZbHeapMalloc()is used to allocate memory during the run-time operation of the stack. These are mostly short-lived memories, such as packets, timers, etc. Once the memory is no longer needed, it is freed by calling ZbHeapFree().
By default, these memory allocation APIs are linked to the ST memory manager. The relevant functions, including ZIGBEE_PLAT_HeapInit(), ZIGBEE_PLAT_HeapMalloc(), ZIGBEE_PLAT_HeapFree(), ZIGBEE_PLAT_ZbHeapInit(), ZIGBEE_PLAT_ZbHeapMalloc(), and ZIGBEE_PLAT_ZbHeapFree(), are defined within the zigbee_plat.c file. By default, in the examples provided inside our Cube firmware, the ZIGBEE_PLAT_xx APIs are mapped to our Advanced Memory Manager (AMM). The size of the memory pool which is used by the AMM is available in the app_conf.h file and is specific to each example. These APIs are customizable and can be redefined to meet specific application requirements if necessary. Additionally, using STM32CubeMX, the AMM can be easily customized.
For more detailed information about the ST memory manager, consult the resource provided in the STM32CubeWBA Memory Management wiki
4.2. Typical memory footprint of a Zigbee application
The measurements are derived from our default Zigbee library, which notably contains trace functions that are highly beneficial for debugging and support tasks. It should be noted that these figures do not account for any flash memory that might be utilized to store persistent data, if such storage is necessary. Removing the traces from the lib may save several tens of kilobytes, but for support and maintenance reasons, it has been decided to activate those traces. Regarding the NVM, 16KB at minimum should be reserved.
In our standard application examples, as included in our regular releases, we have used default parameters of the Zbheap size and various Zigbee table sizes for all applications including SED ones. To optimize memory usage, we have adjusted the configurations of the tables and memory pool size. These adjustments are tailored based on whether the application uses RFD or FFD Zigbee stack. Below is a table that illustrates memory consumption values for some application examples on the Nucleo board: Apart from the Zigbee_OnOff_Server_Coord_ThreadX application, all the other applications shown below are using a baremetal implementation.
| Application | Flash (KB) | RAM (KB) (*) | |
| Zigbee R23 | Zigbee_OnOff_Server_Coord (FFD) | 434 | 73 |
| Zigbee_OnOff_Client_SED (RFD) | 360 | 47 | |
| Zigbee_FindBind_Coord (FFD) | 446 | 73 | |
| Zigbee_TempMeas_Client_Coord (FFD) | 434 | 73 | |
| Zigbee_OnOff_Server_Coord_ThreadX (FFD) | 443 | 105 | |
| Zigbee_OnOff_Client_Router (FFD) | 434 | 73 | |
| Zigbee R22 | Zigbee_OnOff_Server_Coord (FFD) | 375 | 72 |
| Zigbee_OnOff_Client_SED (RFD) | 309 | 46 | |
| Zigbee R22 Smart Energy | Zigbee_SE_Server_Router_R22 (internal example) (FFD) | 375 | 82 |
Note(*) : RAM consumption depends on the topology and can be tuned if necessary.
4.3. Typical memory footprint of a Zigbee/BLE application
In addition to the standard Zigbee applications, ST also delivers examples showing how to manage Zigbee and BLE concurrently. Inside the Firmware package, a dedicated application is provided demonstrating the activation of the BLE Heart Rate profile and an Zigbee OnOff Toggle transmission. To handle this use case, the standard Zigbee stack (ZigBeeProR23_FFD.a) and Zigbee Cluster (ZigbeeClusters.a) libraries are used. Regarding the linklayer, a dedicated library (WBA6_LinkLayer_BLE_Mac_lib.a) is used.
| Application | Flash (KB) | RAM (KB) | |
| Zigbee R23_FFD + BLE | BLE_HeartRate_Zigbee (FFD) | 574 | 105 |
4.4. Details of the memory consumed by the OnOff coordinator application example
The details for a typical Zigbee application acting as an OnOff coordinator (Example :Zigbee_OnOff_Server_Coord) based on the R23 Zigbee stack are summarized below (based on the v1.5 cube firmware release):
| Component | Type | Flash consumption | RAM consumption | Comment |
| Zigbee stack (R23 FFD) |
Library: ZigBeeProR23_FFD.a | 325 KB | 41 KB of dynamic memory (ZbHeap) + 3 KB of static memory.
|
Full R23 FFD Zigbee stack library including Green Power Proxy feature, Touch link and traces |
| MAC | Library: wba_mac.lib.a | 15 KB | 3.1 KB | |
| LinkLayer | Library: LinkLayer15_4.a | 56 KB | 5.3 KB | |
| Clusters | Library: ZigbeeClusters.a
Can be delivered in source code on demand |
1 KB (at minimum)
See Comment |
12 KB of ZbHeap for clusters and run time operations
|
This is fully dependent on the Clusters selection done by the Application. To give some rough data, we can consider:
|
| Appli | Source code | 4 KB (at minimum)
See Comment |
1.6 KB of static memory
|
This is fully dependent on the application (Here it is Zigbee _OnOff_Server_Coord example) |
| Infra | Source code | 33 KB (at minimum) | 3 KB of static memory (at minimum including traces) | This includes the standard framework and drivers used in the Applications provided inside the Firmware Cube delivery |
| TOTAL | Binary ready to be flashed | 434 KB (at minimum) | 73 KB (at minimum) | The Zigbee_OnOff_Server_Coord application provided in the firmware package consume 434 KB of flash and 73 KB of RAM. This doesn’t include Flash used for persistent data |
Note (1): The 41 KB value can be adjusted via the #define CFG_AMM_VIRTUAL_STACK_ZIGBEE_INIT_BUFFER_SIZE. This value is by default set to 10500 for the Zigbee coordinator application. It is expressed in words (32bits) and is defined in app_conf.h file. As explained in chapter 4.7, this value can be adjusted according to the size of the tables requested by the topology. In our example, we are using the default setting. The theoretical value requested can be computed using the following formula.
Note (2): The 12 KB of heap for clusters and run-time operations can be adjusted via the #define CFG_AMM_VIRTUAL_STACK_ZIGBEE_HEAP_BUFFER_SIZE. This value is by default set to 3000, is expressed in words (32bits) and is defined in app_conf.h file.
Note (3): On this application, the AMM is used only for the Zigbee stack. No specific buffers are used by the application. After the subtraction of CFG_AMM_VIRTUAL_STACK_ZIGBEE_INIT_BUFFER and the CFG_AMM_VIRTUAL_STACK_ZIGBEE_INIT_BUFFER buffers, no buffers are being left for the application. Refer to the figure above for more details.:
CFG_MM_POOL_SIZE - (CFG_AMM_VIRTUAL_STACK_ZIGBEE_INIT_BUFFER_SIZE + CFG_AMM_VIRTUAL_STACK_ZIGBEE_HEAP_BUFFER_SIZE) *4 = 0.
4.5. Zigbee stack size for standard configuration
The choice of the stack flavor depends on the use case and the targeted role. For an application in which the device acts as a sleepy end device for example, the RFD flavor of the stack should be used.
The typical values as tuned inside the V1.5 Cube Firmware are defined below:
| Component | Flash consumption | RAM consumption | Comment |
| Zigbee R23 FFD | 325 KB | Depends on the topology in use.
For instance 41 KB of ZbHeap reserved for allocation of the routing tables (to address a large mesh network with 64 devices) and 10 KB for run time operations Refer to chapter 4.7 for more details) |
Full R23 FFD Zigbee stack library including Green Power Proxy feature, touchlink feature and traces |
| ZigBee R23 RFD | 265 KB | Depends on the topology in use.
For instance, on the default configuration as shown on the Zigbee_OnOff_Client_SED example, 26 KB of ZbHeap are reserved for allocation of the network tables and 10 KB for run time operations. Refer to chapter 4.7 for more details |
Full 23 RFD Zigbee stack library including traces |
| ZigBee R22 FFD | 266 KB | Depends on the topology in use.
Refer to chapter 4.7 for more details. |
Full R22 FFD Zigbee stack library including Green Power Proxy feature, touchlink feature and traces |
| ZigBee R22 RFD | 215 KB | Depends on the topology in use.
Refer to chapter 4.7 for more details. |
Full 22 RFD Zigbee stack library including traces |
| ZigBee R22 FFD_SmartEnergy | 261 KB | Depends on the topology in use.
Refer to chapter 4.7 for more details. |
Full 22 FFD Zigbee stack supporting SmartEnergy features and including traces |
Remarks:
a) Flash size: The flash size includes the traces which are integrated by default. Delivering a stack without trace can save up to 88 KB, as shown in the next chapter.
b) RAM size: The RAM required depends on the topology and depends on the number of tables allocated when initializing the Zigbee stack. The number of tables used by default are defined below.
On Cube firmware releases prior to V1.5 version:
| Default config (Prior to V1.5 Cube Firmware release) | FFD | RFD |
| Number of NWK_NEIGHBOR_TABLE | 32 | 32 |
| Number of NWK_NLME_ADDRMAP_TABLE | 64 | 64 |
| Number of NWK_NLME_ROUTE_TABLE | 32 | NA |
| Number of NWK_NLDE_BTT_TABLE | 32 | 32 |
| Number of ZB_NWK_NLME_RREQ_TABLE | 16 | NA |
| Number of ZB_APS_DEVICE_KEY_PAIR_COUNT | 32 | 32 |
On the upcoming cube firmware releases (starting from V1.5), these values are tuned as follows:
| Default config (Actual releases) | FFD | RFD |
| Number of NWK_NEIGHBOR_TABLE | 64 | 16 |
| Number of NWK_NLME_ADDRMAP_TABLE | 32 | 2 |
| Number of NWK_NLME_ROUTE_TABLE | 32 | NA |
| Number of NWK_NLDE_BTT_TABLE | 32 | 9 |
| Number of ZB_NWK_NLME_RREQ_TABLE | 16 | NA |
| Number of ZB_APS_DEVICE_KEY_PAIR_COUNT | 32 | 2 |
4.6. Zigbee stack size for small mesh network and without traces
For small mesh network, 5 neighbor tables, 10 address map tables, 5 routing tables, 3 broadcast transaction tables, 3 route request tables, and 5 APS device key pair tables might be sufficient. In this case the RAM values are as follows:
| Component | Flash consumption (without traces) | RAM consumption (small topology) | Comment |
| Zigbee R23 FFD | 236 KB | 28 KB | Full R23 FFD Zigbee stack library including Green Power Proxy feature and touchlink feature |
| ZigBee R23 RFD | 200 KB | 18 KB | Full 23 RFD Zigbee stack library |
Note : The stack flavor without traces is not provided inside the Cube Firmware package.
In this small mesh network configuration, the number of tables used for this topology are as follows:
| Config to address a small mesh network | FFD | RFD |
| Number of NWK_NEIGHBOR_TABLE | 5 | 5 |
| Number NWK_NLME_ADDRMAP_TABLE | 10 | 2 |
| Number of NWK_NLME_ROUTE_TABLE | 5 | NA |
| Number of NWK_NLDE_BTT_TABLE | 3 | 3 |
| Number of NWK_NLME_RREQ_TABLE | 3 | NA |
| Number of APS_DEVICE_KEY_PAIR_COUNT | 5 | 2 |
4.7. STM32WBA stack heap size configuration for a Zigbee device
From an application point of view, we can consider two types of heaps.
- The standard heap (Heap) which can be used by any application using dynamic memory allocation (typically using malloc or free function calls).
- The zigbee heap (ZbHeap) which is used only by the Zigbee stack when it needs to allocate memory either at initialization or in real time.
The ZbHeap size should be carefully tuned according to the targeted use case. A router used to support a large mesh network needs to allocate larger routing tables than a simple router connected to one or two end devices. With the default setup available on the V1.4 Cube release, the Zigbee Router is able to address 32 end devices in parallel and requires at minimum 44 KB of RAM.
For both the coordinator and router device types, the number of neighbors or children that the device can support depends on the size of the Network Neighbor Table (NNT). The NNT must be large enough to maintain direct contact with other routers to route packets through the network, and also large enough to accommodate any potential end-device children that want to join.
All the Zigbee tables are allocated at startup dynamically when calling ZbInit().
ZbInit(uint64_t extAddr, struct ZbInitTblSizesT *tblSizes, struct ZbInitSetLoggingT *setLogging)
If the parameter tblSizes is set to NULL, default table sizes are used by the stack to manage typical use cases (e.g., FFD : Router addressing 32 neighbors , RFD : End device addressing 16 neighbors in the V1.5 release).
The meanings of these tables are described below:
| Parameter name | Comment |
| NWK_NEIGHBOR_TABLE | This table stores information about devices that are within the radio range of a particular device. It typically includes the device's network address, extended address, relationship (parent, child, sibling), device type (coordinator, router, end device), and other link quality indicators.
The number of those tables can be configured by the user via the parameter tblSizes (field nwkNeighborTblSz) passed through the ZbInit(..) function. This number is named NB_ZB_NWK_NEIGHBOR_TABLE in the formulas below. Its defaults value is available in the tables above (64 in the case of an FFD on version V1.5 Cube Firmware). Inside the stack, this value is set via the ZB_NWK_NEIGHBOR_TABLE_DEFAULT_SIZE define. |
| NWK_NLME_ADDRMAP_TABLE | The Address Map table is used to map between the network address and the corresponding extended (IEEE 64-bit) address. This is useful for routing and for various network layer operations.
The number of those tables can be configured by the user via the parameter tblSizes (field nwkAddrMapTblSz) passed through the ZbInit(..) function. This number is named NB_ZB_NWK_NLME_ADDRMAP_TABLE in the formulas below. Its defaults value is available in the tables above (32 in the case of an FFD on version V1.5 Cube Firmware). Inside the stack, this value is set via the ZB_NWK_NLME_ADDRMAP_TABLE_DEFAULT_SIZE define. |
| NWK_NLME_ROUTE_TABLE | This table contains the routing information that a device uses to send packets to other devices in the network. It includes entries for destination addresses and the next hop addresses to which frames should be forwarded to reach the destination.
The number of those tables can be configured by the user via the parameter tblSizes (field nwkRouteTblSz) passed through the ZbInit(..) function. This number is named NB_NWK_NLME_ROUTE_TABLE in the formulas below. Its defaults value is available in the tables above (32 in the case of an FFD on version V1.5 Cube Firmware). Inside the stack, this value is set via the ZB_NWK_NLME_ROUTE_TABLE_DEFAULT_SIZE define. |
| ZB_NWK_NLDE_BTT_TABLE | Size of the NWK_NLDE_BTT_TABLE. The Broadcast Transaction Table is used to track broadcast messages and ensure they are only relayed once through the network. It helps prevent broadcast storms by keeping a record of the recent broadcasts and their transaction sequence numbers.
The number of those tables can be configured by the user via the parameter tblSizes (field nwkBttSz) passed through the ZbInit(..) function. This number is named NB_NWK_NLDE_BTT_TABLE in the formulas below. Its defaults value is available in the tables above (32 in the case of an FFD on version V1.5 Cube Firmware). Inside the stack, this value is set via the ZB_NWK_NLDE_BTT_TABLE_DEFAULT_SIZE define. |
| ZB_NWK_NLME_RREQ_TABLE | When a device needs to discover a route to another device, it uses a route request. This table keeps track of these route requests to avoid redundant requests and manage the route discovery process.
The number of those tables can be configured by the user via the parameter tblSizes (field nwkRReqSz) passed through the ZbInit(..) function. This number is named NB_ZB_NWK_NLME_RREQ_TABLE in the formulas below. Its defaults value is available in the tables above (16 in the case of an FFD on version V1.5 Cube Firmware). Inside the stack, this value is set via the ZB_NWK_NLME_RREQ_TABLE_DEFAULT_SIZE define. |
| ZB_APS_DEVICE_KEY_PAIR_COUNT | This table is part of the Application Support Sublayer (APS) and is used for storing security key material related to other devices in the network. It includes the network address of the partner device and the associated link keys for secure communication.
The number of those tables can be configured by the user via the parameter tblSizes (field apsPeerLinkKeyTblSz) passed through the ZbInit(..) function. This number is named NB_ZB_APS_DEVICE_KEY_PAIR_COUNT in the formulas below. Its defaults value is available in the tables above (32 in the case of an FFD on version V1.5 Cube Firmware). Inside the stack, this value is set via the ZB_APS_DEVICE_KEY_PAIR_DEFAULT_COUNT define. |
4.8. STM32WBA memory requirements estimation formula
By knowing the size of each table and the content of each of them, it is possible to compute the necessary ZbHeap to be allocated when initiating the Zigbee stack.
4.8.1. R23 revision
The formula to be used is described below:
Total (ZbHeap requested to start R23 FFD Zigbee stack) = NB_NWK_NEIGHBOR_TABLE * 136
+ NB_NWK_NLDE_BTT_TABLE * 8
+ NB_NWK_NLME_ADDRMAP_TABLE * 16
+ NB_NWK_NLME_ROUTE_TABLE * 32
+ NB_NWK_NLME_RREQ_TABLE * 72
+ NB_APS_DEVICE_KEY_PAIR_COUNT * 88
+ 27520
According to this formula, when using the default table sizes for an FFD R23 stack, the minimum ZbHeap to be allocated is equal to 41 KB. As explained in Note (1) chapter 4.4, These 41 KB are reserved and defined via the CFG_AMM_VIRTUAL_STACK_ZIGBEE_INIT_BUFFER_SIZE parameter.
Total (ZbHeap requested to start R23 RFD Zigbee stack) = NB_NWK_NEIGHBOR_TABLE * 136
+ NB_NWK_NLDE_BTT_TABLE * 8
+ NB_NWK_NLME_ADDRMAP_TABLE * 16
+ NB_APS_DEVICE_KEY_PAIR_COUNT * 88
+ 9500
4.8.2. R22 revision
The formula to be used is described below:
Total (ZbHeap requested to start R22 FFD Zigbee stack) = NB_NWK_NEIGHBOR_TABLE * 136
+ NB_NWK_NLDE_BTT_TABLE * 8
+ NB_NWK_NLME_ADDRMAP_TABLE * 16
+ NB_NWK_NLME_ROUTE_TABLE * 32
+ NB_NWK_NLME_RREQ_TABLE * 72
+ NB_APS_DEVICE_KEY_PAIR_COUNT * 48
+ 18248
Total (ZbHeap requested to start R22 RFD Zigbee stack) = NB_NWK_NEIGHBOR_TABLE * 136
+ NB_NWK_NLDE_BTT_TABLE * 8
+ NB_NWK_NLME_ADDRMAP_TABLE * 16
+ NB_APS_DEVICE_KEY_PAIR_COUNT * 48
+ 6712
5. Acronyms and definitions
| Term | Definition |
|---|---|
| AMM | Advanced Memory Manager |
| RAM | Random Access Memory |
| SRAM | Static Random Access Memory |
| ROM | Read Only Memory |
| FFD | Full Function Device |
| RFD | Reduced Function Device |
| SED | Sleepy End Device |
| NVM | Non-Volatile Memory |