NVRAM

Data Structures
struct	zb_nvram_failure_report_s
	Structure that contains report about any NVRAM failure. Pointer to this structure will be set as additional info in error_app_handler with error code ERROR_CODE(ERROR_CATEGORY_NVRAM, ZB_ERROR_NVRAM_WRITE_VALIDATION_FAILURE). Upon receiving of this error, user can decide what to do: More...

Macros
#define	ZB_NVRAM_DATA_SET_TYPE_PAGE_HDR_R22   30u
#define	ZB_NVRAM_APP_DATASET_NUMBER   4U

Typedefs
typedef enum zb_nvram_dataset_types_e	zb_nvram_dataset_types_t
typedef struct zb_nvram_failure_report_s	zb_nvram_failure_report_t
	Structure that contains report about any NVRAM failure. Pointer to this structure will be set as additional info in error_app_handler with error code ERROR_CODE(ERROR_CATEGORY_NVRAM, ZB_ERROR_NVRAM_WRITE_VALIDATION_FAILURE). Upon receiving of this error, user can decide what to do: More...
typedef void(*	zb_nvram_read_app_data_t) (zb_uint8_t page, zb_uint32_t pos, zb_uint16_t payload_length)
typedef zb_ret_t(*	zb_nvram_write_app_data_t) (zb_uint8_t page, zb_uint32_t pos)
typedef zb_uint16_t(*	zb_nvram_get_app_data_size_t) (void)

Enumerations
enum	zb_nvram_dataset_types_e {   ZB_NVRAM_RESERVED = 0, ZB_NVRAM_COMMON_DATA = 1, ZB_NVRAM_HA_DATA = 2, ZB_NVRAM_ZCL_REPORTING_DATA = 3,   ZB_NVRAM_APS_SECURE_DATA_GAP = 4, ZB_NVRAM_APS_BINDING_DATA_GAP = 5, ZB_NVRAM_HA_POLL_CONTROL_DATA = 6, ZB_NVRAM_APS_SECURE_DATA = 7,   ZB_NVRAM_DATASET_GRPW_DATA = 8, ZB_NVRAM_APP_DATA1 = 9, ZB_NVRAM_APP_DATA2 = 10, ZB_NVRAM_ADDR_MAP = 11,   ZB_NVRAM_NEIGHBOUR_TBL = 12, ZB_NVRAM_INSTALLCODES = 13, ZB_NVRAM_IB_COUNTERS = 14, ZB_NVRAM_APS_BINDING_DATA = 15,   ZB_NVRAM_DATASET_GP_PRPOXYT = 16, ZB_NVRAM_DATASET_GP_SINKT = 17, ZB_NVRAM_DATASET_GP_CLUSTER = 18, ZB_NVRAM_APS_GROUPS_DATA = 19,   ZB_NVRAM_DATASET_SE_CERTDB = 20, ZB_NVRAM_ZCL_WWAH_DATA = 21, ZB_NVRAM_DATASET_GP_APP_TBL = 22, ZB_NVRAM_APP_DATA3 = 27,   ZB_NVRAM_APP_DATA4 = 28, ZB_NVRAM_KE_WHITELIST = 29, ZB_NVRAM_DATASET_ZB_DIRECT = 30, ZB_NVRAM_ZDO_DIAGNOSTICS_DATA = 31,   ZB_NVRAM_DATASET_NUMBER, ZB_NVRAM_DATA_SET_TYPE_PAGE_HDR = 0xFFFFU }

Functions
void	zb_nvram_register_app1_read_cb (zb_nvram_read_app_data_t cb)
void	zb_nvram_register_app2_read_cb (zb_nvram_read_app_data_t cb)
void	zb_nvram_register_app3_read_cb (zb_nvram_read_app_data_t cb)
void	zb_nvram_register_app4_read_cb (zb_nvram_read_app_data_t cb)
void	zb_nvram_register_app1_write_cb (zb_nvram_write_app_data_t wcb, zb_nvram_get_app_data_size_t gcb)
void	zb_nvram_register_app2_write_cb (zb_nvram_write_app_data_t wcb, zb_nvram_get_app_data_size_t gcb)
void	zb_nvram_register_app3_write_cb (zb_nvram_write_app_data_t wcb, zb_nvram_get_app_data_size_t gcb)
void	zb_nvram_register_app4_write_cb (zb_nvram_write_app_data_t wcb, zb_nvram_get_app_data_size_t gcb)
zb_ret_t	zb_nvram_write_dataset (zb_nvram_dataset_types_t t)
void	zb_nvram_erase (void)
void	zb_set_nvram_erase_at_start (zb_bool_t erase)
void	zb_nvram_transaction_start (void)
void	zb_nvram_transaction_commit (void)
zb_ret_t	zb_nvram_read_data (zb_uint8_t page, zb_uint32_t pos, zb_uint8_t *buf, zb_uint16_t len)
zb_ret_t	zb_nvram_write_data (zb_uint8_t page, zb_uint32_t pos, zb_uint8_t *buf, zb_uint16_t len)

