The Simulated EEPROM v1 and v2 libraries responsible for abstracting non-volatile data storage ("tokens") across the underlying flash wear-leveling medium are designed to accommodate changes in token definitions between the in-memory data on the chip and the compile-time parameters used by the currently running application. This is done at SimEEPROM initialization time by examining the token metadata at the top of each SimEEPROM virtual page (see AN703 for background), which records the size in bytes and creator ID (a unique 16-bit value defined in the token header) of each token, and comparing this with the running application's token definitions.
In general, the result of the token comparison will be as follows:
If the size of a Basic or Counter token or per-element size of an Indexed token has changed, the token is assumed to be different/incompatible and will be re-initialized at startup to its compile-time default value.
Regarding Indexed (array) tokens: If an array size is decreased, elements above the new array size will be flagged as out of range and ignored. If an array size is increased, elements that are not found in flash will be loaded from default values.
If the token type (Basic/Counter/Indexed) has changed, the token is considered different and will be reinitialized to its default value.
Also note that changes between SimEEPROM versions can impact the tokens:
If the saved data is in SimEEPROM v1 format and the new firmware uses SimEEPROM v2 Library and does not include upgrade library code (sim-eeprom2-1to2upgrade-stub plugin used), the SimEEPROM code will fail to initialize and will reset with an assert() failure, leaving intact the existing tokens in flash.
If the saved data is in SimEEPROM v1 format and the new firmware uses SimEEPROM v2 Library and does include upgrade library code (sim-eeprom2-1to2upgrade), the SimEEPROM code will attempt to preserve all tokens in the manner noted earlier in this article and convert them into SimEEPROM v2 format.
If the saved data is in SimEEPROM v2 format and the new firmware uses SimEEPROM v1 Library and does not include the plugin option for "Destructive downgrade", the SimEEPROM code will fail to initialize and will reset with an assert() failure, leaving intact the existing tokens in flash.
If the saved data is in SimEEPROM v2 format and the new firmware uses SimEEPROM v1 Library and does include the plugin option for "Destructive downgrade", the SimEEPROM code will remove/reinitialize all token data, setting them to their compile-time default values.
The process for upgrading from SimEEPROM v2 to NVM3 format requires addition of Creator and Key defines. This is described in AN1135.
Zigbee & Thread Knowledge Base
How do the Simulated EEPROM libraries handle changes in tokens after firmware update?
The Simulated EEPROM v1 and v2 libraries responsible for abstracting non-volatile data storage ("tokens") across the underlying flash wear-leveling medium are designed to accommodate changes in token definitions between the in-memory data on the chip and the compile-time parameters used by the currently running application. This is done at SimEEPROM initialization time by examining the token metadata at the top of each SimEEPROM virtual page (see AN703 for background), which records the size in bytes and creator ID (a unique 16-bit value defined in the token header) of each token, and comparing this with the running application's token definitions.
In general, the result of the token comparison will be as follows:
Also note that changes between SimEEPROM versions can impact the tokens:
For further information about tokens and SimEEPROM, see UG103.7: Non-Volatile Data Storage Fundamentals