Developing with ZBOSS for Zigbee

Data Structures

struct  zb_nvram_failure_report_s
 Structure that contains report about any NVRAM failure. More...
 

Macros

#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. 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_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_DATASET_GP_APP_TBL = 22, ZB_NVRAM_APP_DATA3 = 27,
  ZB_NVRAM_APP_DATA4 = 28, ZB_NVRAM_KE_WHITELIST = 29, ZB_NVRAM_ZDO_DIAGNOSTICS_DATA = 31, ZB_NVRAM_DATASET_NUMBER = 32,
  ZB_NVRAM_DATA_SET_TYPE_PAGE_HDR = 30
}
 

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 */
/* Write to 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_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_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,
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,
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 */

See light_sample application

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_failure_report_t

Structure that contains report about any NVRAM 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

◆ 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 Neighbor 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_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_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 */
/* Write to 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.
ZB_NVRAM_APP_DATA1
@ ZB_NVRAM_APP_DATA1
Definition: zboss_api.h:1090
ZB_ZCL_GET_ATTRIBUTE_VAL_8
#define ZB_ZCL_GET_ATTRIBUTE_VAL_8(attr_desc)
Definition: zb_zcl_common.h:926
zb_uint8_t
unsigned char zb_uint8_t
Project-local 1-byte unsigned int type.
Definition: zb_types.h:153
TRACE_MSG
#define TRACE_MSG(lm, fmts, args)
Put trace output.
Definition: zb_trace.h:359
ZB_ZCL_ATTR_LEVEL_CONTROL_CURRENT_LEVEL_ID
@ ZB_ZCL_ATTR_LEVEL_CONTROL_CURRENT_LEVEL_ID
Current Level attribute.
Definition: zb_zcl_level_control.h:53
ZB_ZCL_CLUSTER_ID_ON_OFF
#define ZB_ZCL_CLUSTER_ID_ON_OFF
Definition: zb_zcl_common.h:212
ZB_NVRAM_HA_DATA
@ ZB_NVRAM_HA_DATA
Definition: zboss_api.h:1083
zb_ret_t
zb_int32_t zb_ret_t
Return type for ZB functions returning execution status.
Definition: zb_errors.h:33
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)
zb_zcl_attr_s
ZCL attribute definition structure.
Definition: zb_zcl_common.h:706
zb_uint32_t
unsigned int zb_uint32_t
Project-local 4-byte unsigned int type.
Definition: zb_types.h:201
ZB_ZCL_SET_DIRECTLY_ATTR_VAL16
#define ZB_ZCL_SET_DIRECTLY_ATTR_VAL16(attr_desc, value)
Set attribute 16-bit value without any check. Use this macro on your own risk, if and only if you are...
Definition: zb_zcl_common.h:910
ZB_ZCL_CLUSTER_SERVER_ROLE
#define ZB_ZCL_CLUSTER_SERVER_ROLE
Definition: zb_zcl_common.h:189
zb_nvram_register_app1_read_cb
void zb_nvram_register_app1_read_cb(zb_nvram_read_app_data_t cb)
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)
ZB_NVRAM_ZCL_REPORTING_DATA
@ ZB_NVRAM_ZCL_REPORTING_DATA
Definition: zboss_api.h:1084
zb_nvram_write_dataset
zb_ret_t zb_nvram_write_dataset(zb_nvram_dataset_types_t t)
ZB_ZCL_CLUSTER_ID_LEVEL_CONTROL
#define ZB_ZCL_CLUSTER_ID_LEVEL_CONTROL
Definition: zb_zcl_common.h:214
zb_zcl_get_attr_desc_a
zb_zcl_attr_t * zb_zcl_get_attr_desc_a(zb_uint8_t ep, zb_uint16_t cluster_id, zb_uint8_t cluster_role, zb_uint16_t attr_id)
RET_OK
#define RET_OK
Error codes for non-void stack functions. In general, function can return OK, BLOCKED or some error....
Definition: zb_errors.h:78
zb_uint16_t
unsigned short zb_uint16_t
Project-local 2-byte unsigned int type.
Definition: zb_types.h:157
ZB_ZCL_SET_DIRECTLY_ATTR_VAL8
#define ZB_ZCL_SET_DIRECTLY_ATTR_VAL8(attr_desc, value)
Set attribute 8-bit value without any check. Use this macro on your own risk, if and only if you are ...
Definition: zb_zcl_common.h:899
ZB_ZCL_ATTR_ON_OFF_ON_OFF_ID
@ ZB_ZCL_ATTR_ON_OFF_ON_OFF_ID
OnOff attribute.
Definition: zb_zcl_on_off.h:60
ZB_FALSE
#define ZB_FALSE
Definition: zb_types.h:374
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)