Detailed Description

After the zboss_start() call, the ZBOSS stack reads the whole flash page and looks for the valid version of each dataset. If the valid application dataset is found, the read/load callback is called. The callback should store the read value inside the RAM using its own static/global variable.

Afterwards, it is assumed that the application uses the static/global variable to perform changes or read dataset field values.

Whenever needed, the application may call the zb_nvram_write_dataset() in order to store the updated dataset inside the flash.

Every call to the zb_nvram_write_dataset() triggers the write/store callback. The callback should get the static/global variable and use the zb_osif_nvram_write() to store its current value.

If there is no user dataset stored inside the flash, the callback will not be called, so the static/global variable should be initialized with valid default values before calling zboss_start().

There are also four predefined dataset IDs for a user application: ZB_NVRAM_APP_DATA1 , ZB_NVRAM_APP_DATA2 , ZB_NVRAM_APP_DATA3 and ZB_NVRAM_APP_DATA4. It is up to the application to decide what data to store in the NVRAM in these datasets.

To use application specific datasets, the appropriate callbacks should be defined in the application and registered by zb_nvram_register_appx_read_cb() and zb_nvram_register_appx_write_cb().

One callback is to be passed to zb_nvram_register_appx_read_cb(). This callback should get the static/global variable and use zb_osif_nvram_read() to read its value from the flash memory. Two callbacks are to be passed to zb_nvram_register_appx_write_cb(). One of them should get the static/global variable and use zb_osif_nvram_write() to store its current value. It should return error code from zb_osif_nvram_write(). The second should return the size of the application dataset structure.

Note

The total data size (all datasets) stored in the NVRAM storage should be less than one virtual page size.

Example #1:

  /* If we fail, trace is given and assertion is triggered */
  /* Write to NVRAM HA profile Zigbee data */
  (void)zb_nvram_write_dataset(ZB_NVRAM_HA_DATA);
  /* Write to NVRAM ZCL reporting data */
  (void)zb_nvram_write_dataset(ZB_NVRAM_ZCL_REPORTING_DATA);

Example #2 (Using application callbacks):
Define user dataset type:

/* Application dataset for persisting into nvram */
typedef ZB_PACKED_PRE struct bulb_device_nvram_dataset_s
{
  zb_uint8_t onoff_state;
  zb_uint8_t current_level;
  /* Size of the structure in bytes must be divisible by 4 */
  zb_uint8_t reserved[2];
} ZB_PACKED_STRUCT
bulb_device_nvram_dataset_t;

Callback prototypes:

/* Application callback for writing application data to NVRAM */
zb_ret_t bulb_nvram_write_app_data(zb_uint8_t page, zb_uint32_t pos);
/* Application callback for reading application data from NVRAM */
void bulb_nvram_read_app_data(zb_uint8_t page, zb_uint32_t pos, zb_uint16_t payload_length);
/* Application callback to determine application NVRAM stored dataset size */
zb_uint16_t bulb_get_nvram_data_size();

Register application callbacks:

  /* Register application callback for reading application data from NVRAM */
  zb_nvram_register_app1_read_cb(bulb_nvram_read_app_data);
  /* Register application callback for writing application data to NVRAM */
  zb_nvram_register_app1_write_cb(bulb_nvram_write_app_data, bulb_get_nvram_data_size);

Callback implementation:

zb_uint16_t bulb_get_nvram_data_size(void)
{
  TRACE_MSG(TRACE_APP1, "bulb_get_nvram_data_size, ret %hd", (FMT__H, sizeof(bulb_device_nvram_dataset_t)));
  return sizeof(bulb_device_nvram_dataset_t);
}
 
