|
Coming soon |
1. Introduction
In a Zigbee network, if a node is turned off due to a power shutdown or any other reason, the network data stored in its Random Access Memory (RAM) will be lost. This can result in the loss of important information and affect the functioning of the network, which is why we need to store some data, called Persistent Data, in a Non-Volatile Memory (NVM). These data can be network settings, security keys, or other configuration information.
This wiki describes the dedicated persistent data APIs used for storing data in the STM32WB flash memory.
2. STM32WB persistent data management
By saving critical data in the NVM each time they change, the Zigbee network node ensures that they are always up-to-date and that the node can quickly recover from a power failure or other unexpected event.
The end user has two options:
- Manually manage when to save data in the NVM.
- Rely on the stack notification.
If the end user chooses to manage the saving of data in the NVM himself, they need to determine the appropriate time to call the save data function based on their specific use case and application requirements. On the other hand, if the end user chooses to rely on the stack notifications, they can use these notifications as triggers to automatically save critical data in the NVM, ensuring that the data is always up-to-date and persistent.
2.1. Stack Notification
The STM32WB ZigBee stack notifies the application each time the persistent data change. First, the application must enable notification by registering persistent data change notification.
/* Register Persistent data change notification */
ZbPersistNotifyRegister(zigbee_app_info.zb, APP_ZIGBEE_persist_notify_cb, NULL);
Once persistent data change notification is registered, end-user needs to implement the callback function to handle the notification. This function will be called each time there is a persistent data change in the Zigbee network.
/*
* @brief notify to save persistent data callback
* @param zb: zigbee context pointer, cbarg: callback arg pointer
* @retval: None
*/
static void APP_ZIGBEE_persist_notify_cb(struct ZigbeeT * zb, void *cbarg)
{
APP_DBG("Notification to save persistent data requested from stack");
/* Save the persistent data */
APP_ZIGBEE_persist_save();
}
In order to disable the notification, the application calls the stack API with NULL parameters:
/* Disable Notification */
ZbPersistNotifyRegister(zigbee_app_info.zb, NULL, NULL);
2.2. STM32WB Memory Mapping
As shown in the figure below, there are two APIs used to store and retrieve the persistent data:
- The ZbPersistGet API allows getting data and its length from an internal stack buffer in RAM. They are then copied into a RAM cache and written to Flash through the EEPROM emulator.
- The ZbStartupPersist API allows initializing/starting Zigbee stack using persistent data from the buffer (previously copied from the Flash through the EEPROM emulator).
It is important to note that both APIs are at the M0 level and only manipulate the internal stack buffers in RAM.
| Memory Mapping |
|---|
Note : Cluster attributes are not persistent data by default. An attribute must be declared using ZCL_ATTR_FLAG_PERSISTABLE flag to be persistent data.
const struct ZbZclAttrT zcl_onoff_server_attr_list[] =
{
{
ZCL_ONOFF_ATTR_ONOFF, ZCL_DATATYPE_BOOLEAN,
ZCL_ATTR_FLAG_REPORTABLE|ZCL_ATTR_FLAG_PERSISTABLE, 0, NULL, {0, 0}, {0, 0}
},
};
3. EEPROM Emulator
NVM is typically implemented using flash memory or EEPROM technology, which allows data to be written and rewritten many times, providing long-term data storage capabilities. In a Zigbee network, the EEPROM Emulator is made up of three parts: the EEPROM Emulation header, the NVN layer, and the application layer.
The STM32WB NVM uses the EEPROM emulator which impact the real size available for the persistent data.
The STM32WB internal Flash memory unit is the page, a page size is 4 Kbytes and its width is 64 bits.
It is important to note that the available size of EEPROM Emulator is limited, and care should be taken to use this storage space efficiently to ensure the stable and reliable operation of the Zigbee network.
Basically, as shown in the figure below, we have a first header of 4 U64 words is taken for the page, and a second EE header for each record that sizes U32 words (2032 bytes). Thus, the remaining size per page for data is 2032 bytes.
| Flash memory example with EEPROM Emulator |
|---|
End-user must declare the allocated Flash memory dedicated for NVM in the scatter file. It must be ranged between the M0 starting address and the M4 starting address, and must be a multiple of 2 pages.
4. STM32WB NVM application example
An example of NVM utilization is provided in STM32CubeWB MCU Package[1]. This example is based on On/Off cluster.
4.1. STM32WB APIs Description
To handle persistent data management in Zigbee networks, we need to implement a set of APIs that allow devices to read and write data to non-volatile memory. The following table describes the list of APIs that we have implemented in this application example.
| API | Description |
|---|---|
| Persistent data application APIs | |
| APP_ZIGBEE_persistent_save | Starts the persistent data saving procedure |
| APP_ZIGBEE_persistent_load | Starts the persistent data loading procedure |
| APP_ZIGBEE_persistent_delete | Starts the persistent data clearing procedure |
| NVM application APIs | |
| APP_ZIGBEE_NVM_Init | Initializes the NVM |
| APP_ZIGBEE_NVM_Write | Starts to write the persistent data to the NVM form cache |
| APP_ZIGBEE_NVM_Read | Starts to read the persistent data from the NVM and load the cache |
| APP_ZIGBEE_NVM_Erase | Starts to erase the NVM and clear the cache |
| EE APIs | |
| EE_Init | Initializes the EE. If format variable is set the NVM Erase is triggered |
| EE_Write | Writes the persistent data to NVM adding EE header |
| EE_Read | Read the persistent data from NVM stripping EE header off |
4.2. STM32WB Application Setup
We provide two projects on STM32WB, one for coordinator and the other for the router.
To test the application, we need at least 2 STM32WB boards. Both boards are flashed with stm32wb5x_Zigbee_FFD_fw.bin for wireless coprocessor, and for the application, we flash the first board with the Zigbee_OnOff_Coord_NVM binary and the second board with the Zigbee_OnOff_Router_NVM binary.
The goal of this application is to enable NVM capability for storing persistent data. OnOff attributes are defined with the ZCL_ATTR_FLAG_PERSISTABLE flag, so their last values are stored in the NVM. If the Router is powered off then back on, it will start from its persisted state (Green Led light On) and restore its previous red LED state.
| Application use case |
|---|
5. Why NVM is significant ?
- It is recommended to activate the NVM feature in order to store binding information. Binding [2] information includes details about which devices are bound together, how they are bound together, and what settings are used for communication between them. Ideally, these information must be retained even if the device loses power.
For example, if a light switch control is bound to a light bulb, the binding information would be stored in the NVM of both devices. If the light switch is turned off or the light bulb loses power, the binding information is still retained in the NVM of both devices, so they will still be able to communicate with each other and resume their previous state when power is restored.
- Typically, reporting configuration for a particular attribute is stored in the device's NVM. This means that even if the device loses power or is reset, the reporting configuration for that attribute will be retained.
For example, if a temperature sensor is configured to report its temperature reading every 15 seconds, this configuration would be stored in the device's NVM. If the device loses power and is restarted, it will automatically resume reporting its temperature reading every 15 seconds without needing to be reconfigured.
- OTA upgrade[3] device firmware also need the NVM technology. In fact, when OTA update is received, it can be stored in the device's NVM until the device is restarted or reprogrammed to apply the update.
Hence, NVM helps to ensure reliable and consistent communication between devices in Zigbee network.
For more details, please refer to the AN5492: Persistent data management ZigBee® and non-volatile memory in STM32WB Series[4].
6. References
[[Category:Zigbee|40]]