tr_nvram_attr.h File Reference

this file formats plugin data for saving to non-volatile space. More...

#include "tr_af.h"

Include dependency graph for tr_nvram_attr.h:

Go to the source code of this file.

Data Structures
struct	tr_nvram_section_header_t
	struct for the section header that starts each data section More...
struct	tr_nvram_data_info_t
	struct that a plugin fills in to have its plugin data saved More...

Macros
#define	TR_NVRAM_STORAGE_VER_1   (1)
#define	TR_NVRAM_STORAGE_VER_2   (2)
#define	TR_NVRAM_WRITE_DELAY_MS   (2000)
#define	TR_NVRAM_ATTR_STORAGE_VER_1   (1)
#define	TR_NVRAM_ATTR_STORAGE_CUR_VER   (TR_NVRAM_ATTR_STORAGE_VER_1)
#define	TR_NVRAM_SECTION_ID_ZIGBEE_ATTRS   0x8001
#define	tr_nvram_printf(...)
#define	tr_nvram_verbose_printf(...)
#define	TR_NVRAM_SCENES_SLOTS   0
	this defines the number of slots available for plugins to register to save their data
#define	TR_NVRAM_DOOR_LOCK_SLOTS   0
#define	TR_NVRAM_NUM_APP_SECTIONS   1
#define	TR_NVRAM_NUM_TABLE_SLOTS   (TR_NVRAM_NUM_APP_SECTIONS + TR_NVRAM_DOOR_LOCK_SLOTS + TR_NVRAM_SCENES_SLOTS)

Typedefs
struct {
zb_uint8_t   endpoint
zb_uint16_t   cluster_id
zb_uint16_t   attr_id
zb_uint8_t   cluster_role
zb_uint16_t   manuf_code
zb_uint8_t   data_type
}	tr_nvram_attr_storage_v1_t
	structure for storing information about zigbee attributes in NV
typedef zb_bool_t(*	tr_nvram_clear_data_t) (void)
	function pointer type for clearing the callback data or NULL to use default behavior (set to 0)
typedef zb_bool_t(*	tr_nvram_err_handler_t) (zb_uint8_t *saved_data_ptr, zb_uint8_t data_entry_size, zb_uint8_t data_num_entries)
	function pointer type for handling size or version errors or NULL to abort data read in this casee

Enumerations
enum	tr_nvram_section_id_t {   TR_NVRAM_SECTION_ZIGBEE_ATTRIBUTES = 1 ,   TR_NVRAM_SECTION_SCENES_TABLE = 2 ,   TR_NVRAM_SECTION_DOOR_LOCK_USER_TABLE = 3 ,   TR_NVRAM_SECTION_TSTAT_SCHEDULE_TABLE = 4 ,   TR_NVRAM_SECTION_APP_DATA_1 = 101 }
	standard section IDs used by Trident plugins and reserved for use by the application More...

Functions
zb_uint16_t	tr_get_nvram_data_size (void)
	there are 3 API functions needed by ZBOSS and passed by the apps
zb_ret_t	tr_nvram_write_app_data_cb (zb_uint8_t page, zb_uint32_t pos)
	write API: do not change this without reading below
void	tr_nvram_read_app_data_cb (zb_uint8_t page, zb_uint32_t pos, zb_uint16_t payload_length)
	read API: do not change this without reading below
void	tr_check_for_attr_nvram_update (zb_uint8_t ep, zb_uint16_t cluster_id, zb_uint8_t cluster_role, zb_uint16_t attr_id, zb_uint16_t manuf_code)
	check if a changed attr is supposed to be saved in NV and if so, save it
void	tr_check_for_attr_nvram_update_delay (zb_uint8_t ep, zb_uint16_t cluster_id, zb_uint8_t cluster_role, zb_uint16_t attr_id, zb_uint16_t manuf_code, zb_uint16_t delay_time_ms)
	check if a changed attr is supposed to be saved in NV and if so, save it
void	tr_nvram_register (tr_nvram_data_info_t *register_data)
	this API is called by a plugin to register to have its data saved
void	tr_nvram_save (zb_uint16_t delay_time_ms)
	this API is called by a plugin when plugin data has changed

Detailed Description