void bulb_nvram_read_app_data(zb_uint8_t page, zb_uint32_t pos, zb_uint16_t payload_length)
{
  bulb_device_nvram_dataset_t ds;
  zb_ret_t ret;
/* [trace_msg] */
  TRACE_MSG(TRACE_APP1, ">> bulb_nvram_read_app_data page %hd pos %d", (FMT__H_D, page, pos));
/* [trace_msg] */
  ZB_ASSERT(payload_length == sizeof(ds));
 
  ret = zb_nvram_read_data(page, pos, (zb_uint8_t*)&ds, sizeof(ds));
 
  if (ret == RET_OK)
  {
    zb_zcl_attr_t *attr_desc;
 
    attr_desc = zb_zcl_get_attr_desc_a(HA_DIMMABLE_LIGHT_ENDPOINT,ZB_ZCL_CLUSTER_ID_ON_OFF,
                                       ZB_ZCL_CLUSTER_SERVER_ROLE, ZB_ZCL_ATTR_ON_OFF_ON_OFF_ID);
 
    ZB_ZCL_SET_DIRECTLY_ATTR_VAL8(attr_desc, ds.onoff_state);
 
    attr_desc = zb_zcl_get_attr_desc_a(HA_DIMMABLE_LIGHT_ENDPOINT, ZB_ZCL_CLUSTER_ID_LEVEL_CONTROL,
                                       ZB_ZCL_CLUSTER_SERVER_ROLE,ZB_ZCL_ATTR_LEVEL_CONTROL_CURRENT_LEVEL_ID);
 
    ZB_ZCL_SET_DIRECTLY_ATTR_VAL16(attr_desc, ds.current_level);
 
    if (ds.onoff_state)
    {
#ifdef ZB_USE_BUTTONS
      bulb_hal_set_level(ds.current_level);
#endif
    }
    else
    {
#ifdef ZB_USE_BUTTONS
      bulb_hal_set_on_off(ZB_FALSE);
#endif
    }
  }
 
  TRACE_MSG(TRACE_APP1, "<< bulb_nvram_read_app_data ret %d", (FMT__D, ret));
}
 
zb_ret_t bulb_nvram_write_app_data(zb_uint8_t page, zb_uint32_t pos)
{
  zb_ret_t ret;
  bulb_device_nvram_dataset_t ds;
  zb_zcl_attr_t *attr_desc = zb_zcl_get_attr_desc_a(HA_DIMMABLE_LIGHT_ENDPOINT,ZB_ZCL_CLUSTER_ID_ON_OFF,
                                                    ZB_ZCL_CLUSTER_SERVER_ROLE,ZB_ZCL_ATTR_ON_OFF_ON_OFF_ID);
 
  TRACE_MSG(TRACE_APP1, ">> bulb_nvram_write_app_data, page %hd, pos %d", (FMT__H_D, page, pos));
 
  ds.onoff_state = ZB_ZCL_GET_ATTRIBUTE_VAL_8(attr_desc);
 
  attr_desc = zb_zcl_get_attr_desc_a(HA_DIMMABLE_LIGHT_ENDPOINT, ZB_ZCL_CLUSTER_ID_LEVEL_CONTROL,
                                     ZB_ZCL_CLUSTER_SERVER_ROLE, ZB_ZCL_ATTR_LEVEL_CONTROL_CURRENT_LEVEL_ID);
 
  ds.current_level = ZB_ZCL_GET_ATTRIBUTE_VAL_8(attr_desc);
 
  ret = zb_nvram_write_data(page, pos, (zb_uint8_t*)&ds, sizeof(ds));
 
  TRACE_MSG(TRACE_APP1, "<< bulb_nvram_write_app_data, ret %d", (FMT__D, ret));
 
  return ret;
}

Application NVRAM usage:

      /* If we fail, trace is given and assertion is triggered */
      /* Persist application data into NVRAM */
      (void)zb_nvram_write_dataset(ZB_NVRAM_APP_DATA1);

See light_sample application

Typedef Documentation

zb_nvram_dataset_types_t

typedef enum zb_nvram_dataset_types_e zb_nvram_dataset_types_t

Enum All NVRAM dataset types

ZB_NVRAM_DATASET_NUMBER - count of dataset types. Not a real dataset type!

zb_nvram_failure_report_t

typedef struct zb_nvram_failure_report_s zb_nvram_failure_report_t

Structure that contains report about any NVRAM failure. Pointer to this structure will be set as additional info in error_app_handler with error code ERROR_CODE(ERROR_CATEGORY_NVRAM, ZB_ERROR_NVRAM_WRITE_VALIDATION_FAILURE). Upon receiving of this error, user can decide what to do:

