Developing with ZBOSS
Zigbee stack flash usage configuration

Table of Contents

Every Zigbee device uses a part of the internal flash memory to store data, which allows to restore its functionality after power cut.

The following data is stored inside the flash memory:

  • Device configuration:
    • stack profile
    • list of allowed channels
    • security settings
  • Current network data:
    • addresses of the network manager, Trust Center, and parent
    • network channel, PAN ID, assigned short address
    • network key, TC link key, install codes
    • neighbor table
    • EUI64 address resolution table
    • poll control intervals and timeout values
  • Device diagnostic data:
    • number of resets
    • number of join attempts
    • number of buffer allocation errors
  • Common application settings:
    • local binding table entries
    • binding table
    • group membership of every active endpoint
    • attribute reporting configuration
    • Green Power Proxy Basic (GPPB) data
  • Cluster specific settings
Note
The memory configuration must not be changed between firmware versions if the firmware is going to be upgraded using the OTA DFU.

Amount of memory used

The memory reserved for storing the data is divided into two virtual pages of the same size. By default, a single page size is set based on the size of the MCU flash memory.

The amount of data that is written by the Zigbee device depends on:

  • its role inside the network,
  • the complexity of the application,
  • the exact number of entries in the tables of the device.

All stored values are organized into datasets that can be updated. This organization affects the flash usage, because if a certain value changes, the whole dataset that contains its value must be updated. The following table contains the list of the defined datasets, their sizes, and the device types for which these datasets are relevant.

Dataset size [bytes] Dataset name Device type
24 NVRAM page header. All devices.
144 Common dataset (device configuration, network data). All devices.
28 Counters (NIB, AIB versions). All devices.
24 + 16 * ZB_CONFIG_IEEE_ADDR_TABLE_SIZE EUI64 address map. All devices.
24 + 8 * ZB_CONFIG_NEIGHBOR_TABLE_SIZE Neighbor table. All devices.
24 + 28 * ZB_CONFIG_N_APS_KEY_PAIR_ARR_MAX_SIZE APS link keys (e.g. TC link key). All devices.
20 + 28 * n_install_codes Install codes. All devices.
60 GPPB cluster data. Coordinator and routers.
20 + 56 * n_gppb_pt_entries GPPB proxy table. Coordinator and routers.
44 HA dataset (poll control, diagnostic data). Application-specific.
24 + 12 * n_groups APS group table. Application-specific.
20 + 24 * n_report_info Attribute reporting configuration. Application-specific.
24 + binding_table_size Local binding table. Application-specific.
44 Poll Control cluster data. Application-specific.
56 + aps_ack_exempt_table_size + aps_link_key_authorization_table_size + use_trust_center_for_cluster_table_size WWAH cluster data. Application-specific.
Defined dataset sizes and device types
Note
  • The n_install_codes variable must be equal to OVERALL_NETWORK_SIZE for the coordinator node and to 2 for other devices.
  • The n_gppb_pt_entries value ranges from 0 to 5 and is the number of entries in GPPB proxy table.
  • The value of n_report_info must be equal to the amount of reportable attributes in your application (see cluster description in the ZCL specification).
  • Use the following formula to calculate maximum value of binding_table_size: ZB_CONFIG_APS_SRC_BINDING_TABLE_SIZE * 4 + ZB_CONFIG_APS_DST_BINDING_TABLE_SIZE * 8
  • All the data tables of WWAH cluster are aligned before writing to the NVRAM.

The following table shows the estimates for the minimum value of flash memory that is written for a Zigbee device. It assumes that the network consists of two nodes.

ZC/ZR Dataset size [bytes] ZED Dataset size [bytes] Dataset name Note
24 24 NVRAM page header. Every virtual page starts with a header.
144 144 Common dataset (device configuration, network data). -
28 28 Counters (NIB, AIB versions). -
24 + 16 24 + 16 EUI64 address map. At least one for the parent device.
24 + 8 24 + 8 Neighbor table. At least one for the parent device.
24 + 56 24 + 56 APS link keys (e.g. TC link key). At least two - provisional and verified.
20 + 28 20 + 28 Install codes. If the device uses install codes for commissioning (recommended).
60 - GPPB cluster data. Mandatory for the coordinator and routers.
20 - GPPB proxy table. Mandatory for the coordinator and routers, but without GP devices in the network.
44 44 HA dataset (poll control, diagnostic data). Application-specific.
24 + 0 24 + 0 APS group table. Application does not use APS groups.
20 + 0 20 + 0 Attribute reporting configuration. Application does not have reportable attributes.
24 24 Local binding table. Low traffic, empty binding table.
Total: 588 bytes Total: 508 bytes - -
Flash memory minimum value estimates

To estimate the required amount of flash memory, you can use the value calculated above as the base. Add more entries of the application-specific datasets and, depending on your application:

  • on the coordinator node: at least 76 bytes for every additional node in the network,
  • on router nodes: at least 20 bytes for every additional node in the network.
Note
  • If the current virtual flash page is filled up with data, every valid dataset must be rewritten into a second page. Because of this, the minimal virtual page size must be greater than the amount of stored data multiplied by 4.
  • Recommended: Use larger virtual pages than calculated for a particular network to reduce the amount of flash erase cycles and extend the device lifetime.

Adjusting persistent data area

In nRF Connect SDK, the ZBOSS persistent data area is adjusted automatically by the Partition Manager. However, you can define the size of partitions by modifying the following Zephyr subsystem configurations in Partition Manager:

  • NVS_STORAGE
  • ZBOSS_NVRAM
  • ZBOSS_PROD_CONFIG

It is recommended to keep the default size of both ZBOSS partitions.

The persistent data is by default stored close to the end of flash memory.