this file formats plugin data for saving to non-volatile space.

---

The code in this file helps to save plugin data to nonvolatile storage. In order to make this work for different chips, and to provide wear leveling it works like this:

1. we expect the zigbee app to setup functions contained in this file as callbacks in ZBOSS, like this: zb_nvram_register_app4_read_cb(tr_nvram_read_app_data_cb); zb_nvram_register_app4_write_cb(tr_nvram_write_app_data_cb, tr_get_nvram_data_size);
2. the APIs in this file call ZBOSS APIs: zb_nvram_read_data(page, position, ptr_to_write_to, len) zb_nvram_write_data(page pos, ptr_to_data, len) zb_nvram_write_dataset(set id) These are in ZBOSS source code and SHOULD NOT be changed.
3. The ZBOSS APIs call OSIF functions, which ties this to a specific chip, and does the actual writing and reading from nonvolatile. for instance, for the CM11: Tridentiot-sdk\platform\T32CM11\zboss\osif\zb_rt570_nvram.c

We need to provide 3 main functions to make this work: READ, WRITE, and SIZE there are helper functions for each of these APIs that handle size, read, and write for any plugin that needs to save data, so far there are 2: zigbee attr table and scenes table.

if a plugin wants to save data in NV, it registers with this module by calling: tr_nvram_register(tr_nvram_data_info_t *register_data);

and passes in a struct that has all the relevant information:

• ptr to the data
• size of a table entry
• number of table entries
• a unique section ID and data version
• a function ptr to clear data, or NULL to use the default "set all to 0s"
• a function ptr to handle errors, or NULL for the code to abort restore on version or size errors

if a plugin changes its RAM data and wants to save the data in NV, it calls: void tr_nvram_save(zb_uint16_t delay_time_ms);

and passes in 0 to save immediately and a nonzero value to save at that time (this delay allows other changes to happen in the delay window which would start another delay window and minimizes the flash writes)

In order to allow for apps to change and support different plugins each plugins data is saved as a section. Each section has a 4 bytes header:

• section ID (must be unique, currently the ones used are in tr_nvram_attr.h)
• section data version
• data entry size (size of 1 entry in a table, usually the stored struct)
• number of entries in the table By understanding the data entry size and number of entries, the NV save/restore code can handle when table sizes get larger or smaller. If the data itself changes (like a field in the struct) there is no straightforward way to handle this so the data is sent back to the plugin via the error callback function. Similarly, the plugin can rev the data version and force an upgrade to go thru the plugin (since this would make the NV save/restore call the plugin error function)

SPDX-License-Identifier: LicenseRef-TridentMSLA SPDX-FileCopyrightText: 2025 Trident IoT, LLC https://www.tridentiot.com

---

Macro Definition Documentation

TR_NVRAM_ATTR_STORAGE_CUR_VER

#define TR_NVRAM_ATTR_STORAGE_CUR_VER   (TR_NVRAM_ATTR_STORAGE_VER_1)

TR_NVRAM_ATTR_STORAGE_VER_1

#define TR_NVRAM_ATTR_STORAGE_VER_1   (1)

tr_nvram_printf

#define tr_nvram_printf

(

...

)

---

enable this to print when errors occur

---

TR_NVRAM_SECTION_ID_ZIGBEE_ATTRS

#define TR_NVRAM_SECTION_ID_ZIGBEE_ATTRS   0x8001

TR_NVRAM_STORAGE_VER_1

#define TR_NVRAM_STORAGE_VER_1   (1)

TR_NVRAM_STORAGE_VER_2

#define TR_NVRAM_STORAGE_VER_2   (2)

tr_nvram_verbose_printf

#define tr_nvram_verbose_printf

(

...

)

---

these are for verbose printing of the read, write, and size APIs

---

TR_NVRAM_WRITE_DELAY_MS

#define TR_NVRAM_WRITE_DELAY_MS   (2000)

Variable Documentation

attr_id

zb_uint16_t attr_id

cluster_id

zb_uint16_t cluster_id

cluster_role

zb_uint8_t cluster_role

data_type

zb_uint8_t data_type

endpoint

zb_uint8_t endpoint

manuf_code

zb_uint16_t manuf_code