1. Do nothing - stack will be reset immediately, all not corrupted datasets will be copied to another page.
2. Clear nvram.
3. Manually implement function that implements user logic in this case.

zb_nvram_get_app_data_size_t

typedef zb_uint16_t(* zb_nvram_get_app_data_size_t) (void)

Returns size of application datasets

Returns

- size of application dataset in bytes

zb_nvram_read_app_data_t

typedef void(* zb_nvram_read_app_data_t) (zb_uint8_t page, zb_uint32_t pos, zb_uint16_t payload_length)

Declares application callback used for reading application datasets from NVRAM.

Parameters

page	- page in NVRAM from data will be read
pos	- offset in page
payload_length	- number of bytes to read (aligned to 4)

zb_nvram_write_app_data_t

typedef zb_ret_t(* zb_nvram_write_app_data_t) (zb_uint8_t page, zb_uint32_t pos)

Declares application callback used for writing application datasets into NVRAM.

Parameters

page	- page in NVRAM where data will be stored
pos	- offset in page

Returns

- RET_OK on successful write

Enumeration Type Documentation

zb_nvram_dataset_types_e

enum zb_nvram_dataset_types_e

Enum All NVRAM dataset types

ZB_NVRAM_DATASET_NUMBER - count of dataset types. Not a real dataset type!

Enumerator
ZB_NVRAM_RESERVED	Reserved value
ZB_NVRAM_COMMON_DATA	Dataset, contains common Zigbee data
ZB_NVRAM_HA_DATA	Dataset, contains HA profile Zigbee data
ZB_NVRAM_ZCL_REPORTING_DATA	Dataset, contains ZCL reporting data
ZB_NVRAM_APS_SECURE_DATA_GAP	Reserved value
ZB_NVRAM_APS_BINDING_DATA_GAP	Reserved value
ZB_NVRAM_HA_POLL_CONTROL_DATA	Dataset, contains HA POLL CONTROL data
ZB_NVRAM_APS_SECURE_DATA	Dataset, contains NIB outgoing frame counter
ZB_NVRAM_DATASET_GRPW_DATA	Green Power dataset
ZB_NVRAM_APP_DATA1	Application-specific data #1
ZB_NVRAM_APP_DATA2	Application-specific data #2
ZB_NVRAM_ADDR_MAP	Dataset stores address map info
ZB_NVRAM_NEIGHBOUR_TBL	Dataset stores Neighbor table info
ZB_NVRAM_INSTALLCODES	Dataset contains APS installcodes data
ZB_NVRAM_IB_COUNTERS	Dataset, contains APS secure keys data
ZB_NVRAM_APS_BINDING_DATA	Dataset, contains APS binding data
ZB_NVRAM_DATASET_GP_PRPOXYT	Green Power Proxy table
ZB_NVRAM_DATASET_GP_SINKT	Green Power Sink table
ZB_NVRAM_DATASET_GP_CLUSTER	Green Power Cluster data
ZB_NVRAM_APS_GROUPS_DATA	Dataset, contains APS groups data
ZB_NVRAM_DATASET_SE_CERTDB	Smart Energy Dataset - Certificates DataBase
ZB_NVRAM_ZCL_WWAH_DATA	Dataset, contains ZCL WWAH data
ZB_NVRAM_DATASET_GP_APP_TBL	Dataset, contains ZCL WWAH data
ZB_NVRAM_APP_DATA3	Application-specific data #3
ZB_NVRAM_APP_DATA4	Application-specific data #4
ZB_NVRAM_DATASET_ZB_DIRECT	Zigbee Direct dataset
ZB_NVRAM_ZDO_DIAGNOSTICS_DATA	Dataset of the Diagnostics cluster
ZB_NVRAM_DATASET_NUMBER	Count of Dataset
ZB_NVRAM_DATA_SET_TYPE_PAGE_HDR	Special internal dataset type

Function Documentation

zb_nvram_erase()

void zb_nvram_erase

(

void

)

Erase Informational Bases to NVRAM or other persistent storage

zb_nvram_read_data()

zb_ret_t zb_nvram_read_data	(	zb_uint8_t	page,
		zb_uint32_t	pos,
		zb_uint8_t *	buf,
		zb_uint16_t	len
	)

Reads a portion of some dataset.

Parameters

page	- an NVRAM page to read from
pos	- a position on the NVRAM page
buf	- a buffer where read data will be saved
len	- a data length to read

Returns

Status of operation

zb_nvram_register_app1_read_cb()

