Developing with ZBOSS

Typedefs

typedef enum zb_nvram_dataset_types_e zb_nvram_dataset_types_t
 
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_IB_COUNTERS = 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_APS_SECURE_DATA = 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_APP_DATA3 = 27, ZB_NVRAM_APP_DATA4 = 28,
  ZB_NVRAM_DATASET_NUMBER, ZB_NVRAM_DATA_SET_TYPE_PAGE_HDR = 0x1e
}
 

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)
 
void 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)
 

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.

Typedef Documentation

◆ 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_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

◆ 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 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_IB_COUNTERS 

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 Neighbour table info

ZB_NVRAM_INSTALLCODES 

Dataset contains APS installcodes data

ZB_NVRAM_APS_SECURE_DATA 

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_APP_DATA3 

Application-specific data #3

ZB_NVRAM_APP_DATA4 

Application-specific data #4

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_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_dataset()

void 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

Example :

/* Write to NVRAM HA profile Zigbee data */
/* Write to NVRAM ZCL reporting data */

See light_sample

◆ 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.