1. Introduction
The Zigbee stack is a software component designed to enable Zigbee communication on the STM32WB/WBA microcontroller. Like any software, the stack requires memory to operate. There are two main types of memory that are relevant to the stack: RAM and Flash memory.
RAM (Random Access Memory) is a type of volatile memory that is used for temporary storage of data and program code. The stack uses RAM to store data structures, variables, and other runtime objects.
Flash memory, on the other hand, is a type of non-volatile memory used for long-term storage of program code and data. The stack uses Flash memory to store the code and data that make up the stack itself. The amount of Flash and RAM required depends on the application and the features used.
| Memory Types in Microcontrollers |
|---|
Another important concept to understand is memory allocation. The stack uses a heap to allocate memory dynamically at runtime. This means that the stack can allocate memory as needed, rather than requiring a fixed amount of memory to be allocated at compile time. However, this also means that the stack requires some amount of overhead to manage the heap.
Developers should carefully consider their application's requirements and consult the stack's documentation to determine the appropriate memory requirements.
2. Memory Layout of C Code
Microcontrollers Flash memory contains different segments of application code such as, interrupt vector table, code segment, initialized data segment, uninitialized data segment, constant data segment etc. The linker script file defines where each of these segments will store in flash memory.
These are the typical sections of a given C binary:
- Text Section: This section contains the machine code of the compiled C program. It is read-only and contains the instructions that the processor executes.
- Data Section: This section contains the initialized global and static variables of the program. It is writable and read-only.
- BSS Section: This section contains the uninitialized global and static variables of the program. It is writable and read-only.
- Heap Section: This section is dynamically allocated by the program during runtime. It is used for dynamic memory allocation. The heap area begins at the end of the BSS segment and grows upwards to higher memory addresses.
- Stack Section: This section is used for storing local variables and function parameters. It grows and shrinks as functions are called and returned. On the standard x86 architecture it grows downwards to lower addresses.
| Simple Memory Layout of C Program |
|---|
Heap is not automatically managed and should be explicitly allocated using malloc() for example, and deallocated using free(). So it is managed by the programmer.
Later, we will focus on heap memory and we will give formula to compute it on STM32WB for a given Zigbee application.
3. Startup File and Linker Script
The startup file and the linker script allow to initialize 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.
The following figure shows the memory map representation of the On/Off STM32WB55.Nucleo application example of the STM32Cube MCU Package. We have two separate linker files, the first for M4 and the second for M0, which is common and necessary to ensure that the code and data are placed in the correct memory regions for each core.
4. STM32WB series
4.1. STM32WB Zigbee software architecture
As a reminder, the STM32WB MCUs are built with two separate cores, Arm® Cortex®-M4 and Arm® Cortex®-M0+ cores. The architecture is depicted in the figure below. Mainly, the M0 core contains the Zigbee stack, and the M4 core contains clusters and the developer’s application.
| STM32WB Zigbee architecture |
|---|
STM32WB contains up to 1 Mbyte of flash memory single bank architecture, can be accessed starting from address 0x0000 0000 or 0x0800 0000, internal SRAM1 (up to 192 KB) and internal SRAM2a (32 KB) + SRAM2b (32 KB).
From system point of view, there are 2 heaps:
- one on M4 side
- one on M0 side to be used by Zigbee stack
4.2. STM32WB stack memory requirements
4.2.1. STM32WB stack heap size
The stack allocates run-time objects, such as packets, timers, and endpoints, using a heap. The application can configure the size of the heap using the ZbInit struct ZbInitTblSizesT parameters, specifically heapPtr and heapSz. The heap memory is allocated from the M4 core, allowing any memory, such as packets, passed between the M0 and M4 to be accessed and modified by either core.
M0 heap is included in M4 heap and allocated using ZbMalloc when ZbInit is called.
If ZbInit is called providing a NULL heapPtr, M0 heap will be allocated with default size depending on SW type:
- FFD SW: 32 KB
- RFD SW: 16 KB
4.2.2. STM32WB stack tables size
The following table describes the impact on memory usage for each additional entry:
| Entry Type | Memory Usage Per Entry (bytes) |
| Network Neighbor Table entry (nwkNeighborTblSz) | 144 |
| Network Routing Table entry (nwkRouteTblSz) | 28 |
| Network Address Mapping Table (nwkAddrMapTblSz) | 24 |
| APS Link Key Table (apsPeerLinkKeyTblSz) | 48 |
Default network topology in FFD SW is:
- ZB_NWK_NEIGHBOR_TABLE_DEFAULT_SIZE=16U
- ZB_NWK_NLME_ADDRMAP_TABLE_DEFAULT_SIZE=16U
- ZB_NWK_NLME_ROUTE_TABLE_DEFAULT_SIZE=16U
- ZB_NWK_NLDE_BTT_TABLE_DEFAULT_SIZE=16U
- ZB_NWK_NLME_RREQ_TABLE_DEFAULT_SIZE=4U
- ZB_APS_DEVICE_KEY_PAIR_DEFAULT_COUNT=16U
With such configuration, overall M4 heap consumption is close to 52 KB with 32 KB allocated for M0 heap + fixed M0 allocation + variable memory size depending on topology.
To compute M4 heap requirement for a given topology, you can use below formula:
M4 heap size= (32+16)*1024 + neighb_table_size*144 + routing_table_size*28 + address_mapping_table_size*24 + aps_link_key_table_size*48
4.2.3. Device Configuration And Memory Usage
| Description | nwkNeighborTblSz | nwkRouteTblSz | nwkAddrMapTblSz | apsPeerLinkKeyTblSz | Heap kB | Total Memory (kB) |
| Coordinator, 30 Devices, 30 Neighbors / Children | 30 | 30 | 30 | 30 | 32 | 54 |
| Coordinator, 100 Devices, 40 Neighbors / Children | 40 | 30 | 100 | 100 | 32 | 60 |
| Coordinator, 200 Devices, 40 Neighbors / Children | 40 | 30 | 200 | 200 | 32 | 67 |
| Router, 30 Neighbors / Children | 30 | 30 | 4 | 4 | 32 | 52 |
| Router, 100 Neighbors / Children | 100 | 30 | 4 | 4 | 32 | 61 |
| End-Device, 8 Neighbors | 8 | 0 | 2 | 2 | 8 | 14.5 |
Note: Total Memory includes some items with constant overhead, which are not listed in this table.
5. STM32WBA series
5.1. 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 as defined below:
- SRAM1 region start = 0x20000000
- SRAM1 region end = 0x2003FFFF
- SRAM2 region start = 0x20040000
- SRAM2 region end = 0x2007FFFF
5.2. STM32WBA stack memory requirements
5.2.1. Memory consideration
The stack allocates run-time objects, such as packets, timers, and endpoints, using the heap. 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_ZbMalloc()
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. The size of the memory pool which is used by the advanced memory manager 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.
For a more detailed information about the ST memory manager, please consult the resource provided in the STM32CubeWBA Memory Management wiki
5.2.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 heap 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 applications 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) | 438 | 82 |
| Zigbee_OnOff_Client_SED (RFD) | 370 | 39 | |
| Zigbee_FindBind_Coord (FFD) | 450 | 82 | |
| Zigbee_TempMeas_Client_Coord (FFD) | 439 | 82 | |
| Zigbee_OnOff_Server_Coord_ThreadX (FFD) | 450 | 114 | |
| Zigbee_OnOff_Client_Router (FFD) | 438 | 82 | |
| Zigbee R22 | Zigbee_OnOff_Server_Coord (FFD) | 381 | 82 |
| Zigbee_OnOff_Client_SED (RFD) | 329 | 39 |
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.4 release):
| Component | Type | Flash consumption | RAM consumption | Comment |
| Zigbee stack (R23 FFD) |
Library: ZigBeeProR23_FFD.a | 324 KB | 39 KB of dynamic memory (Heap) + 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) | 7 KB of heap 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)
|
16 KB for heap
Refer to Note(3) for more details
|
This is fully dependent on the application Zigbee_OnOff_Router : 3KB |
| Infra | Source code | 38 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 | 438 KB (at minimum) | 82 KB (at minimum) | The Zigbee_OnOff_Server_Coord application provided in the firmware package consume 438 KB of flash and 82KB of RAM. This doesn’t include Flash used for persistent data |
Note (1): The 39 KB value can be adjusted via the #define CFG_AMM_VIRTUAL_STACK_ZIGBEE_INIT_BUFFER_SIZE. This value is by default set to 10000, is expressed in words (32bits) and is defined in app_conf.h file. As explained in chapter XXX, 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 (as provided by the computation formula) gives a minimal value of 31 KB on which we are adding a margin of 8 KB. It means that in total, we allocate 39 KB (31 + 8) as defined by the CFG_AMM_VIRTUAL_STACK_ZIGBEE_INIT_BUFFER_SIZE macro.
Note (2): The 7 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 2000, is expressed in words (32bits) and is defined in app_conf.h file.
Note (3): These 16 KB are the remaining memory used by the AMM (Advanced Memory Manager) after the subtraction of CFG_AMM_VIRTUAL_STACK_ZIGBEE_INIT_BUFFER and the CFG_AMM_VIRTUAL_STACK_ZIGBEE_INIT_BUFFER buffers. Refer to the figure above for more details. These 16KB can be computed as follow:
CFG_MM_POOL_SIZE - (CFG_AMM_VIRTUAL_STACK_ZIGBEE_INIT_BUFFER_SIZE + CFG_AMM_VIRTUAL_STACK_ZIGBEE_HEAP_BUFFER_SIZE) *4.
The choice of the stack flavor, FFD or RFD, depends on the use case and the targeted role. For an application in which the device will act as a sleepy end device for example, the RFD flavor of the stack should be used.
| Component | Flash consumption | RAM consumption | Comment |
| Zigbee R23 FFD | 324 KB | 43 KB of Heap reserved for dynamic allocation by the Application (typical value. Refer to chapter STM32WBA stack heap size for a Zigbee device for more details) | Full R23 FFD Zigbee stack library including Green Power Proxy feature, touchlink feature and traces |
| ZigBee R23 RFD | 265 KB | 26 KB of Heap reserved for dynamic allocation by the Application (typical value. Refer to chapter STM32WBA stack heap size for a Zigbee device for more details) | Full 23 RFD Zigbee stack library including traces |
| ZigBee R22 FFD | 266 KB | 43 KB of Heap reserved for dynamic allocation by the Application (typical value. Refer to chapter STM32WBA stack heap size for a Zigbee device for more details) | Full R22 FFD Zigbee stack library including Green Power Proxy feature, touchlink feature and traces |
| ZigBee R22 RFD | 217 KB | 26 KB Refer to chapter STM32WBA stack heap size for a Zigbee device for more details)Refer to chapter STM32WBA stack heap chapter for more details) | Full 22 RFD Zigbee stack library including traces |
In addition to the standard Zigbee applications, ST is also delivering examples showing how to manage Zigbee and BLE in concurrency. 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 being used. Regarding the linklayer, a dedicated library (WBA6_LinkLayer_BLE_Mac_lib.a) is being used
| Application | Flash (KB) | RAM (KB) | |
| Zigbee R23_FFD + BLE | Zigbee_OnOff_Server_Coord (FFD) | 564 | 104 |
5.2.3. STM32WBA stack heap size for a Zigbee device
The heap size should be carefully tuned according to the targeted use case. A Router which wants to support a huge mesh network will need 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 will require at minimum 44 KB of RAM.
For both the Coordinator and Router device types, the number of neighbors or children the device can support depends on the size of the Network Neighbor Table (NNT). The NNT must be large enough to maintain other Routers it is in direct contact with to route packets through the network, and also large enough to maintain any potential End-Device children that want to join it.
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 0, default table sizes are used by the stack to manage typical use cases (For ex : FFD : Router addressing 32 neighbors , RFD : End device addressing 16 neighbors on the V1.5 release)
The following table represents the default table sizes on the V1.4 release:
| Default config (V.14 release) | FFD | RFD | Comment |
| ZB_NWK_NEIGHBOR_TABLE_DEFAULT_SIZE | 32 | 32 | 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. |
| ZB_NWK_NLME_ADDRMAP_TABLE_DEFAULT_SIZE | 64 | 64 | 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. |
| ZB_NWK_NLME_ROUTE_TABLE_DEFAULT_SIZE | 32 | NA | 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. |
| ZB_NWK_NLDE_BTT_TABLE_DEFAULT_SIZE | 32 | 32 | 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. |
| ZB_NWK_NLME_RREQ_TABLE_DEFAULT_SIZE | 16 | NA | requests and manage the route discovery process. |
| ZB_APS_DEVICE_KEY_PAIR_DEFAULT_COUNT | 32 | 32 | 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. |
On the comming release (V1.5,...), these values will be tuned as follow:
| Default config (Coming releases) | FFD | RFD |
| ZB_NWK_NEIGHBOR_TABLE_DEFAULT_SIZE | 64 | 16 |
| ZB_NWK_NLME_ADDRMAP_TABLE_DEFAULT_SIZE | 32 | 2 |
| ZB_NWK_NLME_ROUTE_TABLE_DEFAULT_SIZE | 32 | NA |
| ZB_NWK_NLDE_BTT_TABLE_DEFAULT_SIZE | 32 | 9 |
| ZB_NWK_NLME_RREQ_TABLE_DEFAULT_SIZE | 16 | NA |
| ZB_APS_DEVICE_KEY_PAIR_DEFAULT_COUNT | 32 | 2 |
5.2.4. STM32WBA memory requirements estimation formula
Knowing the size of each table, and the content of each of them, it is possible to compute the necessary heap to be allocated when initiating the Zigbee stack. The formula to be used is described below:
Total (Heap requested to start R23 FFD Zigbee stack) = ZB_NWK_NEIGHBOR_TABLE_DEFAULT_SIZE * 136
+ ZB_NWK_NLDE_BTT_TABLE_DEFAULT_SIZE * 8
+ ZB_NWK_NLME_ADDRMAP_TABLE_DEFAULT_SIZE * 16
+ ZB_NWK_NLME_ROUTE_TABLE_DEFAULT_SIZE * 32
+ ZB_NWK_NLME_RREQ_TABLE_DEFAULT_SIZE * 72
+ ZB_APS_DEVICE_KEY_PAIR_DEFAULT_COUNT * 88
+ 20600
According to this formula, when using the default table sizes for an FFD 23 stack, the minimal heap to be allocated is equal to 31 KB. As explained in Note (1) chapter 5.2.2, 8 KB of margin have been added in our standard Zigbee application provided in our Cube delivery. In total, 39 KB are reserved and set via the CFG_AMM_VIRTUAL_STACK_ZIGBEE_INIT_BUFFER_SIZE define.
Total (Heap requested to start R23 RFD Zigbee stack) = ZB_NWK_NEIGHBOR_TABLE_DEFAULT_SIZE * 136
+ ZB_NWK_NLDE_BTT_TABLE_DEFAULT_SIZE * 8
+ ZB_NWK_NLME_ADDRMAP_TABLE_DEFAULT_SIZE * 24
+ ZB_APS_DEVICE_KEY_PAIR_DEFAULT_COUNT * 88
+ 8448
6. Acronyms and definitions
| Term | Definition |
|---|---|
| RAM | Random Access Memory |
| ROM | Read Only Memory |
| FFD | Full Function Device |
| RFD | Reduced Function Device |
| SED | Sleepy End Device |
[[Category:Getting_Started_with_STM32WB-WBA_and_Zigbee|10]]