void zb_nvram_register_app1_read_cb

(

zb_nvram_read_app_data_t

cb

)

Register application callback for reading ZB_NVRAM_APP_DATA1 from NVRAM

Parameters

cb	- callback that will be called upon reading dataset

zb_nvram_register_app1_write_cb()

void zb_nvram_register_app1_write_cb	(	zb_nvram_write_app_data_t	wcb,
		zb_nvram_get_app_data_size_t	gcb
	)

Register application callback for writing ZB_NVRAM_APP_DATA1 to NVRAM

Parameters

wcb	- callback that will be called upon writing
gcb	- this callback will be called upon writing to determine dataset size

zb_nvram_register_app2_read_cb()

void zb_nvram_register_app2_read_cb

(

zb_nvram_read_app_data_t

cb

)

Register application callback for reading ZB_NVRAM_APP_DATA2 from NVRAM

Parameters

cb	- callback that will be called upon reading dataset

zb_nvram_register_app2_write_cb()

void zb_nvram_register_app2_write_cb	(	zb_nvram_write_app_data_t	wcb,
		zb_nvram_get_app_data_size_t	gcb
	)

Register application callback for writing ZB_NVRAM_APP_DATA2 to NVRAM

Parameters

wcb	- callback that will be called upon writing
gcb	- this callback will be called upon writing to determine dataset size

zb_nvram_register_app3_read_cb()

void zb_nvram_register_app3_read_cb

(

zb_nvram_read_app_data_t

cb

)

Register application callback for reading ZB_NVRAM_APP_DATA3 from NVRAM

Parameters

cb	- callback that will be called upon reading dataset

zb_nvram_register_app3_write_cb()

void zb_nvram_register_app3_write_cb	(	zb_nvram_write_app_data_t	wcb,
		zb_nvram_get_app_data_size_t	gcb
	)

Register application callback for writing ZB_NVRAM_APP_DATA3 to NVRAM

Parameters

wcb	- callback that will be called upon writing
gcb	- this callback will be called upon writing to determine dataset size

zb_nvram_register_app4_read_cb()

void zb_nvram_register_app4_read_cb

(

zb_nvram_read_app_data_t

cb

)

Register application callback for reading ZB_NVRAM_APP_DATA4 from NVRAM

Parameters

cb	- callback that will be called upon reading dataset

zb_nvram_register_app4_write_cb()

void zb_nvram_register_app4_write_cb	(	zb_nvram_write_app_data_t	wcb,
		zb_nvram_get_app_data_size_t	gcb
	)

Register application callback for writing ZB_NVRAM_APP_DATA4 to NVRAM

Parameters

wcb	- callback that will be called upon writing
gcb	- this callback will be called upon writing to determine dataset size

zb_nvram_transaction_commit()

void zb_nvram_transaction_commit

(

void

)

Commit NVRAM transaction.

Finish writing multiple datasets at once. A transaction must started by calling zb_nvram_transaction_start().

zb_nvram_transaction_start()

void zb_nvram_transaction_start

(

void

)

Start NVRAM transaction.

Start writing multiple datasets at once. A transaction must finished by calling zb_nvram_transaction_commit().

zb_nvram_write_data()

zb_ret_t zb_nvram_write_data	(	zb_uint8_t	page,
		zb_uint32_t	pos,
		zb_uint8_t *	buf,
		zb_uint16_t	len
	)

Writes a portion of some dataset.

Parameters

page	- an NVRAM page to write
pos	- a position on the NVRAM page
buf	- a buffer with data to be written
len	- a buffer size

Returns

Status of operation

zb_nvram_write_dataset()

zb_ret_t zb_nvram_write_dataset

(

zb_nvram_dataset_types_t

t

)

Write specified dataset into NVRAM

Parameters

t	- dataset index, see zb_nvram_dataset_types_e

Returns

Status of operation

Example

  /* If we fail, trace is given and assertion is triggered */
  /* Write to NVRAM HA profile Zigbee data */
  (void)zb_nvram_write_dataset(ZB_NVRAM_HA_DATA);
  /* Write to NVRAM ZCL reporting data */
  (void)zb_nvram_write_dataset(ZB_NVRAM_ZCL_REPORTING_DATA);

zb_set_nvram_erase_at_start()

void zb_set_nvram_erase_at_start

(

zb_bool_t

erase

)

Enable or disable NVRAM erasing on every application startup.

Parameters

erase

- 1 to enable erasing; 0 - disable. Erasing is disabled by default.